create-threenative 0.2.5 → 0.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -1
- package/agent-docs/references/assertion-reference.md +40 -1
- package/agent-docs/references/capability-reference.md +972 -66
- package/agent-docs/references/finding-assets.md +8 -1
- package/agent-docs/references/performance-basics.md +114 -0
- package/agent-docs/references/rigging-characters.md +51 -0
- package/agent-docs/references/webview-ui.md +3 -2
- package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
- package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
- package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
- package/agent-files/.claude/settings.json +38 -0
- package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
- package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
- package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
- package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
- package/agent-files/.codex/hooks.json +40 -0
- package/capabilities.json +1344 -88
- package/dist/index.d.ts +10 -1
- package/dist/index.js +186 -1
- package/dist/threenative.js +660 -150
- package/package.json +6 -6
- package/template-assets/patches/three@0.185.1.patch +179 -19
- package/templates/action-rpg/AGENTS.md +5 -5
- package/templates/action-rpg/CLAUDE.md +5 -5
- package/templates/action-rpg/package.json +8 -8
- package/templates/defense/AGENTS.md +5 -5
- package/templates/defense/CLAUDE.md +5 -5
- package/templates/defense/package.json +8 -8
- package/templates/minimal/AGENTS.md +5 -5
- package/templates/minimal/CLAUDE.md +5 -5
- package/templates/minimal/package.json +7 -7
- package/templates/minimal/threenative.config.ts +1 -0
- package/templates/platformer/AGENTS.md +5 -5
- package/templates/platformer/CLAUDE.md +5 -5
- package/templates/platformer/package.json +9 -9
- package/templates/puzzle/AGENTS.md +5 -5
- package/templates/puzzle/CLAUDE.md +5 -5
- package/templates/puzzle/package.json +8 -8
- package/templates/racing/AGENTS.md +5 -5
- package/templates/racing/CLAUDE.md +5 -5
- package/templates/racing/package.json +8 -8
- package/templates/runner/AGENTS.md +5 -5
- package/templates/runner/CLAUDE.md +5 -5
- package/templates/runner/package.json +8 -8
- package/templates/sailing/AGENTS.md +6 -6
- package/templates/sailing/CLAUDE.md +6 -6
- package/templates/sailing/package.json +8 -8
- package/templates/shooter/AGENTS.md +5 -5
- package/templates/shooter/CLAUDE.md +5 -5
- package/templates/shooter/package.json +8 -8
- package/templates/starter/AGENTS.md +8 -8
- package/templates/starter/CLAUDE.md +8 -8
- package/templates/starter/package.json +9 -9
- package/templates/starter/playtests/production-readiness.playtest.json +96 -0
- package/templates/starter/src/ui/Hud.tsx +2 -2
- package/templates/starter/src/ui/Menu.tsx +5 -1
|
@@ -10,6 +10,21 @@ MCP server is available.
|
|
|
10
10
|
|
|
11
11
|
## `@threenative/assets`
|
|
12
12
|
|
|
13
|
+
### `atlasManifest`
|
|
14
|
+
|
|
15
|
+
`function` — Pack texture sources into deterministic atlas pages and answer each source's UV transform, so a build can stop giving every material a private texture.
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
export function atlasManifest(result: IAtlasResult): string { … }
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **Use when:** a merge found nothing to collapse because each imported part owns its own texture · cut the material count of an imported model pack at build time
|
|
22
|
+
- **Constraints:** deterministic by construction: the packing order is derived from the sources, never from directory order, so a rebuild places every source at the same pixel · a source the scene samples outside [0, 1] is excluded and reported, never clamped onto a shared page · page bounds hold regardless of input order; padding keeps a mip tap from reaching the next source
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
const { pages, transforms, excluded } = packAtlas(sources, { pageSize: 4096, padding: 4 });
|
|
26
|
+
```
|
|
27
|
+
|
|
13
28
|
### `audioPass`
|
|
14
29
|
|
|
15
30
|
`function` — Conditions a game's audio and proves the conditioning did not destroy it.
|
|
@@ -25,6 +40,21 @@ export function audioPass(options: IAudioPassOptions = { … }
|
|
|
25
40
|
const pass = audioPass({ overrides: [{ glob: "audio/*-bed.ogg", loop: true }] });
|
|
26
41
|
```
|
|
27
42
|
|
|
43
|
+
### `censusDocument`
|
|
44
|
+
|
|
45
|
+
`function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
export function censusDocument( model: string, document: Document, pageSize = 4_096, ): IContentCensus { … }
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- **Use when:** find out whether "fewer objects" is available in this content before promising it · explain why a per-material merge collapsed nothing
|
|
52
|
+
- **Constraints:** reads geometry and materials only: no GPU, no runtime, no game · a texture whose size the document does not state is reported excluded, never assumed square · a model the reader cannot open is named, never skipped silently
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
pnpm census:content public/assets
|
|
56
|
+
```
|
|
57
|
+
|
|
28
58
|
### `compileAssets`
|
|
29
59
|
|
|
30
60
|
`function` — Compiles a project's source assets into content-addressed runtime files and a manifest.
|
|
@@ -40,6 +70,21 @@ export async function compileAssets( options: IAssetCompileOptions = { … }
|
|
|
40
70
|
const result = await compileAssets({ source: "assets", output: "public" });
|
|
41
71
|
```
|
|
42
72
|
|
|
73
|
+
### `dedupeMaterials`
|
|
74
|
+
|
|
75
|
+
`function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
export function dedupeMaterials(materials: readonly IMaterialState[]): { … }
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- **Use when:** decide whether fewer objects is actually available in this content · report why a per-material merge collapsed nothing
|
|
82
|
+
- **Constraints:** the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand · the census reads geometry and materials only: no GPU, no runtime, no game
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
pnpm census:content public/assets
|
|
86
|
+
```
|
|
87
|
+
|
|
43
88
|
### `formatAudioSizes`
|
|
44
89
|
|
|
45
90
|
`function` — Formats audio conditioning measurements for a build report.
|
|
@@ -130,6 +175,36 @@ export function lightmapPass(options: ILightmapPassOptions): IAssetPass { … }
|
|
|
130
175
|
const pass = lightmapPass({ atlasSize: 1024, padding: 2 });
|
|
131
176
|
```
|
|
132
177
|
|
|
178
|
+
### `materialSignature`
|
|
179
|
+
|
|
180
|
+
`function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
export function materialSignature(material: IMaterialState): string { … }
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
- **Use when:** decide whether fewer objects is actually available in this content · report why a per-material merge collapsed nothing
|
|
187
|
+
- **Constraints:** the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand · the census reads geometry and materials only: no GPU, no runtime, no game
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
pnpm census:content public/assets
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### `materialStateOf`
|
|
194
|
+
|
|
195
|
+
`function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
export function materialStateOf(material: Material): IMaterialState { … }
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
- **Use when:** find out whether "fewer objects" is available in this content before promising it · explain why a per-material merge collapsed nothing
|
|
202
|
+
- **Constraints:** reads geometry and materials only: no GPU, no runtime, no game · a texture whose size the document does not state is reported excluded, never assumed square · a model the reader cannot open is named, never skipped silently
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
pnpm census:content public/assets
|
|
206
|
+
```
|
|
207
|
+
|
|
133
208
|
### `modelPass`
|
|
134
209
|
|
|
135
210
|
`function` — Optimizes self-contained GLB models through the configured geometry and embedded-texture passes.
|
|
@@ -145,6 +220,21 @@ export function modelPass(options: IModelPassOptions = { … }
|
|
|
145
220
|
const pass = modelPass({ simplify: { ratio: 0.5 } });
|
|
146
221
|
```
|
|
147
222
|
|
|
223
|
+
### `packAtlas`
|
|
224
|
+
|
|
225
|
+
`function` — Pack texture sources into deterministic atlas pages and answer each source's UV transform, so a build can stop giving every material a private texture.
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
export function packAtlas( sources: readonly IAtlasSource[], options: IAtlasOptions = { … }
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
- **Use when:** a merge found nothing to collapse because each imported part owns its own texture · cut the material count of an imported model pack at build time
|
|
232
|
+
- **Constraints:** deterministic by construction: the packing order is derived from the sources, never from directory order, so a rebuild places every source at the same pixel · a source the scene samples outside [0, 1] is excluded and reported, never clamped onto a shared page · page bounds hold regardless of input order; padding keeps a mip tap from reaching the next source
|
|
233
|
+
|
|
234
|
+
```ts
|
|
235
|
+
const { pages, transforms, excluded } = packAtlas(sources, { pageSize: 4096, padding: 4 });
|
|
236
|
+
```
|
|
237
|
+
|
|
148
238
|
### `parseAudioConfig`
|
|
149
239
|
|
|
150
240
|
`function` — Validates a game's declared `assets.audio` block, the one place its keys and ranges are checked.
|
|
@@ -190,6 +280,36 @@ export function resolveBasisTranscoder(cwd: string): IBasisTranscoder { … }
|
|
|
190
280
|
const transcoder = resolveBasisTranscoder(process.cwd());
|
|
191
281
|
```
|
|
192
282
|
|
|
283
|
+
### `resolveSourceTexel`
|
|
284
|
+
|
|
285
|
+
`function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
|
|
286
|
+
|
|
287
|
+
```ts
|
|
288
|
+
export function resolveSourceTexel( atlasUv: readonly [number, number], transform: IAtlasTransform, source: { … }
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
- **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
|
|
292
|
+
- **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### `rewriteUvs`
|
|
299
|
+
|
|
300
|
+
`function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
export function rewriteUvs(uv: Float32Array, transform: IAtlasTransform): Float32Array { … }
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
- **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
|
|
307
|
+
- **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
|
|
308
|
+
|
|
309
|
+
```ts
|
|
310
|
+
if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
|
|
311
|
+
```
|
|
312
|
+
|
|
193
313
|
### `runHealthReport`
|
|
194
314
|
|
|
195
315
|
`function` — Measures compiled assets and grades them against declared project targets.
|
|
@@ -220,6 +340,36 @@ export function texturePass(options: ITexturePassOptions = { … }
|
|
|
220
340
|
const pass = texturePass({ quality: 150 });
|
|
221
341
|
```
|
|
222
342
|
|
|
343
|
+
### `totalCensus`
|
|
344
|
+
|
|
345
|
+
`function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
|
|
346
|
+
|
|
347
|
+
```ts
|
|
348
|
+
export function totalCensus(entries: readonly IContentCensus[]): Omit<IContentCensus, "model"> { … }
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
- **Use when:** find out whether "fewer objects" is available in this content before promising it · explain why a per-material merge collapsed nothing
|
|
352
|
+
- **Constraints:** reads geometry and materials only: no GPU, no runtime, no game · a texture whose size the document does not state is reported excluded, never assumed square · a model the reader cannot open is named, never skipped silently
|
|
353
|
+
|
|
354
|
+
```ts
|
|
355
|
+
pnpm census:content public/assets
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
### `uvsTile`
|
|
359
|
+
|
|
360
|
+
`function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
|
|
361
|
+
|
|
362
|
+
```ts
|
|
363
|
+
export function uvsTile(uv: ArrayLike<number>): boolean { … }
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
- **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
|
|
367
|
+
- **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
|
|
368
|
+
|
|
369
|
+
```ts
|
|
370
|
+
if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
|
|
371
|
+
```
|
|
372
|
+
|
|
223
373
|
### `watchAssets`
|
|
224
374
|
|
|
225
375
|
`function` — Watches an asset source directory and recompiles settled changes during development.
|
|
@@ -235,6 +385,36 @@ export function watchAssets(options: IAssetWatchOptions = { … }
|
|
|
235
385
|
const watcher = watchAssets({ cwd: process.cwd() });
|
|
236
386
|
```
|
|
237
387
|
|
|
388
|
+
### `withAtlasTextures`
|
|
389
|
+
|
|
390
|
+
`function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
|
|
391
|
+
|
|
392
|
+
```ts
|
|
393
|
+
export function withAtlasTextures( materials: readonly IMaterialState[], pageOf: (texture: string) => string | undefined, ): IMaterialState[] { … }
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
- **Use when:** decide whether fewer objects is actually available in this content · report why a per-material merge collapsed nothing
|
|
397
|
+
- **Constraints:** the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand · the census reads geometry and materials only: no GPU, no runtime, no game
|
|
398
|
+
|
|
399
|
+
```ts
|
|
400
|
+
pnpm census:content public/assets
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### `wrapTiles`
|
|
404
|
+
|
|
405
|
+
`function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
|
|
406
|
+
|
|
407
|
+
```ts
|
|
408
|
+
export function wrapTiles(wrapS: number | undefined, wrapT: number | undefined): boolean { … }
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
- **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
|
|
412
|
+
- **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
|
|
413
|
+
|
|
414
|
+
```ts
|
|
415
|
+
if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
|
|
416
|
+
```
|
|
417
|
+
|
|
238
418
|
## `@threenative/core`
|
|
239
419
|
|
|
240
420
|
### `addInSlices`
|
|
@@ -256,6 +436,37 @@ const report = await addInSlices(objects, (object) => ctx.add(object), {
|
|
|
256
436
|
});
|
|
257
437
|
```
|
|
258
438
|
|
|
439
|
+
### `addSpan`
|
|
440
|
+
|
|
441
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
442
|
+
|
|
443
|
+
```ts
|
|
444
|
+
export function addSpan(id: SpanId, ms: number): void { … }
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
448
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
449
|
+
|
|
450
|
+
```ts
|
|
451
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
### `aerodynamicCoefficients`
|
|
455
|
+
|
|
456
|
+
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
457
|
+
|
|
458
|
+
```ts
|
|
459
|
+
export function aerodynamicCoefficients( alpha: number, flaps = 0, gear = 0, brakes = 0, ): { … }
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
463
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
464
|
+
|
|
465
|
+
```ts
|
|
466
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
467
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
468
|
+
```
|
|
469
|
+
|
|
259
470
|
### `afterPhysics`
|
|
260
471
|
|
|
261
472
|
`function` — Register work that reads a body or camera after physics has moved it and before this frame draws. The engine owns the phase ordering; a callback cannot be misplaced by plugin-array order.
|
|
@@ -271,6 +482,55 @@ export function afterPhysics( context: IAfterPhysicsContext, callback: AfterPhys
|
|
|
271
482
|
afterPhysics(ctx, (dt) => camera.position.copy(player.mesh.position));
|
|
272
483
|
```
|
|
273
484
|
|
|
485
|
+
### `aircraftMass`
|
|
486
|
+
|
|
487
|
+
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
488
|
+
|
|
489
|
+
```ts
|
|
490
|
+
export function aircraftMass(state: IFlightState, airframe: IAircraftAirframe): number { … }
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
494
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
495
|
+
|
|
496
|
+
```ts
|
|
497
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
498
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
### `airDensity`
|
|
502
|
+
|
|
503
|
+
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
504
|
+
|
|
505
|
+
```ts
|
|
506
|
+
export function airDensity(y: number): number { … }
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
510
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
511
|
+
|
|
512
|
+
```ts
|
|
513
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
514
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
### `alwaysRender`
|
|
518
|
+
|
|
519
|
+
`function` — Keep an object drawn even when the render camera cannot resolve it. The engine's projected-size gate is on by default: an object whose world bounding sphere projects to fewer than 0.5 raster pixels in the camera about to render it is not submitted, per camera. Mark the player's own cockpit, a nameplate, a quest marker, or anything a game never wants to pop out of the frame. `alwaysRender(object, false)` removes the marker. Camera-attached objects and shadow casters are already kept, and the number of marked objects is reported beside the cull in the `TN_PROJECTION` window rather than hidden. The threshold itself is `renderer.minimumProjectedPixels` — a larger number cuts more aggressively, `false` leaves every object drawn while still measuring.
|
|
520
|
+
|
|
521
|
+
```ts
|
|
522
|
+
export function alwaysRender(object: Object3D, enabled = true): void { … }
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
- **Use when:** keep a small object drawn when the engine would skip it as too far to resolve · stop my cockpit, marker or player model popping out at distance · a tiny object disappeared at range and I need it always visible · widen or narrow the projected-size cull with a named threshold
|
|
526
|
+
- **Constraints:** the marker is per object and is reported as `exemptMarked` in the projection window · `renderer.minimumProjectedPixels: false` leaves the scene drawn and keeps the measurement on · the marker is per object and survives scene rebuilds only as long as the object does · disabling the gate (`renderer.minimumProjectedPixels: false`) keeps its measurement on
|
|
527
|
+
- **Overrides:** renderer.minimumProjectedPixels sets the projected-pixel threshold, default 0.5
|
|
528
|
+
|
|
529
|
+
```ts
|
|
530
|
+
import { alwaysRender } from "@threenative/core";
|
|
531
|
+
alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
|
|
532
|
+
```
|
|
533
|
+
|
|
274
534
|
### `AnimationPlayer`
|
|
275
535
|
|
|
276
536
|
`class` — Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
|
|
@@ -334,6 +594,22 @@ import { attachToBone } from "@threenative/core";
|
|
|
334
594
|
attachToBone(character, "RightHand", rifle);
|
|
335
595
|
```
|
|
336
596
|
|
|
597
|
+
### `attitudeAxes`
|
|
598
|
+
|
|
599
|
+
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
600
|
+
|
|
601
|
+
```ts
|
|
602
|
+
export function attitudeAxes(state: IFlightState): IFlightAxes { … }
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
606
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
607
|
+
|
|
608
|
+
```ts
|
|
609
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
610
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
611
|
+
```
|
|
612
|
+
|
|
337
613
|
### `AudioBus`
|
|
338
614
|
|
|
339
615
|
`class` — Route effects through a named audio bus.
|
|
@@ -350,6 +626,35 @@ export class AudioBus { … }
|
|
|
350
626
|
const effects = new AudioBus({ camera });
|
|
351
627
|
```
|
|
352
628
|
|
|
629
|
+
### `baseGeometryOf`
|
|
630
|
+
|
|
631
|
+
`function` — The full-detail geometry of a mesh the loader gave an automatic LOD chain. Selection swaps `mesh.geometry`, so a ray test or a collision body built from the current geometry would change with the camera. Framework picking and gameplay collide against this instead: the authored LOD0, which never changes as the camera moves.
|
|
632
|
+
|
|
633
|
+
```ts
|
|
634
|
+
export function baseGeometryOf(mesh: Mesh): BufferGeometry { … }
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
- **Use when:** collide or ray-test the authored geometry of a mesh whose render detail changes with distance
|
|
638
|
+
|
|
639
|
+
```ts
|
|
640
|
+
const geometry = baseGeometryOf(mesh);
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
### `beginSpan`
|
|
644
|
+
|
|
645
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
646
|
+
|
|
647
|
+
```ts
|
|
648
|
+
export function beginSpan(id: SpanId): void { … }
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
652
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
653
|
+
|
|
654
|
+
```ts
|
|
655
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
656
|
+
```
|
|
657
|
+
|
|
353
658
|
### `Billboard3D`
|
|
354
659
|
|
|
355
660
|
`class` — Face a game-owned object toward a perspective or orthographic camera.
|
|
@@ -546,6 +851,21 @@ export class ComputeDrivenRegistry { … }
|
|
|
546
851
|
const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);
|
|
547
852
|
```
|
|
548
853
|
|
|
854
|
+
### `counterDeviceOf`
|
|
855
|
+
|
|
856
|
+
`function` — Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing count and a millisecond split describe the same frames.
|
|
857
|
+
|
|
858
|
+
```ts
|
|
859
|
+
export function counterDeviceOf(raw: unknown): unknown { … }
|
|
860
|
+
```
|
|
861
|
+
|
|
862
|
+
- **Use when:** decide whether a CPU-bound frame is paying for the V8-to-host boundary · measure how many bytes a frame writes into GPU buffers, and how many commands it issues
|
|
863
|
+
- **Constraints:** counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in · `gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included · `jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it
|
|
864
|
+
|
|
865
|
+
```ts
|
|
866
|
+
const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
|
|
867
|
+
```
|
|
868
|
+
|
|
549
869
|
### `createAssetLoader`
|
|
550
870
|
|
|
551
871
|
`function` — Create the portable asset loader a scene also receives as `ctx.assets`.
|
|
@@ -625,6 +945,36 @@ export function defineGame<TState extends Record<string, unknown>, TPhysics = un
|
|
|
625
945
|
const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: "Play" });
|
|
626
946
|
```
|
|
627
947
|
|
|
948
|
+
### `describeSceneShape`
|
|
949
|
+
|
|
950
|
+
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
951
|
+
|
|
952
|
+
```ts
|
|
953
|
+
export function describeSceneShape( window: IFrameBudgetWindow, cull: IRenderCameraCullReport | undefined, ): ISceneShape | undefined { … }
|
|
954
|
+
```
|
|
955
|
+
|
|
956
|
+
- **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
|
|
957
|
+
- **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
|
|
958
|
+
|
|
959
|
+
```ts
|
|
960
|
+
defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
961
|
+
```
|
|
962
|
+
|
|
963
|
+
### `describeSceneWarning`
|
|
964
|
+
|
|
965
|
+
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
966
|
+
|
|
967
|
+
```ts
|
|
968
|
+
export function describeSceneWarning(warning: ISceneWarning): string { … }
|
|
969
|
+
```
|
|
970
|
+
|
|
971
|
+
- **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
|
|
972
|
+
- **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
|
|
973
|
+
|
|
974
|
+
```ts
|
|
975
|
+
defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
976
|
+
```
|
|
977
|
+
|
|
628
978
|
### `directionalTransmittance`
|
|
629
979
|
|
|
630
980
|
`function` — Approximate direct transmittance for a ray leaving the game surface.
|
|
@@ -655,6 +1005,36 @@ export function directionFromSolarPosition(elevation: number, azimuth: number):
|
|
|
655
1005
|
const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
|
|
656
1006
|
```
|
|
657
1007
|
|
|
1008
|
+
### `displayPeriodMs`
|
|
1009
|
+
|
|
1010
|
+
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1011
|
+
|
|
1012
|
+
```ts
|
|
1013
|
+
export function displayPeriodMs( declaredTargetFps: number | undefined, ): { … }
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
- **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
|
|
1017
|
+
- **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
|
|
1018
|
+
|
|
1019
|
+
```ts
|
|
1020
|
+
defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
1021
|
+
```
|
|
1022
|
+
|
|
1023
|
+
### `endSpan`
|
|
1024
|
+
|
|
1025
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
1026
|
+
|
|
1027
|
+
```ts
|
|
1028
|
+
export function endSpan(id: SpanId): void { … }
|
|
1029
|
+
```
|
|
1030
|
+
|
|
1031
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
1032
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
1033
|
+
|
|
1034
|
+
```ts
|
|
1035
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
1036
|
+
```
|
|
1037
|
+
|
|
658
1038
|
### `ensureVelocityOutput`
|
|
659
1039
|
|
|
660
1040
|
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
@@ -676,37 +1056,129 @@ renderer.render(scene, camera);
|
|
|
676
1056
|
tracker.commit(scene);
|
|
677
1057
|
```
|
|
678
1058
|
|
|
679
|
-
### `
|
|
1059
|
+
### `FlightModel`
|
|
1060
|
+
|
|
1061
|
+
`class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
1062
|
+
|
|
1063
|
+
```ts
|
|
1064
|
+
export class FlightModel<TState extends IFlightState = IFlightState> { … }
|
|
1065
|
+
```
|
|
1066
|
+
|
|
1067
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
1068
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
1069
|
+
|
|
1070
|
+
```ts
|
|
1071
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
1072
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
1073
|
+
```
|
|
1074
|
+
|
|
1075
|
+
### `FluidField2D`
|
|
1076
|
+
|
|
1077
|
+
`class` — Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
|
|
1078
|
+
|
|
1079
|
+
```ts
|
|
1080
|
+
export class FluidField2D extends Group { … }
|
|
1081
|
+
```
|
|
1082
|
+
|
|
1083
|
+
- **Use when:** simulate smoke, fire, fog, wind, or fluid response on a grid · inject a touch, pointer, or gameplay impulse into a fluid field · sample fluid dye or velocity in a game-owned render node · simulate ocean currents and wind affecting a sailing ship · simulate ocean fluid dynamics and currents that affect a ship
|
|
1084
|
+
- **Constraints:** add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic · `dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code · the conformance sample measures mean absolute velocity divergence at 0.001732 after four 32² steps with pressureIterations 2, below the 0.0025 threshold
|
|
1085
|
+
- **Overrides:** pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
|
|
1086
|
+
|
|
1087
|
+
```ts
|
|
1088
|
+
const field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
|
|
1089
|
+
ctx.add(field);
|
|
1090
|
+
field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
|
|
1091
|
+
```
|
|
1092
|
+
|
|
1093
|
+
### `formatSceneWarning`
|
|
1094
|
+
|
|
1095
|
+
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1096
|
+
|
|
1097
|
+
```ts
|
|
1098
|
+
export function formatSceneWarning(warning: ISceneWarning): string { … }
|
|
1099
|
+
```
|
|
1100
|
+
|
|
1101
|
+
- **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
|
|
1102
|
+
- **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
|
|
1103
|
+
|
|
1104
|
+
```ts
|
|
1105
|
+
defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
1106
|
+
```
|
|
1107
|
+
|
|
1108
|
+
### `formatSpansWindow`
|
|
1109
|
+
|
|
1110
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
1111
|
+
|
|
1112
|
+
```ts
|
|
1113
|
+
export function formatSpansWindow(window: ISpanWindow): string { … }
|
|
1114
|
+
```
|
|
1115
|
+
|
|
1116
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
1117
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
1118
|
+
|
|
1119
|
+
```ts
|
|
1120
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
1121
|
+
```
|
|
1122
|
+
|
|
1123
|
+
### `formatValidationReport`
|
|
1124
|
+
|
|
1125
|
+
`function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
|
|
1126
|
+
|
|
1127
|
+
```ts
|
|
1128
|
+
export function formatValidationReport(report: IValidationReport): string { … }
|
|
1129
|
+
```
|
|
1130
|
+
|
|
1131
|
+
- **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
|
|
1132
|
+
- **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
|
|
1133
|
+
|
|
1134
|
+
```ts
|
|
1135
|
+
if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
1136
|
+
```
|
|
1137
|
+
|
|
1138
|
+
### `FrameBudget`
|
|
1139
|
+
|
|
1140
|
+
`class` — Read where the frame's milliseconds went, per presented frame, on any platform; each `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and triangles each render pass submitted.
|
|
1141
|
+
|
|
1142
|
+
```ts
|
|
1143
|
+
export class FrameBudget { … }
|
|
1144
|
+
```
|
|
1145
|
+
|
|
1146
|
+
- **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass
|
|
1147
|
+
- **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
|
|
1148
|
+
|
|
1149
|
+
```ts
|
|
1150
|
+
defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
|
|
1151
|
+
```
|
|
1152
|
+
|
|
1153
|
+
### `FrameCounters`
|
|
680
1154
|
|
|
681
|
-
`class` —
|
|
1155
|
+
`class` — Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing count and a millisecond split describe the same frames.
|
|
682
1156
|
|
|
683
1157
|
```ts
|
|
684
|
-
export class
|
|
1158
|
+
export class FrameCounters { … }
|
|
685
1159
|
```
|
|
686
1160
|
|
|
687
|
-
- **Use when:**
|
|
688
|
-
- **Constraints:**
|
|
689
|
-
- **Overrides:** pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
|
|
1161
|
+
- **Use when:** decide whether a CPU-bound frame is paying for the V8-to-host boundary · measure how many bytes a frame writes into GPU buffers, and how many commands it issues
|
|
1162
|
+
- **Constraints:** counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in · `gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included · `jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it
|
|
690
1163
|
|
|
691
1164
|
```ts
|
|
692
|
-
const
|
|
693
|
-
ctx.add(field);
|
|
694
|
-
field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
|
|
1165
|
+
const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
|
|
695
1166
|
```
|
|
696
1167
|
|
|
697
|
-
### `
|
|
1168
|
+
### `gearClearance`
|
|
698
1169
|
|
|
699
|
-
`
|
|
1170
|
+
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
700
1171
|
|
|
701
1172
|
```ts
|
|
702
|
-
export
|
|
1173
|
+
export function gearClearance(state: IFlightState): number { … }
|
|
703
1174
|
```
|
|
704
1175
|
|
|
705
|
-
- **Use when:**
|
|
706
|
-
- **Constraints:**
|
|
1176
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
1177
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
707
1178
|
|
|
708
1179
|
```ts
|
|
709
|
-
|
|
1180
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
1181
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
710
1182
|
```
|
|
711
1183
|
|
|
712
1184
|
### `getPlatform`
|
|
@@ -786,6 +1258,21 @@ import { GroundSnap } from "@threenative/core";
|
|
|
786
1258
|
const snap = new GroundSnap(character, { enabled: true });
|
|
787
1259
|
```
|
|
788
1260
|
|
|
1261
|
+
### `installSpanProbes`
|
|
1262
|
+
|
|
1263
|
+
`function` — Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's `sort`, the per-draw submission, and the scene-graph walk. Installed for you when `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.
|
|
1264
|
+
|
|
1265
|
+
```ts
|
|
1266
|
+
export function installSpanProbes(target: ISpanProbeTarget, root: Object3D): () => void { … }
|
|
1267
|
+
```
|
|
1268
|
+
|
|
1269
|
+
- **Use when:** measure which part of three's render path costs the frame · attach the span tree to a renderer a test or a tool constructed itself
|
|
1270
|
+
- **Constraints:** returns an uninstall that restores every wrapper, asserted by test · a renderer whose internals have moved loses that span rather than throwing, and it is absent from the report rather than zero · only the outermost `_projectObject` opens a span, because three's recurses per child
|
|
1271
|
+
|
|
1272
|
+
```ts
|
|
1273
|
+
const uninstall = installSpanProbes(renderer.raw, scene);
|
|
1274
|
+
```
|
|
1275
|
+
|
|
789
1276
|
### `InstancedBatch`
|
|
790
1277
|
|
|
791
1278
|
`class` — Collapse many copies of one game-authored shape into a single draw, without counting them first. `new InstancedMesh(geometry, material, count)` needs the count before anything is placed, so a procedural builder ends up walking its layout twice or over-allocating. Place as you go and `build()` once; the shape, the surface and every transform stay the game's, and the built mesh is returned so instances can still be animated by the index `place` and `span` hand back.
|
|
@@ -804,6 +1291,21 @@ curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0
|
|
|
804
1291
|
curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
|
|
805
1292
|
```
|
|
806
1293
|
|
|
1294
|
+
### `invalidateStatic`
|
|
1295
|
+
|
|
1296
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
1297
|
+
|
|
1298
|
+
```ts
|
|
1299
|
+
export function invalidateStatic(object: Object3D): number | undefined { … }
|
|
1300
|
+
```
|
|
1301
|
+
|
|
1302
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
1303
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
1304
|
+
|
|
1305
|
+
```ts
|
|
1306
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
1307
|
+
```
|
|
1308
|
+
|
|
807
1309
|
### `isMobile`
|
|
808
1310
|
|
|
809
1311
|
`function` — Read the host platform without reaching for browser globals.
|
|
@@ -834,6 +1336,21 @@ export function isNative(): boolean { … }
|
|
|
834
1336
|
if (isMobile()) showTouchControls();
|
|
835
1337
|
```
|
|
836
1338
|
|
|
1339
|
+
### `isStatic`
|
|
1340
|
+
|
|
1341
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
1342
|
+
|
|
1343
|
+
```ts
|
|
1344
|
+
export function isStatic(root: Object3D): boolean { … }
|
|
1345
|
+
```
|
|
1346
|
+
|
|
1347
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
1348
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
1349
|
+
|
|
1350
|
+
```ts
|
|
1351
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
1352
|
+
```
|
|
1353
|
+
|
|
837
1354
|
### `isTouchscreenAvailable`
|
|
838
1355
|
|
|
839
1356
|
`function` — Read the host platform without reaching for browser globals.
|
|
@@ -880,6 +1397,38 @@ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TI
|
|
|
880
1397
|
const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
|
|
881
1398
|
```
|
|
882
1399
|
|
|
1400
|
+
### `markStatic`
|
|
1401
|
+
|
|
1402
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
1403
|
+
|
|
1404
|
+
```ts
|
|
1405
|
+
export function markStatic(root: Object3D): number { … }
|
|
1406
|
+
```
|
|
1407
|
+
|
|
1408
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
1409
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
1410
|
+
|
|
1411
|
+
```ts
|
|
1412
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
1413
|
+
```
|
|
1414
|
+
|
|
1415
|
+
### `MatrixWorldPass`
|
|
1416
|
+
|
|
1417
|
+
`class` — Walk the scene graph's world matrices each frame without recursing into a hidden subtree. On by default as `renderer.matrixWorld: "visible"`. three's `updateMatrixWorld` recurses into every child whatever its `visible` flag, so a hidden LOD body, a merged stand-in and a parked model cost a world-matrix multiply each while nothing under them can draw. This pass mirrors three exactly for every visible node and defers a hidden node's subtree until the frame it shows again. A class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a hidden node that holds bones is walked, so no skeleton or view matrix goes stale.
|
|
1418
|
+
|
|
1419
|
+
```ts
|
|
1420
|
+
export class MatrixWorldPass { … }
|
|
1421
|
+
```
|
|
1422
|
+
|
|
1423
|
+
- **Use when:** the per-frame world matrix walk is hot in a profile · stop multiplying matrices for hidden models, LOD levels and merged stand-ins · a game needs every node walked, exactly as three's own updateMatrixWorld does
|
|
1424
|
+
- **Constraints:** a game that reads a hidden object's matrixWorld directly must use getWorldPosition or updateWorldMatrix(true, false) first · `renderer.matrixWorld: "all"` visits every node; `TN_PROJECTION` reports the visited count either way
|
|
1425
|
+
- **Overrides:** renderer.matrixWorld: "all" runs three's full walk instead of the visible-only default
|
|
1426
|
+
|
|
1427
|
+
```ts
|
|
1428
|
+
import { MatrixWorldPass } from "@threenative/core";
|
|
1429
|
+
const pass = new MatrixWorldPass(); // renderer.matrixWorld defaults to "visible"
|
|
1430
|
+
```
|
|
1431
|
+
|
|
883
1432
|
### `measureThreePose`
|
|
884
1433
|
|
|
885
1434
|
`function` — Measure a Three.js pose for grounded or attachment-aware checks.
|
|
@@ -897,20 +1446,22 @@ const measurement = measureThreePose(model);
|
|
|
897
1446
|
|
|
898
1447
|
### `mergeParts`
|
|
899
1448
|
|
|
900
|
-
`function` — Merge pieces a game authored out of primitives into one buffer, keeping each piece's own
|
|
1449
|
+
`function` — Merge pieces a game authored out of primitives into one buffer, keeping each piece's own look. `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that never move relative to each other — a building, a ship, a character built from boxes, or the static parts of an imported glTF model. Two things go wrong every time and neither is about how any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing, and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other primitive is indexed, so the merge fails at the first piece and the scene never loads. And a merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat `color` attribute written before the merge. Both are mechanical. By default every part is stripped to position and the normals are recomputed from the merged buffer; pass `preserve` to keep authored normals and texture UVs while baking each part's object transform. Geometry, placement, colour and the surface it draws with all stay the game's.
|
|
901
1450
|
|
|
902
1451
|
```ts
|
|
903
1452
|
export function mergeParts( parts: Iterable<IMergePart>, options: IMergePartsOptions, ): BufferGeometry { … }
|
|
904
1453
|
```
|
|
905
1454
|
|
|
906
|
-
- **Use when:** bake a building, ship or character authored out of primitives into one draw call · merge many small geometries and keep each piece's own colour · stop mergeGeometries from silently returning null on an extruded shape
|
|
907
|
-
- **Constraints:** every part is de-indexed
|
|
908
|
-
- **Overrides:** color is per part and optional; without it no colour attribute is written and the surface alone decides
|
|
1455
|
+
- **Use when:** bake a building, ship or character authored out of primitives into one draw call · merge multiple static Three.js meshes into one mesh per material · consolidate the static parts of an imported glTF model into one buffer · preserve texture UV coordinates and authored normals while baking object transforms · merge many small geometries and keep each piece's own colour · stop mergeGeometries from silently returning null on an extruded shape
|
|
1456
|
+
- **Constraints:** every part is de-indexed; without preserve it is stripped to position and normals are recomputed from the merged buffer · preserve keeps the listed channels, transforming position and normal by the part's placement matrix while UV values are retained unchanged · a part that does not carry a listed preserve channel throws naming the label, the part and the channel · either every part names a color or none does, and a mix throws · an empty part list throws, and a merge three.js refuses throws naming the label
|
|
1457
|
+
- **Overrides:** color is per part and optional; without it no colour attribute is written and the surface alone decides · preserve is optional and empty by default: position-only merge with recomputed normals, exactly as before
|
|
909
1458
|
|
|
910
1459
|
```ts
|
|
911
1460
|
const wall = new Mesh(mergeParts(pieces, { label: "gatehouse" }), stone);
|
|
912
1461
|
// pieces are meshes, or { geometry, matrix, color } when the colour is per piece:
|
|
913
1462
|
const banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: "banner" });
|
|
1463
|
+
// keep a model's texture UVs and authored normals while baking its transforms:
|
|
1464
|
+
const hull = mergeParts(hullParts, { label: "hull", preserve: ["uv", "normal"] });
|
|
914
1465
|
```
|
|
915
1466
|
|
|
916
1467
|
### `normaliseToMetres`
|
|
@@ -929,6 +1480,20 @@ export function normaliseToMetres(object: Object3D, options: INormaliseToMetresO
|
|
|
929
1480
|
normaliseToMetres(character, { metres: 1.8, axis: "height" });
|
|
930
1481
|
```
|
|
931
1482
|
|
|
1483
|
+
### `onLaunchFailure`
|
|
1484
|
+
|
|
1485
|
+
`function` — Called for every launch failure the engine notices, with the message to show the player.
|
|
1486
|
+
|
|
1487
|
+
```ts
|
|
1488
|
+
export function onLaunchFailure(listener: (failure: ILaunchFailure) => void): () => void { … }
|
|
1489
|
+
```
|
|
1490
|
+
|
|
1491
|
+
- **Use when:** show the player why the game stopped loading instead of leaving the loading screen up · report a stalled launch or a lost GPU device in the game's own UI
|
|
1492
|
+
|
|
1493
|
+
```ts
|
|
1494
|
+
const off = onLaunchFailure((failure) => shell.loading({ failure: failure.message }));
|
|
1495
|
+
```
|
|
1496
|
+
|
|
932
1497
|
### `parseReplayRecording`
|
|
933
1498
|
|
|
934
1499
|
`function` — Validate and parse a replay recording file.
|
|
@@ -1177,6 +1742,21 @@ import { reconcileMirroredClips } from "@threenative/core";
|
|
|
1177
1742
|
if (reconcileMirroredClips(gltf.scene, gltf.animations)) console.info("clips were z-mirrored; repaired");
|
|
1178
1743
|
```
|
|
1179
1744
|
|
|
1745
|
+
### `refreshStaticTransforms`
|
|
1746
|
+
|
|
1747
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
1748
|
+
|
|
1749
|
+
```ts
|
|
1750
|
+
export function refreshStaticTransforms(): void { … }
|
|
1751
|
+
```
|
|
1752
|
+
|
|
1753
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
1754
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
1755
|
+
|
|
1756
|
+
```ts
|
|
1757
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
1758
|
+
```
|
|
1759
|
+
|
|
1180
1760
|
### `RenderChain`
|
|
1181
1761
|
|
|
1182
1762
|
`class` — Compose game-provided render nodes in a measured, fail-closed chain. Authored stages use an opaque id and anchor before or after a built-in or another supplied stage; the engine does not need to know the effect's visual vocabulary.
|
|
@@ -1192,6 +1772,36 @@ export class RenderChain { … }
|
|
|
1192
1772
|
const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
|
|
1193
1773
|
```
|
|
1194
1774
|
|
|
1775
|
+
### `renderListValidationRequested`
|
|
1776
|
+
|
|
1777
|
+
`function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
|
|
1778
|
+
|
|
1779
|
+
```ts
|
|
1780
|
+
export function renderListValidationRequested(): boolean { … }
|
|
1781
|
+
```
|
|
1782
|
+
|
|
1783
|
+
- **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
|
|
1784
|
+
- **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
|
|
1785
|
+
|
|
1786
|
+
```ts
|
|
1787
|
+
if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
1788
|
+
```
|
|
1789
|
+
|
|
1790
|
+
### `RenderListValidator`
|
|
1791
|
+
|
|
1792
|
+
`class` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
|
|
1793
|
+
|
|
1794
|
+
```ts
|
|
1795
|
+
export class RenderListValidator { … }
|
|
1796
|
+
```
|
|
1797
|
+
|
|
1798
|
+
- **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
|
|
1799
|
+
- **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
|
|
1800
|
+
|
|
1801
|
+
```ts
|
|
1802
|
+
if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
1803
|
+
```
|
|
1804
|
+
|
|
1195
1805
|
### `replay`
|
|
1196
1806
|
|
|
1197
1807
|
`function` — Record or replay deterministic game input and state.
|
|
@@ -1207,6 +1817,35 @@ export function replay< TState extends Record<string, unknown> = Record<string,
|
|
|
1207
1817
|
const driver = createReplayDriver(recording, ctx.renderer.domElement);
|
|
1208
1818
|
```
|
|
1209
1819
|
|
|
1820
|
+
### `resetAudioCueLedger`
|
|
1821
|
+
|
|
1822
|
+
`function` — Forgets every recorded cue.
|
|
1823
|
+
|
|
1824
|
+
```ts
|
|
1825
|
+
export function resetAudioCueLedger(): void { … }
|
|
1826
|
+
```
|
|
1827
|
+
|
|
1828
|
+
- **Use when:** clear the recorded audio cue counts between tests so one test cannot read another's plays
|
|
1829
|
+
|
|
1830
|
+
```ts
|
|
1831
|
+
resetAudioCueLedger();
|
|
1832
|
+
```
|
|
1833
|
+
|
|
1834
|
+
### `resetStaticTransforms`
|
|
1835
|
+
|
|
1836
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
1837
|
+
|
|
1838
|
+
```ts
|
|
1839
|
+
export function resetStaticTransforms(): void { … }
|
|
1840
|
+
```
|
|
1841
|
+
|
|
1842
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
1843
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
1844
|
+
|
|
1845
|
+
```ts
|
|
1846
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
1847
|
+
```
|
|
1848
|
+
|
|
1210
1849
|
### `resolveAtmosphereLutResolutions`
|
|
1211
1850
|
|
|
1212
1851
|
`function` — Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
|
|
@@ -1237,6 +1876,25 @@ export function resolveAtmosphereParameters( options: IAtmosphereParameters, ):
|
|
|
1237
1876
|
const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
1238
1877
|
```
|
|
1239
1878
|
|
|
1879
|
+
### `RippleField`
|
|
1880
|
+
|
|
1881
|
+
`class` — Propagate a disturbance across a patch of water surface and let it fade. step is 1/60s or the CFL stability limit for the given resolution and speed, whichever is smaller
|
|
1882
|
+
|
|
1883
|
+
```ts
|
|
1884
|
+
export class RippleField { … }
|
|
1885
|
+
```
|
|
1886
|
+
|
|
1887
|
+
- **Use when:** make a splash or explosion ripple outward across water · show the sea reacting to a bomb, shell, or torpedo hitting it · leave a foam trail behind something moving through water · disturb a water surface the player can see respond · spread and drift foam on a water surface over time
|
|
1888
|
+
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · add its height to an analytic swell, never in place of one · the patch is finite and its rim absorbs; call recenter to keep it over the action · there is no obstacle mask, because a mask is only correct for a body that never moves
|
|
1889
|
+
- **Overrides:** speed, damping, foamHalfLife, current, step and maxSteps tune the solve; the default
|
|
1890
|
+
|
|
1891
|
+
```ts
|
|
1892
|
+
const ripples = new RippleField({ resolution: 128, size: 400 });
|
|
1893
|
+
ripples.impulse(hit.x, hit.z, 6, -40, 0.5);
|
|
1894
|
+
ripples.advance(dt);
|
|
1895
|
+
const lift = ripples.heightAt(boat.x, boat.z);
|
|
1896
|
+
```
|
|
1897
|
+
|
|
1240
1898
|
### `Scene`
|
|
1241
1899
|
|
|
1242
1900
|
`class` — Implement a portable Godot-shaped game scene lifecycle.
|
|
@@ -1245,11 +1903,12 @@ const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRad
|
|
|
1245
1903
|
export abstract class Scene< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, > { … }
|
|
1246
1904
|
```
|
|
1247
1905
|
|
|
1248
|
-
- **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point
|
|
1906
|
+
- **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point · run scene work once per actual world draw, after the frame's last fixed update and before the projection packs
|
|
1249
1907
|
- **Constraints:** scene code must stay portable across web and native
|
|
1250
1908
|
|
|
1251
1909
|
```ts
|
|
1252
1910
|
class Play extends Scene { update(ctx, dt) {} }
|
|
1911
|
+
ctx.beforeRender(() => packBatches()); // cleared on scene change and stop, like ctx.afterPhysics
|
|
1253
1912
|
```
|
|
1254
1913
|
|
|
1255
1914
|
### `ScenePicker`
|
|
@@ -1267,6 +1926,21 @@ export class ScenePicker { … }
|
|
|
1267
1926
|
const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });
|
|
1268
1927
|
```
|
|
1269
1928
|
|
|
1929
|
+
### `sceneWarning`
|
|
1930
|
+
|
|
1931
|
+
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1932
|
+
|
|
1933
|
+
```ts
|
|
1934
|
+
export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, ): ISceneWarning | undefined { … }
|
|
1935
|
+
```
|
|
1936
|
+
|
|
1937
|
+
- **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
|
|
1938
|
+
- **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
|
|
1939
|
+
|
|
1940
|
+
```ts
|
|
1941
|
+
defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
1942
|
+
```
|
|
1943
|
+
|
|
1270
1944
|
### `Scheduler`
|
|
1271
1945
|
|
|
1272
1946
|
`class` — Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
|
|
@@ -1283,6 +1957,37 @@ const door = { y: 0 };
|
|
|
1283
1957
|
await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
|
|
1284
1958
|
```
|
|
1285
1959
|
|
|
1960
|
+
### `setAttitude`
|
|
1961
|
+
|
|
1962
|
+
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
1963
|
+
|
|
1964
|
+
```ts
|
|
1965
|
+
export function setAttitude( state: IFlightState, heading = 0, pitch = 0, roll = 0, ): IFlightQuaternion { … }
|
|
1966
|
+
```
|
|
1967
|
+
|
|
1968
|
+
- **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
|
|
1969
|
+
- **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
|
|
1970
|
+
|
|
1971
|
+
```ts
|
|
1972
|
+
const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
1973
|
+
model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
1974
|
+
```
|
|
1975
|
+
|
|
1976
|
+
### `setSpanRecorder`
|
|
1977
|
+
|
|
1978
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
1979
|
+
|
|
1980
|
+
```ts
|
|
1981
|
+
export function setSpanRecorder(next: SpanRecorder | undefined): void { … }
|
|
1982
|
+
```
|
|
1983
|
+
|
|
1984
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
1985
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
1986
|
+
|
|
1987
|
+
```ts
|
|
1988
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
1989
|
+
```
|
|
1990
|
+
|
|
1286
1991
|
### `SkeletalMesh3D`
|
|
1287
1992
|
|
|
1288
1993
|
`class` — Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting.
|
|
@@ -1381,6 +2086,66 @@ export function solarPositionAt( date: Date | string, latitude: number, longitud
|
|
|
1381
2086
|
const sun = solarPositionAt(new Date(), 49.28, -123.12);
|
|
1382
2087
|
```
|
|
1383
2088
|
|
|
2089
|
+
### `spanNow`
|
|
2090
|
+
|
|
2091
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
2092
|
+
|
|
2093
|
+
```ts
|
|
2094
|
+
export function spanNow(): number { … }
|
|
2095
|
+
```
|
|
2096
|
+
|
|
2097
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
2098
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
2099
|
+
|
|
2100
|
+
```ts
|
|
2101
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
2102
|
+
```
|
|
2103
|
+
|
|
2104
|
+
### `spanRecorder`
|
|
2105
|
+
|
|
2106
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
2107
|
+
|
|
2108
|
+
```ts
|
|
2109
|
+
export function spanRecorder(): SpanRecorder | undefined { … }
|
|
2110
|
+
```
|
|
2111
|
+
|
|
2112
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
2113
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
2114
|
+
|
|
2115
|
+
```ts
|
|
2116
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
2117
|
+
```
|
|
2118
|
+
|
|
2119
|
+
### `SpanRecorder`
|
|
2120
|
+
|
|
2121
|
+
`class` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
2122
|
+
|
|
2123
|
+
```ts
|
|
2124
|
+
export class SpanRecorder { … }
|
|
2125
|
+
```
|
|
2126
|
+
|
|
2127
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
2128
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
2129
|
+
|
|
2130
|
+
```ts
|
|
2131
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
2132
|
+
```
|
|
2133
|
+
|
|
2134
|
+
### `spansRequested`
|
|
2135
|
+
|
|
2136
|
+
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
2137
|
+
|
|
2138
|
+
```ts
|
|
2139
|
+
export function spansRequested(): boolean { … }
|
|
2140
|
+
```
|
|
2141
|
+
|
|
2142
|
+
- **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
|
|
2143
|
+
- **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
2144
|
+
|
|
2145
|
+
```ts
|
|
2146
|
+
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
2147
|
+
```
|
|
2148
|
+
|
|
1384
2149
|
### `SpectralOcean`
|
|
1385
2150
|
|
|
1386
2151
|
`class` — Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
|
|
@@ -1411,6 +2176,21 @@ export class SpriteAnimator3D { … }
|
|
|
1411
2176
|
const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
|
|
1412
2177
|
```
|
|
1413
2178
|
|
|
2179
|
+
### `staticTransformCensus`
|
|
2180
|
+
|
|
2181
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
2182
|
+
|
|
2183
|
+
```ts
|
|
2184
|
+
export function staticTransformCensus(): IStaticTransformCensus { … }
|
|
2185
|
+
```
|
|
2186
|
+
|
|
2187
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
2188
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
2189
|
+
|
|
2190
|
+
```ts
|
|
2191
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
2192
|
+
```
|
|
2193
|
+
|
|
1414
2194
|
### `TracerPool3D`
|
|
1415
2195
|
|
|
1416
2196
|
`class` — Pool travelling bullet-streak meshes for hitscan shots.
|
|
@@ -1427,6 +2207,21 @@ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
|
|
|
1427
2207
|
tracers.spawn(muzzle, shotDirection, hit.distance);
|
|
1428
2208
|
```
|
|
1429
2209
|
|
|
2210
|
+
### `unmarkStatic`
|
|
2211
|
+
|
|
2212
|
+
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
2213
|
+
|
|
2214
|
+
```ts
|
|
2215
|
+
export function unmarkStatic(root: Object3D): void { … }
|
|
2216
|
+
```
|
|
2217
|
+
|
|
2218
|
+
- **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
|
|
2219
|
+
- **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
2220
|
+
|
|
2221
|
+
```ts
|
|
2222
|
+
markStatic(island); invalidateStatic(drawbridge);
|
|
2223
|
+
```
|
|
2224
|
+
|
|
1430
2225
|
### `updateAtmosphereParameters`
|
|
1431
2226
|
|
|
1432
2227
|
`function` — Apply a partial game-owned atmosphere change while preserving validation.
|
|
@@ -1456,6 +2251,39 @@ export function updateClusteredMeshes( root: { … }
|
|
|
1456
2251
|
updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
|
|
1457
2252
|
```
|
|
1458
2253
|
|
|
2254
|
+
### `updateModelLods`
|
|
2255
|
+
|
|
2256
|
+
`function` — Draw a model at the detail its projected geometric error earns, from a chain the asset cook baked. **This is engine-owned, and a game does not call it.** `assets.lod: {}` opts in — the default-on front door opens after qualification — the `model` pass bakes `TN_discrete_lod` into eligible models, the loader registers the reader, and the engine runs the selection every frame before it renders. Each frame the mesh picks the cheapest baked level whose measured error projects to fewer than the resolved pixel budget, taking the camera's own projection, zoom, viewport and a conservative nearest depth into account. Refinement is immediate; coarsening waits for the resolved hysteresis. A mesh with no baked chain draws its full geometry.
|
|
2257
|
+
|
|
2258
|
+
```ts
|
|
2259
|
+
export function updateModelLods( root: { … }
|
|
2260
|
+
```
|
|
2261
|
+
|
|
2262
|
+
- **Use when:** draw a vehicle or hull built from many small meshes at distance without its full triangles · stop a distant model from costing its authored mesh count and triangle count · one source model, right detail by default, no hand-authored LOD files
|
|
2263
|
+
- **Constraints:** the chain is baked by the asset cook; there is no runtime generation and no runtime flag · `assets.lod: false` opts out globally and `assets.lod.overrides` per asset, with no runtime controller installed · only static indexed triangles are eligible; skinned, morphed, alpha-blended or authored-LOD meshes keep full detail · the real gate is measured benefit: a level must save at least `minSaving` (20% default) of its predecessor, and a mesh that cannot is skipped, not forced
|
|
2264
|
+
- **Overrides:** `assets.lod.generation.maxLevels`, `.minTriangles`, `.minTrianglesScope`, `.minSaving` and `.errorTargets` move the bake's ceiling, pre-filter, its scope, its saving rule and its error ladder; `assets.lod.runtime.maxPixelError` and `.hysteresis` move the runtime budget and coarsen band; all by project, preset or asset
|
|
2265
|
+
|
|
2266
|
+
```ts
|
|
2267
|
+
// Nothing to call: the loader returns a mesh with the chain and the engine selects every frame.
|
|
2268
|
+
const hull = await ctx.assets.model("hull.glb");
|
|
2269
|
+
ctx.scene.add(hull.scene);
|
|
2270
|
+
```
|
|
2271
|
+
|
|
2272
|
+
### `validateWorldMatrices`
|
|
2273
|
+
|
|
2274
|
+
`function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
|
|
2275
|
+
|
|
2276
|
+
```ts
|
|
2277
|
+
export function validateWorldMatrices(root: Object3D): { … }
|
|
2278
|
+
```
|
|
2279
|
+
|
|
2280
|
+
- **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
|
|
2281
|
+
- **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
|
|
2282
|
+
|
|
2283
|
+
```ts
|
|
2284
|
+
if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
2285
|
+
```
|
|
2286
|
+
|
|
1459
2287
|
### `velocityTexture`
|
|
1460
2288
|
|
|
1461
2289
|
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
@@ -1538,28 +2366,30 @@ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) })
|
|
|
1538
2366
|
export class WaterSurface3D { … }
|
|
1539
2367
|
```
|
|
1540
2368
|
|
|
1541
|
-
- **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes
|
|
1542
|
-
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world
|
|
2369
|
+
- **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame
|
|
2370
|
+
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only · on a crowded scene the mirrored pass is draw-bound: name reflection.layers or pay twice · reflection.refreshInterval is in presented frames; 1 is every frame, and the default · the mirror plane is level, from level alone; do not parent target to a scaled mesh
|
|
1543
2371
|
|
|
1544
2372
|
```ts
|
|
1545
|
-
const
|
|
2373
|
+
const REFLECTED = 1; // the layer the big silhouettes sit on
|
|
2374
|
+
const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });
|
|
1546
2375
|
material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
|
|
1547
2376
|
```
|
|
1548
2377
|
|
|
1549
2378
|
### `WaveField`
|
|
1550
2379
|
|
|
1551
|
-
`class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
|
|
2380
|
+
`class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph. wanted, and the warp jacobian, every slope and both allocations are skipped
|
|
1552
2381
|
|
|
1553
2382
|
```ts
|
|
1554
2383
|
export class WaveField { … }
|
|
1555
2384
|
```
|
|
1556
2385
|
|
|
1557
2386
|
- **Use when:** float a boat on waves · make water move · find the water surface height at a point
|
|
1558
|
-
- **Constraints:** supply every wave amplitude, wavelength, direction, speed and warp value · call setTime for the default graph clock when the game advances its own time
|
|
2387
|
+
- **Constraints:** supply every wave amplitude, wavelength, direction, speed and warp value · call setTime for the default graph clock when the game advances its own time · sample allocates a result and a normal vector; ask heightAt when only the height is
|
|
1559
2388
|
|
|
1560
2389
|
```ts
|
|
1561
2390
|
const field = new WaveField({ waves });
|
|
1562
2391
|
const { height, normal } = field.sample(x, z, elapsed);
|
|
2392
|
+
const lift = field.heightAt(x, z, elapsed);
|
|
1563
2393
|
```
|
|
1564
2394
|
|
|
1565
2395
|
### `withVelocityContext`
|
|
@@ -1807,8 +2637,8 @@ publishHitRegions({ bridge });
|
|
|
1807
2637
|
export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }
|
|
1808
2638
|
```
|
|
1809
2639
|
|
|
1810
|
-
- **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same
|
|
1811
|
-
- **Constraints:** publishes
|
|
2640
|
+
- **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same coalesced state stream
|
|
2641
|
+
- **Constraints:** publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening
|
|
1812
2642
|
|
|
1813
2643
|
```ts
|
|
1814
2644
|
publishUiState(bridge, game.state);
|
|
@@ -2193,17 +3023,18 @@ const result = evaluateRichPlaytestAssertions(input);
|
|
|
2193
3023
|
|
|
2194
3024
|
### `invalidScenario`
|
|
2195
3025
|
|
|
2196
|
-
`function` —
|
|
3026
|
+
`function` — Construct a named invalid-scenario error without loading or executing a scenario.
|
|
2197
3027
|
|
|
2198
3028
|
```ts
|
|
2199
3029
|
export function invalidScenario(scenarioPath: string, message: string): PlaytestScenarioError { … }
|
|
2200
3030
|
```
|
|
2201
3031
|
|
|
2202
|
-
- **Use when:**
|
|
2203
|
-
- **Constraints:**
|
|
3032
|
+
- **Use when:** construct a validation error for malformed scenario input
|
|
3033
|
+
- **Constraints:** returns an error; the caller must throw it
|
|
2204
3034
|
|
|
2205
3035
|
```ts
|
|
2206
|
-
|
|
3036
|
+
import { invalidScenario } from "@threenative/playtest";
|
|
3037
|
+
throw invalidScenario("smoke.playtest.json", "Expected a non-empty assertion set");
|
|
2207
3038
|
```
|
|
2208
3039
|
|
|
2209
3040
|
### `jsonByteLength`
|
|
@@ -2223,17 +3054,18 @@ assertJsonSafe({ score: 10 });
|
|
|
2223
3054
|
|
|
2224
3055
|
### `loadPlaytestScenario`
|
|
2225
3056
|
|
|
2226
|
-
`function` — Load and validate a scenario
|
|
3057
|
+
`function` — Load and validate a scenario and its referenced evidence before running it.
|
|
2227
3058
|
|
|
2228
3059
|
```ts
|
|
2229
3060
|
export async function loadPlaytestScenario(projectPath: string, scenarioPath: string): Promise<IPlaytestScenario> { … }
|
|
2230
3061
|
```
|
|
2231
3062
|
|
|
2232
|
-
- **Use when:** create a browser or device playtest scenario ·
|
|
2233
|
-
- **Constraints:** unknown scenario keys fail closed
|
|
3063
|
+
- **Use when:** create a browser or device playtest scenario · load a deterministic tick-based playtest scenario
|
|
3064
|
+
- **Constraints:** unknown scenario keys and missing referenced evidence fail closed · loading validates the fixture; use the runner to execute it
|
|
2234
3065
|
|
|
2235
3066
|
```ts
|
|
2236
|
-
|
|
3067
|
+
import { loadPlaytestScenario } from "@threenative/playtest";
|
|
3068
|
+
const scenario = await loadPlaytestScenario(process.cwd(), "playtests/smoke.playtest.json");
|
|
2237
3069
|
```
|
|
2238
3070
|
|
|
2239
3071
|
### `missingPlaytestCapabilities`
|
|
@@ -2326,62 +3158,66 @@ playtestDiagnostic("TN_PLAYTEST_CAPABILITY_MISSING", "body missing", "register r
|
|
|
2326
3158
|
|
|
2327
3159
|
### `PlaytestScenarioError`
|
|
2328
3160
|
|
|
2329
|
-
`class` —
|
|
3161
|
+
`class` — Carry a structured scenario validation diagnostic as an error.
|
|
2330
3162
|
|
|
2331
3163
|
```ts
|
|
2332
3164
|
export class PlaytestScenarioError extends Error { … }
|
|
2333
3165
|
```
|
|
2334
3166
|
|
|
2335
|
-
- **Use when:**
|
|
2336
|
-
- **Constraints:**
|
|
3167
|
+
- **Use when:** catch a structured playtest scenario validation error
|
|
3168
|
+
- **Constraints:** the diagnostic describes a failed load, not a successfully executed scenario
|
|
2337
3169
|
|
|
2338
3170
|
```ts
|
|
2339
|
-
|
|
3171
|
+
import { PlaytestScenarioError } from "@threenative/playtest";
|
|
3172
|
+
const error = new PlaytestScenarioError({ code: "TN_PLAYTEST_SCENARIO_INVALID", message: "Invalid fixture", severity: "error", suggestion: "Fix the fixture" });
|
|
2340
3173
|
```
|
|
2341
3174
|
|
|
2342
3175
|
### `playtestStepHoldTicks`
|
|
2343
3176
|
|
|
2344
|
-
`function` —
|
|
3177
|
+
`function` — Read a validated step's input-hold duration in simulation ticks.
|
|
2345
3178
|
|
|
2346
3179
|
```ts
|
|
2347
3180
|
export function playtestStepHoldTicks(step: IPlaytestStep, fallback = 1): number { … }
|
|
2348
3181
|
```
|
|
2349
3182
|
|
|
2350
|
-
- **Use when:**
|
|
2351
|
-
- **Constraints:**
|
|
3183
|
+
- **Use when:** read the deterministic number of ticks to hold a playtest input
|
|
3184
|
+
- **Constraints:** reads the duration only; the runner advances the simulation
|
|
2352
3185
|
|
|
2353
3186
|
```ts
|
|
2354
|
-
|
|
3187
|
+
import { playtestStepHoldTicks } from "@threenative/playtest";
|
|
3188
|
+
const ticks = playtestStepHoldTicks({ kind: "input", press: "KeyW", holdTicks: 30, release: true });
|
|
2355
3189
|
```
|
|
2356
3190
|
|
|
2357
3191
|
### `playtestStepWaitTicks`
|
|
2358
3192
|
|
|
2359
|
-
`function` —
|
|
3193
|
+
`function` — Read a validated step's no-input duration in simulation ticks.
|
|
2360
3194
|
|
|
2361
3195
|
```ts
|
|
2362
3196
|
export function playtestStepWaitTicks(step: IPlaytestStep): number { … }
|
|
2363
3197
|
```
|
|
2364
3198
|
|
|
2365
|
-
- **Use when:**
|
|
2366
|
-
- **Constraints:**
|
|
3199
|
+
- **Use when:** wait or hold a game for a deterministic number of ticks
|
|
3200
|
+
- **Constraints:** reads the wait duration only; the runner advances the simulation
|
|
2367
3201
|
|
|
2368
3202
|
```ts
|
|
2369
|
-
|
|
3203
|
+
import { playtestStepWaitTicks } from "@threenative/playtest";
|
|
3204
|
+
const ticks = playtestStepWaitTicks({ kind: "wait", waitTicks: 30, release: true });
|
|
2370
3205
|
```
|
|
2371
3206
|
|
|
2372
3207
|
### `rejectUnknownKeys`
|
|
2373
3208
|
|
|
2374
|
-
`function` —
|
|
3209
|
+
`function` — Reject object keys outside the explicitly allowed scenario fields.
|
|
2375
3210
|
|
|
2376
3211
|
```ts
|
|
2377
3212
|
export function rejectUnknownKeys( value: Record<string, unknown>, allowedKeys: readonly string[], scenarioPath: string, objectPath: string, ): void { … }
|
|
2378
3213
|
```
|
|
2379
3214
|
|
|
2380
|
-
- **Use when:**
|
|
2381
|
-
- **Constraints:**
|
|
3215
|
+
- **Use when:** reject an unknown field while validating a scenario object
|
|
3216
|
+
- **Constraints:** throws an invalid-scenario error on the first unknown key
|
|
2382
3217
|
|
|
2383
3218
|
```ts
|
|
2384
|
-
|
|
3219
|
+
import { rejectUnknownKeys } from "@threenative/playtest";
|
|
3220
|
+
rejectUnknownKeys({ name: "smoke" }, ["name"], "smoke.playtest.json", "scenario");
|
|
2385
3221
|
```
|
|
2386
3222
|
|
|
2387
3223
|
### `requiredPlaytestCapabilities`
|
|
@@ -3123,17 +3959,18 @@ const report = await runStandalonePlaytest(options);
|
|
|
3123
3959
|
|
|
3124
3960
|
### `reconcileBrowserPointers`
|
|
3125
3961
|
|
|
3126
|
-
`function` —
|
|
3962
|
+
`function` — Compare pointer snapshots and produce down, move, and up transitions.
|
|
3127
3963
|
|
|
3128
3964
|
```ts
|
|
3129
3965
|
export function reconcileBrowserPointers( previous: ReadonlyMap<number, Required<IPlaytestPointer>>, next: readonly IPlaytestPointer[], ): IBrowserPointerChange[] { … }
|
|
3130
3966
|
```
|
|
3131
3967
|
|
|
3132
|
-
- **Use when:**
|
|
3133
|
-
- **Constraints:**
|
|
3968
|
+
- **Use when:** reconcile pointer contacts into down move and up events
|
|
3969
|
+
- **Constraints:** returns changes only; the caller dispatches them and retains the next snapshot
|
|
3134
3970
|
|
|
3135
3971
|
```ts
|
|
3136
|
-
|
|
3972
|
+
import { reconcileBrowserPointers } from "@threenative/playtest/runner";
|
|
3973
|
+
const changes = reconcileBrowserPointers(new Map(), [{ id: 1, x: 20, y: 30 }]);
|
|
3137
3974
|
```
|
|
3138
3975
|
|
|
3139
3976
|
### `recordToScenario`
|
|
@@ -3168,17 +4005,18 @@ const scenario = recordToScenario(recording);
|
|
|
3168
4005
|
|
|
3169
4006
|
### `resolveBrowserArguments`
|
|
3170
4007
|
|
|
3171
|
-
`function` —
|
|
4008
|
+
`function` — Copy the selected Chromium arguments without silently enabling a rendering recipe.
|
|
3172
4009
|
|
|
3173
4010
|
```ts
|
|
3174
4011
|
export function resolveBrowserArguments(browserArgs: readonly string[] | undefined): string[] { … }
|
|
3175
4012
|
```
|
|
3176
4013
|
|
|
3177
|
-
- **Use when:** run a browser playtest with Vulkan WebGPU
|
|
3178
|
-
- **Constraints:** inspect the adapter
|
|
4014
|
+
- **Use when:** run a browser playtest with Vulkan WebGPU
|
|
4015
|
+
- **Constraints:** pass WEBGPU_BROWSER_ARGS explicitly; undefined selects no additional arguments · inspect the observed adapter before claiming hardware GPU evidence
|
|
3179
4016
|
|
|
3180
4017
|
```ts
|
|
3181
|
-
|
|
4018
|
+
import { resolveBrowserArguments, WEBGPU_BROWSER_ARGS } from "@threenative/playtest/runner";
|
|
4019
|
+
const args = resolveBrowserArguments(WEBGPU_BROWSER_ARGS);
|
|
3182
4020
|
```
|
|
3183
4021
|
|
|
3184
4022
|
### `resolveManagedServerCommand`
|
|
@@ -3318,17 +4156,18 @@ const report = await runStandalonePlaytest(options);
|
|
|
3318
4156
|
|
|
3319
4157
|
### `softwareAdapterName`
|
|
3320
4158
|
|
|
3321
|
-
`function` —
|
|
4159
|
+
`function` — Identify a software renderer in the fields reported by adapter.info.
|
|
3322
4160
|
|
|
3323
4161
|
```ts
|
|
3324
4162
|
export function softwareAdapterName(adapter: Readonly<Record<string, string>> | undefined): string | undefined { … }
|
|
3325
4163
|
```
|
|
3326
4164
|
|
|
3327
|
-
- **Use when:**
|
|
3328
|
-
- **Constraints:**
|
|
4165
|
+
- **Use when:** reject a SwiftShader adapter as evidence
|
|
4166
|
+
- **Constraints:** undefined means no software name was found, not proof of a hardware adapter
|
|
3329
4167
|
|
|
3330
4168
|
```ts
|
|
3331
|
-
|
|
4169
|
+
import { softwareAdapterName } from "@threenative/playtest/runner";
|
|
4170
|
+
const software = softwareAdapterName({ architecture: "swiftshader" });
|
|
3332
4171
|
```
|
|
3333
4172
|
|
|
3334
4173
|
### `substituteManagedPort`
|
|
@@ -3466,6 +4305,23 @@ export function viewportRestoreCommands(): string[][] { … }
|
|
|
3466
4305
|
const adb = discoverAdb(process.env);
|
|
3467
4306
|
```
|
|
3468
4307
|
|
|
4308
|
+
### `withBrowserCapture`
|
|
4309
|
+
|
|
4310
|
+
`function` — Capture a ready ThreeNative game with the runner's display, lock, server and browser ownership.
|
|
4311
|
+
|
|
4312
|
+
```ts
|
|
4313
|
+
export async function withBrowserCapture<T>( config: IStandalonePlaytestConfig, capture: (session: IBrowserCaptureSession) => Promise<T>, signal?: AbortSignal, ): Promise<T> { … }
|
|
4314
|
+
```
|
|
4315
|
+
|
|
4316
|
+
- **Use when:** write a custom browser capture without owning Xvfb or Chromium cleanup
|
|
4317
|
+
- **Constraints:** browser only; requires a scenario and runtime.startup; does not execute scenario steps or assertions · cancellation is checked between resource acquisitions; lock waiting retains its own bounded queue policy · use session.screenshot for nonblank PNGs; private-display captures are not FPS evidence · use threenative-playtest trace --url <url> for slow-frame attribution instead of creating another profiler
|
|
4318
|
+
|
|
4319
|
+
```ts
|
|
4320
|
+
import { parseStandalonePlaytestArgs, withBrowserCapture } from "@threenative/playtest/runner";
|
|
4321
|
+
const config = parseStandalonePlaytestArgs(["--scenario", "playtests/smoke.playtest.json", "--url", "http://127.0.0.1:5173"]);
|
|
4322
|
+
await withBrowserCapture(config, async (session) => session.screenshot("ready"));
|
|
4323
|
+
```
|
|
4324
|
+
|
|
3469
4325
|
### `writeCaptureProvenance`
|
|
3470
4326
|
|
|
3471
4327
|
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
@@ -4094,13 +4950,14 @@ const model = new UEFormatLoader(manager).parse(data);
|
|
|
4094
4950
|
|
|
4095
4951
|
### `DebugOverlay`
|
|
4096
4952
|
|
|
4097
|
-
`function` — Show framework diagnostics while developing a game.
|
|
4953
|
+
`function` — Show framework diagnostics while developing a game. Backtick opens it; the Entities tab lists registered entity fields, and the Geometry tab captures one frame and ranks the objects that submitted its triangles beside their projected size on screen.
|
|
4098
4954
|
|
|
4099
4955
|
```ts
|
|
4100
4956
|
export function DebugOverlay() { … }
|
|
4101
4957
|
```
|
|
4102
4958
|
|
|
4103
|
-
- **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene
|
|
4959
|
+
- **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene · find out which scene object is submitting the frame's triangles · tell a cheap foreground character from an expensive distant prop
|
|
4960
|
+
- **Constraints:** the Geometry tab captures only on an explicit press; nothing is collected while idle · per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden
|
|
4104
4961
|
|
|
4105
4962
|
```ts
|
|
4106
4963
|
<DebugOverlay />
|
|
@@ -4138,7 +4995,7 @@ export function UiLayer( { … }
|
|
|
4138
4995
|
|
|
4139
4996
|
### `useGameState`
|
|
4140
4997
|
|
|
4141
|
-
`function` — Read
|
|
4998
|
+
`function` — Read the game's coalesced frame snapshot from React.
|
|
4142
4999
|
|
|
4143
5000
|
```ts
|
|
4144
5001
|
export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;
|
|
@@ -4181,6 +5038,55 @@ export function useUiState<TState extends object>(): TState | undefined;
|
|
|
4181
5038
|
const score = useUiState<GameState, number>((state) => state.score);
|
|
4182
5039
|
```
|
|
4183
5040
|
|
|
5041
|
+
## `src/game.ts`
|
|
5042
|
+
|
|
5043
|
+
### `renderer.matrixWorld`
|
|
5044
|
+
|
|
5045
|
+
`function` — The per-frame world-matrix walk, on by default as `"visible"`: a hidden subtree — a full-detail body behind a merged stand-in, a hidden LOD level, a parked or hangared model — is not recursed into, so nothing that cannot draw pays a world-matrix multiply. Every visible node is composed exactly as three does, a class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a hidden node that holds bones is still walked. `"all"` restores three's every-node walk.
|
|
5046
|
+
|
|
5047
|
+
```ts
|
|
5048
|
+
renderer.matrixWorld?: "visible" | "all"
|
|
5049
|
+
```
|
|
5050
|
+
|
|
5051
|
+
- **Use when:** updateMatrixWorld and multiplyMatrices are hot in a profile · the per-frame matrix walk is slow with many hidden LOD bodies or paired full/hull models · stop paying for matrices of models nothing can draw · a skinned mesh or camera goes stale because its world matrix was not refreshed · restore three's own full updateMatrixWorld walk · compare how many scene nodes the engine walks per frame
|
|
5052
|
+
- **Constraints:** Unset is the shipping behaviour: `"visible"`, which does not recurse into a hidden subtree. `"all"` visits every node exactly as three's own `updateMatrixWorld` does. · A game that reads a hidden object's `matrixWorld` directly must not rely on the walk reaching it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` or call `object.updateWorldMatrix(true, false)` first. · The walk is the engine's either way, so three's renderer never walks the scene a second time; the count of nodes visited is reported as `matrixWorld` in every `TN_PROJECTION` window. · Bones are never skipped: a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its skeleton's matrices wherever the armature sits.
|
|
5053
|
+
- **Overrides:** renderer.matrixWorld: "all" restores three's every-node walk; the visited count still reports
|
|
5054
|
+
|
|
5055
|
+
```ts
|
|
5056
|
+
renderer: { matrixWorld: "all" } // in threenative.config.ts; omit for the visible-only default
|
|
5057
|
+
```
|
|
5058
|
+
|
|
5059
|
+
### `renderer.minimumProjectedPixels`
|
|
5060
|
+
|
|
5061
|
+
`function` — Do not submit what the render camera cannot resolve. On by default at a conservative 0.5 projected pixel; an object below it is skipped per render camera. Raise the number to cull more, set `false` to leave every object drawn — the count of what was skipped still reports in `TN_PROJECTION`.
|
|
5062
|
+
|
|
5063
|
+
```ts
|
|
5064
|
+
renderer.minimumProjectedPixels?: number | false
|
|
5065
|
+
```
|
|
5066
|
+
|
|
5067
|
+
- **Use when:** my frame is slow with many distant objects · draw count is high but the screen is mostly empty · far away models, aircraft, boats or props cost draw calls but are specks · a large roster or fleet drops the frame rate while barely visible · stop submitting objects smaller than a pixel to the camera · cull by how big something looks to the camera rather than how far it is from the player · tune how aggressively distant objects are skipped · a small object I need disappeared at range
|
|
5068
|
+
- **Constraints:** Unset is the shipping behaviour: the gate runs at 0.5 px. A game that wants the cut a shipped title tuned names 2; `false` leaves every object drawn. · The decision reads the render camera's projection and viewport, not the player's distance — a camera far from the player still culls its own specks. · It writes only `object.visible`, which the projection's batch key ignores; `castShadow`, `layers` and `frustumCulled` are never flipped, because that churns batch grouping. · Shadow casters and objects attached to the render camera are never dropped on the main view alone. Exempt any other object with `alwaysRender`. · Turning the gate off with `false` does not turn its measurement off: `TN_PROJECTION` still reports considered and skipped counts as `cull`.
|
|
5069
|
+
- **Overrides:** alwaysRender(object) keeps one object drawn whatever the render camera resolves · renderer.minimumProjectedPixels: false leaves the scene drawn and keeps the measurement on
|
|
5070
|
+
|
|
5071
|
+
```ts
|
|
5072
|
+
renderer: { minimumProjectedPixels: 2 } // in threenative.config.ts
|
|
5073
|
+
```
|
|
5074
|
+
|
|
5075
|
+
### `renderer.projection`
|
|
5076
|
+
|
|
5077
|
+
`function` — The engine's scene-render projection — an internal mirror that collapses repeated draws — on by default. Set `renderer.projection: false` to decline it.
|
|
5078
|
+
|
|
5079
|
+
```ts
|
|
5080
|
+
renderer.projection?: boolean
|
|
5081
|
+
```
|
|
5082
|
+
|
|
5083
|
+
- **Use when:** the game got slower after the projection engaged · turn off the render projection, batching, or the instanced mirror · draw count fell but frame time did not · a multi-second freeze when the mirror first engages · opt out of an engine render optimizer
|
|
5084
|
+
- **Constraints:** Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it. · An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame. · TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines.
|
|
5085
|
+
|
|
5086
|
+
```ts
|
|
5087
|
+
renderer: { projection: false } // in threenative.config.ts
|
|
5088
|
+
```
|
|
5089
|
+
|
|
4184
5090
|
## `src/render/worldEnvironment.ts`
|
|
4185
5091
|
|
|
4186
5092
|
### `WorldEnvironment`
|