@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
package/capabilities.json CHANGED
@@ -544,7 +544,7 @@
544
544
  "importPath": "@threenative/core",
545
545
  "kind": "function",
546
546
  "overrides": [
547
- "sliceSize defaults to 256; `marker: false` silences the TN_ADD_SLICES line, not the report"
547
+ "a slice ends on an 8 ms budget unless the game gives `sliceSize`, and the reported sliceSize is then the measured average; `marker: false` silences the TN_ADD_SLICES line, not the report"
548
548
  ],
549
549
  "package": "@threenative/core",
550
550
  "signature": "export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }",
@@ -684,6 +684,30 @@
684
684
  "supersedes": [],
685
685
  "symbol": "alwaysRender"
686
686
  },
687
+ {
688
+ "aliases": [],
689
+ "constraints": [
690
+ "one base phase, one masked override, at most two additive layers and eight actions",
691
+ "root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK",
692
+ "root motion excludes velocity-driven stride sync; unsupported parent transforms throw",
693
+ "source clips remain immutable; dispose at scene exit"
694
+ ],
695
+ "example": "const animation = new AnimationComposer({ root: rig, clips, samples: [\"walk\", \"run\"] });\nanimation.setWeights([0.5, 0.5]); animation.update(dt);",
696
+ "importPath": "@threenative/core",
697
+ "kind": "class",
698
+ "overrides": [],
699
+ "package": "@threenative/core",
700
+ "signature": "export class AnimationComposer { … }",
701
+ "situations": [
702
+ "synchronize walk/run/strafe clips with different durations",
703
+ "reload with the upper body while locomotion continues",
704
+ "apply an additive recoil clip with an explicit reference pose",
705
+ "route root motion through collision-aware character movement"
706
+ ],
707
+ "summary": "Compose game-authored locomotion and masked actions on one Three.js mixer.",
708
+ "supersedes": [],
709
+ "symbol": "AnimationComposer"
710
+ },
687
711
  {
688
712
  "aliases": [],
689
713
  "constraints": [
@@ -712,7 +736,7 @@
712
736
  "symbol": "AnimationPlayer"
713
737
  },
714
738
  {
715
- "aliases": ["bright sky saturated green platforms"],
739
+ "aliases": ["green platforms bright saturated sky"],
716
740
  "constraints": [
717
741
  "supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback",
718
742
  "the game creates the sky object, surface, and sun from the returned nodes"
@@ -794,7 +818,8 @@
794
818
  "aliases": [],
795
819
  "constraints": [
796
820
  "create buses before playing clips and dispose them with the game",
797
- "refDistance and rolloffFactor tune positional falloff and apply to playAt only"
821
+ "refDistance and rolloffFactor tune positional falloff and apply to playAt only",
822
+ "compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum"
798
823
  ],
799
824
  "example": "const effects = new AudioBus({ camera });",
800
825
  "importPath": "@threenative/core",
@@ -806,6 +831,7 @@
806
831
  "play a sound effect with a volume bus",
807
832
  "mute or adjust a category of game audio",
808
833
  "keep a gunshot audible at 20 metres by tuning positional falloff",
834
+ "hold a loud mix below clipping with a compressor on the bus",
809
835
  "play cannon, wave, and ship sound effects"
810
836
  ],
811
837
  "summary": "Route effects through a named audio bus.",
@@ -870,6 +896,46 @@
870
896
  "supersedes": [],
871
897
  "symbol": "Billboard3D"
872
898
  },
899
+ {
900
+ "aliases": [],
901
+ "constraints": [
902
+ "duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization",
903
+ "outside 2D queries project to the nearest boundary subedge; output is borrowed scratch"
904
+ ],
905
+ "example": "const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));",
906
+ "importPath": "@threenative/core",
907
+ "kind": "class",
908
+ "overrides": [],
909
+ "package": "@threenative/core",
910
+ "signature": "export class BlendSpace1D { … }",
911
+ "situations": [
912
+ "calculate 1D walk/run blend weights from speed",
913
+ "calculate 2D locomotion weights from forward and strafe intent"
914
+ ],
915
+ "summary": "Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.",
916
+ "supersedes": [],
917
+ "symbol": "BlendSpace1D"
918
+ },
919
+ {
920
+ "aliases": [],
921
+ "constraints": [
922
+ "duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization",
923
+ "outside 2D queries project to the nearest boundary subedge; output is borrowed scratch"
924
+ ],
925
+ "example": "const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));",
926
+ "importPath": "@threenative/core",
927
+ "kind": "class",
928
+ "overrides": [],
929
+ "package": "@threenative/core",
930
+ "signature": "export class BlendSpace2D { … }",
931
+ "situations": [
932
+ "calculate 1D walk/run blend weights from speed",
933
+ "calculate 2D locomotion weights from forward and strafe intent"
934
+ ],
935
+ "summary": "Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.",
936
+ "supersedes": [],
937
+ "symbol": "BlendSpace2D"
938
+ },
873
939
  {
874
940
  "aliases": [],
875
941
  "constraints": [
@@ -930,6 +996,26 @@
930
996
  "supersedes": [],
931
997
  "symbol": "boneLengths"
932
998
  },
999
+ {
1000
+ "aliases": [],
1001
+ "constraints": [
1002
+ "call rebuild() after a scene transform or geometry change; the snapshot is static by default",
1003
+ "rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray"
1004
+ ],
1005
+ "example": "const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));",
1006
+ "importPath": "@threenative/core",
1007
+ "kind": "function",
1008
+ "overrides": [],
1009
+ "package": "@threenative/core",
1010
+ "signature": "bvhIntersectFirstHit = upstream.bvhIntersectFirstHit",
1011
+ "situations": [
1012
+ "trace thousands of scene rays inside a TSL kernel",
1013
+ "build a contact-occlusion or visibility query over loaded meshes"
1014
+ ],
1015
+ "summary": "Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.",
1016
+ "supersedes": [],
1017
+ "symbol": "bvhIntersectFirstHit"
1018
+ },
933
1019
  {
934
1020
  "aliases": [],
935
1021
  "constraints": [
@@ -967,6 +1053,26 @@
967
1053
  "supersedes": [],
968
1054
  "symbol": "CanvasLayer"
969
1055
  },
1056
+ {
1057
+ "aliases": [],
1058
+ "constraints": [
1059
+ "the browser grants capture only from a user gesture and a refusal is reported, never swallowed",
1060
+ "a relative binding requests capture on canvas click unless `captureOnClick: false` opts out"
1061
+ ],
1062
+ "example": "canvas.addEventListener(\"click\", () => captureMouse(canvas));",
1063
+ "importPath": "@threenative/core",
1064
+ "kind": "function",
1065
+ "overrides": [],
1066
+ "package": "@threenative/core",
1067
+ "signature": "export function captureMouse(target: EventTarget): Promise<void> | undefined { … }",
1068
+ "situations": [
1069
+ "lock the mouse pointer so first-person mouse look keeps the cursor out of the way",
1070
+ "stop the cursor leaving the window in the middle of a turn"
1071
+ ],
1072
+ "summary": "Lock the pointer to the game's surface: the capture every first-person mouse look needs. A browser grants capture only from a user gesture, so call it from a click or a pointerdown handler. A relative binding such as `look: { pointerRelative: true }` already requests capture on the first canvas click; this is the same request for a game that starts capture from another named gesture, and `ctx.input.captureMouse()` is the map's own way to ask.",
1073
+ "supersedes": [],
1074
+ "symbol": "captureMouse"
1075
+ },
970
1076
  {
971
1077
  "aliases": [],
972
1078
  "constraints": ["a track that binds nothing counts as driving nothing"],
@@ -1117,7 +1223,7 @@
1117
1223
  "symbol": "counterDeviceOf"
1118
1224
  },
1119
1225
  {
1120
- "aliases": ["different props in each area", "first playable screen external assets"],
1226
+ "aliases": ["different area props", "first playable screen external assets"],
1121
1227
  "constraints": [
1122
1228
  "reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches"
1123
1229
  ],
@@ -1164,6 +1270,7 @@
1164
1270
  "package": "@threenative/core",
1165
1271
  "signature": "export function createRandom(seed?: number): IRandom { … }",
1166
1272
  "situations": [
1273
+ "get a seeded deterministic random number generator — the same mulberry32 a game would hand-roll",
1167
1274
  "seed enemy patrol choices",
1168
1275
  "reproduce the same procedural level in a playtest"
1169
1276
  ],
@@ -1190,11 +1297,52 @@
1190
1297
  "supersedes": [],
1191
1298
  "symbol": "createReplayDriver"
1192
1299
  },
1300
+ {
1301
+ "aliases": [],
1302
+ "constraints": [
1303
+ "every value is required; there is no default sun, sky, haze or exposure",
1304
+ "`skySize` must keep the sky box's corners inside the camera's far plane",
1305
+ "shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing"
1306
+ ],
1307
+ "example": "const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });\nctx.add(daylight);",
1308
+ "importPath": "@threenative/core",
1309
+ "kind": "class",
1310
+ "overrides": [
1311
+ "sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`"
1312
+ ],
1313
+ "package": "@threenative/core",
1314
+ "signature": "export class Daylight extends Group implements IComputeDriven { … }",
1315
+ "situations": [
1316
+ "daytime sky, sun and shadows for a large outdoor map",
1317
+ "distant terrain should fade into the sky instead of a coloured wall",
1318
+ "match a Blender look-dev scene's sun, sky and exposure in the game"
1319
+ ],
1320
+ "summary": "An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye, hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.",
1321
+ "supersedes": [],
1322
+ "symbol": "Daylight"
1323
+ },
1324
+ {
1325
+ "aliases": [],
1326
+ "constraints": [
1327
+ "a name in camelCase becomes UPPER_SNAKE: `debugFlag(\"freeCam\")` reads `?freeCam` or `TN_DEBUG_FREE_CAM`",
1328
+ "`0` and `false` are off, so a saved URL cannot turn a switch back on"
1329
+ ],
1330
+ "example": "import { debugFlag } from \"@threenative/core\";\nif (debugFlag(\"freeCam\")) camera.flyMode = true;",
1331
+ "importPath": "@threenative/core",
1332
+ "kind": "function",
1333
+ "overrides": [],
1334
+ "package": "@threenative/core",
1335
+ "signature": "export function debugFlag(name: string): boolean { … }",
1336
+ "situations": ["read a debug toggle from the URL or an environment variable"],
1337
+ "summary": "Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.",
1338
+ "supersedes": [],
1339
+ "symbol": "debugFlag"
1340
+ },
1193
1341
  {
1194
1342
  "aliases": [
1195
- "firing line nearest target crosshair",
1343
+ "nearest target crosshair spawns",
1196
1344
  "third-person camera",
1197
- "restart the run without a page reload",
1345
+ "restart run without page reload",
1198
1346
  "field of view while aiming"
1199
1347
  ],
1200
1348
  "constraints": [
@@ -1353,6 +1501,20 @@
1353
1501
  "supersedes": [],
1354
1502
  "symbol": "ensureVelocityOutput"
1355
1503
  },
1504
+ {
1505
+ "aliases": [],
1506
+ "constraints": ["development builds only; a production build publishes nothing"],
1507
+ "example": "import { exposeDebug } from \"@threenative/core\";\nexposeDebug(\"player\", player);\n// then from the console: __THREENATIVE__.debug.player",
1508
+ "importPath": "@threenative/core",
1509
+ "kind": "function",
1510
+ "overrides": [],
1511
+ "package": "@threenative/core",
1512
+ "signature": "export function exposeDebug(name: string, value: unknown): void { … }",
1513
+ "situations": ["expose a game object to a capture script or the console in dev builds"],
1514
+ "summary": "Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.",
1515
+ "supersedes": [],
1516
+ "symbol": "exposeDebug"
1517
+ },
1356
1518
  {
1357
1519
  "aliases": [],
1358
1520
  "constraints": [
@@ -1400,6 +1562,33 @@
1400
1562
  "supersedes": [],
1401
1563
  "symbol": "FluidField2D"
1402
1564
  },
1565
+ {
1566
+ "aliases": [],
1567
+ "constraints": [
1568
+ "add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic",
1569
+ "a renderer without WebGPU compute throws a named error at attach; it never draws nothing",
1570
+ "`emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity",
1571
+ "`sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live"
1572
+ ],
1573
+ "example": "const water = new FluidParticles3D({ capacity: 6000 });\nctx.add(water);\nwater.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);",
1574
+ "importPath": "@threenative/core",
1575
+ "kind": "class",
1576
+ "overrides": [
1577
+ "iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order"
1578
+ ],
1579
+ "package": "@threenative/core",
1580
+ "signature": "export class FluidParticles3D extends Group { … }",
1581
+ "situations": [
1582
+ "pour, splash, or dam-break water that fills a container and flows around obstacles",
1583
+ "simulate water or another liquid as particles in a fluid simulation",
1584
+ "drop a ball or box into liquid and let it displace and float on the water",
1585
+ "emit a stream or waterfall of particle fluid and drain it somewhere else",
1586
+ "sample particle-fluid density or surface height in a game-owned render node"
1587
+ ],
1588
+ "summary": "Simulate liquid as GPU particles (pour, splash, dam break, waterfall) and expose positions, a density volume and a surface height while the game owns every look.",
1589
+ "supersedes": [],
1590
+ "symbol": "FluidParticles3D"
1591
+ },
1403
1592
  {
1404
1593
  "aliases": [],
1405
1594
  "constraints": [
@@ -1443,6 +1632,28 @@
1443
1632
  "supersedes": [],
1444
1633
  "symbol": "formatSpansWindow"
1445
1634
  },
1635
+ {
1636
+ "aliases": [],
1637
+ "constraints": [
1638
+ "derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material",
1639
+ "it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision"
1640
+ ],
1641
+ "example": "defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky",
1642
+ "importPath": "@threenative/core",
1643
+ "kind": "function",
1644
+ "overrides": [
1645
+ "`material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)"
1646
+ ],
1647
+ "package": "@threenative/core",
1648
+ "signature": "export function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string { … }",
1649
+ "situations": [
1650
+ "catch the \"why does my forest look like cardboard\" question before a human plays it",
1651
+ "audit a scene a game built from imported GLB foliage"
1652
+ ],
1653
+ "summary": "Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.",
1654
+ "supersedes": [],
1655
+ "symbol": "formatUnlitFoliageWarning"
1656
+ },
1446
1657
  {
1447
1658
  "aliases": [],
1448
1659
  "constraints": [
@@ -1469,7 +1680,10 @@
1469
1680
  "constraints": [
1470
1681
  "on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement",
1471
1682
  "per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main",
1472
- "GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero"
1683
+ "GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero",
1684
+ "`ctx.renderer.observeGpuFrames({ maxFrames, maxQueries })` is opt-in, bounded and fail-closed; `take()` delivers immutable complete render-query groups once, while `status()` reports pending/undrained/queued membership and losses",
1685
+ "observation preserves ordinary sampling; a complete benchmark explicitly requests `renderer.gpuTimestampFrameInterval: 1` and joins Three query IDs to actual world renders, including separate overlay IDs",
1686
+ "`stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement"
1473
1687
  ],
1474
1688
  "example": "defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });",
1475
1689
  "importPath": "@threenative/core",
@@ -1478,11 +1692,13 @@
1478
1692
  "package": "@threenative/core",
1479
1693
  "signature": "export class FrameBudget { … }",
1480
1694
  "situations": [
1695
+ "show an on-screen frame time meter with p50, p95 and p99 percentiles",
1481
1696
  "find out why a game runs slowly on a phone",
1482
1697
  "attribute a frame to present wait, simulation, three.js render, or overlay",
1483
1698
  "tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp",
1484
1699
  "split a frame's draw calls and triangles per render pass (main, shadow, reflection)",
1485
- "tell a shadow or reflection pass's cost from the main colour pass"
1700
+ "tell a shadow or reflection pass's cost from the main colour pass",
1701
+ "retain every asynchronous GPU render frame for a complete paired benchmark"
1486
1702
  ],
1487
1703
  "summary": "Read where the frame's milliseconds went, per presented frame, on any platform; each `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and triangles each render pass submitted.",
1488
1704
  "supersedes": [],
@@ -1553,11 +1769,24 @@
1553
1769
  },
1554
1770
  {
1555
1771
  "aliases": [],
1556
- "constraints": ["geometry, color, and timing remain supplied by the game"],
1557
- "example": "const particles = new GPUParticles3D(particleOptions);",
1772
+ "constraints": [
1773
+ "geometry, color, and timing remain supplied by the game",
1774
+ "a `spawn` kernel makes bursts requests: `emitParticle({ count, origin })` reserves ring slots, the engine stamps `buffers.births` and `process` reads age as `runtime.time - births[i]`; there is no readback",
1775
+ "a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent",
1776
+ "requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option",
1777
+ "the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view",
1778
+ "a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view",
1779
+ "when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget"
1780
+ ],
1781
+ "example": "const particles = new GPUParticles3D(particleOptions);\nparticles.emitParticle({ count: 220, origin: hit.position });",
1558
1782
  "importPath": "@threenative/core",
1559
1783
  "kind": "class",
1560
- "overrides": [],
1784
+ "overrides": [
1785
+ "localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring",
1786
+ "onCull: \"clear\" restarts a returning effect, the default \"pause\" resumes it with buffers intact",
1787
+ "bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence",
1788
+ "graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling"
1789
+ ],
1561
1790
  "package": "@threenative/core",
1562
1791
  "signature": "export class GPUParticles3D extends Sprite implements IComputeDriven { … }",
1563
1792
  "situations": [
@@ -1565,7 +1794,13 @@
1565
1794
  "update many small visual particles",
1566
1795
  "trail dust, exhaust, or spray behind a moving object",
1567
1796
  "emit cannon smoke and muzzle flash particles",
1568
- "fire a cannonball projectile with cannon smoke particles"
1797
+ "fire a cannonball projectile with cannon smoke particles",
1798
+ "splash spray droplets with lifetime and gravity",
1799
+ "spawn water droplets, mist, or foam bubbles above a fluid surface",
1800
+ "falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard",
1801
+ "kick up a spray of powder snow or dust where a foot or a ball lands",
1802
+ "a hit, impact or explosion burst that starts at the point and moment it is asked for, and a second hit that must not move the first hit's live particles",
1803
+ "emitParticle a burst of GPU particles at a world position with its own free slots"
1569
1804
  ],
1570
1805
  "summary": "Dispatch a game-owned particle surface and process function through a pooled system.",
1571
1806
  "supersedes": [],
@@ -1635,6 +1870,27 @@
1635
1870
  "supersedes": [],
1636
1871
  "symbol": "GroundSnap"
1637
1872
  },
1873
+ {
1874
+ "aliases": [],
1875
+ "constraints": [
1876
+ "`buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it",
1877
+ "scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own"
1878
+ ],
1879
+ "example": "const game = defineGame({ input: { move: { up: [\"KeyW\"], down: [\"KeyS\"], left: [\"KeyA\"], right: [\"KeyD\"] } }, scenes: { Play } });\n// inside the scene, per frame: ctx.input.axis(\"move\") is 0 at rest and 1 at full tilt",
1880
+ "importPath": "@threenative/core",
1881
+ "kind": "class",
1882
+ "overrides": [],
1883
+ "package": "@threenative/core",
1884
+ "signature": "export class InputMap { … }",
1885
+ "situations": [
1886
+ "map WASD keys to a movement axis instead of reading the held key set in the update loop",
1887
+ "read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together",
1888
+ "read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks"
1889
+ ],
1890
+ "summary": "The map a game reads input through: named actions, 2D vectors and scalar axes resolved from keyboard, gamepad, mouse, wheel, pinch and touch. `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual route is a binding in the config and `ctx.input.axis(\"move\")` in the update. Construct one directly to drive a menu, a replay or a test outside a running game.",
1891
+ "supersedes": [],
1892
+ "symbol": "InputMap"
1893
+ },
1638
1894
  {
1639
1895
  "aliases": [],
1640
1896
  "constraints": [
@@ -1661,12 +1917,15 @@
1661
1917
  "constraints": [
1662
1918
  "geometry and material are required and come from the game; the batch chooses neither",
1663
1919
  "span stretches along +Y, so its geometry must be unit-height and centred on the origin",
1664
- "placing after build() throws, and build() returns undefined when nothing was placed"
1920
+ "placing after build() throws, and build() returns undefined when nothing was placed",
1921
+ "baked AutoLOD chains survive geometry clone/transform preparation and partition instances automatically into spatially bounded draws in the engine frame loop at 4 px projected error; public instance slots remain stable",
1922
+ "unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE"
1665
1923
  ],
1666
1924
  "example": "const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });\ncurbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });\ncurbs.build({ castShadow: true, name: \"curbs\", parent: ctx.scene });",
1667
1925
  "importPath": "@threenative/core",
1668
1926
  "kind": "class",
1669
1927
  "overrides": [
1928
+ "autoLod: false leaves selection to the game; autoLod.maxPixelError and hysteresis override the measured-camera budget; lods supplies authored distance/geometry levels and wins over the baked chain",
1670
1929
  "castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false"
1671
1930
  ],
1672
1931
  "package": "@threenative/core",
@@ -1674,6 +1933,7 @@
1674
1933
  "situations": [
1675
1934
  "draw hundreds of repeated props without hundreds of draw calls",
1676
1935
  "draw thousands of identical instanced blocks or obstacles in one mesh",
1936
+ "automatically select instanced prop detail from projected screen error using baked AutoLOD chains",
1677
1937
  "place repeated props when the count is not known until the layout has been walked",
1678
1938
  "build a chain, railing, cable, or tie rod out of point-to-point segments"
1679
1939
  ],
@@ -1688,7 +1948,7 @@
1688
1948
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
1689
1949
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
1690
1950
  ],
1691
- "example": "markStatic(island); invalidateStatic(drawbridge);",
1951
+ "example": "invalidateStatic(drawbridge);",
1692
1952
  "importPath": "@threenative/core",
1693
1953
  "kind": "function",
1694
1954
  "overrides": [],
@@ -1751,7 +2011,7 @@
1751
2011
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
1752
2012
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
1753
2013
  ],
1754
- "example": "markStatic(island); invalidateStatic(drawbridge);",
2014
+ "example": "invalidateStatic(drawbridge);",
1755
2015
  "importPath": "@threenative/core",
1756
2016
  "kind": "function",
1757
2017
  "overrides": [],
@@ -1829,11 +2089,30 @@
1829
2089
  "supersedes": [],
1830
2090
  "symbol": "loadAll"
1831
2091
  },
2092
+ {
2093
+ "aliases": [],
2094
+ "constraints": [
2095
+ "a non-positive viewport height, a non-positive frustum height or an unprojectable camera throws",
2096
+ "a non-positive depth has no projected scale and returns Infinity"
2097
+ ],
2098
+ "example": "const pixels = lodPixelScale(camera, canvas.clientHeight, mesh.position.distanceTo(camera.position));",
2099
+ "importPath": "@threenative/core",
2100
+ "kind": "function",
2101
+ "overrides": [],
2102
+ "package": "@threenative/core",
2103
+ "signature": "export function lodPixelScale(camera: Camera, viewportHeight: number, depth: number): number { … }",
2104
+ "situations": [
2105
+ "pick a level of detail from an object's projected size in pixels on screen",
2106
+ "know how many screen pixels a world-space error covers at a given distance"
2107
+ ],
2108
+ "summary": "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.",
2109
+ "supersedes": [],
2110
+ "symbol": "lodPixelScale"
2111
+ },
1832
2112
  {
1833
2113
  "aliases": [],
1834
2114
  "constraints": [
1835
2115
  "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
1836
- "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
1837
2116
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
1838
2117
  ],
1839
2118
  "example": "markStatic(island); invalidateStatic(drawbridge);",
@@ -1843,10 +2122,10 @@
1843
2122
  "package": "@threenative/core",
1844
2123
  "signature": "export function markStatic(root: Object3D): number { … }",
1845
2124
  "situations": [
1846
- "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
1847
- "keep a frozen subtree correct when the game does move it after all"
2125
+ "freeze a static mesh or subtree so its matrices are not recomputed every frame",
2126
+ "stop the engine recomposing the transforms of props, terrain and buildings each frame"
1848
2127
  ],
1849
- "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
2128
+ "summary": "Freeze a subtree nobody moves: `markStatic(root)` composes its transforms once and stops the per-frame recompose. It is the call a game makes on scenery, terrain, buildings and props. The engine re-arms a root whose own transform the game changes; a write deeper inside a frozen subtree is announced with `invalidateStatic(object)`.",
1850
2129
  "supersedes": [],
1851
2130
  "symbol": "markStatic"
1852
2131
  },
@@ -1865,6 +2144,7 @@
1865
2144
  "package": "@threenative/core",
1866
2145
  "signature": "export class MatrixWorldPass { … }",
1867
2146
  "situations": [
2147
+ "update the world matrices of the visible objects each frame instead of the whole scene",
1868
2148
  "the per-frame world matrix walk is hot in a profile",
1869
2149
  "stop multiplying matrices for hidden models, LOD levels and merged stand-ins",
1870
2150
  "a game needs every node walked, exactly as three's own updateMatrixWorld does"
@@ -1887,6 +2167,28 @@
1887
2167
  "supersedes": [],
1888
2168
  "symbol": "measureThreePose"
1889
2169
  },
2170
+ {
2171
+ "aliases": [],
2172
+ "constraints": [
2173
+ "the material is the game's own instance and the split follows the materials the game",
2174
+ "the meshes come back in root's local space and unparented, with the originals still in the",
2175
+ "a skinned or instanced mesh, and a mesh with several materials, is left out — its",
2176
+ "a group where only some meshes carry uv throws naming the label rather than losing the"
2177
+ ],
2178
+ "example": "const [hull, deck] = mergeByMaterial(ship, { label: \"ship\" });\n// a piece that must keep moving at run time:\nconst [steady] = mergeByMaterial(ship, { label: \"ship\", skip: (mesh) => mesh.name === \"radar\" });",
2179
+ "importPath": "@threenative/core",
2180
+ "kind": "function",
2181
+ "overrides": ["skip leaves one mesh out of its group and out of the result"],
2182
+ "package": "@threenative/core",
2183
+ "signature": "export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[] { … }",
2184
+ "situations": [
2185
+ "collapse a building or ship of dozens of boxes into one draw call per material",
2186
+ "consolidate the static parts of a group before adding it to the scene"
2187
+ ],
2188
+ "summary": "Bake a hierarchy's static meshes into one mesh per material, with their transforms baked in. already made; nothing here decides appearance tree: add them to root and remove the sources yourself, or both draw vertices are not its own to bake texture mapping; a missing normal is recomputed",
2189
+ "supersedes": [],
2190
+ "symbol": "mergeByMaterial"
2191
+ },
1890
2192
  {
1891
2193
  "aliases": [],
1892
2194
  "constraints": [
@@ -2247,7 +2549,7 @@
2247
2549
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2248
2550
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2249
2551
  ],
2250
- "example": "markStatic(island); invalidateStatic(drawbridge);",
2552
+ "example": "invalidateStatic(drawbridge);",
2251
2553
  "importPath": "@threenative/core",
2252
2554
  "kind": "function",
2253
2555
  "overrides": [],
@@ -2324,6 +2626,26 @@
2324
2626
  "supersedes": [],
2325
2627
  "symbol": "RenderListValidator"
2326
2628
  },
2629
+ {
2630
+ "aliases": [],
2631
+ "constraints": [
2632
+ "structural scene reads only, one visible-tree walk per entry, at most five material examples",
2633
+ "the audit itself changes no scene state; the game loop's opacity convention is the only writer"
2634
+ ],
2635
+ "example": "renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array",
2636
+ "importPath": "@threenative/core",
2637
+ "kind": "function",
2638
+ "overrides": [],
2639
+ "package": "@threenative/core",
2640
+ "signature": "export function renderTrapAudit(scene: Object3D & { … }",
2641
+ "situations": [
2642
+ "audit an equirectangular sky too narrow for three's WebGPU PMREM",
2643
+ "find visible opaque materials whose authored opacity is ignored"
2644
+ ],
2645
+ "summary": "Catch scene state that silently loses environment fill or ignores authored opacity. After `enter()` the game first applies the opacity convention: a drawn material with `opacity < 1` turns transparent and one `TN_OPACITY_TRANSPARENT` console warning names it (override: `alphaHash: true`, or `opacity: 1`). It then prints `TN_ENVIRONMENT_TOO_SMALL` as a console error with the fix, so playtest `noConsoleErrors` rejects it.",
2646
+ "supersedes": [],
2647
+ "symbol": "renderTrapAudit"
2648
+ },
2327
2649
  {
2328
2650
  "aliases": ["fixed seed fixed-step simulation"],
2329
2651
  "constraints": [
@@ -2366,7 +2688,7 @@
2366
2688
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2367
2689
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2368
2690
  ],
2369
- "example": "markStatic(island); invalidateStatic(drawbridge);",
2691
+ "example": "invalidateStatic(drawbridge);",
2370
2692
  "importPath": "@threenative/core",
2371
2693
  "kind": "function",
2372
2694
  "overrides": [],
@@ -2412,6 +2734,22 @@
2412
2734
  "supersedes": [],
2413
2735
  "symbol": "resolveAtmosphereParameters"
2414
2736
  },
2737
+ {
2738
+ "aliases": [],
2739
+ "constraints": [
2740
+ "pass the measured display rate when you have one; without it the answer is the 60 fallback and says so"
2741
+ ],
2742
+ "example": "resolveTargetFps(config, getPlatform()).targetFps;",
2743
+ "importPath": "@threenative/core",
2744
+ "kind": "function",
2745
+ "overrides": [],
2746
+ "package": "@threenative/core",
2747
+ "signature": "export function resolveTargetFps( config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number, ): ITargetFps { … }",
2748
+ "situations": ["my game does frame-rate-dependent work and must not hardcode 60"],
2749
+ "summary": "Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.",
2750
+ "supersedes": [],
2751
+ "symbol": "resolveTargetFps"
2752
+ },
2415
2753
  {
2416
2754
  "aliases": [],
2417
2755
  "constraints": [
@@ -2510,7 +2848,8 @@
2510
2848
  "situations": [
2511
2849
  "delay an enemy patrol transition",
2512
2850
  "run a callback every simulation tick",
2513
- "tween a numeric property with a game-owned curve"
2851
+ "tween a numeric property with a game-owned curve",
2852
+ "a countdown timer: end the level when its time limit runs out"
2514
2853
  ],
2515
2854
  "summary": "Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.",
2516
2855
  "supersedes": [],
@@ -2602,6 +2941,22 @@
2602
2941
  "supersedes": [],
2603
2942
  "symbol": "skeletonBones"
2604
2943
  },
2944
+ {
2945
+ "aliases": [],
2946
+ "constraints": [
2947
+ "pass the measured display rate when you have one; without it the answer is the 60 fallback and says so"
2948
+ ],
2949
+ "example": "resolveTargetFps(config, getPlatform()).targetFps;",
2950
+ "importPath": "@threenative/core",
2951
+ "kind": "function",
2952
+ "overrides": [],
2953
+ "package": "@threenative/core",
2954
+ "signature": "export function snapRefreshRate(refreshHz: number): number { … }",
2955
+ "situations": ["my game does frame-rate-dependent work and must not hardcode 60"],
2956
+ "summary": "Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.",
2957
+ "supersedes": [],
2958
+ "symbol": "snapRefreshRate"
2959
+ },
2605
2960
  {
2606
2961
  "aliases": [],
2607
2962
  "constraints": [
@@ -2822,7 +3177,7 @@
2822
3177
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2823
3178
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2824
3179
  ],
2825
- "example": "markStatic(island); invalidateStatic(drawbridge);",
3180
+ "example": "invalidateStatic(drawbridge);",
2826
3181
  "importPath": "@threenative/core",
2827
3182
  "kind": "function",
2828
3183
  "overrides": [],
@@ -2850,12 +3205,35 @@
2850
3205
  "signature": "export class TracerPool3D { … }",
2851
3206
  "situations": [
2852
3207
  "show where a hitscan round went",
3208
+ "show each round a weapon fires, one tracer per trigger press",
2853
3209
  "draw incoming fire without spawning projectiles"
2854
3210
  ],
2855
3211
  "summary": "Pool travelling bullet-streak meshes for hitscan shots.",
2856
3212
  "supersedes": [],
2857
3213
  "symbol": "TracerPool3D"
2858
3214
  },
3215
+ {
3216
+ "aliases": [],
3217
+ "constraints": [
3218
+ "derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material",
3219
+ "it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision"
3220
+ ],
3221
+ "example": "defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky",
3222
+ "importPath": "@threenative/core",
3223
+ "kind": "function",
3224
+ "overrides": [
3225
+ "`material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)"
3226
+ ],
3227
+ "package": "@threenative/core",
3228
+ "signature": "export function unlitFoliageWarning( scene: Object3D & { … }",
3229
+ "situations": [
3230
+ "catch the \"why does my forest look like cardboard\" question before a human plays it",
3231
+ "audit a scene a game built from imported GLB foliage"
3232
+ ],
3233
+ "summary": "Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.",
3234
+ "supersedes": [],
3235
+ "symbol": "unlitFoliageWarning"
3236
+ },
2859
3237
  {
2860
3238
  "aliases": [],
2861
3239
  "constraints": [
@@ -2863,7 +3241,7 @@
2863
3241
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2864
3242
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2865
3243
  ],
2866
- "example": "markStatic(island); invalidateStatic(drawbridge);",
3244
+ "example": "invalidateStatic(drawbridge);",
2867
3245
  "importPath": "@threenative/core",
2868
3246
  "kind": "function",
2869
3247
  "overrides": [],
@@ -2999,14 +3377,17 @@
2999
3377
  "constraints": [
3000
3378
  "the light must be a DirectionalLight with `castShadow` and a target in the scene",
3001
3379
  "clipExtents are half-widths in world units, finest first, strictly increasing",
3002
- "call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves"
3380
+ "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",
3381
+ "`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",
3382
+ "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"
3003
3383
  ],
3004
3384
  "example": "const sun = new DirectionalLight(0xffffff, 3);\nsun.castShadow = true;\nsun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });",
3005
3385
  "importPath": "@threenative/core",
3006
3386
  "kind": "class",
3007
3387
  "overrides": [
3008
3388
  "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",
3009
- "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults"
3389
+ "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults",
3390
+ "followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias"
3010
3391
  ],
3011
3392
  "package": "@threenative/core",
3012
3393
  "signature": "export class VirtualShadowNode extends ShadowBaseNode { … }",
@@ -3044,14 +3425,16 @@
3044
3425
  "the material must be transparent so the frame beneath it is already drawn",
3045
3426
  "thickness is metres, saturating at maxThickness; sky behind the surface reads deep",
3046
3427
  "one reflection is a second draw of the world; resolutionScale is its pixels only",
3047
- "on a crowded scene the mirrored pass is draw-bound: name reflection.layers or pay twice",
3428
+ "omitted reflection.layers automatically reflects terrain-sized surfaces and large non-instanced casters, excluding instanced/skinned props; TN_WATER_REFLECTION_DEFAULT reports the set once",
3048
3429
  "reflection.refreshInterval is in presented frames; 1 is every frame, and the default",
3049
3430
  "the mirror plane is level, from level alone; do not parent target to a scaled mesh"
3050
3431
  ],
3051
- "example": "const REFLECTED = 1; // the layer the big silhouettes sit on\nconst surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });\nmaterial.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);",
3432
+ "example": "const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });\nmaterial.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);",
3052
3433
  "importPath": "@threenative/core",
3053
3434
  "kind": "class",
3054
- "overrides": [],
3435
+ "overrides": [
3436
+ "reflection.layers is an explicit Three Layers mask and wins over automatic filtering, including layer-0 mask 1; reflection.minSize overrides the default 10 metre minimum extent"
3437
+ ],
3055
3438
  "package": "@threenative/core",
3056
3439
  "signature": "export class WaterSurface3D { … }",
3057
3440
  "situations": [
@@ -3060,7 +3443,8 @@
3060
3443
  "know how deep the water is under a pixel without a second render pass",
3061
3444
  "stop a water surface repeating in visible bands or stripes",
3062
3445
  "keep a crowd of small actors out of the water's reflection so the frame can afford it",
3063
- "stop the water reflection redrawing the whole world every frame"
3446
+ "stop the water reflection redrawing the whole world every frame",
3447
+ "automatically reflect terrain and large casters without redrawing instanced small props"
3064
3448
  ],
3065
3449
  "summary": "Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres of water between them.",
3066
3450
  "supersedes": [],
@@ -3200,6 +3584,27 @@
3200
3584
  "supersedes": [],
3201
3585
  "symbol": "playtest"
3202
3586
  },
3587
+ {
3588
+ "aliases": [],
3589
+ "constraints": [
3590
+ "desktop only, and the game host must be built with the CSS backend (`TN_ENABLE_CSS_UI=1`); Android, iOS and web phones render a React HUD in a web overlay instead",
3591
+ "import `react`, never `react-dom`, from a native entry",
3592
+ "styling is CSS resolved by the native engine; JS only mirrors the element tree"
3593
+ ],
3594
+ "example": "const root = createCssUiRoot();\nroot.render(createElement(\"section\", { className: \"fixed inset-0 bg-zinc-900/90\" }, \"READY\"));",
3595
+ "importPath": "@threenative/core/react-css",
3596
+ "kind": "function",
3597
+ "overrides": [],
3598
+ "package": "@threenative/core",
3599
+ "signature": "export function createCssUiRoot(options: ICssUiRootOptions = { … }",
3600
+ "situations": [
3601
+ "mount a React HUD on the desktop host with no DOM in the runtime",
3602
+ "write one React component and run it on the web and on the desktop host"
3603
+ ],
3604
+ "summary": "Mount React into a native CSS engine.",
3605
+ "supersedes": [],
3606
+ "symbol": "createCssUiRoot"
3607
+ },
3203
3608
  {
3204
3609
  "aliases": [],
3205
3610
  "constraints": [
@@ -3409,6 +3814,22 @@
3409
3814
  "supersedes": [],
3410
3815
  "symbol": "subscribeUiState"
3411
3816
  },
3817
+ {
3818
+ "aliases": [],
3819
+ "constraints": [
3820
+ "the returned view aliases the caller's buffer; writing to it mutates the source"
3821
+ ],
3822
+ "example": "const records = cellPlacements(buffer, { asset: \"tree\", offset: 0, count: 120 });",
3823
+ "importPath": "@threenative/core/world",
3824
+ "kind": "function",
3825
+ "overrides": [],
3826
+ "package": "@threenative/core",
3827
+ "signature": "export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }",
3828
+ "situations": ["feed one cell's instance transforms into a batch without copying"],
3829
+ "summary": "Borrow the run's placement records as a live view over the placement buffer.",
3830
+ "supersedes": [],
3831
+ "symbol": "cellPlacements"
3832
+ },
3412
3833
  {
3413
3834
  "aliases": [],
3414
3835
  "constraints": [
@@ -3449,43 +3870,314 @@
3449
3870
  "generate a terrain a player can walk across",
3450
3871
  "query the same ground height or normal that a player sees and collides with",
3451
3872
  "ask how high the ground is here",
3452
- "build islands and coastlines from terrain"
3873
+ "build islands and coastlines from terrain",
3874
+ "keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)"
3453
3875
  ],
3454
3876
  "summary": "One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.",
3455
3877
  "supersedes": [],
3456
3878
  "symbol": "Heightfield"
3457
3879
  },
3458
3880
  {
3459
- "aliases": ["stream terrain across chunks"],
3881
+ "aliases": [],
3460
3882
  "constraints": [
3461
- "sampleHeight and surface are required game choices; no landform or surface preset is installed",
3462
- "residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws"
3883
+ "the sampler reads the game's data; the framework never selects a terrain shape"
3463
3884
  ],
3464
- "example": "const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });",
3885
+ "example": "const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));",
3465
3886
  "importPath": "@threenative/core/world",
3466
- "kind": "class",
3467
- "overrides": [
3468
- "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets"
3469
- ],
3887
+ "kind": "function",
3888
+ "overrides": [],
3470
3889
  "package": "@threenative/core",
3471
- "signature": "export class TerrainTiles extends Object3D implements IComputeDriven { … }",
3890
+ "signature": "export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWorldExtent, data: Uint16Array, ): (x: number, z: number) => number { … }",
3472
3891
  "situations": [
3473
- "stream terrain without cracks",
3474
- "keep generated terrain resident around a moving player",
3475
- "put a generated terrain tile into a game-owned physics world"
3892
+ "turn an exported raw heightmap into terrain collision and rendering",
3893
+ "query ground height from a Blender-authored world package"
3894
+ ],
3895
+ "summary": "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)`.",
3896
+ "supersedes": [],
3897
+ "symbol": "heightSamplerFromHeightmap"
3898
+ },
3899
+ {
3900
+ "aliases": [],
3901
+ "constraints": [
3902
+ "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",
3903
+ "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"
3904
+ ],
3905
+ "example": "const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: \"world/world.json\" });\nconst world = await WorldCells.load({ assets: ctx.assets, url: \"world/world.json\", surface, follow, ring: 2 });",
3906
+ "importPath": "@threenative/core/world",
3907
+ "kind": "function",
3908
+ "overrides": [
3909
+ "every value comes from the package's table; the returned material is the game's to adjust"
3910
+ ],
3911
+ "package": "@threenative/core",
3912
+ "signature": "export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }",
3913
+ "situations": [
3914
+ "terrain textured by splat masks exported from Blender with the world package",
3915
+ "the game's terrain should match the DCC's terrain material without a second copy"
3916
+ ],
3917
+ "summary": "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.",
3918
+ "supersedes": [],
3919
+ "symbol": "loadTerrainSplat"
3920
+ },
3921
+ {
3922
+ "aliases": [],
3923
+ "constraints": ["a non-OK response throws; bytes are byte-swapped only on a big-endian host"],
3924
+ "example": "const data = await loadWorldHeightmap(\"/world/terrain/heightmap.u16\");",
3925
+ "importPath": "@threenative/core/world",
3926
+ "kind": "function",
3927
+ "overrides": [],
3928
+ "package": "@threenative/core",
3929
+ "signature": "export async function loadWorldHeightmap(url: string): Promise<Uint16Array> { … }",
3930
+ "situations": ["load a world package's heightmap once before building terrain"],
3931
+ "summary": "Fetch a raw little-endian uint16 heightmap and expose it as samples.",
3932
+ "supersedes": [],
3933
+ "symbol": "loadWorldHeightmap"
3934
+ },
3935
+ {
3936
+ "aliases": [],
3937
+ "constraints": ["radius is metres; the footprint never grows with load, only deeper"],
3938
+ "example": "const footprint = snowDiscFootprint(0.25);",
3939
+ "importPath": "@threenative/core/world",
3940
+ "kind": "function",
3941
+ "overrides": ["softness widens the eased edge without changing the contact radius"],
3942
+ "package": "@threenative/core",
3943
+ "signature": "export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }",
3944
+ "situations": [
3945
+ "press a ball, wheel or probe into snow",
3946
+ "give a sphere a physically sized snow contact instead of a boot shape"
3947
+ ],
3948
+ "summary": "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.",
3949
+ "supersedes": [],
3950
+ "symbol": "snowDiscFootprint"
3951
+ },
3952
+ {
3953
+ "aliases": [],
3954
+ "constraints": [
3955
+ "the field composes onto a Heightfield; construct the terrain first and let this own the surface",
3956
+ "zero depth is bare ground: contacts register no indentation at all",
3957
+ "out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros"
3958
+ ],
3959
+ "example": "import { Heightfield } from \"@threenative/core/world\";\nconst terrain = Heightfield.fromSampler({ rows: 129, columns: 129, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: (x, z) => Math.sin(x * 0.1) * 0.5 });\nconst snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });\nsnow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });\nsnow.recover(1 / 60, 0.0012, 0.4);",
3960
+ "importPath": "@threenative/core/world",
3961
+ "kind": "class",
3962
+ "overrides": [
3963
+ "depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients"
3964
+ ],
3965
+ "package": "@threenative/core",
3966
+ "requires": ["@threenative/core/world Heightfield as the canonical terrain and surface"],
3967
+ "signature": "export class SnowField { … }",
3968
+ "situations": [
3969
+ "leave footprints, tracks and tyre ruts in snow that persist and fill in over time",
3970
+ "let a pushed sphere carve a connected track and a dropped one settle into a crater",
3971
+ "store snow deformation that rendered geometry and collision both read",
3972
+ "reset a snowfield between rounds or change its depth at runtime",
3973
+ "show how packed the snow is where people have walked or objects have rested"
3974
+ ],
3975
+ "summary": "Persistent snow deformation over one canonical heightfield. Snow keeps four channels per cell — indentation, displaced bank, compaction and disturbance — and writes the combined surface (`terrain + depth + bank - indent`) back into the heightfield it was given. Queries, rendered geometry and collider export therefore all read one surface, and no second terrain representation exists. The field is numeric only: it never chooses a boot, a tread, a particle, a material or a camera. Games supply terrain heights, the snow depth, the contact profile and the response coefficients; this class owns the storage, the load-dependent penetration and the bounded recovery. It is a heightfield approximation — not granular snow, displaced-volume conservation, avalanches, melting or a calibrated material law.",
3976
+ "supersedes": [],
3977
+ "symbol": "SnowField"
3978
+ },
3979
+ {
3980
+ "aliases": ["stream terrain across chunks"],
3981
+ "constraints": [
3982
+ "sampleHeight and surface are required game choices; no landform or surface preset is installed",
3983
+ "residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws",
3984
+ "seam gap, LOD pop and the rendered-vertex finiteness scan are measurements that are off by default; TN_TERRAIN_VALIDATE=1, ?tnTerrainValidate=1 or validate: true runs them, and maxSeamGap, maxVisualSeamGap and maxLodPop report undefined while they are off"
3985
+ ],
3986
+ "example": "const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });",
3987
+ "importPath": "@threenative/core/world",
3988
+ "kind": "class",
3989
+ "overrides": [
3990
+ "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets"
3991
+ ],
3992
+ "package": "@threenative/core",
3993
+ "signature": "export class TerrainTiles extends Object3D implements IComputeDriven { … }",
3994
+ "situations": [
3995
+ "stream terrain without cracks",
3996
+ "keep generated terrain resident around a moving player",
3997
+ "put a generated terrain tile into a game-owned physics world"
3476
3998
  ],
3477
3999
  "summary": "Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.",
3478
4000
  "supersedes": [],
3479
4001
  "symbol": "TerrainTiles"
3480
4002
  },
4003
+ {
4004
+ "aliases": [],
4005
+ "constraints": ["off by default: it is the work it checks, every frame"],
4006
+ "example": "// Reads its own the way `renderListValidationRequested` does: a native launch sets the\n// environment variable, a browser asks with the query string, a test or harness sets the\n// global. `0` and `false` are off, so a saved URL that enabled it still says \"off\".\nconst tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });",
4007
+ "importPath": "@threenative/core/world",
4008
+ "kind": "function",
4009
+ "overrides": [],
4010
+ "package": "@threenative/core",
4011
+ "signature": "export function terrainValidationRequested(): boolean { … }",
4012
+ "situations": [
4013
+ "turn terrain's per-frame seam, LOD pop and vertex checks on for one run",
4014
+ "assert the terrain geometry a game streams before it ships"
4015
+ ],
4016
+ "summary": "Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.",
4017
+ "supersedes": [],
4018
+ "symbol": "terrainValidationRequested"
4019
+ },
4020
+ {
4021
+ "aliases": [],
4022
+ "constraints": [
4023
+ "validation only checks structure and ranges; it never fetches the heightmap or GLBs"
4024
+ ],
4025
+ "example": "const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });",
4026
+ "importPath": "@threenative/core/world",
4027
+ "kind": "function",
4028
+ "overrides": [],
4029
+ "package": "@threenative/core",
4030
+ "signature": "export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }",
4031
+ "situations": [
4032
+ "check a Blender-exported world package before the runtime attaches anything",
4033
+ "report why a world package cannot be streamed"
4034
+ ],
4035
+ "summary": "Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.",
4036
+ "supersedes": [],
4037
+ "symbol": "validateWorldPackage"
4038
+ },
4039
+ {
4040
+ "aliases": [],
4041
+ "constraints": [
4042
+ "surface is the game's; this class creates no material, colour or geometry",
4043
+ "budgets are hard caps that report pressure instead of over-committing",
4044
+ "model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell",
4045
+ "refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first",
4046
+ "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",
4047
+ "SkinnedMesh parts are skipped; an instanced copy would draw one rest pose",
4048
+ "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",
4049
+ "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",
4050
+ "`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",
4051
+ "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",
4052
+ "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",
4053
+ "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",
4054
+ "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",
4055
+ "`shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed"
4056
+ ],
4057
+ "example": "const world = await WorldCells.load({ url: \"/world/world.json\", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });\nscene.add(world);\nworld.update();",
4058
+ "importPath": "@threenative/core/world",
4059
+ "kind": "class",
4060
+ "overrides": [
4061
+ "`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"
4062
+ ],
4063
+ "package": "@threenative/core",
4064
+ "signature": "export class WorldCells extends Group implements IComputeDriven { … }",
4065
+ "situations": [
4066
+ "stream a large Blender-authored world by cell instead of one huge GLB",
4067
+ "keep scattered props and hand-placed chunks resident around a moving player",
4068
+ "honour per-asset draw distances and hard streaming budgets without a mid-frame throw"
4069
+ ],
4070
+ "summary": "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.",
4071
+ "supersedes": [],
4072
+ "symbol": "WorldCells"
4073
+ },
4074
+ {
4075
+ "aliases": [],
4076
+ "constraints": [
4077
+ "absolute paths, Windows drive letters, backslashes and any `..` segment throw MetaHumanAssetError with TN_MH_PATH_ESCAPE before the path is joined onto a root"
4078
+ ],
4079
+ "example": "assertAssetPath(\"metahuman/specimen.glb\");",
4080
+ "importPath": "@threenative/metahuman",
4081
+ "kind": "function",
4082
+ "overrides": [],
4083
+ "package": "@threenative/metahuman",
4084
+ "requires": ["npm i @threenative/metahuman"],
4085
+ "signature": "export function assertAssetPath(path: string): string { … }",
4086
+ "situations": ["reject a MetaHuman asset path that would read outside the game's asset root"],
4087
+ "summary": "Keeps a caller-supplied asset path inside the asset directory.",
4088
+ "supersedes": [],
4089
+ "symbol": "assertAssetPath"
4090
+ },
4091
+ {
4092
+ "aliases": [],
4093
+ "constraints": [
4094
+ "the model is loaded through the game's own asset loader and cloned per instance, so",
4095
+ "the rig's own GUI-to-raw mapping runs; the adapter never re-derives it, and a LOD",
4096
+ "an undeclared control, an out-of-domain value, an undeclared LOD and any call after",
4097
+ "in a native host that installed the MetaHuman resident the C++ evaluator runs and"
4098
+ ],
4099
+ "example": "const human = await loadMetaHuman({ assets: ctx.assets, model: \"metahuman/head.glb\",\n dna: \"metahuman/head.dna\", bindings: \"metahuman/bindings.json\" });\n human.setControls({ jawOpen: 0.4 });\n// in the scene update, after any body animation\n human.update();",
4100
+ "importPath": "@threenative/metahuman",
4101
+ "kind": "function",
4102
+ "overrides": [],
4103
+ "package": "@threenative/metahuman",
4104
+ "requires": ["npm i @threenative/metahuman"],
4105
+ "signature": "loadMetaHuman = (options: ILoadMetaHumanOptions): Promise<IMetaHuman> => createMetaHuman( { … }",
4106
+ "situations": [
4107
+ "put a MetaHuman head in a browser game without an Unreal import or a baked clip"
4108
+ ],
4109
+ "summary": "Load a prepared MetaHuman head and drive its expression from the browser's WASM evaluator: declared faceboard controls in, joint deltas and morph weights out, applied to an ordinary Three.js object graph. two characters never write each other's face and nothing is disposed that `ctx.assets` still owns switch re-evaluates the current controls before the replacement mesh is shown `dispose()` throw, each with a stable `code`; nothing is clamped or coerced `diagnostics().backend` reads \"native\"; the game code does not change",
4110
+ "supersedes": [],
4111
+ "symbol": "loadMetaHuman"
4112
+ },
4113
+ {
4114
+ "aliases": [],
4115
+ "constraints": ["`code` is part of the public surface; renaming one is a breaking change"],
4116
+ "example": "if (error instanceof MetaHumanAssetError && error.code === \"TN_MH_HASH_MISMATCH\") refetch();",
4117
+ "importPath": "@threenative/metahuman",
4118
+ "kind": "class",
4119
+ "overrides": [],
4120
+ "package": "@threenative/metahuman",
4121
+ "requires": ["npm i @threenative/metahuman"],
4122
+ "signature": "export class MetaHumanAssetError extends Error { … }",
4123
+ "situations": ["branch on why a MetaHuman asset or evaluator call was refused"],
4124
+ "summary": "The rejection every check in this package raises, carrying a stable machine-readable code.",
4125
+ "supersedes": [],
4126
+ "symbol": "MetaHumanAssetError"
4127
+ },
4128
+ {
4129
+ "aliases": [],
4130
+ "constraints": [
4131
+ "the binary's SHA-256 is checked against the shipped manifest before it is",
4132
+ "every returned array is a copy, so no view survives a memory growth; a disposed",
4133
+ "a native host that installed the MetaHuman resident gets its C++ evaluator from"
4134
+ ],
4135
+ "example": "const rig = await RigEvaluator.create(dna); rig.setGuiControls(gui); rig.evaluate(true); rig.jointOutputs();",
4136
+ "importPath": "@threenative/metahuman",
4137
+ "kind": "class",
4138
+ "overrides": [],
4139
+ "package": "@threenative/metahuman",
4140
+ "requires": ["npm i @threenative/metahuman"],
4141
+ "signature": "export class RigEvaluator implements IRigEvaluator { … }",
4142
+ "situations": [
4143
+ "drive a prepared MetaHuman head's expression from the browser without an Unreal import"
4144
+ ],
4145
+ "summary": "One MetaHuman head rig over the checksum-verified browser WASM build of the shared OpenRigLogic ABI: faceboard GUI controls in, joint deltas, blend shape weights and animated map weights out. instantiated, and nothing is fetched from a CDN evaluator throws instead of reading freed memory `create` and the WASM is never fetched; `RigEvaluator.backend()` says which one runs",
4146
+ "supersedes": [],
4147
+ "symbol": "RigEvaluator"
4148
+ },
4149
+ {
4150
+ "aliases": [],
4151
+ "constraints": [
4152
+ "fails closed: a missing key, a wrong type, a hash that differs from the bytes on",
4153
+ "reads the rig's real names and the GLB's real node, mesh and target counts, so it"
4154
+ ],
4155
+ "example": "const bindings = validateMetaHumanAssets({ bindings: parsed, dnaSha256, glbSha256, rig, gltf });",
4156
+ "importPath": "@threenative/metahuman",
4157
+ "kind": "function",
4158
+ "overrides": [],
4159
+ "package": "@threenative/metahuman",
4160
+ "requires": ["npm i @threenative/metahuman"],
4161
+ "signature": "export function validateMetaHumanAssets(input: IMetaHumanAssetInput): IMetaHumanBindings { … }",
4162
+ "situations": [
4163
+ "refuse a MetaHuman specimen whose bindings point at joints, nodes, blend shape"
4164
+ ],
4165
+ "summary": "Checks one prepared specimen — bindings sidecar, DNA and GLB — against the rig it claims to drive, and returns the bindings only when every name, index, domain and hash holds up. channels, morph targets or LODs the loaded files do not contain disk and an index past the end of its array are rejections, each with a stable code cannot pass a hand-written sidecar the rig cannot drive",
4166
+ "supersedes": [],
4167
+ "symbol": "validateMetaHumanAssets"
4168
+ },
3481
4169
  {
3482
4170
  "aliases": ["pick up item"],
3483
4171
  "constraints": ["add the area to the physics context before stepping the world"],
4172
+ "deprecated": [
4173
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated."
4174
+ ],
3484
4175
  "example": "const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });",
3485
4176
  "importPath": "@threenative/physics",
3486
4177
  "kind": "class",
3487
4178
  "overrides": [],
3488
4179
  "package": "@threenative/physics",
4180
+ "requires": ["npm i @threenative/physics"],
3489
4181
  "signature": "export class Area3D { … }",
3490
4182
  "situations": [
3491
4183
  "detect when an enemy enters a trigger area",
@@ -3495,6 +4187,52 @@
3495
4187
  "supersedes": [],
3496
4188
  "symbol": "Area3D"
3497
4189
  },
4190
+ {
4191
+ "aliases": [],
4192
+ "constraints": [
4193
+ "register `rapier()` before attaching, and call `step` once per fixed step after the physics step",
4194
+ "the backend must expose persistent solved contacts and in-place shape refresh; one that does not fails at attach",
4195
+ "verified on browser WebGPU and the native Linux desktop host; Android and iOS share the native seam but have not run it",
4196
+ "automatic profiles cover sphere, box and capsule; any other shape needs an explicit footprint"
4197
+ ],
4198
+ "example": "const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });\nafterPhysics(ctx, (dt) => snowPhysics.step(dt));",
4199
+ "importPath": "@threenative/physics",
4200
+ "kind": "function",
4201
+ "overrides": [
4202
+ "loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour"
4203
+ ],
4204
+ "package": "@threenative/physics",
4205
+ "requires": ["@threenative/core/world SnowField as the surface it deforms"],
4206
+ "signature": "export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }",
4207
+ "situations": [
4208
+ "leave footprints and tracks where physical bodies actually touch snow",
4209
+ "let a dropped or pushed sphere carve and settle into deformable snow",
4210
+ "make a crate, capsule or ball compress the surface it rests on"
4211
+ ],
4212
+ "summary": "Drive a `SnowField` from real solved contacts. The binding creates the snow surface collider from the field's own canonical samples and keeps it in step with them, so a body lands on the surface a query would report. Each fixed step it reads the solver's persistent contacts — not collision start/stop events, which carry no point or load — deforms the snow only where a contact is supported and loaded downward, then republishes the surface before the next step. Airborne bodies, side contacts and unrelated colliders never deform anything. A dropped sphere settles on the surface it made; a pushed one rotates and carves a connected track without its transform being copied anywhere. Footprints come from the body's own collision shape and orientation unless the game supplies one. Contact load is `impulse / deltaTime * loadScale`: a solver impulse over a step, which estimates a contact force and is not measured. `observe().loadProvenance` says so.",
4213
+ "supersedes": [],
4214
+ "symbol": "attachSnowPhysics"
4215
+ },
4216
+ {
4217
+ "aliases": [],
4218
+ "constraints": [
4219
+ "halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint"
4220
+ ],
4221
+ "example": "const footprint = boxFootprint(0.4, 0.25);",
4222
+ "importPath": "@threenative/physics",
4223
+ "kind": "function",
4224
+ "overrides": [],
4225
+ "package": "@threenative/physics",
4226
+ "requires": ["npm i @threenative/physics"],
4227
+ "signature": "export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }",
4228
+ "situations": [
4229
+ "let a crate, platform or plank press a rectangular pit into snow",
4230
+ "imprint a box's own footprint rather than a circle around it"
4231
+ ],
4232
+ "summary": "A rectangular contact: the face a box rests on, in the contact's own frame. Coverage is full across the face and fades just outside it; the bank rises beyond that.",
4233
+ "supersedes": [],
4234
+ "symbol": "boxFootprint"
4235
+ },
3498
4236
  {
3499
4237
  "aliases": [],
3500
4238
  "constraints": [
@@ -3506,6 +4244,7 @@
3506
4244
  "kind": "function",
3507
4245
  "overrides": [],
3508
4246
  "package": "@threenative/physics",
4247
+ "requires": ["npm i @threenative/physics"],
3509
4248
  "signature": "export function buildStaticColliders( context: IStaticColliderContext, root: Object3D, filter?: StaticColliderFilter, ): readonly RigidBody3D[] { … }",
3510
4249
  "situations": [
3511
4250
  "make the level I built stop the player",
@@ -3523,12 +4262,31 @@
3523
4262
  "kind": "class",
3524
4263
  "overrides": ["buoyancy disables force application while submergedFraction remains measured"],
3525
4264
  "package": "@threenative/physics",
4265
+ "requires": ["npm i @threenative/physics"],
3526
4266
  "signature": "export class Buoyancy3D { … }",
3527
4267
  "situations": ["float a boat on waves", "keep a hull above a moving water surface"],
3528
4268
  "summary": "Float a rigid body on a game-owned height source with fixed-step force ordering.",
3529
4269
  "supersedes": [],
3530
4270
  "symbol": "Buoyancy3D"
3531
4271
  },
4272
+ {
4273
+ "aliases": [],
4274
+ "constraints": ["radius and halfHeight are metres and never grow with load"],
4275
+ "example": "const footprint = capsuleFootprint(0.5, 0.2);",
4276
+ "importPath": "@threenative/physics",
4277
+ "kind": "function",
4278
+ "overrides": [],
4279
+ "package": "@threenative/physics",
4280
+ "requires": ["npm i @threenative/physics"],
4281
+ "signature": "export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }",
4282
+ "situations": [
4283
+ "let a fallen capsule, limb or barrel leave a linear imprint in snow",
4284
+ "give a capsule a shape-appropriate snow contact instead of a sphere's dot"
4285
+ ],
4286
+ "summary": "A stadium contact: a rectangle of half-length `halfHeight` and half-width `radius`, capped by two half-discs of `radius`. The shape a capsule lies on, so a knocked-over body sinks along a line instead of at a point. Coverage is full across the body's own width and fades just outside it, so the body's edge never rests on a half-pressed rim; the bank rises beyond that.",
4287
+ "supersedes": [],
4288
+ "symbol": "capsuleFootprint"
4289
+ },
3532
4290
  {
3533
4291
  "aliases": [
3534
4292
  "raised platform gap hazard restart",
@@ -3538,11 +4296,15 @@
3538
4296
  "run jump coins goal"
3539
4297
  ],
3540
4298
  "constraints": ["use moveAndSlide inside the physics update"],
4299
+ "deprecated": [
4300
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated."
4301
+ ],
3541
4302
  "example": "const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });",
3542
4303
  "importPath": "@threenative/physics",
3543
4304
  "kind": "class",
3544
4305
  "overrides": [],
3545
4306
  "package": "@threenative/physics",
4307
+ "requires": ["npm i @threenative/physics"],
3546
4308
  "signature": "export class CharacterBody3D { … }",
3547
4309
  "situations": [
3548
4310
  "move an enemy or player through a level",
@@ -3560,6 +4322,7 @@
3560
4322
  "kind": "class",
3561
4323
  "overrides": [],
3562
4324
  "package": "@threenative/physics",
4325
+ "requires": ["npm i @threenative/physics"],
3563
4326
  "signature": "export class CollisionShape3D { … }",
3564
4327
  "situations": [
3565
4328
  "add a capsule or box collider to a character",
@@ -3577,6 +4340,7 @@
3577
4340
  "kind": "function",
3578
4341
  "overrides": [],
3579
4342
  "package": "@threenative/physics",
4343
+ "requires": ["npm i @threenative/physics"],
3580
4344
  "signature": "export function interactionGroups(layer: number, mask: number): number { … }",
3581
4345
  "situations": [
3582
4346
  "make an enemy collide with the world but not pickups",
@@ -3589,11 +4353,15 @@
3589
4353
  {
3590
4354
  "aliases": [],
3591
4355
  "constraints": ["both bodies must belong to the same physics context"],
4356
+ "deprecated": [
4357
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated."
4358
+ ],
3592
4359
  "example": "const hinge = Joint3D.hinge({ physics: ctx.physics, bodyA: beam, bodyB: bob, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: 0, y: 2.4, z: 0 }, axis: { x: 1, y: 0, z: 0 } });",
3593
4360
  "importPath": "@threenative/physics",
3594
4361
  "kind": "class",
3595
4362
  "overrides": [],
3596
4363
  "package": "@threenative/physics",
4364
+ "requires": ["npm i @threenative/physics"],
3597
4365
  "signature": "export class Joint3D { … }",
3598
4366
  "situations": [
3599
4367
  "constrain a rigid body to another body",
@@ -3612,6 +4380,7 @@
3612
4380
  "kind": "class",
3613
4381
  "overrides": [],
3614
4382
  "package": "@threenative/physics",
4383
+ "requires": ["npm i @threenative/physics"],
3615
4384
  "signature": "export class PhysicsDirectSpaceState3D { … }",
3616
4385
  "situations": [
3617
4386
  "raycast for visibility or aiming",
@@ -3629,6 +4398,7 @@
3629
4398
  "kind": "function",
3630
4399
  "overrides": [],
3631
4400
  "package": "@threenative/physics",
4401
+ "requires": ["npm i @threenative/physics"],
3632
4402
  "signature": "export function rapier(options: IPhysicsOptions = { … }",
3633
4403
  "situations": [
3634
4404
  "add physics to a portable game",
@@ -3641,6 +4411,9 @@
3641
4411
  {
3642
4412
  "aliases": [],
3643
4413
  "constraints": ["register rapier() in the game plugin list before using bodies"],
4414
+ "deprecated": [
4415
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated."
4416
+ ],
3644
4417
  "example": "const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });",
3645
4418
  "importPath": "@threenative/physics",
3646
4419
  "kind": "class",
@@ -3648,6 +4421,7 @@
3648
4421
  "continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting"
3649
4422
  ],
3650
4423
  "package": "@threenative/physics",
4424
+ "requires": ["npm i @threenative/physics"],
3651
4425
  "signature": "export class RigidBody3D { … }",
3652
4426
  "situations": [
3653
4427
  "give a crate or prop physical motion",
@@ -3671,6 +4445,7 @@
3671
4445
  "kind": "function",
3672
4446
  "overrides": [],
3673
4447
  "package": "@threenative/physics",
4448
+ "requires": ["npm i @threenative/physics"],
3674
4449
  "signature": "export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyCollision { … }",
3675
4450
  "situations": [
3676
4451
  "stop a cloth flag, cape, or curtain at an existing physics wall",
@@ -3680,6 +4455,35 @@
3680
4455
  "supersedes": [],
3681
4456
  "symbol": "softBodyCollision"
3682
4457
  },
4458
+ {
4459
+ "aliases": [
4460
+ "racing car racing kart drift vehicle go-kart",
4461
+ "suspension wheel traction tyre grip",
4462
+ "accelerator pedal handbrake steering wheel",
4463
+ "rescue respawn flip back on track"
4464
+ ],
4465
+ "constraints": [
4466
+ "write engineForce, brake and steering every physics update; a car with no input does not move",
4467
+ "suspensionStiffness is a frequency squared, not newtons per metre; 100 is a road car and 20 bottoms out"
4468
+ ],
4469
+ "example": "const car = new VehicleBody3D({ object: chassis, physics: ctx.physics, shape: CollisionShape3D.box(1.6, 0.5, 3.6), mass: 900, wheels: [{ position: { x: 0.8, y: -0.15, z: -1.2 }, wheelRadius: 0.34, suspensionRestLength: 0.3, suspensionStiffness: 100, dampingCompression: 2.3, dampingRelaxation: 4.4, wheelFrictionSlip: 10.5, maxSuspensionTravel: 0.3, useAsSteering: true, useAsTraction: false }] });",
4470
+ "importPath": "@threenative/physics",
4471
+ "kind": "class",
4472
+ "overrides": [
4473
+ "a wheel ray never hits the chassis it hangs from, and it honours the chassis collision mask",
4474
+ "continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall"
4475
+ ],
4476
+ "package": "@threenative/physics",
4477
+ "requires": ["npm i @threenative/physics"],
4478
+ "signature": "export class VehicleBody3D extends RigidBody3D { … }",
4479
+ "situations": [
4480
+ "drive a car, truck or bike around a track",
4481
+ "make a vehicle roll over kerbs, brake into a corner or stop at a wall"
4482
+ ],
4483
+ "summary": "Drive a car on ray-cast suspension instead of faking speed and heading.",
4484
+ "supersedes": [],
4485
+ "symbol": "VehicleBody3D"
4486
+ },
3683
4487
  {
3684
4488
  "aliases": ["close engagement range"],
3685
4489
  "constraints": [
@@ -3690,6 +4494,7 @@
3690
4494
  "kind": "class",
3691
4495
  "overrides": [],
3692
4496
  "package": "@threenative/physics",
4497
+ "requires": ["npm i @threenative/physics"],
3693
4498
  "signature": "export class NavigationAgent3D { … }",
3694
4499
  "situations": [
3695
4500
  "enemy walks around a wall",
@@ -3712,6 +4517,7 @@
3712
4517
  "kind": "class",
3713
4518
  "overrides": [],
3714
4519
  "package": "@threenative/physics",
4520
+ "requires": ["npm i @threenative/physics"],
3715
4521
  "signature": "export class NavigationObstacle3D { … }",
3716
4522
  "situations": [
3717
4523
  "keep navigation agents away from a blocking prop",
@@ -3729,6 +4535,7 @@
3729
4535
  "kind": "class",
3730
4536
  "overrides": [],
3731
4537
  "package": "@threenative/physics",
4538
+ "requires": ["npm i @threenative/physics"],
3732
4539
  "signature": "export class NavigationRegion3D { … }",
3733
4540
  "situations": [
3734
4541
  "let enemies walk around level geometry",
@@ -3746,6 +4553,7 @@
3746
4553
  "kind": "function",
3747
4554
  "overrides": [],
3748
4555
  "package": "@threenative/physics",
4556
+ "requires": ["npm i @threenative/physics"],
3749
4557
  "signature": "export function recast(): NavigationPlugin { … }",
3750
4558
  "situations": ["enemy walks around a wall", "NPC patrols a level and chases a player"],
3751
4559
  "summary": "Install navmesh pathfinding and crowd avoidance.",
@@ -4139,6 +4947,37 @@
4139
4947
  "supersedes": [],
4140
4948
  "symbol": "assertCaptureNotBlank"
4141
4949
  },
4950
+ {
4951
+ "aliases": [],
4952
+ "constraints": ["keeps the uniform-frame checks and replaces only the bright-pixel floor"],
4953
+ "example": "assertDesktopCaptureNotBlank(png, \"panned-culled.png\");",
4954
+ "importPath": "@threenative/playtest/capture",
4955
+ "kind": "function",
4956
+ "overrides": [],
4957
+ "package": "@threenative/playtest",
4958
+ "signature": "export function assertDesktopCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }",
4959
+ "situations": ["guard a native desktop capture of a 3D scene"],
4960
+ "summary": "Fail closed when a desktop-host frame shows no rendered content. A native desktop frame has no HTML overlay, so the browser bright-pixel floor does not apply.",
4961
+ "supersedes": [],
4962
+ "symbol": "assertDesktopCaptureNotBlank"
4963
+ },
4964
+ {
4965
+ "aliases": [],
4966
+ "constraints": ["the assertion throws instead of returning a false pass"],
4967
+ "example": "assertFrameShowsSomething(png, \"first frame\");",
4968
+ "importPath": "@threenative/playtest/capture",
4969
+ "kind": "function",
4970
+ "overrides": [],
4971
+ "package": "@threenative/playtest",
4972
+ "signature": "assertFrameShowsSomething = assertCaptureNotBlank",
4973
+ "situations": [
4974
+ "guard a visual playtest against a blank frame",
4975
+ "prove a screenshot contains more than a loading surface"
4976
+ ],
4977
+ "summary": "Fail closed when a screenshot is blank or uniform.",
4978
+ "supersedes": [],
4979
+ "symbol": "assertFrameShowsSomething"
4980
+ },
4142
4981
  {
4143
4982
  "aliases": [],
4144
4983
  "constraints": [],
@@ -4156,6 +4995,20 @@
4156
4995
  "supersedes": [],
4157
4996
  "symbol": "CaptureGuardError"
4158
4997
  },
4998
+ {
4999
+ "aliases": [],
5000
+ "constraints": ["does not acquire another screenshot or alter frame timing"],
5001
+ "example": "collectRegionalTone(png, assertions, \"character\", \"posed\");",
5002
+ "importPath": "@threenative/playtest/capture",
5003
+ "kind": "function",
5004
+ "overrides": [],
5005
+ "package": "@threenative/playtest",
5006
+ "signature": "export function collectRegionalTone( png: Buffer, assertions: readonly IPlaytestToneAssertion[], label: string, atStep?: string, ): IPlaytestRegionalToneObservation[] { … }",
5007
+ "situations": ["measure a specified pixel crop in a captured playtest frame"],
5008
+ "summary": "Collect opt-in regional tone observations from the same acquired PNG.",
5009
+ "supersedes": [],
5010
+ "symbol": "collectRegionalTone"
5011
+ },
4159
5012
  {
4160
5013
  "aliases": [],
4161
5014
  "constraints": [],
@@ -4205,6 +5058,24 @@
4205
5058
  "supersedes": [],
4206
5059
  "symbol": "jsonByteLength"
4207
5060
  },
5061
+ {
5062
+ "aliases": [],
5063
+ "constraints": [
5064
+ "throws on an unrecognised value instead of falling back to a fixed-step run"
5065
+ ],
5066
+ "example": "if (requestedPlaytestClockMode() === \"wall-clock\") host.pumpDrivesTheSimulation();",
5067
+ "importPath": "@threenative/playtest/protocol",
5068
+ "kind": "function",
5069
+ "overrides": [],
5070
+ "package": "@threenative/playtest",
5071
+ "signature": "export function requestedPlaytestClockMode(): PlaytestClockMode | undefined { … }",
5072
+ "situations": [
5073
+ "report which clock a playtest producer is really running on, before judging its ticks"
5074
+ ],
5075
+ "summary": "The clock the host asked for, or `undefined` for the default deterministic run. `wall-clock` is the production profile's opt-in and the only one this protocol has. An unrecognised value throws instead of falling back, because a misspelling that quietly left the loop frozen would publish a frame rate for a game that was not playing. Read at the moment it is needed rather than once at install: a request that arrives after the producer was installed is still a request, and a producer that missed it would judge a live frame pump by a count it never asked for.",
5076
+ "supersedes": [],
5077
+ "symbol": "requestedPlaytestClockMode"
5078
+ },
4208
5079
  {
4209
5080
  "aliases": [],
4210
5081
  "constraints": ["Android evidence must name its target and transport"],
@@ -4230,7 +5101,7 @@
4230
5101
  "kind": "function",
4231
5102
  "overrides": [],
4232
5103
  "package": "@threenative/playtest",
4233
- "signature": "export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, \"advance\">, ticks: number, ): Promise<void> { … }",
5104
+ "signature": "export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, \"advance\">, ticks: number, render = false, ): Promise<void> { … }",
4234
5105
  "situations": [
4235
5106
  "run a complete browser or device playtest",
4236
5107
  "capture diagnostics and screenshots from a managed server"
@@ -4409,35 +5280,66 @@
4409
5280
  "supersedes": [],
4410
5281
  "symbol": "connectPlaytestBridgeTransport"
4411
5282
  },
5283
+ {
5284
+ "aliases": [],
5285
+ "constraints": ["a private Xvfb is software, so a rate read there measures the X server"],
5286
+ "example": "import { decideDisplayStrategy } from \"@threenative/playtest/runner\";\nconst lane = decideDisplayStrategy({ env: process.env, platform: \"linux\" });\nif (lane.kind === \"private-xvfb\") throw new Error(\"refuse to judge this frame rate\");",
5287
+ "importPath": "@threenative/playtest/runner",
5288
+ "kind": "function",
5289
+ "overrides": [],
5290
+ "package": "@threenative/playtest",
5291
+ "signature": "export function decideDisplayStrategy(input: IDisplayDecisionInput): IDisplayStrategy { … }",
5292
+ "situations": ["judge whether a measured frame rate came from a display that can carry one"],
5293
+ "summary": "Decide which display a pixel-producing run paints on, the same decision the runner makes.",
5294
+ "supersedes": [],
5295
+ "symbol": "decideDisplayStrategy"
5296
+ },
4412
5297
  {
4413
5298
  "aliases": [],
4414
5299
  "constraints": ["the mailbox lifecycle must be disposed after the run"],
4415
5300
  "example": "const driver = new DesktopPlaytestDriver(options);",
4416
5301
  "importPath": "@threenative/playtest/runner",
4417
- "kind": "class",
5302
+ "kind": "function",
4418
5303
  "overrides": [],
4419
5304
  "package": "@threenative/playtest",
4420
- "signature": "export class DesktopPlaytestDriver implements IDevicePlaytestDriver { … }",
5305
+ "signature": "export function desktopConsoleType(stream: \"stderr\" | \"stdout\", line: string): string { … }",
4421
5306
  "situations": [
4422
5307
  "run a desktop target through the playtest protocol",
4423
5308
  "exchange observations with a native desktop host"
4424
5309
  ],
4425
5310
  "summary": "Drive a local desktop playtest mailbox.",
4426
5311
  "supersedes": [],
4427
- "symbol": "DesktopPlaytestDriver"
5312
+ "symbol": "desktopConsoleType"
4428
5313
  },
4429
5314
  {
4430
5315
  "aliases": [],
4431
- "constraints": ["paths stay inside the managed artifact directory"],
4432
- "example": "const paths = deviceMailboxPaths(projectRoot);",
5316
+ "constraints": ["the mailbox lifecycle must be disposed after the run"],
5317
+ "example": "const driver = new DesktopPlaytestDriver(options);",
4433
5318
  "importPath": "@threenative/playtest/runner",
4434
5319
  "kind": "class",
4435
5320
  "overrides": [],
4436
5321
  "package": "@threenative/playtest",
4437
- "signature": "export class DeviceBridgeTransport implements IDevicePlaytestTransport { … }",
5322
+ "signature": "export class DesktopPlaytestDriver implements IDevicePlaytestDriver { … }",
4438
5323
  "situations": [
4439
- "connect a native host to the playtest runner",
4440
- "validate an Android or iOS device endpoint"
5324
+ "run a desktop target through the playtest protocol",
5325
+ "exchange observations with a native desktop host"
5326
+ ],
5327
+ "summary": "Drive a local desktop playtest mailbox.",
5328
+ "supersedes": [],
5329
+ "symbol": "DesktopPlaytestDriver"
5330
+ },
5331
+ {
5332
+ "aliases": [],
5333
+ "constraints": ["paths stay inside the managed artifact directory"],
5334
+ "example": "const paths = deviceMailboxPaths(projectRoot);",
5335
+ "importPath": "@threenative/playtest/runner",
5336
+ "kind": "class",
5337
+ "overrides": [],
5338
+ "package": "@threenative/playtest",
5339
+ "signature": "export class DeviceBridgeTransport implements IDevicePlaytestTransport { … }",
5340
+ "situations": [
5341
+ "connect a native host to the playtest runner",
5342
+ "validate an Android or iOS device endpoint"
4441
5343
  ],
4442
5344
  "summary": "Resolve a native device transport and its mailbox paths.",
4443
5345
  "supersedes": [],
@@ -5446,6 +6348,125 @@
5446
6348
  "supersedes": [],
5447
6349
  "symbol": "ThreePlaytestPhysicsRecorder"
5448
6350
  },
6351
+ {
6352
+ "aliases": [],
6353
+ "constraints": [
6354
+ "identity parent required; material and motion are editable game source; no move/Mixer/composer writer exists"
6355
+ ],
6356
+ "example": "const wolf = createAnimalActor(bake, { motion, material, ground });",
6357
+ "importPath": "@threenative/procedural-animals",
6358
+ "kind": "function",
6359
+ "overrides": [],
6360
+ "package": "@threenative/procedural-animals",
6361
+ "requires": ["npm i @threenative/procedural-animals"],
6362
+ "signature": "export function createAnimalActor(bake: IAnimalBake, options: IAnimalActorOptions) { … }",
6363
+ "situations": ["follow a baked animal from accepted fixed-step Rapier state"],
6364
+ "summary": "Own one actor's pose/lifetime, accepting the completed physics state as its only root writer.",
6365
+ "supersedes": [],
6366
+ "symbol": "createAnimalActor"
6367
+ },
6368
+ {
6369
+ "aliases": [],
6370
+ "constraints": [
6371
+ "this creates bind geometry only; game-owned DQS material and animated bounds remain required"
6372
+ ],
6373
+ "example": "const { bake, geometry } = createAnimalGeometry(bytes);",
6374
+ "importPath": "@threenative/procedural-animals",
6375
+ "kind": "function",
6376
+ "overrides": [],
6377
+ "package": "@threenative/procedural-animals",
6378
+ "requires": ["npm i @threenative/procedural-animals"],
6379
+ "signature": "export function createAnimalGeometry(buffer: ArrayBuffer): { … }",
6380
+ "situations": ["construct a Three.js geometry from a validated procedural wolf bake"],
6381
+ "summary": "Validates all bytes before constructing geometry with the bake's skin and rig attributes.",
6382
+ "supersedes": [],
6383
+ "symbol": "createAnimalGeometry"
6384
+ },
6385
+ {
6386
+ "aliases": [],
6387
+ "constraints": ["a corrupt served bake rejects rather than falling back to a different file"],
6388
+ "example": "const bake = await loadAnimalBake(ctx.assets, \"wolf.animal\");",
6389
+ "importPath": "@threenative/procedural-animals",
6390
+ "kind": "function",
6391
+ "overrides": [],
6392
+ "package": "@threenative/procedural-animals",
6393
+ "requires": ["npm i @threenative/procedural-animals"],
6394
+ "signature": "export async function loadAnimalBake( assets: IAnimalAssetResolver, logicalPath: string, options: { … }",
6395
+ "situations": ["load a cooked animal from ctx.assets without runtime generation"],
6396
+ "summary": "Resolves and loads a prebuilt wolf through the game's ordinary asset resolver.",
6397
+ "supersedes": [],
6398
+ "symbol": "loadAnimalBake"
6399
+ },
6400
+ {
6401
+ "aliases": [],
6402
+ "constraints": [
6403
+ "unknown revisions, malformed sections, indices and skin weights throw by name"
6404
+ ],
6405
+ "example": "const bake = parseAnimalBake(bytes);",
6406
+ "importPath": "@threenative/procedural-animals",
6407
+ "kind": "function",
6408
+ "overrides": [],
6409
+ "package": "@threenative/procedural-animals",
6410
+ "requires": ["npm i @threenative/procedural-animals"],
6411
+ "signature": "export function parseAnimalBake(buffer: ArrayBuffer): IAnimalBake { … }",
6412
+ "situations": ["validate a baked procedural animal before allocating geometry"],
6413
+ "summary": "Validates a pinned wolf PANM bake before constructing any renderer resource.",
6414
+ "supersedes": [],
6415
+ "symbol": "parseAnimalBake"
6416
+ },
6417
+ {
6418
+ "aliases": [],
6419
+ "constraints": [
6420
+ "only .animal inputs are interpreted; corruption fails the cook, without regeneration"
6421
+ ],
6422
+ "example": "await compileAssets({ passes: [animalBakePass()] });",
6423
+ "importPath": "@threenative/procedural-animals/build",
6424
+ "kind": "function",
6425
+ "overrides": [],
6426
+ "package": "@threenative/procedural-animals",
6427
+ "requires": ["npm i @threenative/procedural-animals"],
6428
+ "signature": "export function animalBakePass() { … }",
6429
+ "situations": ["cook staged animal bakes through the ordinary asset pipeline"],
6430
+ "summary": "Validate staged PANM sources inside the existing asset compiler; it owns the hashed manifest.",
6431
+ "supersedes": [],
6432
+ "symbol": "animalBakePass"
6433
+ },
6434
+ {
6435
+ "aliases": [],
6436
+ "constraints": [
6437
+ "exact pinned Node runtime, donor revision, options and generated bytes are validated; no worker is created"
6438
+ ],
6439
+ "example": "const bytes = await bakeWolf({ seed: 7, tier: \"crowd\" });",
6440
+ "importPath": "@threenative/procedural-animals/build",
6441
+ "kind": "function",
6442
+ "overrides": [],
6443
+ "package": "@threenative/procedural-animals",
6444
+ "requires": ["npm i @threenative/procedural-animals"],
6445
+ "signature": "export async function bakeWolf(options: IWolfBakeOptions): Promise<ArrayBuffer> { … }",
6446
+ "situations": ["bake high and crowd wolf geometry before the ordinary asset cook"],
6447
+ "summary": "Bake the pinned wolf on the build machine, never on the portable runtime path.",
6448
+ "supersedes": [],
6449
+ "symbol": "bakeWolf"
6450
+ },
6451
+ {
6452
+ "aliases": [],
6453
+ "constraints": [
6454
+ "validation and generation complete before the destination is touched; temporary files are removed on failure"
6455
+ ],
6456
+ "example": "await bakeWolfToFile({ seed: 7, tier: \"crowd\" }, \"assets/wolf-crowd.animal\");",
6457
+ "importPath": "@threenative/procedural-animals/build",
6458
+ "kind": "function",
6459
+ "overrides": [],
6460
+ "package": "@threenative/procedural-animals",
6461
+ "requires": ["npm i @threenative/procedural-animals"],
6462
+ "signature": "export async function bakeWolfToFile( options: IWolfBakeOptions, destination: string, ): Promise<string> { … }",
6463
+ "situations": [
6464
+ "publish a generated wolf without replacing the last valid bake on interruption"
6465
+ ],
6466
+ "summary": "Stage a validated source bake with a same-directory atomic rename, then use compileAssets.",
6467
+ "supersedes": [],
6468
+ "symbol": "bakeWolfToFile"
6469
+ },
5449
6470
  {
5450
6471
  "aliases": [],
5451
6472
  "constraints": [
@@ -5896,6 +6917,776 @@
5896
6917
  "symbol": "sparkle",
5897
6918
  "aliases": []
5898
6919
  },
6920
+ {
6921
+ "aliases": [],
6922
+ "constraints": [
6923
+ "headless authoring; game applies transforms against its model bounds and actual terrain surface"
6924
+ ],
6925
+ "example": "const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});",
6926
+ "importPath": "@threenative/terrain",
6927
+ "kind": "function",
6928
+ "overrides": [
6929
+ "transform.grounding=false preserves requested Y while the game still measures clearance"
6930
+ ],
6931
+ "package": "@threenative/terrain",
6932
+ "requires": ["npm i -D @threenative/terrain"],
6933
+ "signature": "export function applyPlacementOverrides(state: ITerrainState, value: unknown): ITerrainState { … }",
6934
+ "situations": ["retain manual prop transforms across terrain scatter re-evaluation"],
6935
+ "summary": "Attach manual transforms to raw evaluated candidates and report orphan keys.",
6936
+ "supersedes": [],
6937
+ "symbol": "applyPlacementOverrides"
6938
+ },
6939
+ {
6940
+ "aliases": [],
6941
+ "constraints": [
6942
+ "no material is chosen; vertex colours exist only with a caller-supplied palette"
6943
+ ],
6944
+ "example": "const mesh = bakeMesh(new Terrain({ resolution: 17 }).evaluate());",
6945
+ "importPath": "@threenative/terrain",
6946
+ "kind": "function",
6947
+ "overrides": ["step, chunk bounds, skirtDepth and palette belong to the caller"],
6948
+ "package": "@threenative/terrain",
6949
+ "requires": ["npm i @threenative/terrain"],
6950
+ "signature": "export function bakeMesh( state: ITerrainState, { … }",
6951
+ "situations": ["bake an authored terrain into portable indexed mesh arrays"],
6952
+ "summary": "Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.",
6953
+ "supersedes": [],
6954
+ "symbol": "bakeMesh"
6955
+ },
6956
+ {
6957
+ "aliases": [],
6958
+ "constraints": [
6959
+ "collision origin is the southwest corner; engine Heightfield origin is its centre"
6960
+ ],
6961
+ "example": "const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCells: 64 });",
6962
+ "importPath": "@threenative/terrain",
6963
+ "kind": "function",
6964
+ "overrides": ["chunkCells, lodSteps, skirtDepth and palette are explicit authoring choices"],
6965
+ "package": "@threenative/terrain",
6966
+ "requires": ["npm i @threenative/terrain"],
6967
+ "signature": "export function bakeTerrain( state: ITerrainState, { … }",
6968
+ "situations": ["prepare terrain arrays and collision before a game starts"],
6969
+ "summary": "Bakes finite LOD chunks, the same collision samples and resolved placements.",
6970
+ "supersedes": [],
6971
+ "symbol": "bakeTerrain"
6972
+ },
6973
+ {
6974
+ "aliases": [],
6975
+ "constraints": [
6976
+ "headless authoring; no three, no DOM, and nothing here decides how the world looks"
6977
+ ],
6978
+ "example": "const { manifest, files } = bakeWorldPackage(state, { assets });",
6979
+ "importPath": "@threenative/terrain",
6980
+ "kind": "function",
6981
+ "overrides": [
6982
+ "every asset path, bound, LOD distance and cell size comes from the caller's options"
6983
+ ],
6984
+ "package": "@threenative/terrain",
6985
+ "requires": ["npm i -D @threenative/terrain"],
6986
+ "signature": "export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }",
6987
+ "situations": ["hand an evaluated Strata terrain to a game without a Blender round trip"],
6988
+ "summary": "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.",
6989
+ "supersedes": [],
6990
+ "symbol": "bakeWorldPackage"
6991
+ },
6992
+ {
6993
+ "aliases": [],
6994
+ "constraints": [
6995
+ "returns candidates only; the caller applies its own exact distance and level test"
6996
+ ],
6997
+ "example": "const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);",
6998
+ "importPath": "@threenative/terrain",
6999
+ "kind": "function",
7000
+ "overrides": [],
7001
+ "package": "@threenative/terrain",
7002
+ "requires": ["npm i @threenative/terrain"],
7003
+ "signature": "export function createSegmentIndex<T>( segments: readonly IWaterSegment<T>[], cellSize: number, ): ISegmentIndex<T> { … }",
7004
+ "situations": [
7005
+ "test scatter candidates or terrain vertices against rivers and lakes without scanning every segment",
7006
+ "find which river stations can reach a heightfield vertex when baking a wet margin"
7007
+ ],
7008
+ "summary": "Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.",
7009
+ "supersedes": [],
7010
+ "symbol": "createSegmentIndex"
7011
+ },
7012
+ {
7013
+ "aliases": [],
7014
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7015
+ "example": "const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);",
7016
+ "importPath": "@threenative/terrain",
7017
+ "kind": "function",
7018
+ "overrides": [],
7019
+ "package": "@threenative/terrain",
7020
+ "requires": ["npm i @threenative/terrain"],
7021
+ "signature": "export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options: IDecodeHeightPngOptions = { … }",
7022
+ "situations": ["import numerical PNG8 or PNG16 terrain elevations"],
7023
+ "summary": "CRC-checked bounded non-interlaced grayscale PNG height decoder.",
7024
+ "supersedes": [],
7025
+ "symbol": "decodeHeightPNG"
7026
+ },
7027
+ {
7028
+ "aliases": [],
7029
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7030
+ "example": "const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });",
7031
+ "importPath": "@threenative/terrain",
7032
+ "kind": "function",
7033
+ "overrides": [],
7034
+ "package": "@threenative/terrain",
7035
+ "requires": ["npm i @threenative/terrain"],
7036
+ "signature": "export function decodeRAW16( input: Uint8Array | ArrayBuffer, { … }",
7037
+ "situations": ["import a RAW16 terrain height buffer with explicit dimensions"],
7038
+ "summary": "Validates dimensions and range before decoding numerical height samples.",
7039
+ "supersedes": [],
7040
+ "symbol": "decodeRAW16"
7041
+ },
7042
+ {
7043
+ "aliases": [],
7044
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7045
+ "example": "const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
7046
+ "importPath": "@threenative/terrain",
7047
+ "kind": "function",
7048
+ "overrides": [],
7049
+ "package": "@threenative/terrain",
7050
+ "requires": ["npm i @threenative/terrain"],
7051
+ "signature": "export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }",
7052
+ "situations": ["export baked terrain geometry without engine extensions"],
7053
+ "summary": "Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.",
7054
+ "supersedes": [],
7055
+ "symbol": "encodeGLB"
7056
+ },
7057
+ {
7058
+ "aliases": [],
7059
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7060
+ "example": "const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());",
7061
+ "importPath": "@threenative/terrain",
7062
+ "kind": "function",
7063
+ "overrides": [],
7064
+ "package": "@threenative/terrain",
7065
+ "requires": ["npm i @threenative/terrain"],
7066
+ "signature": "export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }",
7067
+ "situations": ["export a terrain heightmap without an eight-bit colour conversion"],
7068
+ "summary": "Encodes numerical grayscale PNG16 with embedded elevation range.",
7069
+ "supersedes": [],
7070
+ "symbol": "encodeHeightPNG"
7071
+ },
7072
+ {
7073
+ "aliases": [],
7074
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7075
+ "example": "const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });",
7076
+ "importPath": "@threenative/terrain",
7077
+ "kind": "function",
7078
+ "overrides": [],
7079
+ "package": "@threenative/terrain",
7080
+ "requires": ["npm i @threenative/terrain"],
7081
+ "signature": "export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }",
7082
+ "situations": ["export terrain heights with a numerical range sidecar"],
7083
+ "summary": "Encodes finite metre elevations as an explicit-range RAW16 buffer.",
7084
+ "supersedes": [],
7085
+ "symbol": "encodeRAW16"
7086
+ },
7087
+ {
7088
+ "aliases": [],
7089
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7090
+ "example": "const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());",
7091
+ "importPath": "@threenative/terrain",
7092
+ "kind": "function",
7093
+ "overrides": [],
7094
+ "package": "@threenative/terrain",
7095
+ "requires": ["npm i @threenative/terrain"],
7096
+ "signature": "export async function encodeSplatPNGs(state: ITerrainState) { … }",
7097
+ "situations": ["export terrain splat weights as linear data"],
7098
+ "summary": "Encodes the eight linear material-weight channels as two RGBA images.",
7099
+ "supersedes": [],
7100
+ "symbol": "encodeSplatPNGs"
7101
+ },
7102
+ {
7103
+ "aliases": [],
7104
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7105
+ "example": "const archive = encodeZIP([{ name: \"height.raw\", bytes: new Uint8Array(8) }]);",
7106
+ "importPath": "@threenative/terrain",
7107
+ "kind": "function",
7108
+ "overrides": [],
7109
+ "package": "@threenative/terrain",
7110
+ "requires": ["npm i @threenative/terrain"],
7111
+ "signature": "export function encodeZIP(files: readonly IExportFile[]) { … }",
7112
+ "situations": ["archive derived terrain files without another dependency"],
7113
+ "summary": "Deterministic store-method ZIP with safe unique relative filenames.",
7114
+ "supersedes": [],
7115
+ "symbol": "encodeZIP"
7116
+ },
7117
+ {
7118
+ "aliases": [],
7119
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7120
+ "example": "const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);",
7121
+ "importPath": "@threenative/terrain",
7122
+ "kind": "function",
7123
+ "overrides": [],
7124
+ "package": "@threenative/terrain",
7125
+ "requires": ["npm i @threenative/terrain"],
7126
+ "signature": "export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }",
7127
+ "situations": ["measure an authored terrain gradient in metres"],
7128
+ "summary": "World-space height gradient from the canonical samples.",
7129
+ "supersedes": [],
7130
+ "symbol": "gradientAt"
7131
+ },
7132
+ {
7133
+ "aliases": [],
7134
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7135
+ "example": "const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), \"project\");",
7136
+ "importPath": "@threenative/terrain",
7137
+ "kind": "function",
7138
+ "overrides": [],
7139
+ "package": "@threenative/terrain",
7140
+ "requires": ["npm i @threenative/terrain"],
7141
+ "signature": "export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }",
7142
+ "situations": ["export a terrain recipe and its numerical runtime data"],
7143
+ "summary": "Recovered numerical/project exports; GLB/runtime outputs contain terrain only.",
7144
+ "supersedes": [],
7145
+ "symbol": "makeExport"
7146
+ },
7147
+ {
7148
+ "aliases": [],
7149
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7150
+ "example": "const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);",
7151
+ "importPath": "@threenative/terrain",
7152
+ "kind": "function",
7153
+ "overrides": [],
7154
+ "package": "@threenative/terrain",
7155
+ "requires": ["npm i @threenative/terrain"],
7156
+ "signature": "sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid( grid.height, grid.resolution, grid.resolution, x / grid.size + 0.5, z / grid.size + 0.5, )",
7157
+ "situations": ["query an authored heightfield at world coordinates"],
7158
+ "summary": "Bilinear query of canonical height samples; triangle sampling is a separate contract.",
7159
+ "supersedes": [],
7160
+ "symbol": "sampleHeight"
7161
+ },
7162
+ {
7163
+ "aliases": [],
7164
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7165
+ "example": "const slope = slopeAtIndex(new Terrain({ resolution: 17 }).evaluate(), 0);",
7166
+ "importPath": "@threenative/terrain",
7167
+ "kind": "function",
7168
+ "overrides": [],
7169
+ "package": "@threenative/terrain",
7170
+ "requires": ["npm i @threenative/terrain"],
7171
+ "signature": "export function slopeAtIndex(grid: ISampledGrid, i: number): number { … }",
7172
+ "situations": ["measure terrain slope for authoring diagnostics"],
7173
+ "summary": "Slope in degrees at a heightfield sample.",
7174
+ "supersedes": [],
7175
+ "symbol": "slopeAtIndex"
7176
+ },
7177
+ {
7178
+ "aliases": [],
7179
+ "constraints": [
7180
+ "interior vertices only (edges have one-sided differences); quantile must be in [0, 1]"
7181
+ ],
7182
+ "example": "const steep = slopeQuantile(grid, 0.98); if (slopeAt(x, z) > Math.min(30, steep)) placeRock(x, z);",
7183
+ "importPath": "@threenative/terrain",
7184
+ "kind": "function",
7185
+ "overrides": [],
7186
+ "package": "@threenative/terrain",
7187
+ "requires": ["npm i @threenative/terrain"],
7188
+ "signature": "export function slopeQuantile(grid: ISampledGrid, quantile: number): number { … }",
7189
+ "situations": [
7190
+ "place rocks or cliffs on a terrain's own steepest ground instead of a fixed slope in degrees"
7191
+ ],
7192
+ "summary": "A slope, in degrees, that the given share of this terrain's interior vertices lie at or below. Placement rules keyed to fixed degrees break when a world is rebaked smoother or rougher: an outcrop rule of \"over 30 degrees\" placed nothing on a forest whose 98th percentile is 22. Asking the terrain for its own steepest share keeps the rule meaning the same thing on every world.",
7193
+ "supersedes": [],
7194
+ "symbol": "slopeQuantile"
7195
+ },
7196
+ {
7197
+ "aliases": [],
7198
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7199
+ "example": "const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);",
7200
+ "importPath": "@threenative/terrain",
7201
+ "kind": "function",
7202
+ "overrides": [],
7203
+ "package": "@threenative/terrain",
7204
+ "requires": ["npm i @threenative/terrain"],
7205
+ "signature": "export function splinePoints( points: readonly (readonly [number, number, number])[], step = 3, smooth = true, ): [number, number, number][] { … }",
7206
+ "situations": ["sample a road or river profile without vertical overshoot"],
7207
+ "summary": "Recovered horizontal Catmull–Rom and vertically linear profile sampler.",
7208
+ "supersedes": [],
7209
+ "symbol": "splinePoints"
7210
+ },
7211
+ {
7212
+ "aliases": [],
7213
+ "constraints": [
7214
+ "authoring stays outside the game's steady-play graph; no renderer or physics is created",
7215
+ "units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin",
7216
+ "`resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025",
7217
+ "`seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays",
7218
+ "`evaluate()` is synchronous on the calling thread: run it in a build script, never per frame",
7219
+ "no art is chosen or shipped: materials, models and texture paths belong to the game"
7220
+ ],
7221
+ "example": "const terrain = new Terrain({ size: 512, resolution: 257, seed: 73 }).noise({ id: \"hills\", amplitude: 35 });",
7222
+ "importPath": "@threenative/terrain",
7223
+ "kind": "class",
7224
+ "overrides": ["size, resolution, seed and all layer parameters are caller choices"],
7225
+ "package": "@threenative/terrain",
7226
+ "requires": ["npm i @threenative/terrain"],
7227
+ "signature": "export class Terrain { … }",
7228
+ "situations": [
7229
+ "author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter",
7230
+ "generate a procedural heightmap landscape or island for a game"
7231
+ ],
7232
+ "summary": "Ordered, stable-ID terrain authoring with synchronous atomic transactions.",
7233
+ "supersedes": [],
7234
+ "symbol": "Terrain"
7235
+ },
7236
+ {
7237
+ "aliases": [],
7238
+ "constraints": ["evaluates authoring documents only; games consume pre-baked arrays"],
7239
+ "example": "const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());",
7240
+ "importPath": "@threenative/terrain",
7241
+ "kind": "class",
7242
+ "overrides": ["cacheMB bounds retained prefix data"],
7243
+ "package": "@threenative/terrain",
7244
+ "requires": ["npm i @threenative/terrain"],
7245
+ "signature": "export class TerrainEvaluator { … }",
7246
+ "situations": ["reuse terrain evaluation prefixes while authoring a finite heightfield"],
7247
+ "summary": "Recovered prefix-caching authoring evaluator. Returned buffers belong to the caller.",
7248
+ "supersedes": [],
7249
+ "symbol": "TerrainEvaluator"
7250
+ },
7251
+ {
7252
+ "aliases": [],
7253
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7254
+ "example": "validateDocument(new Terrain({ resolution: 17 }).toJSON());",
7255
+ "importPath": "@threenative/terrain",
7256
+ "kind": "function",
7257
+ "overrides": [],
7258
+ "package": "@threenative/terrain",
7259
+ "requires": ["npm i @threenative/terrain"],
7260
+ "signature": "export function validateDocument(doc: ITerrainDocument): void { … }",
7261
+ "situations": ["validate a terrain document before accepting an authoring write"],
7262
+ "summary": "Validates the recovered recipe schema, operation allow-lists and numeric bounds.",
7263
+ "supersedes": [],
7264
+ "symbol": "validateDocument"
7265
+ },
7266
+ {
7267
+ "aliases": [],
7268
+ "constraints": [
7269
+ "grounding defaults on only when omitted; position and scale have three components and quaternion is unit length"
7270
+ ],
7271
+ "example": "const transforms = validatePlacementOverrides(document.placementOverrides);",
7272
+ "importPath": "@threenative/terrain",
7273
+ "kind": "function",
7274
+ "overrides": ["grounding=false preserves authored Y and keeps clearance observable"],
7275
+ "package": "@threenative/terrain",
7276
+ "requires": ["npm i -D @threenative/terrain"],
7277
+ "signature": "export function validatePlacementOverrides( value: unknown = { … }",
7278
+ "situations": [
7279
+ "validate finite positive manual prop transforms before a terrain authoring transaction"
7280
+ ],
7281
+ "summary": "Validate and clone stable-key placement transforms before saving or previewing them.",
7282
+ "supersedes": [],
7283
+ "symbol": "validatePlacementOverrides"
7284
+ },
7285
+ {
7286
+ "aliases": [],
7287
+ "constraints": [
7288
+ "throws by name; HDR/EXR environment files and ordinary images are accepted, models are not"
7289
+ ],
7290
+ "example": "checkEnvironmentAssets({ sky: { image: \"dusk\" } }, document.assets ?? []);",
7291
+ "importPath": "@threenative/terrain/editor",
7292
+ "kind": "function",
7293
+ "overrides": ["the project owns which images it registers"],
7294
+ "package": "@threenative/terrain",
7295
+ "requires": ["npm i -D @threenative/terrain"],
7296
+ "signature": "export function checkEnvironmentAssets( environment: IEnvironment, assets: readonly { … }",
7297
+ "situations": [
7298
+ "refuse a saved environment whose sky or lighting image is not a registered file"
7299
+ ],
7300
+ "summary": "Check that the images an environment names are registered environment or image assets. @summary Validate the assets a preview environment refers to",
7301
+ "supersedes": [],
7302
+ "symbol": "checkEnvironmentAssets"
7303
+ },
7304
+ {
7305
+ "aliases": [],
7306
+ "constraints": ["framing only; an unknown target returns a named diagnostic and no camera"],
7307
+ "example": "const outcome = focusCamera(camera, { target: { kind: \"prop\", id: \"pine-3\" }, aspect: 16 / 9 }, resolve);",
7308
+ "importPath": "@threenative/terrain/editor",
7309
+ "kind": "function",
7310
+ "overrides": ["the view supplies target bounds, the live aspect and the camera to keep"],
7311
+ "package": "@threenative/terrain",
7312
+ "requires": ["npm i -D @threenative/terrain"],
7313
+ "signature": "export function focusCamera( camera: ISavedCamera, request: IFocusRequest, resolve: IFocusResolver, ): IFocusOutcome { … }",
7314
+ "situations": [
7315
+ "frame one selected prop, a registered landmark, a terrain region or a local point"
7316
+ ],
7317
+ "summary": "Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera",
7318
+ "supersedes": [],
7319
+ "symbol": "focusCamera"
7320
+ },
7321
+ {
7322
+ "aliases": [],
7323
+ "constraints": [
7324
+ "headers and checksums only; throws by name for a damaged, truncated or oversize file"
7325
+ ],
7326
+ "example": "const report = inspectImage(bytes, \"png\", { maxDimension: 8192 });",
7327
+ "importPath": "@threenative/terrain/editor",
7328
+ "kind": "function",
7329
+ "overrides": ["the project sets the dimension limit"],
7330
+ "package": "@threenative/terrain",
7331
+ "requires": ["npm i -D @threenative/terrain"],
7332
+ "signature": "export function inspectImage( bytes: Uint8Array, format: string, limits: { … }",
7333
+ "situations": [
7334
+ "check an imported surface or environment image for damage and for the project's size limit"
7335
+ ],
7336
+ "summary": "Validate a PNG, JPEG, WebP, Radiance HDR or OpenEXR container and read its pixel size. @summary Inspect an image file's container and pixel size without decoding it",
7337
+ "supersedes": [],
7338
+ "symbol": "inspectImage"
7339
+ },
7340
+ {
7341
+ "aliases": [],
7342
+ "constraints": [
7343
+ "authoring data only; queries outside the extent or without observations throw"
7344
+ ],
7345
+ "example": "const observation = inspectSpatial(state, revision, { kind: \"point\", at: [0, 0] });",
7346
+ "importPath": "@threenative/terrain/editor",
7347
+ "kind": "function",
7348
+ "overrides": [
7349
+ "the caller owns the revision identity and the evaluated state being inspected"
7350
+ ],
7351
+ "package": "@threenative/terrain",
7352
+ "requires": ["npm i -D @threenative/terrain"],
7353
+ "signature": "export function inspectSpatial( state: ITerrainState, revision: string, query: ISpatialQuery, ): ISpatialObservation { … }",
7354
+ "situations": [
7355
+ "measure a point, profile a transect or score a saved reference against the world"
7356
+ ],
7357
+ "summary": "Read-only spatial inspection of one evaluated terrain revision.",
7358
+ "supersedes": [],
7359
+ "symbol": "inspectSpatial"
7360
+ },
7361
+ {
7362
+ "aliases": [],
7363
+ "constraints": [
7364
+ "browser authoring only; createView and materialColours are required game choices"
7365
+ ],
7366
+ "example": "await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });",
7367
+ "importPath": "@threenative/terrain/editor",
7368
+ "kind": "function",
7369
+ "overrides": ["createView owns the renderer scene, materials, lighting and camera"],
7370
+ "package": "@threenative/terrain",
7371
+ "requires": ["npm i -D @threenative/terrain"],
7372
+ "signature": "export async function mountTerrainEditor(options: { … }",
7373
+ "situations": ["open the terrain brush and layer GUI around game-owned rendering"],
7374
+ "summary": "Mount recovered terrain controls around the project-owned ThreeNative view.",
7375
+ "supersedes": [],
7376
+ "symbol": "mountTerrainEditor"
7377
+ },
7378
+ {
7379
+ "aliases": [],
7380
+ "constraints": ["authoring data only; non-finite, malformed and out-of-extent queries throw"],
7381
+ "example": "const probe = probeTerrain(state, revision, [12, -4]);",
7382
+ "importPath": "@threenative/terrain/editor",
7383
+ "kind": "function",
7384
+ "overrides": [
7385
+ "the caller owns the revision identity and the evaluated state being inspected"
7386
+ ],
7387
+ "package": "@threenative/terrain",
7388
+ "requires": ["npm i -D @threenative/terrain"],
7389
+ "signature": "export function probeTerrain( state: ITerrainState, revision: string, at: readonly number[], ): IPointObservation { … }",
7390
+ "situations": ["measure an authored terrain point with provenance and a revision identity"],
7391
+ "summary": "Probe the evaluated surface at one world point, separating bilinear from triangle values.",
7392
+ "supersedes": [],
7393
+ "symbol": "probeTerrain"
7394
+ },
7395
+ {
7396
+ "aliases": [],
7397
+ "constraints": [
7398
+ "pure: the input set is never mutated, an unknown id throws, and deleting the live camera falls back"
7399
+ ],
7400
+ "example": "const next = runCameraOperation(set, { op: \"activate\", id: \"survey\" });",
7401
+ "importPath": "@threenative/terrain/editor",
7402
+ "kind": "function",
7403
+ "overrides": ["the caller persists the returned set against its own revision"],
7404
+ "package": "@threenative/terrain",
7405
+ "requires": ["npm i -D @threenative/terrain"],
7406
+ "signature": "export function runCameraOperation(set: ICameraSet, operation: unknown): ICameraResult { … }",
7407
+ "situations": [
7408
+ "drive the terrain editor camera list from an agent or the GUI through one shared dispatch"
7409
+ ],
7410
+ "summary": "Run one create / get / list / update / delete / activate operation over saved cameras. @summary Apply an editor camera operation to a saved camera set",
7411
+ "supersedes": [],
7412
+ "symbol": "runCameraOperation"
7413
+ },
7414
+ {
7415
+ "aliases": [],
7416
+ "constraints": ["authoring metadata only; a null field returns to the project's own value"],
7417
+ "example": "const result = runEnvironmentOperation({}, { op: \"patch\", values: { sun: { elevation: 25 } } });",
7418
+ "importPath": "@threenative/terrain/editor",
7419
+ "kind": "function",
7420
+ "overrides": ["the project's render source decides what each value does"],
7421
+ "package": "@threenative/terrain",
7422
+ "requires": ["npm i -D @threenative/terrain"],
7423
+ "signature": "export function runEnvironmentOperation( current: IEnvironment, operation: unknown, ): IEnvironmentResult { … }",
7424
+ "situations": [
7425
+ "patch sun, haze, exposure or sea overrides from a controller or the editor GUI"
7426
+ ],
7427
+ "summary": "Apply one get / patch / reset against the saved environment overrides; the caller commits it. @summary Run one preview-environment operation",
7428
+ "supersedes": [],
7429
+ "symbol": "runEnvironmentOperation"
7430
+ },
7431
+ {
7432
+ "aliases": [],
7433
+ "constraints": [
7434
+ "reads only the first bytes; a file it cannot name returns undefined and must be refused"
7435
+ ],
7436
+ "example": "const kind = sniff(new Uint8Array(await file.arrayBuffer()))?.kind;",
7437
+ "importPath": "@threenative/terrain/editor",
7438
+ "kind": "function",
7439
+ "overrides": ["the caller decides what to do with an unknown file"],
7440
+ "package": "@threenative/terrain",
7441
+ "requires": ["npm i -D @threenative/terrain"],
7442
+ "signature": "export function sniff( bytes: Uint8Array, ): { … }",
7443
+ "situations": [
7444
+ "decide whether a dropped or downloaded file is a model, surface image or environment image"
7445
+ ],
7446
+ "summary": "The kind and format a file's own bytes declare, whatever its name says. @summary Identify a GLB, PNG, JPEG, WebP, HDR or EXR file by its header",
7447
+ "supersedes": [],
7448
+ "symbol": "sniff"
7449
+ },
7450
+ {
7451
+ "aliases": [],
7452
+ "constraints": [
7453
+ "throws by name for an input that is not <surface>.<channel> with a known channel"
7454
+ ],
7455
+ "example": "const space = surfaceSpace(\"bark.normal\");",
7456
+ "importPath": "@threenative/terrain/editor",
7457
+ "kind": "function",
7458
+ "overrides": ["the project owns which surface inputs exist"],
7459
+ "package": "@threenative/terrain",
7460
+ "requires": ["npm i -D @threenative/terrain"],
7461
+ "signature": "export function surfaceSpace(input: string): \"srgb\" | \"linear\" { … }",
7462
+ "situations": ["decide how an imported image bound to a named surface input must be sampled"],
7463
+ "summary": "The colour space an input's pixels are read in, from the channel its name ends with. @summary Resolve a surface input name to sRGB or linear",
7464
+ "supersedes": [],
7465
+ "symbol": "surfaceSpace"
7466
+ },
7467
+ {
7468
+ "aliases": [],
7469
+ "constraints": [
7470
+ "optional tooling; only subscribe/mount touches DOM; stale revisions fail explicitly"
7471
+ ],
7472
+ "example": "const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();",
7473
+ "importPath": "@threenative/terrain/editor",
7474
+ "kind": "class",
7475
+ "overrides": ["editorUrl is the activation-returned project URL"],
7476
+ "package": "@threenative/terrain",
7477
+ "requires": ["npm i -D @threenative/terrain"],
7478
+ "signature": "export class TerrainEditorController { … }",
7479
+ "situations": ["inspect and atomically edit the terrain editor from an agent"],
7480
+ "summary": "HTTP controller for the project-local terrain editor.",
7481
+ "supersedes": [],
7482
+ "symbol": "TerrainEditorController"
7483
+ },
7484
+ {
7485
+ "aliases": [],
7486
+ "constraints": [
7487
+ "authoring metadata only; ids, content-hashed paths, bounds and unit adjustments are checked, files are not read"
7488
+ ],
7489
+ "example": "const asset = validateAsset({ id: \"oak\", kind: \"model\", name: \"oak.glb\", path: \"models/0123456789ab-oak.glb\", sha256: \"0123456789ab\".padEnd(64, \"0\"), bytes: 2180, status: \"ready\" });",
7490
+ "importPath": "@threenative/terrain/editor",
7491
+ "kind": "function",
7492
+ "overrides": ["the project owns its asset directory and which entries it keeps"],
7493
+ "package": "@threenative/terrain",
7494
+ "requires": ["npm i -D @threenative/terrain"],
7495
+ "signature": "export function validateAsset(input: unknown): IProjectAsset { … }",
7496
+ "situations": [
7497
+ "check a model, image or environment asset entry before saving it in the authoring document"
7498
+ ],
7499
+ "summary": "Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry",
7500
+ "supersedes": [],
7501
+ "symbol": "validateAsset"
7502
+ },
7503
+ {
7504
+ "aliases": [],
7505
+ "constraints": ["at most 64 entries; unique ids; each entry as validateAsset"],
7506
+ "example": "const assets = validateAssets(document.assets ?? []);",
7507
+ "importPath": "@threenative/terrain/editor",
7508
+ "kind": "function",
7509
+ "overrides": ["the project owns its asset directory and which entries it keeps"],
7510
+ "package": "@threenative/terrain",
7511
+ "requires": ["npm i -D @threenative/terrain"],
7512
+ "signature": "export function validateAssets(input: unknown): IProjectAsset[] { … }",
7513
+ "situations": [
7514
+ "check every registered model, image and environment entry together, with unique ids"
7515
+ ],
7516
+ "summary": "Validate the whole asset list of an authoring document. @summary Validate the registered terrain-editor assets",
7517
+ "supersedes": [],
7518
+ "symbol": "validateAssets"
7519
+ },
7520
+ {
7521
+ "aliases": [],
7522
+ "constraints": [
7523
+ "authoring metadata only; finite noncoincident poses, usable up, valid projection, ordered planes"
7524
+ ],
7525
+ "example": "const camera = validateCamera({ id: \"survey\", name: \"Survey\", position: [40, 60, 40], target: [0, 12, 0], up: [0, 1, 0], projection: \"perspective\", fov: 50, near: 0.5, far: 900 });",
7526
+ "importPath": "@threenative/terrain/editor",
7527
+ "kind": "function",
7528
+ "overrides": ["the caller owns the document revision and the live viewport aspect"],
7529
+ "package": "@threenative/terrain",
7530
+ "requires": ["npm i -D @threenative/terrain"],
7531
+ "signature": "export function validateCamera( input: unknown, existing: readonly ISavedCamera[] = [], ): ISavedCamera { … }",
7532
+ "situations": [
7533
+ "create or update a named terrain-editor camera in the shared authoring document"
7534
+ ],
7535
+ "summary": "Normalise and validate one saved camera, exactly as a document commit would store it. @summary Validate an editor observation camera bookmark",
7536
+ "supersedes": [],
7537
+ "symbol": "validateCamera"
7538
+ },
7539
+ {
7540
+ "aliases": [],
7541
+ "constraints": ["authoring metadata only; the same validation the camera operations apply"],
7542
+ "example": "const cameras = validateCameras(JSON.parse(saved).cameras ?? []);",
7543
+ "importPath": "@threenative/terrain/editor",
7544
+ "kind": "function",
7545
+ "overrides": [
7546
+ "the document owns how many cameras it keeps; the list bound is the editor's own"
7547
+ ],
7548
+ "package": "@threenative/terrain",
7549
+ "requires": ["npm i -D @threenative/terrain"],
7550
+ "signature": "export function validateCameras(input: unknown): ISavedCamera[] { … }",
7551
+ "situations": ["reject a disk document whose saved cameras are malformed or duplicated"],
7552
+ "summary": "Validate a document's saved camera list, keeping ids unique across it. @summary Validate the saved editor camera list of an authoring document",
7553
+ "supersedes": [],
7554
+ "symbol": "validateCameras"
7555
+ },
7556
+ {
7557
+ "aliases": [],
7558
+ "constraints": [
7559
+ "authoring metadata only; unknown fields and unsupported fog modes are refused by name"
7560
+ ],
7561
+ "example": "const environment = validateEnvironment({ sun: { elevation: 25, intensity: 3 } });",
7562
+ "importPath": "@threenative/terrain/editor",
7563
+ "kind": "function",
7564
+ "overrides": [
7565
+ "the project's render source defines what each value does; absent fields keep its own"
7566
+ ],
7567
+ "package": "@threenative/terrain",
7568
+ "requires": ["npm i -D @threenative/terrain"],
7569
+ "signature": "export function validateEnvironment(input: unknown): IEnvironment { … }",
7570
+ "situations": [
7571
+ "save sun, sky, haze, exposure or ocean overrides in the shared authoring document"
7572
+ ],
7573
+ "summary": "Validate a complete overrides object exactly as a document commit stores it. @summary Validate preview environment overrides",
7574
+ "supersedes": [],
7575
+ "symbol": "validateEnvironment"
7576
+ },
7577
+ {
7578
+ "aliases": [],
7579
+ "constraints": [
7580
+ "authoring metadata only; rejects unknown fields, malformed points and unknown scale"
7581
+ ],
7582
+ "example": "const reference = validateSpatialReference(JSON.parse(saved));",
7583
+ "importPath": "@threenative/terrain/editor",
7584
+ "kind": "function",
7585
+ "overrides": [
7586
+ "a project owns the image file; only its hash and provenance travel in the document"
7587
+ ],
7588
+ "package": "@threenative/terrain",
7589
+ "requires": ["npm i -D @threenative/terrain"],
7590
+ "signature": "export function validateSpatialReference(input: unknown): ISavedSpatialReference { … }",
7591
+ "situations": [
7592
+ "accept a bounded local reference image registration into the shared document"
7593
+ ],
7594
+ "summary": "Normalise and validate one saved reference, exactly as a document commit would store it.",
7595
+ "supersedes": [],
7596
+ "symbol": "validateSpatialReference"
7597
+ },
7598
+ {
7599
+ "aliases": [],
7600
+ "constraints": [
7601
+ "authoring metadata only; each input is <surface>.<channel>; every asset must be a registered image"
7602
+ ],
7603
+ "example": "const surfaces = validateSurfaces({ \"bark.normal\": { asset: \"my-normal\" } }, document.assets ?? []);",
7604
+ "importPath": "@threenative/terrain/editor",
7605
+ "kind": "function",
7606
+ "overrides": [
7607
+ "the project's render source defines which surface inputs exist and what they draw"
7608
+ ],
7609
+ "package": "@threenative/terrain",
7610
+ "requires": ["npm i -D @threenative/terrain"],
7611
+ "signature": "export function validateSurfaces( input: unknown, assets: readonly IProjectAsset[], ): ISurfaceMappings { … }",
7612
+ "situations": [
7613
+ "save which imported PBR image replaces which named surface input of the project's render source"
7614
+ ],
7615
+ "summary": "Validate surface mappings against the registered images they name. @summary Validate terrain-editor surface image mappings",
7616
+ "supersedes": [],
7617
+ "symbol": "validateSurfaces"
7618
+ },
7619
+ {
7620
+ "aliases": [],
7621
+ "constraints": [
7622
+ "dev tooling only; serve a project-owned /terrain-editor/index.html; no runtime import"
7623
+ ],
7624
+ "example": "const editor = terrainEditor({ documentPath: resolve(\"terrain/world.json\") });",
7625
+ "importPath": "@threenative/terrain/editor/server",
7626
+ "kind": "function",
7627
+ "overrides": ["documentPath and optional configured viewerUrl belong to the project"],
7628
+ "package": "@threenative/terrain",
7629
+ "requires": ["npm i -D @threenative/terrain vite"],
7630
+ "signature": "export function terrainEditor(options: { … }",
7631
+ "situations": ["share terrain recipe edits between an agent and the live terrain editor"],
7632
+ "summary": "Mount the optional terrain document API on an existing loopback Vite server.",
7633
+ "supersedes": [],
7634
+ "symbol": "terrainEditor"
7635
+ },
7636
+ {
7637
+ "aliases": [],
7638
+ "constraints": [
7639
+ "Node authoring only; documentPath is a configured absolute regular file; input is bounded to 64 MiB"
7640
+ ],
7641
+ "example": "const document = new TerrainEditorDocument(\"/project/terrain/world.json\"); const snapshot = document.snapshot();",
7642
+ "importPath": "@threenative/terrain/editor/server",
7643
+ "kind": "class",
7644
+ "overrides": ["the project chooses its document path; revisions come from validated content"],
7645
+ "package": "@threenative/terrain",
7646
+ "requires": ["npm i -D @threenative/terrain"],
7647
+ "signature": "export class TerrainEditorDocument { … }",
7648
+ "situations": ["validate atomic revision-based project-local terrain document edits"],
7649
+ "summary": "Project-local terrain document authority; no renderer or game dependency.",
7650
+ "supersedes": [],
7651
+ "symbol": "TerrainEditorDocument"
7652
+ },
7653
+ {
7654
+ "aliases": [],
7655
+ "constraints": [
7656
+ "browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless"
7657
+ ],
7658
+ "example": "const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });",
7659
+ "importPath": "@threenative/terrain/export",
7660
+ "kind": "function",
7661
+ "overrides": [
7662
+ "actual static models, final matrices and baked PBR maps are supplied by the game"
7663
+ ],
7664
+ "package": "@threenative/terrain",
7665
+ "requires": ["npm i -D @threenative/terrain"],
7666
+ "signature": "export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }",
7667
+ "situations": [
7668
+ "export terrain, resolved models and final manual placement transforms as a portable GLB",
7669
+ "export the whole terrain world as one glb for another three.js project"
7670
+ ],
7671
+ "summary": "Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.",
7672
+ "supersedes": [],
7673
+ "symbol": "exportWorldGLB"
7674
+ },
7675
+ {
7676
+ "aliases": [],
7677
+ "constraints": ["creates only geometry; the caller owns its material, scene and disposal"],
7678
+ "example": "const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
7679
+ "importPath": "@threenative/terrain/three",
7680
+ "kind": "function",
7681
+ "overrides": ["every surface choice remains in game source"],
7682
+ "package": "@threenative/terrain",
7683
+ "requires": ["npm i @threenative/terrain"],
7684
+ "signature": "export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }",
7685
+ "situations": ["put an authored terrain mesh in a game-owned Three.js scene"],
7686
+ "summary": "Converts baked arrays to ordinary geometry using the consumer's installed Three.js.",
7687
+ "supersedes": [],
7688
+ "symbol": "toGeometry"
7689
+ },
5899
7690
  {
5900
7691
  "aliases": [],
5901
7692
  "constraints": [
@@ -6029,6 +7820,7 @@
6029
7820
  "kind": "function",
6030
7821
  "overrides": [],
6031
7822
  "package": "@threenative/ui",
7823
+ "requires": ["npm i @threenative/ui"],
6032
7824
  "signature": "export function DebugOverlay() { … }",
6033
7825
  "situations": [
6034
7826
  "display runtime and playtest diagnostics in a React HUD",
@@ -6048,6 +7840,7 @@
6048
7840
  "kind": "function",
6049
7841
  "overrides": [],
6050
7842
  "package": "@threenative/ui",
7843
+ "requires": ["npm i @threenative/ui"],
6051
7844
  "signature": "export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( { … }",
6052
7845
  "situations": [
6053
7846
  "add a game viewport to a React application",
@@ -6065,6 +7858,7 @@
6065
7858
  "kind": "function",
6066
7859
  "overrides": [],
6067
7860
  "package": "@threenative/ui",
7861
+ "requires": ["npm i @threenative/ui"],
6068
7862
  "signature": "export function UiLayer( { … }",
6069
7863
  "situations": [
6070
7864
  "write one HUD that looks the same on the web build and on a phone",
@@ -6082,6 +7876,7 @@
6082
7876
  "kind": "function",
6083
7877
  "overrides": [],
6084
7878
  "package": "@threenative/ui",
7879
+ "requires": ["npm i @threenative/ui"],
6085
7880
  "signature": "export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;",
6086
7881
  "situations": [
6087
7882
  "bind a HUD component to game state",
@@ -6099,6 +7894,7 @@
6099
7894
  "kind": "function",
6100
7895
  "overrides": [],
6101
7896
  "package": "@threenative/ui",
7897
+ "requires": ["npm i @threenative/ui"],
6102
7898
  "signature": "export function useUiIntent(): (intent: string, payload?: unknown) => void { … }",
6103
7899
  "situations": [
6104
7900
  "wire a Restart button in a HUD to the running game",
@@ -6116,6 +7912,7 @@
6116
7912
  "kind": "function",
6117
7913
  "overrides": [],
6118
7914
  "package": "@threenative/ui",
7915
+ "requires": ["npm i @threenative/ui"],
6119
7916
  "signature": "export function useUiState<TState extends object>(): TState | undefined;",
6120
7917
  "situations": [
6121
7918
  "bind a HUD to game state on web and native alike",
@@ -6125,6 +7922,35 @@
6125
7922
  "supersedes": [],
6126
7923
  "symbol": "useUiState"
6127
7924
  },
7925
+ {
7926
+ "symbol": "createStormAudio",
7927
+ "package": "template:rain",
7928
+ "importPath": "src/audio/storm.ts",
7929
+ "kind": "function",
7930
+ "signature": "createStormAudio(ctx: ICtx<GameState>): IStormAudio",
7931
+ "summary": "The storm's sound as generated source, mixed through the engine's own `AudioBus`: a rain hiss, a wind bed, and thunder queued strike by strike and delayed and filtered by how far away it was struck.",
7932
+ "situations": [
7933
+ "rain hiss, wind bed, thunder, a storm you can hear",
7934
+ "delay thunder by the distance it was struck",
7935
+ "sound that follows pause, mute and tab visibility",
7936
+ "audio that queues strikes instead of cutting each other off"
7937
+ ],
7938
+ "example": "src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene",
7939
+ "constraints": [
7940
+ "`queueStrike({ at, metres })` queues: a second strike does not overwrite one still crossing the air, and `at` is absolute simulation time, which is what lets a strike survive a freeze.",
7941
+ "Two holds, kept apart so neither latches the other: `setSilenced` is the game's own pause intent, `setHidden` is the UI realm or engine lifecycle visibility. The bus is released only when both are clear.",
7942
+ "`update(state)` is the frame's truth and is called once per frame after the simulation advances; `debug()` is what a playtest reads back.",
7943
+ "The caller owns entity registration, updates and disposal; creating the helper does not register it.",
7944
+ "Audio begins only after a user gesture — the bus's unlock error is surfaced rather than swallowed.",
7945
+ "The three clips are baked by `tools/make-storm-audio.mjs` from the study's own maths; this file plays them, it does not synthesise them live.",
7946
+ "The helper requests the source's compressor settings ahead of master gain: threshold -15 dB, knee 30 dB, ratio 5, attack 0.003 s and release 0.25 s.",
7947
+ "Each thunder voice is a labelled `thunder` cue, so a playtest's `audio` assertion reads it from the runtime ledger; the rain kit's `playtests/lightning.playtest.json` proves one cue after a strike, sounded only once the strike's `distance / 343` delay had passed.",
7948
+ "This entry describes the Rain starter scaffold's own generated `src/audio/storm.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
7949
+ ],
7950
+ "overrides": [],
7951
+ "supersedes": [],
7952
+ "aliases": []
7953
+ },
6128
7954
  {
6129
7955
  "symbol": "renderer.matrixWorld",
6130
7956
  "package": "@threenative/core",
@@ -6190,20 +8016,132 @@
6190
8016
  "package": "@threenative/core",
6191
8017
  "importPath": "src/game.ts",
6192
8018
  "kind": "function",
6193
- "signature": "renderer.projection?: boolean",
6194
- "summary": "The engine's scene-render projection — an internal mirror that collapses repeated draws — on by default. Set `renderer.projection: false` to decline it.",
8019
+ "signature": "renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }",
8020
+ "summary": "The engine's scene-render projection — an internal mirror that collapses repeated draws, including animated skinned rigs that share a geometry and material into one palette draw per pass — on by default. Set `renderer.projection: false` to decline it, or `projection: { materialChecks: 'everyFrame' }` to keep it and pay for a per-material check on every frame.",
6195
8021
  "situations": [
8022
+ "a crowd of animated characters draws slowly",
8023
+ "many SkinnedMesh copies of one rig, each its own draw call",
6196
8024
  "the game got slower after the projection engaged",
6197
8025
  "turn off the render projection, batching, or the instanced mirror",
6198
8026
  "draw count fell but frame time did not",
6199
8027
  "a multi-second freeze when the mirror first engages",
6200
- "opt out of an engine render optimizer"
8028
+ "opt out of an engine render optimizer",
8029
+ "thousands of props each with their own material, one colour apart",
8030
+ "a material edit takes a few frames to show up",
8031
+ "check every batched material every frame anyway"
6201
8032
  ],
6202
8033
  "example": "renderer: { projection: false } // in threenative.config.ts",
6203
8034
  "constraints": [
6204
8035
  "Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it.",
6205
8036
  "An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame.",
6206
- "TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines."
8037
+ "TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines.",
8038
+ "`materialChecks: 'spread'` is the default: a bounded slice of the batched materials is proved per frame instead of all of them, so a frame of 4,096 colour-only materials costs 512 checks rather than 4,096. A base-colour edit is never delayed — that write is O(1) per member.",
8039
+ "The price of `spread` is staleness on every other material edit: a material that gains a roughness, a map or a define still leaves its group and is drawn exactly, up to `materialCheckStaleFrames` frames later. TN_RENDER_PROJECTION reports that bound; `materialChecks: 'everyFrame'` sets it to 0 and restores the per-member, per-frame check.",
8040
+ "Any other `materialChecks` value throws at startup rather than falling back to a default."
8041
+ ],
8042
+ "overrides": [
8043
+ "renderer.projection: false declines the whole mirror and costs nothing to decline",
8044
+ "renderer: { projection: { materialChecks: 'everyFrame' } } proves every batched material every frame instead of the default bounded slice"
8045
+ ],
8046
+ "supersedes": [],
8047
+ "aliases": []
8048
+ },
8049
+ {
8050
+ "symbol": "createStormLightning",
8051
+ "package": "template:rain",
8052
+ "importPath": "src/render/lightning.ts",
8053
+ "kind": "function",
8054
+ "signature": "createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning",
8055
+ "summary": "A branching lightning bolt as generated Rain source: `makeBolt(end, random)` walks a 30-segment channel down from the cloud deck with side branches, and one additive camera-facing ribbon draw (gaussian core inside a wide halo) shows it while the caller's flash envelope is above zero. `strike(position, random)` returns where the bolt entered the sky.",
8056
+ "situations": [
8057
+ "generate branching lightning ribbon geometry",
8058
+ "a lightning strike that lights the scene and the clouds",
8059
+ "a camera-facing ribbon or beam that stays the same pixel width at any distance",
8060
+ "a flash envelope that stutters rather than fades once"
8061
+ ],
8062
+ "example": "src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay",
8063
+ "constraints": [
8064
+ "Pass the game's seeded random so a strike is reproducible; a non-finite position or random value throws rather than drawing NaN geometry.",
8065
+ "The buffers hold the worst case (30 channel segments plus 24 branches of 9) and are allocated once; a strike rewrites them and opens the draw range, never reallocating.",
8066
+ "`update(flash)` takes an envelope already gated on photosensitivity mode by the caller; below 0.003 the mesh is hidden. Register it with `alwaysRender`: its quads are projected by its own vertex stage, so its bounds say nothing about where it lands.",
8067
+ "It depth-tests against the coast's written depth, so a bolt behind the headland is hidden by it.",
8068
+ "This entry describes the Rain starter scaffold's own generated `src/render/lightning.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
8069
+ ],
8070
+ "overrides": [],
8071
+ "supersedes": [],
8072
+ "aliases": []
8073
+ },
8074
+ {
8075
+ "symbol": "createNoiseVolume",
8076
+ "package": "template:rain",
8077
+ "importPath": "src/render/noise-volume.ts",
8078
+ "kind": "function",
8079
+ "signature": "createNoiseVolume(): INoiseVolume",
8080
+ "summary": "The 64³ RGBA cloud noise volume as generated Rain source: `{ data: Uint8Array, texture: Data3DTexture }`. Its authored seed, octave weights and source-exact generator define the storm's cloud shapes.",
8081
+ "situations": [
8082
+ "generate a 3D noise volume instead of shipping one as an asset",
8083
+ "rebuild the storm's clouds procedurally at startup",
8084
+ "tileable 3D noise that does not crease at the edges",
8085
+ "four octave scales packed into one texture"
8086
+ ],
8087
+ "example": "src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there",
8088
+ "constraints": [
8089
+ "Seed 13291 uses the source's mulberry32 sequence. The generated volume matches all 1,048,576 reference bytes; changing the authored seed or generator changes its appearance.",
8090
+ "Two distinct failure channels, not one: `TN_NOISE_CHANNEL` is a channel value that does not fit a byte, `TN_NOISE_LENGTH` is a byte count that does not fill the volume. Both throw rather than uploading a volume the shader would read wrong.",
8091
+ "64³ of RGBA is 1 MiB, and `NOISE_SIZE` is what the loops and the byte count are written against; changing the size changes the memory cost with it.",
8092
+ "Indices wrap at every face, which is what makes the volume tile, and the fractional part is smoothed by `f²(3 − 2f)` so lattice edges do not show as creases in the cloud.",
8093
+ "This entry describes the Rain starter scaffold's own generated `src/render/noise-volume.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
8094
+ ],
8095
+ "overrides": [],
8096
+ "supersedes": [],
8097
+ "aliases": []
8098
+ },
8099
+ {
8100
+ "symbol": "createStormRain",
8101
+ "package": "template:rain",
8102
+ "importPath": "src/render/rain.ts",
8103
+ "kind": "function",
8104
+ "signature": "createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain",
8105
+ "summary": "Camera-anchored falling rain as generated Rain source: one instanced draw whose vertex stage hashes each drop from its index, wraps it in a 66 × 30 × 66 m cell that follows the camera in 12 m steps, and projects a quad stretched along its own fall — no particle simulation, no texture.",
8106
+ "situations": [
8107
+ "rain streaks around the camera",
8108
+ "thousands of falling drops in one draw",
8109
+ "rain that leans with the wind and lights up in a lightning flash"
8110
+ ],
8111
+ "example": "src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget",
8112
+ "constraints": [
8113
+ "The drawn count is `round(rainBudget × weather.rain)` for the tier, read back from `geometry.instanceCount` (`instanceCount`), not from the budget.",
8114
+ "Stateless by design: a drop's position is a function of its index and the clock, so pausing the clock freezes the rain and nothing accumulates. `GPUParticles3D` is the engine's emitter with lifetimes; reach for it when drops must spawn, live and die.",
8115
+ "Register it with `alwaysRender`: the vertex stage places every drop, so the geometry's own bounds do not.",
8116
+ "This entry describes the Rain starter scaffold's own generated `src/render/rain.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
8117
+ ],
8118
+ "overrides": [],
8119
+ "supersedes": [],
8120
+ "aliases": []
8121
+ },
8122
+ {
8123
+ "symbol": "createWeatherWorld",
8124
+ "package": "template:rain",
8125
+ "importPath": "src/render/world.ts",
8126
+ "kind": "function",
8127
+ "signature": "createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld",
8128
+ "summary": "The raymarched coastal storm as generated source: one screen quad whose TSL shader draws the sky, the sea, the coast, the road, the forest and the lamps, and whose wet ground reflects them, written from the uniforms the game feeds it each frame. The sky it samples is the live cloud pass this call builds, not a stand-in gradient. Returns `{ quad, update(options), dispose() }`.",
8129
+ "situations": [
8130
+ "a procedural storm, sea, coastline or open horizon drawn from maths rather than geometry",
8131
+ "rain and wind that change how a scene looks without swapping a mesh",
8132
+ "a lightning flash that lights the coast and the sky at once",
8133
+ "wet reflections on a ground plane",
8134
+ "sky that darkens as cloud cover rises"
8135
+ ],
8136
+ "example": "src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts",
8137
+ "constraints": [
8138
+ "`update` takes `{ elapsed, flash, weather, strike, quality }`: absolute seconds, a flash envelope already gated on the photosensitivity switch by the caller, the bolt's entry point in the cloud deck in metres (what the clouds glow around and the coast is lit from), and a quality name of `performance | balanced | high | ultra`.",
8139
+ "The tier's cloud resolution share, march steps and reflection switch come from `STUDY_TIERS` in src/render/quality.ts; `performance` skips the 36-step reflection march, so a low tier loses reflections, not the coast. `clouds()` reads back the cloud target the renderer really drew and its steps.",
8140
+ "Its colours and lights are uniforms set once from src/render/palette.ts, sky.ts, lighting.ts and materials.ts; the shader itself is generated from tools/tempest-*.frag by tools/generate-shaders.mjs — edit the .frag, not the generated file.",
8141
+ "The engine's `Scene` and `PerspectiveCamera` are injected as arguments; the file holds no engine lifetime of its own. `dispose()` removes the quad and disposes the geometry, material and sky texture — the scene does not do it for you.",
8142
+ "The quad has `frustumCulled = false`, because its two-metre bounds would otherwise be culled the moment the camera looks along the coast.",
8143
+ "The cloud pass is built first and its texture feeds the world shader (sampled with the render-target flip); `update` also drives the clouds. Rain streaks and the bolt are separate draws: `createStormRain`, `createStormLightning`.",
8144
+ "This entry describes the Rain starter scaffold's own generated `src/render/world.ts`, not a `@threenative/` or three export — there is no installed package to import it from. Appearance lives in that source with no package import at all; nothing in packages/ decides how this storm looks."
6207
8145
  ],
6208
8146
  "overrides": [],
6209
8147
  "supersedes": [],
@@ -6520,7 +8458,7 @@
6520
8458
  ],
6521
8459
  "notOwned": [
6522
8460
  {
6523
- "guidance": "The framework owns no save/load system. Write a save module in your project's src/ using your own plain state shape (for example, ctx.state), and read agent-docs/gameplay-recipes.md for the template recipe.",
8461
+ "guidance": "The framework owns no save/load system. Write a save module in your project's src/ using your own plain state shape (for example, ctx.state), and read node_modules/create-threenative/agent-docs/references/gameplay-recipes.md for the template recipe.",
6524
8462
  "id": "save-load",
6525
8463
  "situations": [
6526
8464
  "persist a player's progress between sessions",
@@ -6529,12 +8467,12 @@
6529
8467
  ]
6530
8468
  },
6531
8469
  {
6532
- "guidance": "The framework owns no inventory system. Write inventory state in your project's src/ with plain objects under ctx.state, and read agent-docs/gameplay-recipes.md for the template recipe.",
8470
+ "guidance": "The framework owns no inventory system. Write inventory state in your project's src/ with plain objects under ctx.state, and read node_modules/create-threenative/agent-docs/references/gameplay-recipes.md for the template recipe.",
6533
8471
  "id": "inventory",
6534
8472
  "situations": ["inventory system", "manage inventory contents"]
6535
8473
  },
6536
8474
  {
6537
- "guidance": "The framework owns no dialogue system. Write the conversation data and state in your project's src/; render it with the template UI (starter uses src/ui/), and read agent-docs/gameplay-recipes.md.",
8475
+ "guidance": "The framework owns no dialogue system. Write the conversation data and state in your project's src/; render it with the template UI (starter uses src/ui/), and read node_modules/create-threenative/agent-docs/references/gameplay-recipes.md.",
6538
8476
  "id": "dialogue",
6539
8477
  "situations": ["NPC dialogue system", "write conversation choices for an NPC"]
6540
8478
  },
@@ -6542,6 +8480,28 @@
6542
8480
  "guidance": "The framework owns the optional authenticated transport seam at @threenative/core/net. Import connect with an HTTPS endpoint and a game-issued credential; it validates channels, message sizes, and bounded queues, but reliable overflow returns false and native qualification depends on the installed bridge (iOS remains unverified). Write authoritative replication, snapshots, prediction, interpolation, and rejoin policy in your project's src/ and server code.",
6543
8481
  "id": "networked-multiplayer",
6544
8482
  "situations": ["authoritative replication", "client prediction"]
8483
+ },
8484
+ {
8485
+ "guidance": "The framework owns no vegetation system. Copy the MIT source in examples/integrations/vegetation/src/ (https://github.com/ThreeNativeHQ/threenative/tree/develop/examples/integrations/vegetation) into your src/ and follow its README: generate seeded, vertex-budgeted EZ Tree variants offline (tree.ts, from the pinned ez-tree source, not the npm 1.1.0 bundle), write them with treeToGlb into assets/, cook them with assets.models.passes.prune: false (prune strips the uv and _WIND weight your materials read), load with ctx.assets.model and re-material by glTF material name. render/wind.ts is editable TSL wind in world metres; call expandBounds(geometry, minWorldScale) per variant geometry. assets.lod bakes bark levels and keeps alpha-masked leaves at LOD0. Worked sample: the grove game in github.com/ThreeNativeHQ/examples.",
8486
+ "id": "procedural-vegetation",
8487
+ "situations": [
8488
+ "procedural trees",
8489
+ "swaying trees",
8490
+ "tree foliage wind sway",
8491
+ "generate a forest of trees"
8492
+ ]
8493
+ },
8494
+ {
8495
+ "guidance": "The framework owns no IK system. Copy the MIT source in examples/integrations/ik/src/ (https://github.com/ThreeNativeHQ/threenative/tree/develop/examples/integrations/ik) into your src/ and follow its README: it needs the closed-chain-ik/core dependency its own package.json pins, three keeps the only rendered pose, and new ConstrainedIK({root, joints: [{bone, axes, min, max}], effectors: [{bone, orientation?}], iterations, positionTolerance, rotationTolerance}) admits direct Bone hierarchies under rigid or positive-uniform-scale parents (shear, reflection, non-uniform or singular scale throws before the pose is touched). Call ik.update(targets) once per frame after AnimationPlayer/mixer and before render, with one world-space metre position per effector in order plus an optional quaternion only where the effector declared orientation: true; it never starts a loop, never moves the root and installs no bone translation or root-motion controller. Joint limits are X/Y/Z offsets relative to the animation pose supplied that call, so reapply the animation pose before solving to avoid accumulation, and the solver only rotates: bone lengths hold to under 1e-15 m. Iterations are 1-128; an unreachable goal returns converged false with finite residuals and never throws, a solver failure restores the original pose, and dispose() at scene teardown. Worked demo: the rifle grip game in examples/constrained-ik/, which plays on web, desktop native and Android.",
8496
+ "id": "constrained-ik",
8497
+ "situations": [
8498
+ "two-handed grip on a prop",
8499
+ "grip shared by two hands",
8500
+ "rifle grip follows sway",
8501
+ "inverse kinematics for a hand on a target",
8502
+ "hand IK pose correction",
8503
+ "elbow limits during an aiming pose"
8504
+ ]
6545
8505
  }
6546
8506
  ],
6547
8507
  "version": 2