create-threenative 0.2.18 → 0.2.21

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 (186) hide show
  1. package/agent-docs/references/assertion-reference.md +1 -1
  2. package/agent-docs/references/capability-reference.md +792 -5
  3. package/agent-docs/references/kit-racing.md +4 -2
  4. package/agent-docs/references/performance-basics.md +2 -1
  5. package/agent-docs/references/terrain-authoring.md +25 -7
  6. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  7. package/dist/index.js +268 -237
  8. package/dist/quality.d.ts +5 -1
  9. package/dist/quality.js +75 -6
  10. package/dist/terrain-kit.js +1 -1
  11. package/dist/threenative.js +7 -5
  12. package/dist/web-engine-post-effects.js +6 -0
  13. package/dist/web-engine-runtime.js +407 -38
  14. package/package.json +6 -6
  15. package/template-assets/assets/floor-fern-0.glb +0 -0
  16. package/template-assets/assets/floor-litter-0.glb +0 -0
  17. package/template-assets/assets/floor-log-0.glb +0 -0
  18. package/template-assets/assets/floor-log-1.glb +0 -0
  19. package/template-assets/assets/floor-stump-0.glb +0 -0
  20. package/template-assets/assets/floor-twig-0.glb +0 -0
  21. package/template-assets/patches/three@0.187.0.patch +108 -21
  22. package/template-assets/quality/eslint.config.js +1 -1
  23. package/templates/action-rpg/package.json +7 -7
  24. package/templates/action-rpg/src/loot/drops.ts +3 -7
  25. package/templates/action-rpg/src/render/camera.ts +2 -2
  26. package/templates/action-rpg/src/render/clouds.ts +3 -1
  27. package/templates/action-rpg/src/render/materials.ts +3 -2
  28. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  29. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  30. package/templates/adventure/AGENTS.md +3 -3
  31. package/templates/adventure/CLAUDE.md +3 -3
  32. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  33. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  34. package/templates/adventure/package.json +7 -7
  35. package/templates/adventure/playtests/grass.playtest.json +61 -0
  36. package/templates/adventure/playtests/performance.playtest.json +1 -1
  37. package/templates/adventure/playtests/survives.playtest.json +2 -2
  38. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  39. package/templates/adventure/src/entities/LockOn.ts +42 -4
  40. package/templates/adventure/src/entities/Warden.ts +12 -3
  41. package/templates/adventure/src/level/Vale.ts +241 -16
  42. package/templates/adventure/src/render/camera.ts +2 -2
  43. package/templates/adventure/src/render/foliage.ts +64 -20
  44. package/templates/adventure/src/render/grass.ts +325 -0
  45. package/templates/adventure/src/render/materials.ts +3 -2
  46. package/templates/adventure/src/render/palette.ts +3 -0
  47. package/templates/adventure/src/render/touch-controls.ts +4 -1
  48. package/templates/adventure/src/scenes/Play.ts +96 -1
  49. package/templates/collectathon/package.json +7 -7
  50. package/templates/collectathon/src/level/Course.ts +2 -7
  51. package/templates/collectathon/src/level/terrain.ts +2 -1
  52. package/templates/collectathon/src/render/camera.ts +2 -2
  53. package/templates/collectathon/src/render/ground.ts +4 -4
  54. package/templates/collectathon/src/render/hero.ts +1 -1
  55. package/templates/collectathon/src/render/materials.ts +0 -1
  56. package/templates/collectathon/src/render/sky.ts +4 -3
  57. package/templates/kart/package.json +6 -6
  58. package/templates/kart/src/entities/Kart.ts +2 -1
  59. package/templates/kart/src/render/course.ts +2 -1
  60. package/templates/kart/src/track/Course.ts +3 -1
  61. package/templates/minimal/package.json +6 -6
  62. package/templates/minimal/src/render/camera.ts +2 -2
  63. package/templates/minimal/src/render/clouds.ts +3 -1
  64. package/templates/minimal/src/render/materials.ts +3 -2
  65. package/templates/minimal/src/render/touch-controls.ts +7 -6
  66. package/templates/platformer/package.json +7 -7
  67. package/templates/platformer/playtests/collect.playtest.json +4 -1
  68. package/templates/platformer/src/level/Stage.ts +2 -6
  69. package/templates/platformer/src/scenes/Play.ts +2 -1
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/puzzle/src/entities/Warden.ts +3 -3
  72. package/templates/puzzle/src/render/camera.ts +2 -2
  73. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  74. package/templates/racing/AGENTS.md +2 -2
  75. package/templates/racing/CLAUDE.md +2 -2
  76. package/templates/racing/CREDITS.md +29 -0
  77. package/templates/racing/assets/engine-loop.wav +0 -0
  78. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  79. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  80. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  81. package/templates/racing/assets/nitro-burst.wav +0 -0
  82. package/templates/racing/assets/tyre-squeal.wav +0 -0
  83. package/templates/racing/package.json +7 -7
  84. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  85. package/templates/racing/playtests/drift.playtest.json +100 -0
  86. package/templates/racing/playtests/hud.playtest.json +117 -0
  87. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  88. package/templates/racing/playtests/nitro.playtest.json +158 -0
  89. package/templates/racing/playtests/outcome.playtest.json +4 -4
  90. package/templates/racing/playtests/performance.playtest.json +1 -1
  91. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  92. package/templates/racing/src/audio/engine.ts +138 -0
  93. package/templates/racing/src/entities/CarBody.ts +83 -10
  94. package/templates/racing/src/entities/Drift.ts +243 -0
  95. package/templates/racing/src/entities/LineDriver.ts +2 -2
  96. package/templates/racing/src/entities/Nitro.ts +72 -0
  97. package/templates/racing/src/entities/RacingCar.ts +86 -21
  98. package/templates/racing/src/entities/Rival.ts +35 -21
  99. package/templates/racing/src/game.ts +6 -0
  100. package/templates/racing/src/gauges.ts +74 -0
  101. package/templates/racing/src/render/camera.ts +29 -4
  102. package/templates/racing/src/render/clouds.ts +3 -1
  103. package/templates/racing/src/render/effects.ts +244 -0
  104. package/templates/racing/src/render/materials.ts +43 -8
  105. package/templates/racing/src/render/shapes.ts +37 -0
  106. package/templates/racing/src/render/skids.ts +84 -0
  107. package/templates/racing/src/render/touch-controls.ts +10 -10
  108. package/templates/racing/src/scenes/Race.ts +277 -25
  109. package/templates/racing/src/state.ts +35 -0
  110. package/templates/racing/src/style.css +3 -0
  111. package/templates/racing/src/track/Ranking.ts +8 -4
  112. package/templates/racing/src/track/Track.ts +132 -58
  113. package/templates/racing/src/track/TrackSector.ts +19 -1
  114. package/templates/racing/src/track/circuit.ts +21 -15
  115. package/templates/racing/src/ui/GameUi.tsx +0 -2
  116. package/templates/racing/src/ui/Hud.tsx +417 -50
  117. package/templates/racing/threenative.config.ts +15 -0
  118. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  119. package/templates/rain/package.json +6 -6
  120. package/templates/rain/src/render/noise-volume.ts +2 -1
  121. package/templates/rain/src/state.ts +3 -1
  122. package/templates/rain/src/ui/GameUi.tsx +1 -1
  123. package/templates/rain/src/ui/automation.ts +10 -8
  124. package/templates/rain/src/ui/tempest.ts +3 -4
  125. package/templates/rts/package.json +6 -6
  126. package/templates/rts/src/sim/terrain.ts +1 -0
  127. package/templates/rts/src/sim/types.ts +1 -0
  128. package/templates/runner/package.json +7 -7
  129. package/templates/runner/src/render/clouds.ts +3 -1
  130. package/templates/runner/src/render/materials.ts +3 -2
  131. package/templates/runner/src/render/touch-controls.ts +7 -6
  132. package/templates/runner/src/scenes/Run.ts +4 -9
  133. package/templates/sailing/package.json +7 -7
  134. package/templates/sailing/src/render/touch-controls.ts +7 -6
  135. package/templates/shooter/package.json +7 -7
  136. package/templates/shooter/src/render/clouds.ts +3 -1
  137. package/templates/snow/package.json +7 -7
  138. package/templates/snow/src/entities/Explorer.ts +6 -12
  139. package/templates/snow/src/render/bootPrint.ts +3 -1
  140. package/templates/snow/src/render/camera.ts +3 -2
  141. package/templates/snow/src/render/scenery.ts +3 -3
  142. package/templates/snow/src/render/touch-controls.ts +7 -6
  143. package/templates/snow/src/render/weather.ts +3 -5
  144. package/templates/snow/src/terrain.ts +2 -1
  145. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  146. package/templates/starter/package.json +7 -7
  147. package/templates/starter/src/entities/Player.ts +10 -2
  148. package/templates/starter/src/render/camera.ts +2 -2
  149. package/templates/starter/src/render/clouds.ts +3 -1
  150. package/templates/starter/src/render/materials.ts +3 -2
  151. package/templates/starter/src/render/touch-controls.ts +7 -6
  152. package/templates/starter/src/scenes/Play.ts +1 -14
  153. package/templates/tower-defense/package.json +7 -7
  154. package/templates/tower-defense/src/render/shapes.ts +1 -2
  155. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  156. package/template-assets/terrain/alpine/assets.json +0 -12
  157. package/template-assets/terrain/alpine/bake.mjs +0 -6
  158. package/template-assets/terrain/alpine/credits.json +0 -164
  159. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  160. package/template-assets/terrain/alpine/recipe.json +0 -119
  161. package/template-assets/terrain/alpine/surface.json +0 -53
  162. package/template-assets/terrain/coastal/assets.json +0 -11
  163. package/template-assets/terrain/coastal/bake.mjs +0 -6
  164. package/template-assets/terrain/coastal/credits.json +0 -117
  165. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  166. package/template-assets/terrain/coastal/recipe.json +0 -113
  167. package/template-assets/terrain/coastal/surface.json +0 -41
  168. package/template-assets/terrain/desert/assets.json +0 -12
  169. package/template-assets/terrain/desert/bake.mjs +0 -6
  170. package/template-assets/terrain/desert/credits.json +0 -164
  171. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  172. package/template-assets/terrain/desert/recipe.json +0 -108
  173. package/template-assets/terrain/desert/surface.json +0 -54
  174. package/template-assets/terrain/forest/assets.json +0 -65
  175. package/template-assets/terrain/forest/bake.mjs +0 -8
  176. package/template-assets/terrain/forest/credits.json +0 -225
  177. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  178. package/template-assets/terrain/forest/recipe.json +0 -350
  179. package/template-assets/terrain/forest/surface.json +0 -79
  180. package/template-assets/terrain/tundra/assets.json +0 -12
  181. package/template-assets/terrain/tundra/bake.mjs +0 -6
  182. package/template-assets/terrain/tundra/credits.json +0 -164
  183. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  184. package/template-assets/terrain/tundra/recipe.json +0 -277
  185. package/template-assets/terrain/tundra/surface.json +0 -54
  186. package/templates/racing/src/ui/Menu.tsx +0 -7
@@ -3,7 +3,7 @@
3
3
 
4
4
  # Capability reference
5
5
 
6
- Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
6
+ Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/procedural-environment`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
7
7
  generated from the doc tags the engine itself compiles, so this page cannot disagree with
8
8
  the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
9
9
  MCP server is available.
@@ -1117,6 +1117,22 @@ import { debugFlag } from "@threenative/core";
1117
1117
  if (debugFlag("freeCam")) camera.flyMode = true;
1118
1118
  ```
1119
1119
 
1120
+ ### `debugValue`
1121
+
1122
+ `function` — Read the text a debug switch was given by the launch, on the same rule as `debugFlag`.
1123
+
1124
+ ```ts
1125
+ export function debugValue(name: string): string | undefined { … }
1126
+ ```
1127
+
1128
+ - **Use when:** read a debug override whose value is not a boolean · override a quality tier or a mode for one run without changing the code
1129
+ - **Constraints:** the same name rule as `debugFlag`: `?quality=` on the web, `TN_DEBUG_QUALITY` on a native launch · a name in camelCase becomes UPPER_SNAKE: `debugValue("quality")` reads `?quality=` or `TN_DEBUG_QUALITY`
1130
+
1131
+ ```ts
1132
+ import { debugValue } from "@threenative/core";
1133
+ const tier = debugValue("quality");
1134
+ ```
1135
+
1120
1136
  ### `defineGame`
1121
1137
 
1122
1138
  `function` — Define the portable game entry shared by web and native.
@@ -1606,6 +1622,25 @@ export class GPUSceneBVH extends Group implements IComputeDriven { … }
1606
1622
  const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
1607
1623
  ```
1608
1624
 
1625
+ ### `GrassField3D`
1626
+
1627
+ `class` — Stream instanced grass in chunks around the camera; the game owns the blade and its TSL material.
1628
+
1629
+ ```ts
1630
+ export class GrassField3D extends Group { … }
1631
+ ```
1632
+
1633
+ - **Use when:** grass that sways and parts around the player · a meadow, lawn or grassy field over terrain that streams around the camera · ground cover grass blades with distance thinning and LOD that does not pop · grass flattened or pushed aside where the player, a creature or a vehicle walks · grow grass on a terrain biome's grass rows with grassFieldFromBiome · Grass that sways and parts around the player across a large terrain. · Stream instanced ground cover in chunks around the camera under a frame budget. · Meadow, lawn or field grass with distance thinning and LOD that does not pop.
1634
+ - **Constraints:** call `update(camera)` once per rendered frame from `ctx.beforeRender`; chunks build nearest first inside `buildBudgetMs` · the material reads `GRASS_FIELD_ATTRIBUTES` and the field's `nodes` uniforms, so its thinning matches the CPU trim · a chunk is built inside 1.3 × the draw distance and discarded past 1.4 ×, so a camera on the edge rebuilds nothing · Call `update(camera)` once per rendered frame, from `ctx.beforeRender`. · Rotating or scaling the field is not supported; translating it is.
1635
+ - **Overrides:** densityScale and cullDistanceScale scale every density and distance at once; prewarm() builds all in range on the next update
1636
+
1637
+ ```ts
1638
+ // the look lives in the kit's src/render/grass.ts
1639
+ const grass = new GrassField3D({ blade: grassBlade(), material: grassMaterial, getHeight: height });
1640
+ ctx.add(grass);
1641
+ ctx.beforeRender(() => { grass.pushers[0]?.set(hero.x, hero.y, hero.z, 1.2); grass.update(ctx.camera); });
1642
+ ```
1643
+
1609
1644
  ### `GroundSnap`
1610
1645
 
1611
1646
  `class` — Keep a rendered model's feet on a surface while preserving an auditable override.
@@ -2562,6 +2597,24 @@ ripples.advance(dt);
2562
2597
  const lift = ripples.heightAt(boat.x, boat.z);
2563
2598
  ```
2564
2599
 
2600
+ ### `ScatterField3D`
2601
+
2602
+ `class` — Stream instanced copies of any baked mesh around a follow point, with distance thinning and levels of detail, from the game's own placement rule.
2603
+
2604
+ ```ts
2605
+ export class ScatterField3D extends Group { … }
2606
+ ```
2607
+
2608
+ - **Use when:** scatter fallen logs, twigs, leaf litter, stones and ferns over a forest floor · stream instanced props of any baked mesh round the player without one draw per prop · place rocks, debris or plants on a heightfield with distance thinning and level of detail
2609
+ - **Constraints:** call `update(follow)` once per rendered frame · `place` runs once per candidate per tile build: return false for paths and clearings · rotating or scaling the field is not supported; translating it is
2610
+ - **Requires:** npm i -D @threenative/procedural-environment for the bake these instances come from
2611
+
2612
+ ```ts
2613
+ const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });
2614
+ ctx.add(floor);
2615
+ ctx.beforeRender(() => floor.update(hero.position));
2616
+ ```
2617
+
2565
2618
  ### `Scene`
2566
2619
 
2567
2620
  `class` — Implement a portable Godot-shaped game scene lifecycle.
@@ -2624,6 +2677,24 @@ const door = { y: 0 };
2624
2677
  await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
2625
2678
  ```
2626
2679
 
2680
+ ### `ScreenProbeGather`
2681
+
2682
+ `class` — Lumen's Screen Probe Gather: one probe per 16 x 16 pixels traces an 8 x 8 octahedron of rays, the probes are filtered into an irradiance octahedron each, and a pixel blends the four nearest probes it can see, instead of every pixel tracing its own rays. A ray that hits on screen returns the lit frame minus the cache along it; a ray that leaves the screen continues through the packed scene up to the radiance cache's cell and reads the cache where it ended, so the light that arrives from off screen is that direction's and not the pixel's mean.
2683
+
2684
+ ```ts
2685
+ export class ScreenProbeGather { … }
2686
+ ```
2687
+
2688
+ - **Use when:** bounce light that reads the room off screen instead of a flat ambient term · global illumination that costs a fraction of one ray per pixel · the light a corner sees from around the wall, which a per-pixel screen trace loses · lumen screen probe gather · lumen final gather
2689
+ - **Constraints:** the owned engine only: on engine: "threejs" the upstream node takes the camera as its fourth argument and has no probes, and gather() refuses · the gather is a delta in E / pi: multiply it by the receiver's diffuse colour (mrt({ diffuseColor })) and add it after the scene pass, and give the scene pass no other indirect diffuse or the light is counted twice · a viewport resize needs a new gather: the probe grid is fixed when it is built · the grid is the cost: downsampleFactor 16 and an 8 x 8 octahedron are Unreal's Epic, 32 and 8 its High · radiance answers in the frame's units (the cache read times the frame's gain), and a trace reads it only where the screen has nothing
2690
+ - **Overrides:** downsampleFactor, tracingOctahedronResolution, cacheCellSize, timedPass and the strength of the composite are game-owned choices
2691
+
2692
+ ```ts
2693
+ const gather = new ScreenProbeGather({ camera, viewport, radiance, trace });
2694
+ const gi = gather.gather(convertToTexture(input), depth(), normalView());
2695
+ const bounce = gather.getGINode().rgb.mul(diffuseColor.rgb);
2696
+ ```
2697
+
2627
2698
  ### `setAttitude`
2628
2699
 
2629
2700
  `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
@@ -2672,6 +2743,24 @@ const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60,
2672
2743
  ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
2673
2744
  ```
2674
2745
 
2746
+ ### `ShortRangeAO`
2747
+
2748
+ `class` — Unreal's Short Range AO: a horizon search of 2 sweeps around the view normal, 3 samples each at the squared fraction of a 32 px screen reach, at full resolution, with a bent normal at Epic. It is the occlusion that runs *with* dynamic global illumination — the contact detail Lumen keeps after the screen probe gather has already answered the wide occlusion — so a gathered frame is not darkened twice by two wide treatments. The result is one texture: `rgb` the bent normal in view space, `a` the share of the hemisphere left open, which multiplies indirect light only.
2749
+
2750
+ ```ts
2751
+ export class ShortRangeAO { … }
2752
+ ```
2753
+
2754
+ - **Use when:** contact shadow at the foot of an object while dynamic GI runs · dark line where a wall meets the floor, without a second wide AO over the gathered light · lumen short range ao
2755
+ - **Constraints:** it replaces GTAO when dynamic GI runs; a tier without GI keeps ambientOcclusion · the occlusion multiplies indirect light only: direct light and emission keep their own occlusion · multi-bounce and its albedo cap belong to the game's composite; Unreal caps the albedo at 0.5 · an authored stage that carries its name must anchor itself (`before: "ssgi"`), because the chain's built-in order names no shortRangeAO
2756
+ - **Overrides:** horizonSearchSliceCount, horizonSearchStepCount, reachPx, bentNormal and intensity are game-owned choices
2757
+
2758
+ ```ts
2759
+ const shortRange = new ShortRangeAO({ camera, viewport: renderer.drawingBufferSize });
2760
+ const contact = shortRange.occlusion(depth(), normalView());
2761
+ const indirect = input.rgb.mul(contact.a);
2762
+ ```
2763
+
2675
2764
  ### `SkeletalMesh3D`
2676
2765
 
2677
2766
  `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. Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: "auto"` default; `updateRate: 1` evaluates every frame, another positive safe integer requests that interval, and `updateRateReport` exposes the effective rate, override status and latest result. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"` listener promotes effective evaluation to 1 and observes only loop events after registration, so skipped pre-registration cycles are not replayed.
@@ -4237,13 +4326,13 @@ const reach = lakeReach(field, { ...lake, margin: 1.12 });
4237
4326
 
4238
4327
  ### `lakeSurfaceGeometry`
4239
4328
 
4240
- `function` — A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with water at a corner get triangles, so the surface does not hover over dry hillside and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.
4329
+ `function` — A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with a corner the seed's water reaches get triangles, so the surface does not hover over dry hillside, a hollow past the basin's rim (a river valley beyond the dam) stays dry instead of standing under a sheet that stops where the reach does, and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.
4241
4330
 
4242
4331
  ```ts
4243
4332
  export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }
4244
4333
  ```
4245
4334
 
4246
- - **Use when:** draw a lake's water surface from the baked level and seed · a lake's drawn water and the swimmer's water disagree
4335
+ - **Use when:** draw a lake's water surface from the baked level and seed · a lake's drawn water and the swimmer's water disagree · lake water ends in a straight edge over a valley past the basin's rim
4247
4336
  - **Constraints:** the lake row and field come from the game's bake; the game's material shades the geometry
4248
4337
 
4249
4338
  ```ts
@@ -4543,7 +4632,7 @@ export class WorldCells extends Group implements IComputeDriven { … }
4543
4632
 
4544
4633
  - **Use when:** stream a large Blender-authored world by cell instead of one huge GLB · keep scattered props and hand-placed chunks resident around a moving player · honour per-asset draw distances and hard streaming budgets without a mid-frame throw
4545
4634
  - **Constraints:** surface is the game's; this class creates no material, colour or geometry · a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first · budgets are hard caps that report pressure instead of over-committing · `whenSpawnReady(position, radius, timeoutMs)` snapshots a fixed region and settles from existing updates or disposal; it does not drive streaming, and `prewarmed` remains the separate draw gate · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · residency and `placementReach` follow `follow`; levels and `maxDistance` are graded from the render camera, as UE picks instance LODs per view; `lodFrom: "follow"`, `?tnLodFromCamera=0` or `TN_LOD_FROM_CAMERA=0` grade from `follow`, reported as `TN_WORLD_MAIN_CULL lodFrom=` · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts · eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
4546
- - **Overrides:** `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
4635
+ - **Overrides:** `hlod: false` keeps source rendering; `partMaterial` gives a part the game's own surface (a swaying tree); ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
4547
4636
 
4548
4637
  ```ts
4549
4638
  const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
@@ -6733,6 +6822,110 @@ export async function bakeWolfToFile( options: IWolfBakeOptions, destination: st
6733
6822
  await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
6734
6823
  ```
6735
6824
 
6825
+ ## `@threenative/procedural-environment`
6826
+
6827
+ ### `bakeCity`
6828
+
6829
+ `function` — Bake an Apex City Kit module to one GLB: a road tile, a building, a street prop, a vehicle, a race kit piece, a block or lot, a sidewalk, transit, a public space, a utility or a decal. The page's own generator and GLTFExporter run headless, so the GLB carries its merged meshes, its materials and textures (Poly Haven CC0 PBR maps and the canvas-drawn signs, liveries and markings) and its road sockets in the root node's extras.
6830
+
6831
+ ```ts
6832
+ export async function bakeCity(options: IBakeCityOptions): Promise<IEnvironmentBake[]> { … }
6833
+ ```
6834
+
6835
+ - **Use when:** generate a modular city street, intersection, roundabout or highway tile as a GLB · a procedural building, storefront, office tower, apartment block, house or warehouse for a city level · street props for a city: traffic signal, streetlight, bus shelter, hydrant, bench, mailbox, dumpster · a race track kit: starting grid, timing gantry, barriers, tire wall, kerbs, pit lane; or a car, van, kart or formula car
6836
+ - **Constraints:** fails closed: an unknown module throws naming the nearest ids; seed is an integer 0 to 4294967295, detail 0 to 2, wet 0 to 100, floors an integer 2 to 12, text at most 24 characters, dressing a boolean · the same options write identical bytes on one Node major and machine (fonts draw the sign text); files are written atomically (temporary file, then rename) · units are metres, +Y up; stock roads fit a 24 m grid, and custom straights and bends export updated socket positions, directions, widths and lane centres in the root node's extras · roadWidth and markings apply to straight and curve; roadLength applies to straight; bendAngle, bendRadius and bendSide apply to curve; roadSurface applies to socketed road modules · bake-time only, so keep it a dev dependency; textures are capped at 1024 px like the page's export
6837
+ - **Requires:** npm i -D @threenative/procedural-environment
6838
+
6839
+ ```ts
6840
+ await bakeCity({ module: "cross", out: "assets/city" });
6841
+ await bakeCity({ module: "curve", bendAngle: 55, bendRadius: 24, bendSide: "left", roadWidth: 12, sidewalk: false, curb: false, out: "assets/city" });
6842
+ await bakeCity({ module: "apartments", seed: 7, floors: 8, out: "assets/city" });
6843
+ ```
6844
+
6845
+ ### `bakeRock`
6846
+
6847
+ `function` — Bake a procedural rock (Outcrop) to GLBs, one per level of detail: a boulder, slab, spire, hoodoo, sea stack, mesa, arch, tileable cliff module or a mountain, weathered and coloured for its biome (moss in a forest, snow in the tundra, sand in the desert, algae below the tide line).
6848
+
6849
+ ```ts
6850
+ export async function bakeRock(options: IBakeRockOptions): Promise<IEnvironmentBake[]> { … }
6851
+ ```
6852
+
6853
+ - **Use when:** generate a procedural rock, boulder or cliff as a GLB for a game level · desert mesa, hoodoo or sandstone arch; coastal sea stack; alpine spire; volcanic basalt columns · a procedural mountain mesh for the horizon, with snow at altitude
6854
+ - **Constraints:** fails closed: an unknown form or biome throws naming the nearest ids, as do unknown traits or surface keys, a non-integer seed, a lod outside 0 to 2 and a detail outside 0 to 1 · the same options write identical bytes; files are written atomically (temporary file, then rename) · each GLB carries POSITION, NORMAL and COLOR_0 (linear RGB, rock and cover already blended) on one `rock` material; units are metres, +Y up, the rock rests on y = 0 · a `cliff` module shows a cut face at each end: bake a run with one seed and `offset: [n * width, 0, 0]`, stand the modules one width apart and bury the two ends of the run · bake-time only, so keep it a dev dependency; the game owns the material and can re-material by the glTF material name `rock`
6855
+ - **Requires:** npm i -D @threenative/procedural-environment
6856
+
6857
+ ```ts
6858
+ await bakeRock({ form: "cliff", biome: "coastal", seed: 7, lods: [0, 1], out: "assets/rocks" });
6859
+ await bakeRock({ form: "boulder", biome: "forest", traits: { weathering: 0.8 }, out: "assets/rocks" });
6860
+ for (const n of [0, 1, 2]) await bakeRock({ form: "cliff", biome: "desert", seed: 7, offset: [n * 10, 0, 0], out: "assets/rocks" }); // three modules of one wall
6861
+ ```
6862
+
6863
+ ### `bakeVegetation`
6864
+
6865
+ `function` — Bake a procedural tree (Arbor) to GLBs, one per level of detail, ready for ctx.assets.model. Each GLB carries the _WIND vertex attribute, COLOR_0 and TEXCOORD_0 and embeds WebP textures: Arbor trees and cover wear a CC0 bark scan and alpha-masked leaves, blades, fronds and needles painted from CC0 leaf scans; forest-kit wood and stone wear a grey CC0 detail scan, and forest-kit cover and leaf litter a grey CC0 blade or leaf scan, each over the kit's COLOR_0 palette.
6866
+
6867
+ ```ts
6868
+ export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IEnvironmentBake[]> { … }
6869
+ ```
6870
+
6871
+ - **Use when:** generate a procedural tree, an oak, pine, spruce, palm or any forest species as a GLB · procedural oak tree GLB with level of detail for a game forest · tree GLB for Unity, Unreal or Godot, with wind weights in a _WIND attribute · a fallen mossy log and leaf litter on the forest floor, with a stump, twigs and boulders · reeds and cattails at a pond edge, or sedge tussocks, clover and seeding grass as cover
6872
+ - **Constraints:** fails closed: an unknown preset throws naming the nearest ids, the seed must be an integer and each lod 0 to 2 · the same preset, seed and lods write identical bytes; files are written atomically (temporary file, then rename) · bake-time only, so keep it a dev dependency; the game owns the look and the sway (a TSL render/wind.ts reading _WIND), because Arbor.three is not shipped · _WIND is vec4 (trunk sway, branch sway, flutter, phase): forest-kit sway is flutter in z, and debris writes all four zero · textures default to "scans" (the bake's `scan` and `leafScan` name them); nine presets with no fitting CC0 leaf scan (ginkgo, palms, banana, joshua, flowers, elephantear) keep Arbor's drawn leaf card; textures: "generated" keeps every generator texture byte for byte · form, leafImage, barkImage and barkNormalImage patch an Arbor preset only; a forest-kit debris or cover preset throws when given any
6873
+ - **Requires:** npm i -D @threenative/procedural-environment
6874
+
6875
+ ```ts
6876
+ await bakeVegetation({ preset: "oak", seed: 7, lods: [0, 1], out: "assets/trees" });
6877
+ await bakeVegetation({ preset: "log", seed: 3, out: "assets/debris" });
6878
+ ```
6879
+
6880
+ ### `environmentBiomes`
6881
+
6882
+ `function` — Every biome: its id, name, the request words that mean it, the rock surface its rocks wear and the element ids that belong there.
6883
+
6884
+ ```ts
6885
+ export function environmentBiomes(): IEnvironmentBiome[] { … }
6886
+ ```
6887
+
6888
+ - **Use when:** which biomes can I bake nature for: forest, desert, jungle, tundra, coast, volcano · what trees, plants, debris and rocks belong in a desert or an alpine biome
6889
+ - **Constraints:** ids match the Strata terrain kits where they overlap (forest, coastal, alpine, desert, tundra)
6890
+ - **Requires:** npm i -D @threenative/procedural-environment
6891
+
6892
+ ```ts
6893
+ environmentBiomes().map((biome) => biome.id);
6894
+ ```
6895
+
6896
+ ### `environmentElements`
6897
+
6898
+ `function` — Find the nature elements to bake, by biome, kind or words: trees, ground cover, forest-floor debris and rock forms (boulders, cliffs, sea stacks, mesas, arches, mountains), each with the exact bake call.
6899
+
6900
+ ```ts
6901
+ export function environmentElements(filter: IEnvironmentFilter = { … }
6902
+ ```
6903
+
6904
+ - **Use when:** what can I bake for a desert, a jungle, a coast, a tundra or a volcanic island · list the rocks, cliffs and mountains for a biome, or every plant that grows there · find a tree or plant by name or latin name, such as pine, palm, cactus or fern
6905
+ - **Constraints:** fails closed: an unknown biome or kind throws naming the nearest ids · biome takes an id or one of its words, so "jungle" finds tropical and "swamp" finds wetland
6906
+ - **Requires:** npm i -D @threenative/procedural-environment
6907
+
6908
+ ```ts
6909
+ environmentElements({ biome: "desert", kind: "rock" }).map((element) => element.bake);
6910
+ environmentElements({ search: "palm" });
6911
+ ```
6912
+
6913
+ ### `vegetationPresets`
6914
+
6915
+ `function` — List every preset a bake can grow: id, name, latin name and kind. Trees and cover come from Arbor; the `debris` rows (log, stump, twig, branch, leaflitter, rock) and the extra cover rows (reeds, tussock, seedgrass, clover, dock, plume) come from forest-kit.
6916
+
6917
+ ```ts
6918
+ export function vegetationPresets(): IVegetationPreset[] { … }
6919
+ ```
6920
+
6921
+ - **Use when:** list the oak, pine, spruce, palm and other tree species a bake can grow · choose a tree species id for bakeVegetation or a terrain arbor: species · what deadwood, leaf litter, boulders, reeds and tussocks can I bake for a forest floor
6922
+ - **Constraints:** ids come from the vendored Arbor and forest-kit presets; trees are kind "tree", grass, ferns and flowers are kind "cover", deadwood, litter and stone are kind "debris"
6923
+ - **Requires:** npm i -D @threenative/procedural-environment
6924
+
6925
+ ```ts
6926
+ vegetationPresets().filter((p) => p.kind === "debris").map((p) => p.id);
6927
+ ```
6928
+
6736
6929
  ## `@threenative/raw-unreal`
6737
6930
 
6738
6931
  ### `createThreeGeometry`
@@ -7433,6 +7626,23 @@ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, n
7433
7626
  const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
7434
7627
  ```
7435
7628
 
7629
+ ### `grassFieldFromBiome`
7630
+
7631
+ `function` — Turns a terrain biome's grass rows and its ground into `GrassField3D` placement options, so a generated or cooked world grows streamed grass with one call. Returns null when the biome has no grass rows: the game draws no field. Each row covers its own slope band (full to `slope[1]`, gone `slopeFalloff` degrees past it), its own height band above `ground.floor` (fading over `heightFalloff` below the ceiling) and stays `waterMargin` above `ground.waterLevel`; the field takes the strongest row at each spot.
7632
+
7633
+ ```ts
7634
+ export function grassFieldFromBiome( biome: Pick<IBiomeSpec, "grass" | "seed">, ground: IGrassGround, ): IGrassFieldPlacement | null { … }
7635
+ ```
7636
+
7637
+ - **Use when:** grow streamed grass on a terrain world's biome grass rows · a Strata or terrain_generate world with a meadow that sways round the player · feed a cooked biome to GrassField3D
7638
+ - **Constraints:** the look stays the game's: pass the result with the kit's `render/grass.ts` blade and material
7639
+ - **Requires:** npm i -D @threenative/terrain
7640
+
7641
+ ```ts
7642
+ const placement = grassFieldFromBiome(biome, { heightAt: (x, z) => field.heightAt(x, z), waterLevel: 0 });
7643
+ if (placement) ctx.add(new GrassField3D({ ...placement, blade: grassBlade(), material: grassMaterial }));
7644
+ ```
7645
+
7436
7646
  ### `landform`
7437
7647
 
7438
7648
  `function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
@@ -7531,6 +7741,22 @@ export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules {
7531
7741
  const rules = orderedScatterRules(spec);
7532
7742
  ```
7533
7743
 
7744
+ ### `paintCanopyCover`
7745
+
7746
+ `function` — Paint each placed tree's crown into a per-vertex canopy grid, so the ground under a stand reads as forest floor rather than open turf. `values` is row-major Z then X, centred on the origin, at the heightfield's own spacing; each vertex keeps the strongest crown that reaches it (0 to 1).
7747
+
7748
+ ```ts
7749
+ export function paintCanopyCover( values: Float32Array, world: { … }
7750
+ ```
7751
+
7752
+ - **Use when:** shade the ground under a baked stand, at bake time or after a placement edit
7753
+ - **Constraints:** `crowns` is metres of crown radius per unit of placement scale, keyed by asset; other assets paint nothing
7754
+ - **Requires:** npm i -D @threenative/terrain
7755
+
7756
+ ```ts
7757
+ paintCanopyCover(values, { size: 512, resolution: 257 }, placements, { spruce: 7 });
7758
+ ```
7759
+
7534
7760
  ### `placeMassif`
7535
7761
 
7536
7762
  `function` — Stands one surveyed mountain behind a world, chosen and posed by a seed: the tile from a list, a point on a bearing and distance, a turn that faces its steepest wall to the centre within 20 degrees, a mirror and a summit height. It stands on the host's own foot (a smooth surface through the host under its border), replacing the host's hills inside its square, and leaves the centre square untouched. Appends one `heightmap` layer; the placement carries the tile-spacing heights a relief map reads.
@@ -7626,6 +7852,22 @@ export function scatterProps( data: IOrderedScatterField, focus: { … }
7626
7852
  const { placements, counts } = scatterProps(data, focus, clearings);
7627
7853
  ```
7628
7854
 
7855
+ ### `skyVisibility`
7856
+
7857
+ `function` — The share of the sky each heightfield vertex sees past the terrain around it: 1 on open ground, lower on a valley floor, at a cliff foot or in a crater. The logic follows TerraForge3D's horizon ambient pass (MIT, `heightfield/ambient/compute.glsl`): march outward along evenly spaced azimuths, keep the highest horizon each one meets, and integrate the cosine-weighted sky above it, which is `cos²` of the horizon angle per azimuth. Only ground that rises over both the vertex's tangent plane and the horizontal occludes, so a straight slope and a steep face over a flat floor stay open: the lighting already counts the slope's own tilt. Heights are row-major Z then X, centred on the origin, as the baked world stores them. Every node marches: a strided march filled bilinearly erred by 0.13 at p99 on the alpine survey's creases. About 0.4 s of CPU a world, so `bakeKit` runs it and the game loads `<world>.sky.bin`.
7858
+
7859
+ ```ts
7860
+ export function skyVisibility( heights: ArrayLike<number>, resolution: number, size: number, { … }
7861
+ ```
7862
+
7863
+ - **Use when:** bake a heightfield's sky occlusion for the ground's ambient light
7864
+ - **Constraints:** offline: about 0.4 s of CPU for a 257² field; bake it, do not run it per frame
7865
+ - **Requires:** npm i -D @threenative/terrain
7866
+
7867
+ ```ts
7868
+ const sky = skyVisibility(heights, 257, 512);
7869
+ ```
7870
+
7629
7871
  ### `slopeAtIndex`
7630
7872
 
7631
7873
  `function` — Slope in degrees at a heightfield sample.
@@ -8285,7 +8527,7 @@ const prepared = await prepareWorldGLTF(input);
8285
8527
  `function` — Bake a copied kit, optionally using the caller's installed world cook.
8286
8528
 
8287
8529
  ```ts
8288
- export async function bakeKit( url: string, { … }
8530
+ export async function bakeKit( url: string, options: IBakeKitOptions | IBakeKitWorldOptions, ): Promise<void> { … }
8289
8531
  ```
8290
8532
 
8291
8533
  - **Use when:** bake a copied terrain starter kit into its offline world package
@@ -8330,6 +8572,211 @@ export async function addStarterWorld<Extra extends { … }
8330
8572
  await addStarterWorld(ctx, follow, spec);
8331
8573
  ```
8332
8574
 
8575
+ ### `addStreamedGround`
8576
+
8577
+ `function` — PRD-790: the ground past the playable square, streamed around the player by `TerrainTiles` out to the collar's reach. Tiles sample the kit's own height function, the surface the square and the collar's vertices stand on, so a tile meets the square and its neighbours with no step. The tile material slides the outermost tile onto the collar's drawn height (`collarMorph`), so at the collar every tile vertex stands on it; `?tnTerrainValidate=1` reports `streamCollarGap`. The largest block of resident tiles around the player is written to the stream each frame: the tiles draw inside it, the collar everywhere else, so a tile that is still building leaves the collar showing, never a hole.
8578
+
8579
+ ```ts
8580
+ export function addStreamedGround(options: IStreamedGroundOptions): { … }
8581
+ ```
8582
+
8583
+ - **Use when:** stream an authored square's ground past its edge, out to a drawn collar
8584
+ - **Constraints:** the game supplies the height, the collar, its curve and the tile material
8585
+ - **Requires:** npm i -D @threenative/terrain @threenative/physics
8586
+
8587
+ ```ts
8588
+ const ground = addStreamedGround({ ctx, name, size, resolution, height, collar, curve, reach, stream, surface, follow, report });
8589
+ ```
8590
+
8591
+ ### `authoredQuaternion`
8592
+
8593
+ `function` — The quaternion a placement's own scatter numbers describe: the normal tilt, then the yaw.
8594
+
8595
+ ```ts
8596
+ export function authoredQuaternion( placement: IPlacement, ): readonly [number, number, number, number] { … }
8597
+ ```
8598
+
8599
+ - **Use when:** compose a placement's authored rotation before grounding it
8600
+ - **Requires:** npm i -D @threenative/terrain
8601
+
8602
+ ```ts
8603
+ const quaternion = authoredQuaternion(placement);
8604
+ ```
8605
+
8606
+ ### `beginScene`
8607
+
8608
+ `function` — Start a scene's view accounting: the player view it opens in, and nothing measured yet.
8609
+
8610
+ ```ts
8611
+ export function beginScene(world: string): void { … }
8612
+ ```
8613
+
8614
+ - **Use when:** start the run's view accounting when a scene enters
8615
+ - **Requires:** npm i -D @threenative/terrain
8616
+
8617
+ ```ts
8618
+ beginScene("forest");
8619
+ ```
8620
+
8621
+ ### `collarArithmeticHeight`
8622
+
8623
+ `function` — The collar triangle under `(x, z)` found by arithmetic alone, as the tile shader finds it: the ring from the ring spacing, the perimeter step from the face the point projects onto, and the triangle from the point's place in the quad. On one face the world point is an affine map of `(scale, share * scale)`, so weights read there are the drawn triangle's own.
8624
+
8625
+ ```ts
8626
+ export function collarArithmeticHeight( collar: HeightfieldCollar, curve: ICollarRingCurve, x: number, z: number, ): number { … }
8627
+ ```
8628
+
8629
+ - **Use when:** answer a collar height on the CPU exactly as its tile shader computes it
8630
+ - **Constraints:** the curve must be the one the collar was built with
8631
+ - **Requires:** npm i -D @threenative/terrain
8632
+
8633
+ ```ts
8634
+ const y = collarArithmeticHeight(collar, { power: 1.65, reach: 2100 }, x, z);
8635
+ ```
8636
+
8637
+ ### `collarDrawnHeight`
8638
+
8639
+ `function` — The collar's drawn height under `(x, z)`; null where there is no collar.
8640
+
8641
+ ```ts
8642
+ export function collarDrawnHeight(collar: HeightfieldCollar, x: number, z: number): number | null { … }
8643
+ ```
8644
+
8645
+ - **Use when:** measure or collide against the triangles a collar actually draws
8646
+ - **Constraints:** reads the collar it is given; never resamples the square or builds a surface
8647
+ - **Requires:** npm i -D @threenative/terrain
8648
+
8649
+ ```ts
8650
+ const y = collarDrawnHeight(collar, x, z);
8651
+ ```
8652
+
8653
+ ### `collarMorph`
8654
+
8655
+ `function` — PRD-790 box 2: the streamed tiles' vertex shift. Only the outermost tile of the square the tiles draw slides onto the collar's drawn height, smoothly over that tile, so at the square's edge every tile vertex stands on the collar; the ground inside keeps the survey's smooth surface. The collar's heights go to the GPU once, as a float texture of rings by perimeter steps.
8656
+
8657
+ ```ts
8658
+ export function collarMorph( collar: HeightfieldCollar, curve: ICollarRingCurve, stream: ICollarStream, band: number, ): Node<"vec3"> { … }
8659
+ ```
8660
+
8661
+ - **Use when:** slide the streamed ground's outer tile onto a drawn collar without a seam
8662
+ - **Constraints:** the curve must be the one the collar was built with; the band is one tile wide
8663
+ - **Requires:** npm i -D @threenative/terrain
8664
+
8665
+ ```ts
8666
+ tile.positionNode = collarMorph(collar, { power: 1.65, reach: 2100 }, stream, 64);
8667
+ ```
8668
+
8669
+ ### `collarSeamGap`
8670
+
8671
+ `function` — PRD-790: where streamed tiles meet the collar. The tiles draw inside the square `(centreX, centreZ, half)` and the collar outside it, so the seam is that square's edge, past the playable square. `gap` is the largest step at the tiles' edge vertices (`spacing` apart), as core measures a tile-to-tile seam; `fold` is the largest step between them, where a fold of the collar's coarser triangles crosses a tile's straight edge.
8672
+
8673
+ ```ts
8674
+ export function collarSeamGap( collar: HeightfieldCollar, height: (x: number, z: number) => number, centreX: number, centreZ: number, half: number, spacing: number, step = 0.1, ): { … }
8675
+ ```
8676
+
8677
+ - **Use when:** prove a streamed ground and its collar meet without a step
8678
+ - **Constraints:** the caller supplies the height the tiles draw; a coarser `step` samples faster
8679
+ - **Requires:** npm i -D @threenative/terrain
8680
+
8681
+ ```ts
8682
+ const { gap, fold } = collarSeamGap(collar, tilesHeight, x, z, 288, 2);
8683
+ ```
8684
+
8685
+ ### `createDiagnosticsState`
8686
+
8687
+ `function` — The state one world's measurements are reported through, with its own name in it. The game spreads this into its own state and adds the look values it also reports; the counters live here. The window groups and the drawn-frame counts are module-level on purpose: `ctx.goto` builds a new scene for the next world, and the numbers a run reports are the run's, not one scene's.
8688
+
8689
+ ```ts
8690
+ export function createDiagnosticsState(world: string) { … }
8691
+ ```
8692
+
8693
+ - **Use when:** start a kit's game state with the measurements every streamed starter world reports
8694
+ - **Constraints:** the world name is the one this state measures; a blank name fails rather than reporting ""
8695
+ - **Requires:** npm i -D @threenative/terrain @threenative/physics
8696
+
8697
+ ```ts
8698
+ const state = { ...createDiagnosticsState("forest"), showcase: false };
8699
+ ```
8700
+
8701
+ ### `createMeasure`
8702
+
8703
+ `function` — The per-world measurement: contacts, travel, edge overshoot, water and the frame facts a run reports.
8704
+
8705
+ ```ts
8706
+ export function createMeasure(options: IMeasureOptions): IMeasure { … }
8707
+ ```
8708
+
8709
+ - **Use when:** measure one played starter world every fixed step
8710
+ - **Constraints:** the game supplies the actor, the player body and the probe fixture; it owns no look
8711
+ - **Requires:** npm i -D @threenative/terrain @threenative/physics
8712
+
8713
+ ```ts
8714
+ const measure = createMeasure({ world, physics: ctx.physics, raycast, actor, player, ...options });
8715
+ ```
8716
+
8717
+ ### `createMorphedHeight`
8718
+
8719
+ `function` — The height a tile vertex stands at once `collarMorph` moved it: the survey inside the band, the collar's arithmetic height at the drawn square's edge. The seam measure reads this.
8720
+
8721
+ ```ts
8722
+ export function createMorphedHeight( collar: HeightfieldCollar, curve: ICollarRingCurve, height: (x: number, z: number) => number, centreX: number, centreZ: number, half: number, band: number, ): (x: number, z: number) => number { … }
8723
+ ```
8724
+
8725
+ - **Use when:** check on the CPU the surface the tile shader draws after its morph
8726
+ - **Constraints:** mirrors `collarMorph`'s weight exactly; both read the same curve and band
8727
+ - **Requires:** npm i -D @threenative/terrain
8728
+
8729
+ ```ts
8730
+ const height = createMorphedHeight(collar, curve, surveyHeight, x, z, 288, 64);
8731
+ ```
8732
+
8733
+ ### `createPlayerRig`
8734
+
8735
+ `function` — The player: the capsule the solver moves, the mannequin that rides it, and the third-person camera that follows with the terrain as its walls. The stepped world is the authority for both the ground the player stands on and the wall the orbit camera cannot pass, which is why both queries mask to the game's ground layer: what the player can walk on. Every appearance value — the mannequin, its clips, the gait speeds, the capsule and the camera framing — comes from the game.
8736
+
8737
+ ```ts
8738
+ export function createPlayerRig(options: IPlayerRigOptions): IPlayerRig { … }
8739
+ ```
8740
+
8741
+ - **Use when:** give a copied starter kit its player capsule, mannequin and follow camera
8742
+ - **Constraints:** the game builds the camera and the wall probe; the package owns only their wiring
8743
+ - **Requires:** npm i -D @threenative/terrain @threenative/physics
8744
+
8745
+ ```ts
8746
+ const rig = createPlayerRig({ at, field, mannequin, clips, gait, camera, probe, ...options });
8747
+ ```
8748
+
8749
+ ### `createRevealProbe`
8750
+
8751
+ `function` — What the loading reveal showed once the curtain lifts: drawn batches, pipelines and impostor readiness, measured against the reveal's own baseline.
8752
+
8753
+ ```ts
8754
+ export function createRevealProbe(options: IRevealProbeOptions): IRevealProbe { … }
8755
+ ```
8756
+
8757
+ - **Use when:** measure whether the spawn drew before the curtain released it
8758
+ - **Requires:** npm i -D @threenative/terrain
8759
+
8760
+ ```ts
8761
+ const reveal = createRevealProbe({ camera, covered, phase, released, ...options });
8762
+ ```
8763
+
8764
+ ### `createSpawnGate`
8765
+
8766
+ `function` — The spawn gate: one deadline, one settlement, one failure report. `WorldCells.whenSpawnReady` is the data authority and each streamed world's `prewarmed` is the draw gate; this gate turns their landing into the loading screen's release, and writes the one console line a failed spawn leaves behind.
8767
+
8768
+ ```ts
8769
+ export function createSpawnGate(ctx: SpawnGateHost, options: ISpawnGateOptions): ISpawnGate { … }
8770
+ ```
8771
+
8772
+ - **Use when:** hold a streamed starter world's loading screen until its spawn has landed
8773
+ - **Constraints:** Every value it reports is supplied by the game; a failure writes one `TN_` line
8774
+ - **Requires:** npm i -D @threenative/terrain
8775
+
8776
+ ```ts
8777
+ const gate = createSpawnGate(ctx, { world, progress, witness, released });
8778
+ ```
8779
+
8333
8780
  ### `editWorldPlacements`
8334
8781
 
8335
8782
  `function` — Apply deterministic startup edits to the decoded placement data before a world is loaded.
@@ -8346,6 +8793,157 @@ export function editWorldPlacements( data: { … }
8346
8793
  const edited = editWorldPlacements(data, { remove: ["scree:candidate:7:41"] }, (x, z) => field.heightAt(x, z));
8347
8794
  ```
8348
8795
 
8796
+ ### `enterView`
8797
+
8798
+ `function` — The camera cycle moved to another view: a keyed group for it, and a fresh measurement.
8799
+
8800
+ ```ts
8801
+ export function enterView(world: string, view: string): { … }
8802
+ ```
8803
+
8804
+ - **Use when:** switch the measured view when the benchmark camera cycle moves
8805
+ - **Requires:** npm i -D @threenative/terrain
8806
+
8807
+ ```ts
8808
+ const { windows } = enterView("forest", "overview");
8809
+ ```
8810
+
8811
+ ### `invalidatePropShadows`
8812
+
8813
+ `function` — Keep WorldCells' changed caster bounds when forwarding to the existing shadow renderer.
8814
+
8815
+ ```ts
8816
+ export function invalidatePropShadows( shadow: { … }
8817
+ ```
8818
+
8819
+ - **Use when:** forward a streamed world's changed caster bounds to the game's shadow renderer
8820
+ - **Requires:** npm i -D @threenative/terrain
8821
+
8822
+ ```ts
8823
+ invalidatePropShadows(ctx.shadows, region);
8824
+ ```
8825
+
8826
+ ### `leaveScene`
8827
+
8828
+ `function` — The scene is gone: nothing is on screen, so no window can belong to a view.
8829
+
8830
+ ```ts
8831
+ export function leaveScene(): void { … }
8832
+ ```
8833
+
8834
+ - **Use when:** stop attributing windows to a view when its scene is left
8835
+ - **Requires:** npm i -D @threenative/terrain
8836
+
8837
+ ```ts
8838
+ leaveScene();
8839
+ ```
8840
+
8841
+ ### `loadCanopy`
8842
+
8843
+ `function` — The canopy weight the ground shader reads, painted from the placements the bake drew.
8844
+
8845
+ ```ts
8846
+ export async function loadCanopy( assets: Pick<IAssetLoader, "resolve">, world: string, ): Promise<Float32Array> { … }
8847
+ ```
8848
+
8849
+ - **Use when:** load the canopy map a streamed world's ground shades with
8850
+ - **Requires:** npm i -D @threenative/terrain
8851
+
8852
+ ```ts
8853
+ const canopy = await loadCanopy(assets, "forest");
8854
+ ```
8855
+
8856
+ ### `loadPropPackage`
8857
+
8858
+ `function` — The baked prop package of one world, fetched as the bake wrote it. The files are the bake's output, not the game's: the manifest names one container, one reach array and one placement-ID list per streamed world, and nothing here derives a placement.
8859
+
8860
+ ```ts
8861
+ export async function loadPropPackage( assets: Pick<IAssetLoader, "resolve">, world: string, ): Promise<IPropPackage> { … }
8862
+ ```
8863
+
8864
+ - **Use when:** load the prop containers a bake wrote for one world
8865
+ - **Requires:** npm i -D @threenative/terrain
8866
+
8867
+ ```ts
8868
+ const props = await loadPropPackage(assets, "forest");
8869
+ ```
8870
+
8871
+ ### `loadSky`
8872
+
8873
+ `function` — The share of the sky each terrain vertex sees past the relief, as `skyVisibility` baked it.
8874
+
8875
+ ```ts
8876
+ export async function loadSky( assets: Pick<IAssetLoader, "resolve">, world: string, ): Promise<Float32Array> { … }
8877
+ ```
8878
+
8879
+ - **Use when:** load the sky-visibility map a streamed world's ground shades with
8880
+ - **Requires:** npm i -D @threenative/terrain
8881
+
8882
+ ```ts
8883
+ const sky = await loadSky(assets, "forest");
8884
+ ```
8885
+
8886
+ ### `observeFrame`
8887
+
8888
+ `function` — One world frame was drawn: count it, and open a fresh GPU sample window if the view or the readiness changed. Called from the render hook, before the camera is placed.
8889
+
8890
+ ```ts
8891
+ export function observeFrame(ctx: ICounterCtx): void { … }
8892
+ ```
8893
+
8894
+ - **Use when:** count a drawn frame and open the next GPU sample window
8895
+ - **Requires:** npm i -D @threenative/terrain
8896
+
8897
+ ```ts
8898
+ ctx.beforeRender(() => observeFrame(ctx));
8899
+ ```
8900
+
8901
+ ### `observeWindow`
8902
+
8903
+ `function` — The frame-budget window closed: latch it, and update the numbers the run reports.
8904
+
8905
+ ```ts
8906
+ export function observeWindow(window: IFrameBudgetWindow): void { … }
8907
+ ```
8908
+
8909
+ - **Use when:** read the engine's own closed frame window into the run's report
8910
+ - **Requires:** npm i -D @threenative/terrain
8911
+
8912
+ ```ts
8913
+ frameBudget: { onWindow: observeWindow }
8914
+ ```
8915
+
8916
+ ### `preparePose`
8917
+
8918
+ `function` — The pose a prop draws at, grounded on the game's own height field. The record's quaternion, when present, replaces the rotation a live placement composes; every step below it — the ground snap, the boulder burial, the flat-footprint sink and the crag base ring — still runs, because the record is a pose and not an override of the pose. A placement with no ground under it fails closed by its own id, so a streamed world cannot silently float.
8919
+
8920
+ ```ts
8921
+ export function preparePose( geometry: BufferGeometry, _material: Material, placement: IPlacement, transform: IPlacementOverride | undefined, groundAt: PropGroundQuery, rules: IPropGroundRules, pose?: IPropPoseOverride, ): IPropPose { … }
8922
+ ```
8923
+
8924
+ - **Use when:** ground one baked prop record on the game's height field before streaming it
8925
+ - **Constraints:** the burial, footprint and base-ring assets are the game's; the package applies them
8926
+ - **Requires:** npm i -D @threenative/terrain
8927
+
8928
+ ```ts
8929
+ const pose = preparePose(foot.geometry, material, record.placement, undefined, groundAt, rules);
8930
+ ```
8931
+
8932
+ ### `preparePropTransform`
8933
+
8934
+ `function` — The pose and the transform an editor edited, prepared together so one write reports both.
8935
+
8936
+ ```ts
8937
+ export function preparePropTransform( instance: IPropInstance, transform: IPlacementOverride | undefined, groundAt: PropGroundQuery, rules: IPropGroundRules, ) { … }
8938
+ ```
8939
+
8940
+ - **Use when:** re-pose one prop the editor edited and keep the transform it reported
8941
+ - **Requires:** npm i -D @threenative/terrain
8942
+
8943
+ ```ts
8944
+ const prepared = preparePropTransform(instance, transform, groundAt, rules);
8945
+ ```
8946
+
8349
8947
  ### `PropColliders`
8350
8948
 
8351
8949
  `class` — Stream caller-specified fixed collision shapes around a moving follow object.
@@ -8362,6 +8960,128 @@ export class PropColliders extends Object3D implements IComputeDriven { … }
8362
8960
  new PropColliders(ctx, follow, manifest, records, shapes, reach, name);
8363
8961
  ```
8364
8962
 
8963
+ ### `propCounts`
8964
+
8965
+ `function` — Records per asset across the package's buckets: what the run report calls the scatter's counts.
8966
+
8967
+ ```ts
8968
+ export function propCounts( pkg: IPropPackage, assetNames: readonly string[], ): Record<string, number> { … }
8969
+ ```
8970
+
8971
+ - **Use when:** report how many records each asset drew, zero included
8972
+ - **Requires:** npm i -D @threenative/terrain
8973
+
8974
+ ```ts
8975
+ const counts = propCounts(pkg, ["spruce", "boulder"]);
8976
+ ```
8977
+
8978
+ ### `propKey`
8979
+
8980
+ `function` — The model a record draws: its asset, its variant, and the shape a non-uniform edit gave it. `WorldCells` names the model through the run the record sits in, so this key is what the container stores. A placement with one uniform scale draws its variant as authored (`spruce:2`); a placement the editor scaled unevenly draws a model of that shape (`spruce:2@1,0.5,0.5`), so the record stays one uniform scale and the picture keeps the edit.
8981
+
8982
+ ```ts
8983
+ export function propKey(placement: IPlacement, variant: number): string { … }
8984
+ ```
8985
+
8986
+ - **Use when:** name the model a baked or live placement record draws
8987
+ - **Requires:** npm i -D @threenative/terrain
8988
+
8989
+ ```ts
8990
+ const key = propKey(placement, 2);
8991
+ ```
8992
+
8993
+ ### `propRatio`
8994
+
8995
+ `function` — The shape `propKey` wrote, so the loader scales the model the record's one scale cannot carry.
8996
+
8997
+ ```ts
8998
+ export function propRatio(key: string): [number, number, number] { … }
8999
+ ```
9000
+
9001
+ - **Use when:** scale a streamed model by the shape its record's single scale cannot carry
9002
+ - **Requires:** npm i -D @threenative/terrain
9003
+
9004
+ ```ts
9005
+ const ratio = propRatio("spruce:2@1,0.5,0.5");
9006
+ ```
9007
+
9008
+ ### `publish`
9009
+
9010
+ `function` — Publish the measurements and the scene's own facts into state, twice per second.
9011
+
9012
+ ```ts
9013
+ export function publish( ctx: { … }
9014
+ ```
9015
+
9016
+ - **Use when:** write the measured view and frame numbers into the game's state
9017
+ - **Requires:** npm i -D @threenative/terrain
9018
+
9019
+ ```ts
9020
+ publish(ctx, { world, worldReady, frames, ...facts });
9021
+ ```
9022
+
9023
+ ### `readPropTransform`
9024
+
9025
+ `function` — The transform an instance's current pose describes.
9026
+
9027
+ ```ts
9028
+ export function readPropTransform(instance: IPropInstance): IPlacementOverride { … }
9029
+ ```
9030
+
9031
+ - **Use when:** read an edited prop's current pose for the scene format
9032
+ - **Requires:** npm i -D @threenative/terrain
9033
+
9034
+ ```ts
9035
+ const transform = readPropTransform(instance);
9036
+ ```
9037
+
9038
+ ### `streamProps`
9039
+
9040
+ `function` — Load the prop worlds, pose every record on the ground, and hand each bucket to `WorldCells`. The passes are short and yield between slices, because the whole point of streaming is that the first frame does not wait for 200 000 records: the records are decoded and grounded in slices, and each bucket loads as its own world.
9041
+
9042
+ ```ts
9043
+ export async function streamProps(options: IPropWorldOptions) { … }
9044
+ ```
9045
+
9046
+ - **Use when:** stream a world's baked prop containers and its live placements through WorldCells
9047
+ - **Constraints:** the variant, reach, bucket, LOD and gate rows are the game's; the package only applies
9048
+ - **Requires:** npm i -D @threenative/terrain
9049
+
9050
+ ```ts
9051
+ const props = await streamProps({ package: propPackage, groundAt, parts, materials, surface,
9052
+ follow, size, whileCurrent, variantOf, reachOf, bucketOf, lodOf, ...options });
9053
+ ```
9054
+
9055
+ ### `withAuthoredPose`
9056
+
9057
+ `function` — A placement as a package record stores it: the authored pose becomes its transform, at one scale. A record holds position, quaternion and one uniform scale, so an edited placement's own transform is folded down to the scale its record carries. The shape that scale removed is `propKey`'s ratio, and the drawable model that ratio names carries it instead.
9058
+
9059
+ ```ts
9060
+ export function withAuthoredPose(placement: IPlacement): IPlacement { … }
9061
+ ```
9062
+
9063
+ - **Use when:** fold an authored placement into the record transform the bake stores
9064
+ - **Requires:** npm i -D @threenative/terrain
9065
+
9066
+ ```ts
9067
+ const record = withAuthoredPose(placement);
9068
+ ```
9069
+
9070
+ ### `writePropTransform`
9071
+
9072
+ `function` — Writes a prepared pose onto the instance, reporting the transform only when the pose changed.
9073
+
9074
+ ```ts
9075
+ export function writePropTransform( instance: IPropInstance, prepared: ReturnType<typeof preparePropTransform>, ): void { … }
9076
+ ```
9077
+
9078
+ - **Use when:** write an edited prop's prepared pose back onto its instance
9079
+ - **Requires:** npm i -D @threenative/terrain
9080
+
9081
+ ```ts
9082
+ writePropTransform(instance, prepared);
9083
+ ```
9084
+
8365
9085
  ## `@threenative/terrain/three`
8366
9086
 
8367
9087
  ### `toGeometry`
@@ -8593,6 +9313,24 @@ export function useUiStateDuringStartup<TState extends object>(options: { … }
8593
9313
  const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);
8594
9314
  ```
8595
9315
 
9316
+ ## `src/assets.ts`
9317
+
9318
+ ### `ctx.assets.memo`
9319
+
9320
+ `function` — Returns what `build` returned the last time this build of the game ran, read back from disk, and calls `build` only when nothing is stored. Use it for seeded work that is the same every run: placement lists, painted sky pixels, terrain heights, a generated stage.
9321
+
9322
+ ```ts
9323
+ ctx.assets.memo<T>(key: string, build: () => T | Promise<T>): Promise<T>
9324
+ ```
9325
+
9326
+ - **Use when:** cache generated geometry between page loads · stop rebuilding the same generated stage on every page load · cache painted sky pixels or baked terrain heights between runs · keep seeded placement work the same every run without recomputing it · make a slow boot fast without shipping a baked asset
9327
+ - **Constraints:** The value is named typed arrays; a map of names to typed arrays is what is stored. · On the dev server and on a native host `build` runs every time, and `TN_ASSET_MEMO` reports why: the cache is a build artifact, not a substitute for authoring. · A new build of the game regenerates: the key alone does not pin a value across a rebuild. · A game that drives a loader outside `defineGame` may call it whenever it likes; the reveal is not waited on.
9328
+ - **Overrides:** TN_ASSET_MEMO reports why a run rebuilt instead of reading the store
9329
+
9330
+ ```ts
9331
+ const { pixels } = await ctx.assets.memo("sky", () => ({ pixels: paintSky() }));
9332
+ ```
9333
+
8596
9334
  ## `src/audio/storm.ts`
8597
9335
 
8598
9336
  ### `createStormAudio`
@@ -8728,6 +9466,55 @@ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
8728
9466
  src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
8729
9467
  ```
8730
9468
 
9469
+ ## `src/scene.ts`
9470
+
9471
+ ### `ctx.after`
9472
+
9473
+ `function` — Runs `callback` once, `delay` seconds of game time later, and returns a handle that cancels it. Game time stops while the game is paused, so a delayed beat does not fire behind a paused frame.
9474
+
9475
+ ```ts
9476
+ ctx.after(delay: number, callback: () => void): ScheduleHandle
9477
+ ```
9478
+
9479
+ - **Use when:** run a callback after a delay · schedule a one-shot timer that pauses with the game · do something a moment later without setTimeout · cancel a pending delayed action when a scene exits
9480
+ - **Constraints:** The delay is game seconds: a paused game does not age it, and a slow frame does not skip it. · `setTimeout` keeps running while the game is paused and after the scene is gone; this does not. · Call the returned handle to cancel: a pending callback holds its scene's closure alive.
9481
+
9482
+ ```ts
9483
+ const spawn = ctx.after(0.4, () => ctx.add(makeWave()));
9484
+ spawn(); // cancels
9485
+ ```
9486
+
9487
+ ### `ctx.beforeRender`
9488
+
9489
+ `function` — Registers work that runs once per actual world render, after the frame's last fixed update and before the projection reconciles and the renderer draws. The last place to change a transform, a uniform or a camera before the frame is presented.
9490
+
9491
+ ```ts
9492
+ ctx.beforeRender(callback: () => void): () => void
9493
+ ```
9494
+
9495
+ - **Use when:** run a callback just before the frame renders · update a camera or a uniform after physics and before the draw · change a transform in the same frame it is seen · run per-render work that must not run on a loader-only frame
9496
+ - **Constraints:** A held, loader-only frame has no world draw and dispatches nothing. · Runs after every fixed update in the frame, so a value it writes is the one drawn. · Returns an unregister function; call it when the object that needed it is gone.
9497
+
9498
+ ```ts
9499
+ const stop = ctx.beforeRender(() => (material.uniforms.time.value = clock.elapsed));
9500
+ // later: stop();
9501
+ ```
9502
+
9503
+ ### `ctx.startup.progress`
9504
+
9505
+ `function` — How much of the start scene has loaded and presented, 0 to 1, for a loading cover's bar. It never falls: a loader whose pending work grows keeps the number it reached rather than jumping backwards.
9506
+
9507
+ ```ts
9508
+ ctx.startup.progress: number
9509
+ ```
9510
+
9511
+ - **Use when:** boot progress bar · show how much of the start scene has loaded · loading screen percentage · a progress bar that never goes backwards · report startup progress while assets stream in
9512
+ - **Constraints:** Never decreases, even when the loader is asked for more work mid-boot. · Reaches 1 only after the first world render has been presented, not when the last byte arrived. · A loading view the engine drew for you already reads it; this is for a cover the game draws itself.
9513
+
9514
+ ```ts
9515
+ const width = `${Math.round(ctx.startup.progress * 100)}%`; // a cover the game draws on ctx.canvasLayer
9516
+ ```
9517
+
8731
9518
  ## `three/addons/tsl/display/BloomNode.js`
8732
9519
 
8733
9520
  ### `bloom`