create-threenative 0.2.15 → 0.2.17

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 (251) hide show
  1. package/agent-docs/kit-mcp.md +10 -0
  2. package/agent-docs/kit-router.md +14 -0
  3. package/agent-docs/kit-stuck.md +7 -0
  4. package/agent-docs/references/capability-reference.md +958 -30
  5. package/agent-docs/references/conventions.md +271 -0
  6. package/agent-docs/references/kit-action-rpg.md +40 -0
  7. package/agent-docs/references/kit-adventure.md +40 -0
  8. package/agent-docs/references/kit-collectathon.md +38 -0
  9. package/agent-docs/references/kit-kart.md +31 -0
  10. package/agent-docs/references/kit-minimal.md +29 -0
  11. package/agent-docs/references/kit-platformer.md +34 -0
  12. package/agent-docs/references/kit-puzzle.md +22 -0
  13. package/agent-docs/references/kit-racing.md +26 -0
  14. package/agent-docs/references/kit-rain.md +31 -0
  15. package/agent-docs/references/kit-rts.md +34 -0
  16. package/agent-docs/references/kit-runner.md +32 -0
  17. package/agent-docs/references/kit-sailing.md +41 -0
  18. package/agent-docs/references/kit-shooter.md +33 -0
  19. package/agent-docs/references/kit-snow.md +33 -0
  20. package/agent-docs/references/kit-starter.md +55 -0
  21. package/agent-docs/references/kit-tower-defense.md +27 -0
  22. package/agent-docs/references/terrain-authoring.md +2 -1
  23. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  24. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  25. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
  26. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  27. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  28. package/agent-files/.claude/settings.json +25 -0
  29. package/agent-files/.codex/hooks.json +18 -1
  30. package/dist/index.js +256 -120
  31. package/dist/terrain-kit.d.ts +7 -0
  32. package/dist/terrain-kit.js +82 -0
  33. package/dist/threenative.js +23 -4
  34. package/dist/web-engine-gltf-loader.js +20 -7
  35. package/dist/web-engine-post-effects.js +34 -4
  36. package/dist/web-engine-runtime.js +6119 -3311
  37. package/package.json +13 -8
  38. package/template-assets/patches/three@0.187.0.patch +2004 -407
  39. package/templates/action-rpg/AGENTS.md +99 -84
  40. package/templates/action-rpg/CLAUDE.md +99 -84
  41. package/templates/action-rpg/kit.json +1 -0
  42. package/templates/action-rpg/package.json +7 -7
  43. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  44. package/templates/action-rpg/src/game.ts +1 -0
  45. package/templates/action-rpg/src/render/atmosphere.ts +5 -16
  46. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  47. package/templates/action-rpg/src/render/quality.ts +3 -1
  48. package/templates/action-rpg/src/scenes/Play.ts +26 -0
  49. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  50. package/templates/action-rpg/threenative.config.ts +0 -3
  51. package/templates/adventure/AGENTS.md +87 -44
  52. package/templates/adventure/CLAUDE.md +87 -44
  53. package/templates/adventure/package.json +7 -7
  54. package/templates/collectathon/AGENTS.md +88 -42
  55. package/templates/collectathon/CLAUDE.md +88 -42
  56. package/templates/collectathon/package.json +7 -7
  57. package/templates/kart/AGENTS.md +82 -42
  58. package/templates/kart/CLAUDE.md +82 -42
  59. package/templates/kart/package.json +6 -6
  60. package/templates/minimal/AGENTS.md +100 -84
  61. package/templates/minimal/CLAUDE.md +100 -84
  62. package/templates/minimal/package.json +6 -6
  63. package/templates/minimal/src/render/atmosphere.ts +5 -16
  64. package/templates/minimal/src/render/gpuSky.ts +4 -7
  65. package/templates/platformer/AGENTS.md +90 -46
  66. package/templates/platformer/CLAUDE.md +90 -46
  67. package/templates/platformer/package.json +7 -7
  68. package/templates/puzzle/AGENTS.md +92 -80
  69. package/templates/puzzle/CLAUDE.md +92 -80
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/racing/AGENTS.md +95 -82
  72. package/templates/racing/CLAUDE.md +95 -82
  73. package/templates/racing/package.json +7 -7
  74. package/templates/racing/src/render/atmosphere.ts +5 -16
  75. package/templates/racing/src/render/gpuSky.ts +4 -7
  76. package/templates/rain/AGENTS.md +92 -84
  77. package/templates/rain/CLAUDE.md +92 -84
  78. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  79. package/templates/rain/package.json +6 -6
  80. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  81. package/templates/rain/src/scenes/Boot.ts +1 -0
  82. package/templates/rain/src/state.ts +7 -0
  83. package/templates/rain/src/ui/GameUi.tsx +7 -1
  84. package/templates/rts/AGENTS.md +96 -85
  85. package/templates/rts/CLAUDE.md +96 -85
  86. package/templates/rts/package.json +6 -6
  87. package/templates/runner/AGENTS.md +92 -80
  88. package/templates/runner/CLAUDE.md +92 -80
  89. package/templates/runner/package.json +7 -7
  90. package/templates/runner/playtests/performance.playtest.json +1 -1
  91. package/templates/runner/src/render/atmosphere.ts +5 -16
  92. package/templates/runner/src/render/gpuSky.ts +4 -7
  93. package/templates/runner/src/render/lighting.ts +53 -11
  94. package/templates/runner/src/scenes/Run.ts +4 -3
  95. package/templates/runner/threenative.config.ts +0 -3
  96. package/templates/sailing/AGENTS.md +91 -79
  97. package/templates/sailing/CLAUDE.md +91 -79
  98. package/templates/sailing/package.json +7 -7
  99. package/templates/sailing/playtests/sails.playtest.json +1 -0
  100. package/templates/sailing/src/render/sky.ts +4 -0
  101. package/templates/sailing/threenative.config.ts +0 -3
  102. package/templates/shooter/AGENTS.md +93 -68
  103. package/templates/shooter/CLAUDE.md +93 -68
  104. package/templates/shooter/package.json +7 -7
  105. package/templates/shooter/src/render/atmosphere.ts +5 -16
  106. package/templates/shooter/src/render/gpuSky.ts +4 -7
  107. package/templates/shooter/src/render/quality.ts +3 -1
  108. package/templates/snow/AGENTS.md +90 -76
  109. package/templates/snow/CLAUDE.md +90 -76
  110. package/templates/snow/package.json +7 -7
  111. package/templates/snow/threenative.config.ts +0 -3
  112. package/templates/starter/AGENTS.md +104 -88
  113. package/templates/starter/CLAUDE.md +104 -88
  114. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  115. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  116. package/templates/starter/package.json +7 -7
  117. package/templates/starter/src/entities/Player.ts +10 -22
  118. package/templates/starter/src/render/atmosphere.ts +5 -16
  119. package/templates/starter/src/render/gpuSky.ts +4 -7
  120. package/templates/starter/src/render/lighting.ts +54 -4
  121. package/templates/starter/src/render/temporalAA.ts +8 -7
  122. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  123. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  124. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  125. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  126. package/templates/starter/src/render/temporalMoire.ts +190 -0
  127. package/templates/starter/src/render/temporalResolve.ts +75 -16
  128. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  129. package/templates/starter/src/scenes/Play.ts +41 -29
  130. package/templates/tower-defense/AGENTS.md +92 -81
  131. package/templates/tower-defense/CLAUDE.md +92 -81
  132. package/templates/tower-defense/package.json +7 -7
  133. package/capabilities.json +0 -9197
  134. package/templates/AGENTS.md +0 -21
  135. package/templates/CLAUDE.md +0 -23
  136. package/templates/action-rpg/.codex/config.toml +0 -23
  137. package/templates/action-rpg/.cursor/mcp.json +0 -38
  138. package/templates/action-rpg/.gemini/settings.json +0 -38
  139. package/templates/action-rpg/.mcp.json +0 -38
  140. package/templates/action-rpg/.vscode/mcp.json +0 -43
  141. package/templates/action-rpg/.zed/settings.json +0 -43
  142. package/templates/action-rpg/opencode.json +0 -49
  143. package/templates/adventure/.codex/config.toml +0 -23
  144. package/templates/adventure/.cursor/mcp.json +0 -38
  145. package/templates/adventure/.gemini/settings.json +0 -38
  146. package/templates/adventure/.mcp.json +0 -38
  147. package/templates/adventure/.vscode/mcp.json +0 -43
  148. package/templates/adventure/.zed/settings.json +0 -43
  149. package/templates/adventure/opencode.json +0 -49
  150. package/templates/collectathon/.codex/config.toml +0 -23
  151. package/templates/collectathon/.cursor/mcp.json +0 -38
  152. package/templates/collectathon/.gemini/settings.json +0 -38
  153. package/templates/collectathon/.mcp.json +0 -38
  154. package/templates/collectathon/.vscode/mcp.json +0 -43
  155. package/templates/collectathon/.zed/settings.json +0 -43
  156. package/templates/collectathon/opencode.json +0 -49
  157. package/templates/kart/.codex/config.toml +0 -23
  158. package/templates/kart/.cursor/mcp.json +0 -38
  159. package/templates/kart/.gemini/settings.json +0 -38
  160. package/templates/kart/.mcp.json +0 -38
  161. package/templates/kart/.vscode/mcp.json +0 -43
  162. package/templates/kart/.zed/settings.json +0 -43
  163. package/templates/kart/opencode.json +0 -49
  164. package/templates/minimal/.codex/config.toml +0 -23
  165. package/templates/minimal/.cursor/mcp.json +0 -38
  166. package/templates/minimal/.gemini/settings.json +0 -38
  167. package/templates/minimal/.mcp.json +0 -38
  168. package/templates/minimal/.vscode/mcp.json +0 -43
  169. package/templates/minimal/.zed/settings.json +0 -43
  170. package/templates/minimal/opencode.json +0 -49
  171. package/templates/platformer/.codex/config.toml +0 -23
  172. package/templates/platformer/.cursor/mcp.json +0 -38
  173. package/templates/platformer/.gemini/settings.json +0 -38
  174. package/templates/platformer/.mcp.json +0 -38
  175. package/templates/platformer/.vscode/mcp.json +0 -43
  176. package/templates/platformer/.zed/settings.json +0 -43
  177. package/templates/platformer/opencode.json +0 -49
  178. package/templates/puzzle/.codex/config.toml +0 -23
  179. package/templates/puzzle/.cursor/mcp.json +0 -38
  180. package/templates/puzzle/.gemini/settings.json +0 -38
  181. package/templates/puzzle/.mcp.json +0 -38
  182. package/templates/puzzle/.vscode/mcp.json +0 -43
  183. package/templates/puzzle/.zed/settings.json +0 -43
  184. package/templates/puzzle/opencode.json +0 -49
  185. package/templates/racing/.codex/config.toml +0 -23
  186. package/templates/racing/.cursor/mcp.json +0 -38
  187. package/templates/racing/.gemini/settings.json +0 -38
  188. package/templates/racing/.mcp.json +0 -38
  189. package/templates/racing/.vscode/mcp.json +0 -43
  190. package/templates/racing/.zed/settings.json +0 -43
  191. package/templates/racing/opencode.json +0 -49
  192. package/templates/rain/.codex/config.toml +0 -23
  193. package/templates/rain/.cursor/mcp.json +0 -38
  194. package/templates/rain/.gemini/settings.json +0 -38
  195. package/templates/rain/.mcp.json +0 -38
  196. package/templates/rain/.vscode/mcp.json +0 -43
  197. package/templates/rain/.zed/settings.json +0 -43
  198. package/templates/rain/opencode.json +0 -49
  199. package/templates/rts/.codex/config.toml +0 -23
  200. package/templates/rts/.cursor/mcp.json +0 -38
  201. package/templates/rts/.gemini/settings.json +0 -38
  202. package/templates/rts/.mcp.json +0 -38
  203. package/templates/rts/.vscode/mcp.json +0 -43
  204. package/templates/rts/.zed/settings.json +0 -43
  205. package/templates/rts/opencode.json +0 -49
  206. package/templates/runner/.codex/config.toml +0 -23
  207. package/templates/runner/.cursor/mcp.json +0 -38
  208. package/templates/runner/.gemini/settings.json +0 -38
  209. package/templates/runner/.mcp.json +0 -38
  210. package/templates/runner/.vscode/mcp.json +0 -43
  211. package/templates/runner/.zed/settings.json +0 -43
  212. package/templates/runner/README.md +0 -43
  213. package/templates/runner/opencode.json +0 -49
  214. package/templates/sailing/.codex/config.toml +0 -23
  215. package/templates/sailing/.cursor/mcp.json +0 -38
  216. package/templates/sailing/.gemini/settings.json +0 -38
  217. package/templates/sailing/.mcp.json +0 -38
  218. package/templates/sailing/.vscode/mcp.json +0 -43
  219. package/templates/sailing/.zed/settings.json +0 -43
  220. package/templates/sailing/README.md +0 -28
  221. package/templates/sailing/opencode.json +0 -49
  222. package/templates/shooter/.codex/config.toml +0 -23
  223. package/templates/shooter/.cursor/mcp.json +0 -38
  224. package/templates/shooter/.gemini/settings.json +0 -38
  225. package/templates/shooter/.mcp.json +0 -38
  226. package/templates/shooter/.vscode/mcp.json +0 -43
  227. package/templates/shooter/.zed/settings.json +0 -43
  228. package/templates/shooter/opencode.json +0 -49
  229. package/templates/snow/.codex/config.toml +0 -23
  230. package/templates/snow/.cursor/mcp.json +0 -38
  231. package/templates/snow/.gemini/settings.json +0 -38
  232. package/templates/snow/.mcp.json +0 -38
  233. package/templates/snow/.vscode/mcp.json +0 -43
  234. package/templates/snow/.zed/settings.json +0 -43
  235. package/templates/snow/README.md +0 -26
  236. package/templates/snow/opencode.json +0 -49
  237. package/templates/starter/.codex/config.toml +0 -23
  238. package/templates/starter/.cursor/mcp.json +0 -38
  239. package/templates/starter/.gemini/settings.json +0 -38
  240. package/templates/starter/.mcp.json +0 -38
  241. package/templates/starter/.vscode/mcp.json +0 -43
  242. package/templates/starter/.zed/settings.json +0 -43
  243. package/templates/starter/opencode.json +0 -49
  244. package/templates/tower-defense/.codex/config.toml +0 -23
  245. package/templates/tower-defense/.cursor/mcp.json +0 -38
  246. package/templates/tower-defense/.gemini/settings.json +0 -38
  247. package/templates/tower-defense/.mcp.json +0 -38
  248. package/templates/tower-defense/.vscode/mcp.json +0 -43
  249. package/templates/tower-defense/.zed/settings.json +0 -43
  250. package/templates/tower-defense/README.md +0 -16
  251. package/templates/tower-defense/opencode.json +0 -49
@@ -70,6 +70,20 @@ export async function compileAssets( options: IAssetCompileOptions = { … }
70
70
  const result = await compileAssets({ source: "assets", output: "public" });
71
71
  ```
72
72
 
73
+ ### `cookTerrainWorld`
74
+
75
+ `function` — Bake evaluated terrain and static species into an instanced GLB and streaming world package.
76
+
77
+ ```ts
78
+ export function cookTerrainWorld( options: IPreparedTerrainWorldOptions, ): Promise< { … }
79
+ ```
80
+
81
+ - **Use when:** bake a terrain world headlessly into a GLB with instanced trees and rocks · generate a forest world for my game
82
+
83
+ ```ts
84
+ await cookTerrainWorld({ state, species, out: "assets/world" });
85
+ ```
86
+
73
87
  ### `dedupeMaterials`
74
88
 
75
89
  `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.
@@ -340,6 +354,21 @@ export function texturePass(options: ITexturePassOptions = { … }
340
354
  const pass = texturePass({ quality: 150 });
341
355
  ```
342
356
 
357
+ ### `thinFoliageCards`
358
+
359
+ `function` — Build a standalone card-thinned foliage mesh, preserving opaque parts and vertex attributes.
360
+
361
+ ```ts
362
+ export function thinFoliageCards(document: Document, keepRatio: number): number { … }
363
+ ```
364
+
365
+ - **Use when:** prepare a far foliage mesh by thinning whole cards instead of triangles
366
+ - **Constraints:** mutates the supplied document; rejects unsupported MASK topology and invalid ratios
367
+
368
+ ```ts
369
+ thinFoliageCards(document, 0.14);
370
+ ```
371
+
343
372
  ### `totalCensus`
344
373
 
345
374
  `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.
@@ -434,7 +463,7 @@ addFoliageBackLight(leaf, backIrradiance);
434
463
 
435
464
  ### `addInSlices`
436
465
 
437
- `function` — Attach hundreds of built objects to the scene in slices, presenting a frame between each.
466
+ `function` — Attach hundreds of built objects to the scene in slices with an 8 ms default budget, presenting a frame between each.
438
467
 
439
468
  ```ts
440
469
  export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }
@@ -1763,6 +1792,21 @@ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TI
1763
1792
  const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
1764
1793
  ```
1765
1794
 
1795
+ ### `lodChainOf`
1796
+
1797
+ `function` — The cooked automatic LOD chain (`TN_discrete_lod`) a loaded geometry carries, or `undefined`. Its levels share the base's vertex attributes and differ only in index, and `errors` are each level's world-unit error in the base's own space. A caller that draws one geometry many times (an instanced batch, a streamed world level) reads the reduced shapes here instead of re-cooking.
1798
+
1799
+ ```ts
1800
+ export function lodChainOf(geometry: BufferGeometry): ILodChain | undefined { … }
1801
+ ```
1802
+
1803
+ - **Use when:** draw a cooked reduced level of a model in an instanced batch or streamed world level
1804
+ - **Constraints:** a geometry the loader built no chain for returns undefined
1805
+
1806
+ ```ts
1807
+ const chain = lodChainOf(baseGeometryOf(mesh)); const far = chain?.levels.at(-1);
1808
+ ```
1809
+
1766
1810
  ### `lodPixelScale`
1767
1811
 
1768
1812
  `function` — The screen pixels one world unit covers at `depth` for this camera and viewport. Perspective divides the projected scale by the depth; orthographic has no depth term and uses the frustum height instead. This is the number a level of detail is chosen against: multiply a level's world-space error by it and you have the on-screen error a player can see, which is the comparison `updateModelLods` makes from the baked chain.
@@ -2837,6 +2881,21 @@ export class SurfaceLights { … }
2837
2881
  const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
2838
2882
  ```
2839
2883
 
2884
+ ### `thinCards`
2885
+
2886
+ `function` — A far level for a card mesh (needle or leaf quads): keep a share of its cards and grow each kept card about its own centre, so the crown holds its total surface area, as Unreal's Nanite "Preserve Area" foliage does. A simplifier cannot reduce disconnected cards, so the cooked chain leaves them at full count.
2887
+
2888
+ ```ts
2889
+ export function thinCards(geometry: BufferGeometry, keep: number): BufferGeometry { … }
2890
+ ```
2891
+
2892
+ - **Use when:** far trees draw too many alpha-tested needle or leaf card triangles
2893
+ - **Constraints:** the geometry must be indexed and carry no material groups, else it throws · keep is in (0, 1]; a share that drops nothing returns the same geometry · the choice is deterministic, and the source geometry is left untouched
2894
+
2895
+ ```ts
2896
+ const far = thinCards(needles.geometry, 0.4); // 40% of the cards, same area
2897
+ ```
2898
+
2840
2899
  ### `TracedReflections`
2841
2900
 
2842
2901
  `class` — Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material. The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
@@ -3028,9 +3087,9 @@ tracker.commit(scene);
3028
3087
  export class VirtualShadowNode extends ShadowBaseNode { … }
3029
3088
  ```
3030
3089
 
3031
- - **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
3090
+ - **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves · shadow edges, tree lighting or level sharpness change while a third-person camera turns around its hero
3032
3091
  - **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left · `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region · call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
3033
- - **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
3092
+ - **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · setFocus(point) centres every window on a subject (a third-person hero) instead of the eye, so an orbiting eye moves no shadow; setFocus(undefined) hands them back · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
3034
3093
 
3035
3094
  ```ts
3036
3095
  const sun = new DirectionalLight(0xffffff, 3);
@@ -3310,6 +3369,270 @@ const root = createCssUiRoot();
3310
3369
  root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
3311
3370
  ```
3312
3371
 
3372
+ ## `@threenative/core/spells`
3373
+
3374
+ ### `CastPool`
3375
+
3376
+ `class` — Step a spell's timeline: charge, release, travel, impact, linger, done.
3377
+
3378
+ ```ts
3379
+ export class CastPool { … }
3380
+ ```
3381
+
3382
+ - **Use when:** a fireball or a lightning bolt that charges, flies, lands and lingers · several spells mid-flight, with no allocation per cast
3383
+ - **Constraints:** the pool is fixed and recycles the cast alive longest; it never grows · a ball that has passed its target lands on the target, however late the frame notices
3384
+ - **Overrides:** timing, shape, speed and radius come from the spell; a cast may override shape and seed
3385
+
3386
+ ```ts
3387
+ const casts = new CastPool(world);
3388
+ casts.cast(fireball, target, { from: hand });
3389
+ casts.update(dt);
3390
+ ```
3391
+
3392
+ ### `createAegis`
3393
+
3394
+ `function` — A ward around the caster: it forms, holds, and breaks outward when it expires.
3395
+
3396
+ ```ts
3397
+ export function createAegis(world: SpellWorld, overrides: IFireSpellOverrides = { … }
3398
+ ```
3399
+
3400
+ - **Use when:** a shield spell a player casts on themselves · a magic barrier that forms around the caster · make a protective bubble spell · a defensive bubble that flashes when it breaks
3401
+ - **Constraints:** every colour, size, count and timing is a named override on the call
3402
+ - **Overrides:** core, highlight, charge, impact, linger, radius, light · core, highlight, charge, impact, linger, radius, light, shake
3403
+
3404
+ ```ts
3405
+ const aegis = createAegis(world);
3406
+ casts.cast(aegis, world.focus);
3407
+ ```
3408
+
3409
+ ### `createArcaneBarrage`
3410
+
3411
+ `function` — A volley of arcane missiles: fast, precise, and each one pops on arrival.
3412
+
3413
+ ```ts
3414
+ export function createArcaneBarrage(world: SpellWorld, overrides: IFireSpellOverrides = { … }
3415
+ ```
3416
+
3417
+ - **Use when:** an arcane missile spell that fires projectiles at a target · a magic barrage a mage class spams · a magic missile spell · make an arcane bolt spell · an arcane missile spell that fires several projectiles at a target · a pink energy bolt with a short charge
3418
+ - **Constraints:** every colour, size, count and timing is a named override on the call
3419
+ - **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, light
3420
+
3421
+ ```ts
3422
+ const barrage = createArcaneBarrage(world);
3423
+ casts.cast(barrage, target);
3424
+ ```
3425
+
3426
+ ### `createFireball`
3427
+
3428
+ `function` — A ball of fire that charges, crosses the room and leaves the floor burning.
3429
+
3430
+ ```ts
3431
+ export function createFireball(world: SpellWorld, overrides: IFireSpellOverrides = { … }
3432
+ ```
3433
+
3434
+ - **Use when:** a fireball spell the player casts at an enemy · a burning projectile that explodes and scorches the ground · a wizard's fire attack with a wind-up, a flight and an aftermath · make a fireball · a fireball spell a player casts at an enemy
3435
+ - **Constraints:** every colour, size, count and timing is a named override on the call · the first cast costs what the hundredth does: nothing is built at cast time · the stock look ships as the default, and no override rebuilds a pipeline
3436
+ - **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch
3437
+
3438
+ ```ts
3439
+ const fireball = createFireball(world);
3440
+ casts.cast(fireball, target);
3441
+ ```
3442
+
3443
+ ### `createGlacialSpike`
3444
+
3445
+ `function` — A shard of ice that flies flat and fast, and freezes the ground it breaks on.
3446
+
3447
+ ```ts
3448
+ export function createGlacialSpike(world: SpellWorld, overrides: IFireSpellOverrides = { … }
3449
+ ```
3450
+
3451
+ - **Use when:** an ice spike spell that flies at a target and shatters · a freezing projectile that leaves frost on the floor · make an ice spell · a cold spell with a charge, a flight and a lingering chill
3452
+ - **Constraints:** every colour, size, count and timing is a named override on the call
3453
+ - **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, trail, light
3454
+
3455
+ ```ts
3456
+ const spike = createGlacialSpike(world);
3457
+ casts.cast(spike, target);
3458
+ ```
3459
+
3460
+ ### `createInferno`
3461
+
3462
+ `function` — A pillar of fire that erupts where it lands and keeps burning.
3463
+
3464
+ ```ts
3465
+ export function createInferno(world: SpellWorld, overrides: IFireSpellOverrides = { … }
3466
+ ```
3467
+
3468
+ - **Use when:** a fire area spell that erupts at a point and burns there · an inferno column a boss drops on the arena · make a sustained fire area spell · a sustained flame that scorches the ground for seconds
3469
+ - **Constraints:** every colour, size, count and timing is a named override on the call
3470
+ - **Overrides:** core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch
3471
+
3472
+ ```ts
3473
+ const inferno = createInferno(world);
3474
+ casts.cast(inferno, target);
3475
+ ```
3476
+
3477
+ ### `createSpell`
3478
+
3479
+ `function` — Build a spell from a recipe: four beats, a tint, and the numbers between them.
3480
+
3481
+ ```ts
3482
+ export function createSpell(world: SpellWorld, recipe: ISpellRecipe): ISpell { … }
3483
+ ```
3484
+
3485
+ - **Use when:** author a spell the catalog does not cover, out of the same beats
3486
+ - **Constraints:** read the world through SpellWorld only, so a game can swap the scene and the floor
3487
+
3488
+ ```ts
3489
+ const spell = createSpell(world, recipe);
3490
+ ```
3491
+
3492
+ ### `createThunderstrike`
3493
+
3494
+ `function` — A bolt out of the sky: it charges, strikes the point instantly, and the ground remembers it.
3495
+
3496
+ ```ts
3497
+ export function createThunderstrike(world: SpellWorld, overrides: IFireSpellOverrides = { … }
3498
+ ```
3499
+
3500
+ - **Use when:** a lightning strike spell that hits a point immediately · a thunderbolt with a wind-up and a burnt mark where it lands · make a lightning spell · an electrical spell with a column of light from above
3501
+ - **Constraints:** every colour, size, count and timing is a named override on the call
3502
+ - **Overrides:** core, highlight, charge, impact, linger, radius, light, shake, scorch
3503
+
3504
+ ```ts
3505
+ const bolt = createThunderstrike(world);
3506
+ casts.cast(bolt, target);
3507
+ ```
3508
+
3509
+ ### `ParticleKindTable`
3510
+
3511
+ `class` — Tune what a particle kind does, as data rather than a shader.
3512
+
3513
+ ```ts
3514
+ export class ParticleKindTable { … }
3515
+ ```
3516
+
3517
+ - **Use when:** retune a spell's particles at run time from a settings screen · change how long, how fast or how heavy a kind of particle is without a new pipeline
3518
+ - **Constraints:** set writes uniforms; no kernel, material or pipeline is rebuilt · a table knows only the kinds it was asked for, so an unused kind costs nothing
3519
+ - **Overrides:** lifetime, size, speed, cone, gravity, drag, buoyancy, alpha, colour and highlight
3520
+
3521
+ ```ts
3522
+ const kinds = new ParticleKindTable(["flame", "smoke"]);
3523
+ kinds.set("flame", { lifetime: [0.3, 0.6], colour: [0.4, 0.8, 1] });
3524
+ ```
3525
+
3526
+ ### `ReactionField`
3527
+
3528
+ `class` — The marks a spell leaves on the floor: heat, char, wet, frost, crack and glow.
3529
+
3530
+ ```ts
3531
+ export class ReactionField { … }
3532
+ ```
3533
+
3534
+ - **Use when:** a fireball impact that leaves a scorch and fades over time · ice that melts where lightning spread, or a lava geyser's crack
3535
+ - **Constraints:** it draws nothing; the game decides what a mark looks like · the patch is finite and every channel decays on its own half-life
3536
+ - **Overrides:** halfLife, resolution and size tune the patch; pattern, radius, seed and angle set each mark
3537
+
3538
+ ```ts
3539
+ field.splat({ heat: 1, char: 0.6, radius: 2.5, x: hit.x, z: hit.z });
3540
+ field.update(dt);
3541
+ ```
3542
+
3543
+ ### `SpellLights`
3544
+
3545
+ `class` — A fixed pool of spell lights, created once at zero intensity.
3546
+
3547
+ ```ts
3548
+ export class SpellLights { … }
3549
+ ```
3550
+
3551
+ - **Use when:** a spell impact that glows without changing the light count · a charge glow or a falling meteor lighting what it passes
3552
+ - **Constraints:** the whole pool exists before the first cast; a cast changes intensity, never the list · flash returns undefined when the pool is busy; a spell carries on without one
3553
+ - **Overrides:** count is the pool size; each flash supplies position, colour, intensity, range and seconds
3554
+
3555
+ ```ts
3556
+ lights.flash({ x, y, z, color, intensity: 40, range: 12, seconds: 0.35 });
3557
+ ```
3558
+
3559
+ ### `SpellWorld`
3560
+
3561
+ `class` — Everything a spell may touch: the scene, the floor, the light pool, the surface field, one shake and one flash limiter.
3562
+
3563
+ ```ts
3564
+ export class SpellWorld implements ICastEnvironment { … }
3565
+ ```
3566
+
3567
+ - **Use when:** cast an engine spell without passing a scene into every call · honour an accessibility setting that limits flashing
3568
+ - **Constraints:** damage, mana, cooldowns and who the target is stay in the game · with reducedFlashes on, a fourth flash inside one second is refused, never dimmed
3569
+ - **Overrides:** groundAt, castSlots, lightCount, reaction, shake and reducedFlashes are named options
3570
+
3571
+ ```ts
3572
+ const world = new SpellWorld({ scene, groundAt });
3573
+ const casts = new CastPool(world);
3574
+ ```
3575
+
3576
+ ## `@threenative/core/spells/ultra`
3577
+
3578
+ ### `bakeNoise`
3579
+
3580
+ `function` — CPU bake of the Ultra Elements 3D noise, curl and blackbody textures that every spell volume samples.
3581
+
3582
+ ```ts
3583
+ export function bakeNoise( { … }
3584
+ ```
3585
+
3586
+ - **Use when:** the noise and blackbody textures an Ultra Elements spell needs before it first draws
3587
+ - **Constraints:** costs about 0.6 s at 64^3 and about 5 s at 128^3 on the main thread; bake once at load
3588
+
3589
+ ```ts
3590
+ bakeNoise({ noiseSize: 64 }); // once at load, before createFx draws
3591
+ ```
3592
+
3593
+ ### `createFx`
3594
+
3595
+ `function` — The shared Ultra Elements spell world: casts, volumes, spell lights and the per-frame CPU tick. Add `fx.scenes.fx` to the scene, `addSpell` each ported spell, call `renderFrame(dt)` each frame.
3596
+
3597
+ ```ts
3598
+ export function createFx(o: IFxOptions) { … }
3599
+ ```
3600
+
3601
+ - **Use when:** an Ultra Elements spell such as the raymarched teardrop Fireball cast at a target · a volumetric fire spell drawn through the Three.js TSL node API on WebGPU
3602
+ - **Constraints:** call bakeNoise first: the volume shaders sample its noise, curl and blackbody textures
3603
+
3604
+ ```ts
3605
+ const ultra = createFx({ camera, size: () => ({ width: innerWidth, height: innerHeight }), seed: 777 }); const fireball = ultra.addSpell(fire); scene.add(ultra.fx.scenes.fx);
3606
+ ```
3607
+
3608
+ ### `groundShade`
3609
+
3610
+ `function` — The Ultra Elements arena floor's response to the ground field and spell impacts (scorch, char, wet, glowing hot ground) as nodes for a game's own floor material: `color`, `roughness`, `metalness`, `emissive` from the floor's own surface at a world position.
3611
+
3612
+ ```ts
3613
+ export function groundShade(wp: V3, surface: IGroundSurface) { … }
3614
+ ```
3615
+
3616
+ - **Use when:** a floor that shows the Fireball's scorch and hot ground cooling over seconds
3617
+
3618
+ ```ts
3619
+ const shade = groundShade(positionWorld, { albedo, rough: float(0.85), metal: float(0) }); floor.colorNode = vec4(shade.color, 1);
3620
+ ```
3621
+
3622
+ ### `Particles`
3623
+
3624
+ `class` — The Ultra Elements GPU particle system behind `fx.particles`: a spell's kinds, emitters and field emitters.
3625
+
3626
+ ```ts
3627
+ export class Particles { … }
3628
+ ```
3629
+
3630
+ - **Use when:** the flames, embers, sparks, smoke and debris an Ultra Elements spell emits as it charges, flies and hits
3631
+
3632
+ ```ts
3633
+ const flames = ultra.fx.particles.emitter("fire.flame"); // ultra from createFx
3634
+ ```
3635
+
3313
3636
  ## `@threenative/core/ui-layer`
3314
3637
 
3315
3638
  ### `connectUiBridge`
@@ -3434,6 +3757,53 @@ const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url
3434
3757
 
3435
3758
  ## `@threenative/core/world`
3436
3759
 
3760
+ ### `applyTerrainSurface`
3761
+
3762
+ `function` — Apply a cooked GLB's package-authored layered surface to its marked terrain meshes. `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.
3763
+
3764
+ ```ts
3765
+ export async function applyTerrainSurface( root: Object3D, options: ILoadTerrainSplatOptions, ): Promise<void> { … }
3766
+ ```
3767
+
3768
+ - **Use when:** apply the authored layered terrain surface after loading a cooked world GLB
3769
+ - **Constraints:** url names the loaded GLB; tnTerrainSurface extras name a relative world package JSON
3770
+ - **Overrides:** `table` may replace `base`, `breakup`, `macro` and `layers`; baked `splat` and `textures` stay package-owned
3771
+
3772
+ ```ts
3773
+ await applyTerrainSurface(world.scene, { assets: ctx.assets, renderer: ctx.renderer, url: "world/world.glb" });
3774
+ ```
3775
+
3776
+ ### `bakedFractalNoise`
3777
+
3778
+ `function` — Drop-in for `mx_fractal_noise_float(p, octaves, lacunarity, diminish, amplitude)`: one read an octave.
3779
+
3780
+ ```ts
3781
+ export function bakedFractalNoise( p: Node<"vec3">, octaves = 3, lacunarity = 2, diminish = 0.5, amplitude: Scalar = 1, ): Node<"float"> { … }
3782
+ ```
3783
+
3784
+ - **Use when:** fractal or fbm noise in a material costs too much GPU time per pixel
3785
+ - **Constraints:** octaves is a build-time number; each octave is one filtered volume read
3786
+
3787
+ ```ts
3788
+ const macro = bakedFractalNoise(vec3(positionWorld.x, 0, positionWorld.z).mul(0.014), 3);
3789
+ ```
3790
+
3791
+ ### `bakedNoise`
3792
+
3793
+ `function` — Drop-in for `mx_noise_float(p, amplitude, pivot)` on a vec3 `p`: one filtered read of the baked volume instead of the per-pixel Perlin. Only the 3D form: three's 2D Perlin is another function (0.66 scale), so a vec2 caller keeps `mx_noise_float`. `channel` 1 to 3 are independent fields.
3794
+
3795
+ ```ts
3796
+ export function bakedNoise( p: Node<"vec3">, amplitude: Scalar = 1, pivot: Scalar = 0, channel: 0 | 1 | 2 | 3 = 0, ): Node<"float"> { … }
3797
+ ```
3798
+
3799
+ - **Use when:** a terrain, foliage or water shader calls mx_noise_float per pixel and the frame is GPU bound · open world ground material with procedural variation that must hold 60 FPS
3800
+ - **Constraints:** the field tiles every NOISE_PERIOD units of p; at p = world metres x 2.6 that is a 3 m repeat · vec3 input only: three's 2D Perlin is another function
3801
+ - **Overrides:** keep mx_noise_float where exact analytic noise matters more than the frame
3802
+
3803
+ ```ts
3804
+ const patch = smoothstep(-0.35, 0.35, bakedNoise(positionWorld.mul(0.025)));
3805
+ ```
3806
+
3437
3807
  ### `cellPlacements`
3438
3808
 
3439
3809
  `function` — Borrow the run's placement records as a live view over the placement buffer.
@@ -3481,6 +3851,21 @@ export class Heightfield extends Group implements IComputeDriven { … }
3481
3851
  const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
3482
3852
  ```
3483
3853
 
3854
+ ### `HeightfieldCollar`
3855
+
3856
+ `class` — A heightfield's far ring: `rings` square rings past its playable square, one vertex per boundary sample, and the index grid that draws them.
3857
+
3858
+ ```ts
3859
+ export class HeightfieldCollar { … }
3860
+ ```
3861
+
3862
+ - **Use when:** draw the terrain past the playable square without hand-building a ring grid · ground a character past the square, out to the walk band, on drawn triangles
3863
+ - **Constraints:** every ring vertex asks the game's `height` callback; core owns no terrain look · the collar is a ring of triangles, not a field: `heightAt` answers on it and null off it
3864
+
3865
+ ```ts
3866
+ const collar = new HeightfieldCollar({ resolution: 129, size: 512, rings: 384, ringDistance: (ring) => (ring / 384) ** 1.65 * 2100, walkBand: 200, height: ({ x, z }) => surveyed.heightAt(x, z) });
3867
+ ```
3868
+
3484
3869
  ### `heightSamplerFromHeightmap`
3485
3870
 
3486
3871
  `function` — Build a game-usable `sampleHeight` from a raw v1 heightmap. The returned function interpolates bilinearly in world units and clamps to the map edges, so it plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
@@ -3496,6 +3881,35 @@ export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWor
3496
3881
  const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
3497
3882
  ```
3498
3883
 
3884
+ ### `instanceRandom`
3885
+
3886
+ `function` — A random in [0, 1) that stays with its instance, as UE 5.8.3's PerInstanceRandom: hashed from the instance's world origin, never from its draw slot. WorldCells repacks instances on every refilter, main-pass cull and LOD switch, so `instanceIndex` names another tree from one frame to the next; a wind phase hashed from it re-rolled each crown about every 0.7 s of a walk and snapped its top by a median 0.37 m. Parts of one placement share its translation, so its bark and needles read one value.
3887
+
3888
+ ```ts
3889
+ export function instanceRandom(): Node<"float"> { … }
3890
+ ```
3891
+
3892
+ - **Use when:** a per-instance random number that stays with each streamed placement as WorldCells repacks · replace instanceIndex in a WorldCells part material, which WorldCells refuses
3893
+
3894
+ ```ts
3895
+ const phase = instanceRandom().mul(6.2831);
3896
+ ```
3897
+
3898
+ ### `lakeReach`
3899
+
3900
+ `function` — How far a lake's water reaches: the waterline its basin measures, `margin` times out, capped. The drawn surface and the swim footprint both size themselves here, so the shore a player sees is the shore they stop at.
3901
+
3902
+ ```ts
3903
+ export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }
3904
+ ```
3905
+
3906
+ - **Use when:** size a lake's footprint from its basin and the cap its biome row names
3907
+ - **Constraints:** reads the heightfield at every bearing, once per lake, never per frame
3908
+
3909
+ ```ts
3910
+ const reach = lakeReach(field, { ...lake, margin: 1.12 });
3911
+ ```
3912
+
3499
3913
  ### `loadTerrainSplat`
3500
3914
 
3501
3915
  `function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.
@@ -3506,7 +3920,7 @@ export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promi
3506
3920
 
3507
3921
  - **Use when:** terrain textured by splat masks exported from Blender with the world package · the game's terrain should match the DCC's terrain material without a second copy
3508
3922
  - **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe · WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
3509
- - **Overrides:** every value comes from the package's table; the returned material is the game's to adjust
3923
+ - **Overrides:** `table` may replace `base`, `breakup`, `macro` and `layers` from game source; baked `splat` and `textures` stay package-owned
3510
3924
 
3511
3925
  ```ts
3512
3926
  const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
@@ -3528,6 +3942,21 @@ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
3528
3942
  const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
3529
3943
  ```
3530
3944
 
3945
+ ### `noiseVolume`
3946
+
3947
+ `function` — The one volume every material shares: baked on first use, 1 MiB of RGBA8 (it stays in L2).
3948
+
3949
+ ```ts
3950
+ export function noiseVolume(): Data3DTexture { … }
3951
+ ```
3952
+
3953
+ - **Use when:** a material needs the raw baked noise texture to sample in its own TSL
3954
+ - **Constraints:** baked once per page on the main thread (about 0.15 s); every channel is an independent field
3955
+
3956
+ ```ts
3957
+ const volume = noiseVolume();
3958
+ ```
3959
+
3531
3960
  ### `snowDiscFootprint`
3532
3961
 
3533
3962
  `function` — A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.
@@ -3614,29 +4043,59 @@ export function validateWorldPackage( manifest: unknown, options: IWorldPackageV
3614
4043
  const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
3615
4044
  ```
3616
4045
 
3617
- ### `WorldCells`
4046
+ ### `WaterBodies`
3618
4047
 
3619
- `class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.
4048
+ `class` — One world's water, queried: surface height, current and footprint from the baked arrays. Rendering and physics read the same store, as they do for `Heightfield`, so the surface a player sees and the surface a swimmer rests on cannot disagree. Every station, level, extent and speed comes from the game, and the shading stays in the game's own `src/render/`. A river's segments sit in a uniform grid, so a query tests the few that can reach its cell instead of every station of every river.
3620
4049
 
3621
4050
  ```ts
3622
- export class WorldCells extends Group implements IComputeDriven { … }
4051
+ export class WaterBodies { … }
3623
4052
  ```
3624
4053
 
3625
- - **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
3626
- - **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 · 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 · 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
3627
- - **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
4054
+ - **Use when:** ask how high the water is where a player swims · ask which way a current carries a body · ask which water body covers a point, and how high its surface is · share one water store between rendering and physics
4055
+ - **Constraints:** every station, level, extent and speed comes from the game's own bake; a lake is measured on the field passed in
3628
4056
 
3629
4057
  ```ts
3630
- const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
3631
- scene.add(world);
3632
- world.update();
4058
+ const water = new WaterBodies({ ribbons, lakes, field }); const height = water.surfaceAt(x, z);
3633
4059
  ```
3634
4060
 
3635
- ## `@threenative/metahuman`
3636
-
3637
- ### `assertAssetPath`
4061
+ ### `waterlineRadius`
3638
4062
 
3639
- `function` — Keeps a caller-supplied asset path inside the asset directory.
4063
+ `function` — The furthest a lake's basin reaches on a bearing: where the drawn ground crosses its level. Twenty-four bearings step outwards and stop at the first bank, because binary-searching the whole ray can jump a dry ridge into another pond. Eighteen halvings land inside two centimetres at this scale, well under the ground's own sample spacing.
4064
+
4065
+ ```ts
4066
+ export function waterlineRadius( field: Heightfield, centre: readonly number[], level: number, ): number { … }
4067
+ ```
4068
+
4069
+ - **Use when:** measure where a lake's water meets the ground it floods · size a lake's drawn surface or the footprint a swimmer may enter
4070
+ - **Constraints:** returns metres on the furthest bearing; the caller applies its own cap
4071
+
4072
+ ```ts
4073
+ const reach = waterlineRadius(field, lake.at, lake.level) * 1.12;
4074
+ ```
4075
+
4076
+ ### `WorldCells`
4077
+
4078
+ `class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.
4079
+
4080
+ ```ts
4081
+ export class WorldCells extends Group implements IComputeDriven { … }
4082
+ ```
4083
+
4084
+ - **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
4085
+ - **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
4086
+ - **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
4087
+
4088
+ ```ts
4089
+ const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
4090
+ scene.add(world);
4091
+ world.update();
4092
+ ```
4093
+
4094
+ ## `@threenative/metahuman`
4095
+
4096
+ ### `assertAssetPath`
4097
+
4098
+ `function` — Keeps a caller-supplied asset path inside the asset directory.
3640
4099
 
3641
4100
  ```ts
3642
4101
  export function assertAssetPath(path: string): string { … }
@@ -3828,9 +4287,10 @@ const footprint = capsuleFootprint(0.5, 0.2);
3828
4287
  export class CharacterBody3D { … }
3829
4288
  ```
3830
4289
 
3831
- - **Use when:** move an enemy or player through a level · keep a character from walking through walls
3832
- - **Constraints:** use moveAndSlide inside the physics update
4290
+ - **Use when:** move an enemy or player through a level · keep a character from walking through walls · swim in a river, lake or sea; float at the surface and wade slower in shallow water · river current carries a swimmer downstream while it floats
4291
+ - **Constraints:** use moveAndSlide inside the physics update · pass `water: (x, z) => surfaceHeight | undefined`; the body reads `swimming`, `immersionDepth` and `waterSurface` each moveAndSlide · pass `waterCurrent: (x, z) => { x, z } | undefined` in m/s to have the water carry the body; it reads `currentVelocity` back
3833
4292
  - **Requires:** npm i @threenative/physics
4293
+ - **Overrides:** buoyancy (1.6, floats; Unreal 1.0 sinks), maxSwimSpeed (3 m/s) and fluidFriction (12) tune the Unreal MOVE_Swimming defaults
3834
4294
  - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
3835
4295
 
3836
4296
  ```ts
@@ -3926,7 +4386,7 @@ const game = defineGame({ plugins: [rapier()] });
3926
4386
  export class RigidBody3D { … }
3927
4387
  ```
3928
4388
 
3929
- - **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
4389
+ - **Use when:** give a crate or prop physical motion · a ball rolls across the floor · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
3930
4390
  - **Constraints:** register rapier() in the game plugin list before using bodies
3931
4391
  - **Requires:** npm i @threenative/physics
3932
4392
  - **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
@@ -3936,6 +4396,22 @@ export class RigidBody3D { … }
3936
4396
  const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
3937
4397
  ```
3938
4398
 
4399
+ ### `ScatterColliders`
4400
+
4401
+ `class` — Make scattered props solid: fixed bodies for rocks and trunks near a followed point, streamed with it.
4402
+
4403
+ ```ts
4404
+ export class ScatterColliders { … }
4405
+ ```
4406
+
4407
+ - **Use when:** stop the player walking through scattered rocks and trees · give instanced or streamed foliage props collision in an open world
4408
+ - **Constraints:** pass each instance's solid part (stone, bark), not its leaves; shapes are measured: a slender base is a trunk capsule, the rest an 18-DOP hull, and pieces under 0.25 m get none · call update() every frame; it rescans only after the follow point moves a quarter of `radius` (default 40 m) · `collision: "hull" | "trunk" | "none"` on an instance overrides the measured shape
4409
+ - **Requires:** npm i @threenative/physics
4410
+
4411
+ ```ts
4412
+ const solids = new ScatterColliders({ physics: ctx.physics, follow: player, collisionLayer: 4, instances: rocks.map((matrix) => ({ geometry: rockGeometry, matrix })) });
4413
+ ```
4414
+
3939
4415
  ### `softBodyCollision`
3940
4416
 
3941
4417
  `function` — Feed existing rigid-body boxes into `SoftBody3D` without inventing a second collider API.
@@ -6171,6 +6647,22 @@ export function applyPlacementOverrides(state: ITerrainState, value: unknown): I
6171
6647
  const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
6172
6648
  ```
6173
6649
 
6650
+ ### `bakeBiome`
6651
+
6652
+ `function` — Bake one biome: the recipe's evaluated state and the world package it streams. This is the composition `terrain_generate` and a game's build script both call, so the file layout a player streams is decided in one place. The biome is validated first — an inline spec from a request is checked here, not trusted — and the package's own placement runs are checked against the state they came from, so a bake can never ship a cell list that lost instances.
6653
+
6654
+ ```ts
6655
+ export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }
6656
+ ```
6657
+
6658
+ - **Use when:** bake one biome's world package from an evaluated recipe and a biome file
6659
+ - **Constraints:** every instance's asset must be in `assets`; every instance must land in exactly one cell run
6660
+ - **Requires:** npm i -D @threenative/terrain
6661
+
6662
+ ```ts
6663
+ const baked = bakeBiome({ state: terrain.evaluate(), spec: validateBiome(json, "savanna"), assets });
6664
+ ```
6665
+
6174
6666
  ### `bakeMesh`
6175
6667
 
6176
6668
  `function` — Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
@@ -6207,7 +6699,7 @@ const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCe
6207
6699
 
6208
6700
  ### `bakeWorldPackage`
6209
6701
 
6210
- `function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
6702
+ `function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, a placement ID sidecar and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
6211
6703
 
6212
6704
  ```ts
6213
6705
  export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }
@@ -6222,6 +6714,39 @@ export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPacka
6222
6714
  const { manifest, files } = bakeWorldPackage(state, { assets });
6223
6715
  ```
6224
6716
 
6717
+ ### `collarSampler`
6718
+
6719
+ `function` — The collar's height at any (x, z), and a way to raise one of its per-vertex attributes at a placement: both read the collar's own quad grid, so a lane that reshapes the collar moves the trees with it.
6720
+
6721
+ ```ts
6722
+ export function collarSampler(collar: HeightfieldCollar) { … }
6723
+ ```
6724
+
6725
+ - **Use when:** plant a far field on a drawn collar and paint the canopy its crowns cover
6726
+ - **Constraints:** the collar decides where a tree stands; this sampler never resamples the square
6727
+ - **Requires:** npm i -D @threenative/terrain
6728
+
6729
+ ```ts
6730
+ const sampler = collarSampler(collar); const height = sampler.at(x, z);
6731
+ ```
6732
+
6733
+ ### `compilePropBuckets`
6734
+
6735
+ `function` — Group placements into their streamed worlds and write each world's cells and records. The order is the streamed one: cells sorted by `x` then `z`, assets sorted by name inside a cell, and records in the order the entries arrived inside a run. Same-cell, same-asset placements keep their input order, so a re-run of a seeded bake reproduces the buffer byte for byte.
6736
+
6737
+ ```ts
6738
+ export function compilePropBuckets( entries: readonly IPropBucketEntry[], options: ICompilePropBucketsOptions = { … }
6739
+ ```
6740
+
6741
+ - **Use when:** bake the prop worlds a game streams, once, instead of compiling them at load
6742
+ - **Constraints:** headless; the caller decides every placement, its streamed world, its reach and its pose
6743
+ - **Requires:** npm i -D @threenative/terrain
6744
+ - **Overrides:** cellSize and the base extent; the bucket, reach and kind of every entry
6745
+
6746
+ ```ts
6747
+ const pkg = compilePropBuckets(entries, { bounds });
6748
+ ```
6749
+
6225
6750
  ### `createSegmentIndex`
6226
6751
 
6227
6752
  `function` — Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
@@ -6350,6 +6875,38 @@ export function encodeZIP(files: readonly IExportFile[]) { … }
6350
6875
  const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
6351
6876
  ```
6352
6877
 
6878
+ ### `farForestPlacements`
6879
+
6880
+ `function` — Far-field placements on the collar; also paints the collar's `canopy` attribute under each crown.
6881
+
6882
+ ```ts
6883
+ export function farForestPlacements(options: IFarFieldOptions): IPlacement[] { … }
6884
+ ```
6885
+
6886
+ - **Use when:** plant the stand past a game's playable square, out to the drawn collar
6887
+ - **Constraints:** the row's `far` block decides every density; the caller supplies the collar and layer
6888
+ - **Requires:** npm i -D @threenative/terrain
6889
+
6890
+ ```ts
6891
+ const trees = farForestPlacements({ size, resolution, collar, treeline, rules, asset, layer });
6892
+ ```
6893
+
6894
+ ### `fieldWeight`
6895
+
6896
+ `function` — A field's weight at (x, z), clamped to 0..1.
6897
+
6898
+ ```ts
6899
+ export function fieldWeight(field: ICoverField, x: number, z: number): number { … }
6900
+ ```
6901
+
6902
+ - **Use when:** sample the stand field a biome's trees and cover thin on · measure the drift a biome's blades grow by, or the mat field its cover follows
6903
+ - **Constraints:** the field is a value, so two worlds sample the same formula with their own numbers
6904
+ - **Requires:** npm i -D @threenative/terrain
6905
+
6906
+ ```ts
6907
+ const stand = fieldWeight(STAND_FIELD, x, z);
6908
+ ```
6909
+
6353
6910
  ### `gradientAt`
6354
6911
 
6355
6912
  `function` — World-space height gradient from the canonical samples.
@@ -6366,12 +6923,46 @@ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, n
6366
6923
  const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
6367
6924
  ```
6368
6925
 
6926
+ ### `landform`
6927
+
6928
+ `function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
6929
+
6930
+ ```ts
6931
+ export function landform(kind: LandformKind, options: ILandformOptions = { … }
6932
+ ```
6933
+
6934
+ - **Use when:** start an open world, a distant backdrop or a mountain level from a kind of place
6935
+ - **Constraints:** returns an ordinary `Terrain`: add roads, rivers, scatter or more layers, then `evaluate()` in a build script · shape only; materials, colours and textures belong to the game · calibrated at size 5000, resolution 513; other sizes keep the same slopes and scale the relief with `size`
6936
+ - **Requires:** npm i @threenative/terrain
6937
+ - **Overrides:** `relief` is the highest-minus-lowest height in metres before the finishing passes shave a few percent; `size`, `resolution` and `seed` as in `Terrain`
6938
+
6939
+ ```ts
6940
+ const terrain = landform("alpine", { size: 5000, resolution: 513, seed: 4 }); const state = terrain.evaluate();
6941
+ ```
6942
+
6943
+ ### `landformBackdrop`
6944
+
6945
+ `function` — Distant mountains around a playable area: a landform window with a valley floor at its centre.
6946
+
6947
+ ```ts
6948
+ export function landformBackdrop( kind: LandformKind, options: IBackdropOptions = { … }
6949
+ ```
6950
+
6951
+ - **Use when:** add a mountain backdrop around a playable area that the game's detail terrain covers
6952
+ - **Constraints:** resolution up to 513: the window is cut from a world twice as wide at the same spacing; build script only · shape only; the game places, colours and fades it
6953
+ - **Requires:** npm i @threenative/terrain
6954
+ - **Overrides:** `relief` and `centerHeight` in metres; `size`, `resolution` and `seed` as in `landform`
6955
+
6956
+ ```ts
6957
+ const { size, resolution, heights } = landformBackdrop("temperateMountains", { seed: 7, centerHeight: 13 });
6958
+ ```
6959
+
6369
6960
  ### `makeExport`
6370
6961
 
6371
6962
  `function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
6372
6963
 
6373
6964
  ```ts
6374
- export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }
6965
+ export function makeExport( state: ITerrainState | null, recipe: ITerrainDocument, kind: "project", ): Promise<IExportArchive>;
6375
6966
  ```
6376
6967
 
6377
6968
  - **Use when:** export a terrain recipe and its numerical runtime data
@@ -6382,6 +6973,84 @@ export async function makeExport( state: ITerrainState, recipe: ITerrainDocument
6382
6973
  const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
6383
6974
  ```
6384
6975
 
6976
+ ### `measureBands`
6977
+
6978
+ `function` — Resolve a biome's fraction bands against this world's own height samples.
6979
+
6980
+ ```ts
6981
+ export function measureBands( layers: readonly ILayerInfo[], heights: ArrayLike<number>, ): IMeasuredBands { … }
6982
+ ```
6983
+
6984
+ - **Use when:** turn a biome file's height fractions into the metres a world actually measured
6985
+ - **Constraints:** samples are finite and at least one; a flat field resolves every band onto its one height
6986
+ - **Requires:** npm i -D @threenative/terrain
6987
+
6988
+ ```ts
6989
+ const bands = measureBands(spec.layers, state.height);
6990
+ ```
6991
+
6992
+ ### `orderedScatterRules`
6993
+
6994
+ `function` — A biome's rows as the ordered generators read them. The rule is short and shared; only these numbers differ between a wood, a barren shoulder, a dune field and a tundra, so the biome file names them rather than the code. A biome whose tree is not one this generator has art for fails here, naming the species, rather than planting nothing.
6995
+
6996
+ ```ts
6997
+ export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules { … }
6998
+ ```
6999
+
7000
+ - **Use when:** run a biome file's rows through the ordered scatter
7001
+ - **Constraints:** the file carries one foliage row, one grass row and a cover block
7002
+ - **Requires:** npm i -D @threenative/terrain
7003
+
7004
+ ```ts
7005
+ const rules = orderedScatterRules(spec);
7006
+ ```
7007
+
7008
+ ### `propAssetOf`
7009
+
7010
+ `function` — The asset a package run names. A prop run names the model it draws, `asset:variant[@shape]`; a container written by `bakeWorldPackage` names the asset alone. Both reduce to the asset here, which is what a count, a material or a placement's own `asset` field holds.
7011
+
7012
+ ```ts
7013
+ export function propAssetOf(modelKey: string): string { … }
7014
+ ```
7015
+
7016
+ - **Use when:** count one species across a world's prop buckets, or name the asset a run draws
7017
+ - **Requires:** npm i -D @threenative/terrain
7018
+
7019
+ ```ts
7020
+ const asset = propAssetOf("spruce:2"); // "spruce"
7021
+ ```
7022
+
7023
+ ### `propPackageFile`
7024
+
7025
+ `function` — A path under `world/` that no bucket name can break: `local:true` becomes `local-true`. The bucket's own name is kept in the manifest, so this rename is only a file-system concern.
7026
+
7027
+ ```ts
7028
+ export function propPackageFile(world: string, bucket: string, suffix: string): string { … }
7029
+ ```
7030
+
7031
+ - **Use when:** name one of a bucket's three files without a bucket key that breaks a path
7032
+ - **Requires:** npm i -D @threenative/terrain
7033
+
7034
+ ```ts
7035
+ const file = propPackageFile("forest", "local:true", "props.bin"); // "forest.local-true.props.bin"
7036
+ ```
7037
+
7038
+ ### `propPackageFiles`
7039
+
7040
+ `function` — Write a compiled package as the manifest the game fetches and one set of files per bucket. The manifest names the files rather than embedding them, so a loader fetches only the buckets its query flags keep (`?farForest=on` keeps the far field, `?meadow=off` drops the vista cover).
7041
+
7042
+ ```ts
7043
+ export function propPackageFiles(pkg: IPropPackage, world: string): IPropPackageFiles { … }
7044
+ ```
7045
+
7046
+ - **Use when:** write a compiled package to disk: one manifest and three files per streamed world
7047
+ - **Constraints:** the manifest names the files; nothing here touches a file system
7048
+ - **Requires:** npm i -D @threenative/terrain
7049
+
7050
+ ```ts
7051
+ const { manifest, files } = propPackageFiles(pkg, "forest");
7052
+ ```
7053
+
6385
7054
  ### `sampleHeight`
6386
7055
 
6387
7056
  `function` — Bilinear query of canonical height samples; triangle sampling is a separate contract.
@@ -6398,6 +7067,22 @@ sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid(
6398
7067
  const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
6399
7068
  ```
6400
7069
 
7070
+ ### `scatterProps`
7071
+
7072
+ `function` — Every placement, for one world, from one seed: the game's own rule set, in its own draw order.
7073
+
7074
+ ```ts
7075
+ export function scatterProps( data: IOrderedScatterField, focus: { … }
7076
+ ```
7077
+
7078
+ - **Use when:** bake a biome that says `"stream": "ordered"`
7079
+ - **Constraints:** `data.rules` is the biome's rows, and `data.field` the ground they were graded on
7080
+ - **Requires:** npm i -D @threenative/terrain
7081
+
7082
+ ```ts
7083
+ const { placements, counts } = scatterProps(data, focus, clearings);
7084
+ ```
7085
+
6401
7086
  ### `slopeAtIndex`
6402
7087
 
6403
7088
  `function` — Slope in degrees at a heightfield sample.
@@ -6454,7 +7139,7 @@ const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
6454
7139
  export class Terrain { … }
6455
7140
  ```
6456
7141
 
6457
- - **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game
7142
+ - **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game · make realistic mountains, hills, desert, coast, tundra or volcano terrain: start from `landform(kind)`, or add `erode({ method: "fluvial" })` for dendritic valleys
6458
7143
  - **Constraints:** authoring stays outside the game's steady-play graph; no renderer or physics is created · units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin · `resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025 · `seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays · `evaluate()` is synchronous on the calling thread: run it in a build script, never per frame · no art is chosen or shipped: materials, models and texture paths belong to the game
6459
7144
  - **Requires:** npm i @threenative/terrain
6460
7145
  - **Overrides:** size, resolution, seed and all layer parameters are caller choices
@@ -6480,6 +7165,38 @@ export class TerrainEvaluator { … }
6480
7165
  const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());
6481
7166
  ```
6482
7167
 
7168
+ ### `terrainStats`
7169
+
7170
+ `function` — Landform statistics used to calibrate generators against real DEMs.
7171
+
7172
+ ```ts
7173
+ export function terrainStats(height: ArrayLike<number>, n: number, size: number): ITerrainStats { … }
7174
+ ```
7175
+
7176
+ - **Use when:** compare generated terrain with a USGS or SRTM crop on the same footprint
7177
+ - **Constraints:** square grids only; compare crops of equal spacing, because slope and curvature depend on it
7178
+ - **Requires:** npm i @threenative/terrain
7179
+
7180
+ ```ts
7181
+ const stats = terrainStats(state.height, state.resolution, state.size);
7182
+ ```
7183
+
7184
+ ### `validateBiome`
7185
+
7186
+ `function` — One biome file, checked field by field. The file is `biome.data.json`: `biome.json` is Biome's own configuration name, and a data file called that is parsed as a project config and fails the lint.
7187
+
7188
+ ```ts
7189
+ export function validateBiome(spec: unknown, name: string): IBiomeSpec { … }
7190
+ ```
7191
+
7192
+ - **Use when:** read a biome's rules from `starter/<biome>/biome.data.json` before a game or a cook uses them
7193
+ - **Constraints:** The file carries no appearance; colours, materials and shading stay game source
7194
+ - **Requires:** npm i @threenative/terrain
7195
+
7196
+ ```ts
7197
+ const spec = validateBiome(JSON.parse(text), "forest");
7198
+ ```
7199
+
6483
7200
  ### `validateDocument`
6484
7201
 
6485
7202
  `function` — Validates the recovered recipe schema, operation allow-lists and numeric bounds.
@@ -6532,6 +7249,70 @@ export function checkEnvironmentAssets( environment: IEnvironment, assets: reado
6532
7249
  checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
6533
7250
  ```
6534
7251
 
7252
+ ### `createEditorSelection`
7253
+
7254
+ `function` — Gesture and transaction mechanics; the caller owns the controls, proxy and all rendering.
7255
+
7256
+ ```ts
7257
+ export function createEditorSelection( { … }
7258
+ ```
7259
+
7260
+ - **Use when:** drive terrain-editor selection, gizmo drags, undo and saved transactions
7261
+ - **Constraints:** the caller supplies the TransformControls, proxy, controller and every drawing callback
7262
+ - **Requires:** npm i -D @threenative/terrain
7263
+
7264
+ ```ts
7265
+ const selection = createEditorSelection({ gizmo, proxy, controller, grounding, surface, defaultFootprintSize, refreshPose, drawFootprint, restorePlacement, previewPlacement, setSaving, selectedChanged, setNavigation, message });
7266
+ ```
7267
+
7268
+ ### `editorPlacementCenter`
7269
+
7270
+ `function` — Transform the caller's measured geometry centre into the evaluated placement's world space.
7271
+
7272
+ ```ts
7273
+ export function editorPlacementCenter(point: Vector3, pose: IPlacementOverride): Vector3 { … }
7274
+ ```
7275
+
7276
+ - **Use when:** find the world-space centre of a placed terrain-editor instance
7277
+ - **Constraints:** the point is multiplied in place; the pose needs finite position, quaternion and scale
7278
+ - **Requires:** npm i -D @threenative/terrain
7279
+
7280
+ ```ts
7281
+ const centre = editorPlacementCenter(localCentre.clone(), placement);
7282
+ ```
7283
+
7284
+ ### `editorPointToClient`
7285
+
7286
+ `function` — Project an injected world point to client pixels in the caller's viewport.
7287
+
7288
+ ```ts
7289
+ export function editorPointToClient( point: Vector3, camera: Camera, box: { … }
7290
+ ```
7291
+
7292
+ - **Use when:** convert a terrain-editor world point to viewport client pixels
7293
+ - **Constraints:** the point is projected in place; pass a clone to keep the original
7294
+ - **Requires:** npm i -D @threenative/terrain
7295
+
7296
+ ```ts
7297
+ const [x, y] = editorPointToClient(point.clone(), camera, canvas.getBoundingClientRect());
7298
+ ```
7299
+
7300
+ ### `editorSurfaceHeight`
7301
+
7302
+ `function` — Query the rendered heightfield, including its triangulation rather than an interpolated bake.
7303
+
7304
+ ```ts
7305
+ export function editorSurfaceHeight( ctx: { … }
7306
+ ```
7307
+
7308
+ - **Use when:** query terrain-editor surface elevation at world X/Z coordinates
7309
+ - **Constraints:** the supplied mesh and raycast determine the surface; missing intersections return undefined
7310
+ - **Requires:** npm i -D @threenative/terrain
7311
+
7312
+ ```ts
7313
+ const height = editorSurfaceHeight(ctx, terrainMesh, x, z);
7314
+ ```
7315
+
6535
7316
  ### `focusCamera`
6536
7317
 
6537
7318
  `function` — Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera
@@ -6583,6 +7364,22 @@ export function inspectSpatial( state: ITerrainState, revision: string, query: I
6583
7364
  const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
6584
7365
  ```
6585
7366
 
7367
+ ### `landformPose`
7368
+
7369
+ `function` — Recipe footprints are heights over X/Z, never independently transformed solids.
7370
+
7371
+ ```ts
7372
+ export function landformPose(layer: Layer, worldSize: number, defaultSize: number) { … }
7373
+ ```
7374
+
7375
+ - **Use when:** derive a terrain-editor gizmo pose from a landform layer
7376
+ - **Constraints:** the caller supplies world and default footprint sizes; unsupported layers return undefined
7377
+ - **Requires:** npm i -D @threenative/terrain
7378
+
7379
+ ```ts
7380
+ const pose = landformPose(layer, terrain.size, footprintSize);
7381
+ ```
7382
+
6586
7383
  ### `mountTerrainEditor`
6587
7384
 
6588
7385
  `function` — Mount recovered terrain controls around the project-owned ThreeNative view.
@@ -6600,6 +7397,38 @@ export async function mountTerrainEditor(options: { … }
6600
7397
  await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
6601
7398
  ```
6602
7399
 
7400
+ ### `pickEditorPlacement`
7401
+
7402
+ `function` — A foreground terrain hit occludes placements; matching uses the evaluated world position.
7403
+
7404
+ ```ts
7405
+ export function pickEditorPlacement( ctx: Parameters<typeof pickEditorSurface>[0], terrain: Mesh, meshes: readonly Object3D[], placements: Iterable< { … }
7406
+ ```
7407
+
7408
+ - **Use when:** pick a placed instance in the terrain editor from viewport client coordinates
7409
+ - **Constraints:** the caller supplies the raycast context, terrain mesh, instanced meshes and evaluated placements
7410
+ - **Requires:** npm i -D @threenative/terrain
7411
+
7412
+ ```ts
7413
+ const id = pickEditorPlacement(ctx, terrainMesh, meshes, placements, event.clientX, event.clientY);
7414
+ ```
7415
+
7416
+ ### `pickEditorSurface`
7417
+
7418
+ `function` — Convert viewport client coordinates once; the installed picker owns ray intersection.
7419
+
7420
+ ```ts
7421
+ export function pickEditorSurface( ctx: { … }
7422
+ ```
7423
+
7424
+ - **Use when:** pick a terrain-editor surface from viewport client coordinates
7425
+ - **Constraints:** the caller supplies the raycast implementation and ordered targets
7426
+ - **Requires:** npm i -D @threenative/terrain
7427
+
7428
+ ```ts
7429
+ const hit = pickEditorSurface(ctx, [terrainMesh], event.clientX, event.clientY);
7430
+ ```
7431
+
6603
7432
  ### `probeTerrain`
6604
7433
 
6605
7434
  `function` — Probe the evaluated surface at one world point, separating bilinear from triangle values.
@@ -6702,6 +7531,22 @@ export class TerrainEditorController { … }
6702
7531
  const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
6703
7532
  ```
6704
7533
 
7534
+ ### `transformedLandform`
7535
+
7536
+ `function` — Convert a terrain-editor gizmo pose into a heightfield landform footprint.
7537
+
7538
+ ```ts
7539
+ export function transformedLandform( layer: Layer, position: Vector3, quaternion: Quaternion, scale: Vector3, anchor: number, ): Layer { … }
7540
+ ```
7541
+
7542
+ - **Use when:** apply a terrain-editor gizmo transform to a landform layer
7543
+ - **Constraints:** finite coordinates and positive scales are required; X/Z rotations that overhang throw
7544
+ - **Requires:** npm i -D @threenative/terrain
7545
+
7546
+ ```ts
7547
+ const next = transformedLandform(layer, position, quaternion, scale, surfaceHeight);
7548
+ ```
7549
+
6705
7550
  ### `validateAsset`
6706
7551
 
6707
7552
  `function` — Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry
@@ -6859,21 +7704,104 @@ const document = new TerrainEditorDocument("/project/terrain/world.json"); const
6859
7704
 
6860
7705
  ## `@threenative/terrain/export`
6861
7706
 
6862
- ### `exportWorldGLB`
7707
+ ### `prepareWorldGLTF`
7708
+
7709
+ `function` — Prepare the game's validated, frozen portable scene; the server cook owns GLB encoding.
7710
+
7711
+ ```ts
7712
+ export async function prepareWorldGLTF(input: IWorldGLBInput): Promise< { … }
7713
+ ```
7714
+
7715
+ - **Use when:** export the terrain as a glb for another three.js project via the headless cook · prepare the terrain editor's resolved world for headless portable GLB cooking
7716
+ - **Constraints:** browser authoring FileReader/canvas; all appearance and coherent water come from the game
7717
+ - **Requires:** npm i -D @threenative/terrain
7718
+
7719
+ ```ts
7720
+ const prepared = await prepareWorldGLTF(input);
7721
+ ```
7722
+
7723
+ ## `@threenative/terrain/kit`
7724
+
7725
+ ### `bakeKit`
7726
+
7727
+ `function` — Bake a copied kit, optionally using the caller's installed world cook.
7728
+
7729
+ ```ts
7730
+ export async function bakeKit( url: string, { … }
7731
+ ```
7732
+
7733
+ - **Use when:** bake a copied terrain starter kit into its offline world package
7734
+ - **Constraints:** Node authoring only; recipes, asset tables and sky paths stay in the game
7735
+ - **Requires:** npm i -D @threenative/terrain
7736
+
7737
+ ```ts
7738
+ await bakeKit(import.meta.url, { sky: "hdri/game-sky.hdr" });
7739
+ ```
7740
+
7741
+ ### `starterAssetsDir`
7742
+
7743
+ `function` — Resolve shared starter assets locally, or download the package's pinned archive on demand.
7744
+
7745
+ ```ts
7746
+ export async function starterAssetsDir(): Promise<string> { … }
7747
+ ```
7748
+
7749
+ - **Use when:** resolve terrain kit models and textures for offline baking
7750
+ - **Constraints:** Node authoring only; verifies archive size and SHA256 before atomic extraction
7751
+ - **Requires:** npm i -D @threenative/terrain
7752
+
7753
+ ```ts
7754
+ const assets = await starterAssetsDir();
7755
+ ```
7756
+
7757
+ ## `@threenative/terrain/starter`
7758
+
7759
+ ### `addStarterWorld`
7760
+
7761
+ `function` — Load caller-authored starter data with one scene lifetime; all appearance comes from spec.
7762
+
7763
+ ```ts
7764
+ export async function addStarterWorld<Extra extends { … }
7765
+ ```
7766
+
7767
+ - **Use when:** attach a baked starter world with game-owned surfaces, prop dressing and water
7768
+ - **Constraints:** Runtime subpath; the game supplies every appearance and collision choice
7769
+ - **Requires:** npm i -D @threenative/terrain
7770
+
7771
+ ```ts
7772
+ await addStarterWorld(ctx, follow, spec);
7773
+ ```
7774
+
7775
+ ### `editWorldPlacements`
7776
+
7777
+ `function` — Apply deterministic startup edits to the decoded placement data before a world is loaded.
7778
+
7779
+ ```ts
7780
+ export function editWorldPlacements( data: { … }
7781
+ ```
7782
+
7783
+ - **Use when:** change generated terrain composition from game source without rebaking the world
7784
+ - **Requires:** npm i -D @threenative/terrain
7785
+ - **Overrides:** grounding defaults on, while `grounding: false` preserves the authored Y coordinate
7786
+
7787
+ ```ts
7788
+ const edited = editWorldPlacements(data, { remove: ["scree:candidate:7:41"] }, (x, z) => field.heightAt(x, z));
7789
+ ```
7790
+
7791
+ ### `PropColliders`
6863
7792
 
6864
- `function` — Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.
7793
+ `class` — Stream caller-specified fixed collision shapes around a moving follow object.
6865
7794
 
6866
7795
  ```ts
6867
- export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }
7796
+ export class PropColliders extends Object3D implements IComputeDriven { … }
6868
7797
  ```
6869
7798
 
6870
- - **Use when:** export terrain, resolved models and final manual placement transforms as a portable GLB · export the whole terrain world as one glb for another three.js project
6871
- - **Constraints:** browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless
7799
+ - **Use when:** attach nearby prop collision bodies from baked placement records
7800
+ - **Constraints:** Shapes and reach are supplied by the game; detach releases every body
6872
7801
  - **Requires:** npm i -D @threenative/terrain
6873
- - **Overrides:** actual static models, final matrices and baked PBR maps are supplied by the game
6874
7802
 
6875
7803
  ```ts
6876
- const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });
7804
+ new PropColliders(ctx, follow, manifest, records, shapes, reach, name);
6877
7805
  ```
6878
7806
 
6879
7807
  ## `@threenative/terrain/three`