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.
Files changed (58) hide show
  1. package/README.md +23 -1
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/capability-reference.md +972 -66
  4. package/agent-docs/references/finding-assets.md +8 -1
  5. package/agent-docs/references/performance-basics.md +114 -0
  6. package/agent-docs/references/rigging-characters.md +51 -0
  7. package/agent-docs/references/webview-ui.md +3 -2
  8. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
  10. package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
  11. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  12. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  13. package/agent-files/.claude/settings.json +38 -0
  14. package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
  15. package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
  16. package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
  17. package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.codex/hooks.json +40 -0
  19. package/capabilities.json +1344 -88
  20. package/dist/index.d.ts +10 -1
  21. package/dist/index.js +186 -1
  22. package/dist/threenative.js +660 -150
  23. package/package.json +6 -6
  24. package/template-assets/patches/three@0.185.1.patch +179 -19
  25. package/templates/action-rpg/AGENTS.md +5 -5
  26. package/templates/action-rpg/CLAUDE.md +5 -5
  27. package/templates/action-rpg/package.json +8 -8
  28. package/templates/defense/AGENTS.md +5 -5
  29. package/templates/defense/CLAUDE.md +5 -5
  30. package/templates/defense/package.json +8 -8
  31. package/templates/minimal/AGENTS.md +5 -5
  32. package/templates/minimal/CLAUDE.md +5 -5
  33. package/templates/minimal/package.json +7 -7
  34. package/templates/minimal/threenative.config.ts +1 -0
  35. package/templates/platformer/AGENTS.md +5 -5
  36. package/templates/platformer/CLAUDE.md +5 -5
  37. package/templates/platformer/package.json +9 -9
  38. package/templates/puzzle/AGENTS.md +5 -5
  39. package/templates/puzzle/CLAUDE.md +5 -5
  40. package/templates/puzzle/package.json +8 -8
  41. package/templates/racing/AGENTS.md +5 -5
  42. package/templates/racing/CLAUDE.md +5 -5
  43. package/templates/racing/package.json +8 -8
  44. package/templates/runner/AGENTS.md +5 -5
  45. package/templates/runner/CLAUDE.md +5 -5
  46. package/templates/runner/package.json +8 -8
  47. package/templates/sailing/AGENTS.md +6 -6
  48. package/templates/sailing/CLAUDE.md +6 -6
  49. package/templates/sailing/package.json +8 -8
  50. package/templates/shooter/AGENTS.md +5 -5
  51. package/templates/shooter/CLAUDE.md +5 -5
  52. package/templates/shooter/package.json +8 -8
  53. package/templates/starter/AGENTS.md +8 -8
  54. package/templates/starter/CLAUDE.md +8 -8
  55. package/templates/starter/package.json +9 -9
  56. package/templates/starter/playtests/production-readiness.playtest.json +96 -0
  57. package/templates/starter/src/ui/Hud.tsx +2 -2
  58. 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
- ### `FluidField2D`
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` — Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
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 FluidField2D extends Group { … }
1158
+ export class FrameCounters { … }
685
1159
  ```
686
1160
 
687
- - **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
688
- - **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
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 field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
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
- ### `FrameBudget`
1168
+ ### `gearClearance`
698
1169
 
699
- `class` — Read where the frame's milliseconds went, per presented frame, on any platform.
1170
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
700
1171
 
701
1172
  ```ts
702
- export class FrameBudget { … }
1173
+ export function gearClearance(state: IFlightState): number { … }
703
1174
  ```
704
1175
 
705
- - **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay
706
- - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
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
- defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
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 colour. `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. 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. Geometry, placement, colour and the surface it draws with all stay the game's.
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 and stripped to position, so UVs and authored normals do not survive; normals are recomputed from the merged buffer · 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
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, so resolutionScale is the whole cost · the mirror plane is level, from level alone; do not parent target to a scaled mesh
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 surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
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 throttled state stream
1811
- - **Constraints:** publishes at the store's throttled cadence, and not at all with no UI listening
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` — Load and validate a scenario, then control its tick steps.
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:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2203
- - **Constraints:** unknown scenario keys fail closed
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
- const scenario = await loadPlaytestScenario(project, file);
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, then control its tick steps.
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 · wait or hold a game for a deterministic number of ticks
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
- const scenario = await loadPlaytestScenario(project, file);
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` — Load and validate a scenario, then control its tick steps.
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:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2336
- - **Constraints:** unknown scenario keys fail closed
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
- const scenario = await loadPlaytestScenario(project, file);
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` — Load and validate a scenario, then control its tick steps.
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:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2351
- - **Constraints:** unknown scenario keys fail closed
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
- const scenario = await loadPlaytestScenario(project, file);
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` — Load and validate a scenario, then control its tick steps.
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:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2366
- - **Constraints:** unknown scenario keys fail closed
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
- const scenario = await loadPlaytestScenario(project, file);
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` — Load and validate a scenario, then control its tick steps.
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:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2381
- - **Constraints:** unknown scenario keys fail closed
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
- const scenario = await loadPlaytestScenario(project, file);
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` — Select safe Chromium arguments for WebGPU playtests.
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:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3133
- - **Constraints:** inspect the adapter name before claiming GPU proof
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
- const args = resolveBrowserArguments(undefined);
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` — Select safe Chromium arguments for WebGPU playtests.
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 · reject a SwiftShader adapter as evidence
3178
- - **Constraints:** inspect the adapter name before claiming GPU proof
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
- const args = resolveBrowserArguments(undefined);
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` — Select safe Chromium arguments for WebGPU playtests.
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:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3328
- - **Constraints:** inspect the adapter name before claiming GPU proof
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
- const args = resolveBrowserArguments(undefined);
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 throttled game state from React.
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`