create-threenative 0.2.7 → 0.2.9

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 (541) hide show
  1. package/README.md +3 -1
  2. package/agent-docs/references/assertion-reference.md +87 -35
  3. package/agent-docs/references/auto-exposure.md +57 -0
  4. package/agent-docs/references/capability-reference.md +1306 -62
  5. package/agent-docs/references/debug-surface.md +6 -0
  6. package/agent-docs/references/finding-assets.md +46 -10
  7. package/agent-docs/references/performance-basics.md +5 -4
  8. package/agent-docs/references/terrain-authoring.md +140 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  10. package/capabilities.json +1505 -79
  11. package/dist/index.d.ts +28 -3
  12. package/dist/index.js +402 -167
  13. package/dist/threenative.js +989 -237
  14. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  15. package/dist/web-engine-decal-geometry.js +184 -0
  16. package/dist/web-engine-gltf-loader.js +196 -0
  17. package/dist/web-engine-hdr-loader.js +190 -0
  18. package/dist/web-engine-lut-cube-loader.js +122 -0
  19. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  20. package/dist/web-engine-mesh-bvh.js +32 -0
  21. package/dist/web-engine-post-effects.js +168 -0
  22. package/dist/web-engine-runtime.js +42506 -0
  23. package/package.json +11 -8
  24. package/template-assets/autoExposure.ts +225 -0
  25. package/template-assets/exposure.ts +111 -0
  26. package/template-assets/exposureGraph.ts +178 -0
  27. package/template-assets/exposureReadback.ts +79 -0
  28. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  29. package/template-assets/patches/three@0.185.1.patch +6594 -700
  30. package/template-assets/patches/vite@8.2.0.patch +422 -0
  31. package/template-assets/worldEnvironment.ts +433 -30
  32. package/templates/action-rpg/AGENTS.md +11 -10
  33. package/templates/action-rpg/CLAUDE.md +11 -10
  34. package/templates/action-rpg/package.json +11 -9
  35. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  36. package/templates/action-rpg/src/progress.ts +0 -4
  37. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  38. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  39. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  40. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  41. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  42. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  43. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  44. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  45. package/templates/action-rpg/src/render/exposure.ts +111 -0
  46. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  47. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  48. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  49. package/templates/action-rpg/src/render/lighting.ts +26 -1
  50. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  51. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  52. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  53. package/templates/action-rpg/src/render/quality.ts +61 -2
  54. package/templates/action-rpg/src/render/sky.ts +21 -1
  55. package/templates/action-rpg/src/render/vfx.ts +133 -58
  56. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  57. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  58. package/templates/action-rpg/threenative.config.ts +3 -0
  59. package/templates/action-rpg/vite.config.ts +10 -2
  60. package/templates/minimal/AGENTS.md +9 -10
  61. package/templates/minimal/CLAUDE.md +9 -10
  62. package/templates/minimal/package.json +9 -8
  63. package/templates/minimal/playtests/play.playtest.json +7 -1
  64. package/templates/minimal/playtests/sky.playtest.json +10 -1
  65. package/templates/minimal/src/render/autoExposure.ts +225 -0
  66. package/templates/minimal/src/render/backlightControls.ts +66 -0
  67. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  68. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  69. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  70. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  71. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  72. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  73. package/templates/minimal/src/render/exposure.ts +111 -0
  74. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  75. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  76. package/templates/minimal/src/render/heightFog.ts +118 -0
  77. package/templates/minimal/src/render/lighting.ts +25 -1
  78. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  79. package/templates/minimal/src/render/materialLighting.ts +146 -0
  80. package/templates/minimal/src/render/postprocessing.ts +16 -2
  81. package/templates/minimal/src/render/quality.ts +60 -2
  82. package/templates/minimal/src/render/sky.ts +21 -1
  83. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  84. package/templates/minimal/src/scenes/Play.ts +50 -1
  85. package/templates/minimal/vite.config.ts +10 -2
  86. package/templates/platformer/AGENTS.md +7 -5
  87. package/templates/platformer/CLAUDE.md +7 -5
  88. package/templates/platformer/package.json +11 -9
  89. package/templates/platformer/playtests/performance.playtest.json +7 -1
  90. package/templates/platformer/src/render/autoExposure.ts +225 -0
  91. package/templates/platformer/src/render/backlightControls.ts +66 -0
  92. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  93. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  94. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  95. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  96. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  97. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  98. package/templates/platformer/src/render/exposure.ts +111 -0
  99. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  100. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  101. package/templates/platformer/src/render/heightFog.ts +118 -0
  102. package/templates/platformer/src/render/lighting.ts +26 -1
  103. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  104. package/templates/platformer/src/render/materialLighting.ts +155 -0
  105. package/templates/platformer/src/render/materials.ts +7 -2
  106. package/templates/platformer/src/render/palette.ts +3 -3
  107. package/templates/platformer/src/render/postprocessing.ts +17 -2
  108. package/templates/platformer/src/render/quality.ts +61 -2
  109. package/templates/platformer/src/render/sky.ts +72 -23
  110. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  111. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  112. package/templates/platformer/src/scenes/Play.ts +70 -6
  113. package/templates/platformer/vite.config.ts +10 -2
  114. package/templates/puzzle/AGENTS.md +10 -9
  115. package/templates/puzzle/CLAUDE.md +10 -9
  116. package/templates/puzzle/package.json +11 -9
  117. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  118. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  119. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  120. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  121. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  122. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  123. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  124. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  125. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  126. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  127. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  128. package/templates/puzzle/src/render/exposure.ts +111 -0
  129. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  130. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  131. package/templates/puzzle/src/render/heightFog.ts +118 -0
  132. package/templates/puzzle/src/render/lighting.ts +33 -1
  133. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  134. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  135. package/templates/puzzle/src/render/materials.ts +1 -1
  136. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  137. package/templates/puzzle/src/render/quality.ts +62 -1
  138. package/templates/puzzle/src/render/sky.ts +20 -1
  139. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  140. package/templates/puzzle/src/scenes/Play.ts +51 -2
  141. package/templates/puzzle/vite.config.ts +10 -2
  142. package/templates/racing/AGENTS.md +8 -7
  143. package/templates/racing/CLAUDE.md +8 -7
  144. package/templates/racing/package.json +11 -9
  145. package/templates/racing/playtests/performance.playtest.json +7 -1
  146. package/templates/racing/playtests/survives.playtest.json +6 -0
  147. package/templates/racing/src/render/autoExposure.ts +225 -0
  148. package/templates/racing/src/render/backlightControls.ts +66 -0
  149. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  150. package/templates/racing/src/render/environmentContribution.ts +188 -0
  151. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  152. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  153. package/templates/racing/src/render/environmentSampling.ts +193 -0
  154. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  155. package/templates/racing/src/render/exposure.ts +111 -0
  156. package/templates/racing/src/render/exposureGraph.ts +178 -0
  157. package/templates/racing/src/render/exposureReadback.ts +79 -0
  158. package/templates/racing/src/render/heightFog.ts +118 -0
  159. package/templates/racing/src/render/lighting.ts +29 -1
  160. package/templates/racing/src/render/materialAssignments.ts +160 -0
  161. package/templates/racing/src/render/materialLighting.ts +155 -0
  162. package/templates/racing/src/render/palette.ts +1 -10
  163. package/templates/racing/src/render/postprocessing.ts +17 -2
  164. package/templates/racing/src/render/quality.ts +61 -2
  165. package/templates/racing/src/render/shapes.ts +0 -25
  166. package/templates/racing/src/render/sky.ts +21 -1
  167. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  168. package/templates/racing/src/scenes/Race.ts +91 -3
  169. package/templates/racing/src/track/circuit.ts +0 -9
  170. package/templates/racing/vite.config.ts +10 -2
  171. package/templates/rain/.codex/config.toml +19 -0
  172. package/templates/rain/.cursor/mcp.json +32 -0
  173. package/templates/rain/.gemini/settings.json +32 -0
  174. package/templates/rain/.mcp.json +32 -0
  175. package/templates/rain/.vscode/mcp.json +36 -0
  176. package/templates/rain/.zed/settings.json +36 -0
  177. package/templates/rain/AGENTS.md +95 -0
  178. package/templates/rain/CLAUDE.md +97 -0
  179. package/templates/rain/assets/rain-loop.wav +0 -0
  180. package/templates/rain/assets/thunder.wav +0 -0
  181. package/templates/rain/assets/wind-loop.wav +0 -0
  182. package/templates/rain/index.html +18 -0
  183. package/templates/rain/kit.json +7 -0
  184. package/templates/rain/native-playtests/boot.playtest.json +23 -0
  185. package/templates/rain/native-playtests/lightning.playtest.json +173 -0
  186. package/templates/rain/opencode.json +41 -0
  187. package/templates/rain/package.json +59 -0
  188. package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
  189. package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
  190. package/templates/rain/playtests/automation.playtest.json +133 -0
  191. package/templates/rain/playtests/cinematic.playtest.json +59 -0
  192. package/templates/rain/playtests/flash.playtest.json +27 -0
  193. package/templates/rain/playtests/fly.playtest.json +54 -0
  194. package/templates/rain/playtests/lightning.playtest.json +220 -0
  195. package/templates/rain/playtests/loading.playtest.json +57 -0
  196. package/templates/rain/playtests/paused.playtest.json +59 -0
  197. package/templates/rain/playtests/performance.playtest.json +32 -0
  198. package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
  199. package/templates/rain/playtests/simulation.playtest.json +20 -0
  200. package/templates/rain/playtests/storm.playtest.json +150 -0
  201. package/templates/rain/playtests/survives.playtest.json +58 -0
  202. package/templates/rain/playtests/tiers.playtest.json +194 -0
  203. package/templates/rain/playtests/weather.playtest.json +77 -0
  204. package/templates/rain/public/favicon.svg +5 -0
  205. package/templates/rain/src/audio/storm.ts +314 -0
  206. package/templates/rain/src/game.ts +81 -0
  207. package/templates/rain/src/main.ts +15 -0
  208. package/templates/rain/src/render/autoExposure.ts +225 -0
  209. package/templates/rain/src/render/bloom-shader.ts +65 -0
  210. package/templates/rain/src/render/camera.ts +160 -0
  211. package/templates/rain/src/render/clouds-shader.ts +242 -0
  212. package/templates/rain/src/render/clouds.ts +142 -0
  213. package/templates/rain/src/render/exposure.ts +111 -0
  214. package/templates/rain/src/render/exposureGraph.ts +178 -0
  215. package/templates/rain/src/render/exposureReadback.ts +79 -0
  216. package/templates/rain/src/render/lighting.ts +39 -0
  217. package/templates/rain/src/render/lightning.ts +360 -0
  218. package/templates/rain/src/render/loading.ts +327 -0
  219. package/templates/rain/src/render/materials.ts +19 -0
  220. package/templates/rain/src/render/noise-volume.ts +159 -0
  221. package/templates/rain/src/render/palette.ts +18 -0
  222. package/templates/rain/src/render/post-shader.ts +178 -0
  223. package/templates/rain/src/render/postprocessing.ts +229 -0
  224. package/templates/rain/src/render/quality.ts +161 -0
  225. package/templates/rain/src/render/rain.ts +299 -0
  226. package/templates/rain/src/render/sky.ts +28 -0
  227. package/templates/rain/src/render/world-shader.ts +680 -0
  228. package/templates/rain/src/render/world.ts +146 -0
  229. package/templates/rain/src/render/worldEnvironment.ts +1212 -0
  230. package/templates/rain/src/scenes/Boot.ts +348 -0
  231. package/templates/rain/src/state.ts +261 -0
  232. package/templates/rain/src/style.css +1160 -0
  233. package/templates/rain/src/ui/App.tsx +29 -0
  234. package/templates/rain/src/ui/GameUi.tsx +187 -0
  235. package/templates/rain/src/ui/Hud.tsx +327 -0
  236. package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
  237. package/templates/rain/src/ui/Menu.tsx +370 -0
  238. package/templates/rain/src/ui/automation.ts +60 -0
  239. package/templates/rain/src/ui/main.tsx +7 -0
  240. package/templates/rain/src/ui/tempest.ts +149 -0
  241. package/templates/rain/tailwind.config.ts +2 -0
  242. package/templates/rain/threenative.config.ts +66 -0
  243. package/templates/rain/tools/generate-shaders.mjs +656 -0
  244. package/templates/rain/tools/make-storm-audio.mjs +387 -0
  245. package/templates/rain/tools/storm-dsp.mjs +177 -0
  246. package/templates/rain/tools/tempest-bloom.frag +10 -0
  247. package/templates/rain/tools/tempest-clouds.frag +86 -0
  248. package/templates/rain/tools/tempest-post.frag +47 -0
  249. package/templates/rain/tools/tempest-world.frag +210 -0
  250. package/templates/rain/tools/verify-noise-volume.mjs +61 -0
  251. package/templates/rain/tsconfig.json +17 -0
  252. package/templates/rain/vite.config.ts +45 -0
  253. package/templates/rts/AGENTS.md +10 -11
  254. package/templates/rts/CLAUDE.md +10 -11
  255. package/templates/rts/package.json +10 -8
  256. package/templates/rts/playtests/performance.playtest.json +7 -1
  257. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  258. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  259. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  260. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  261. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  262. package/templates/rts/src/render/army.ts +10 -2
  263. package/templates/rts/src/render/autoExposure.ts +225 -0
  264. package/templates/rts/src/render/backlightControls.ts +66 -0
  265. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  266. package/templates/rts/src/render/environmentContribution.ts +188 -0
  267. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  268. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  269. package/templates/rts/src/render/environmentSampling.ts +193 -0
  270. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  271. package/templates/rts/src/render/exposure.ts +111 -0
  272. package/templates/rts/src/render/exposureGraph.ts +178 -0
  273. package/templates/rts/src/render/exposureReadback.ts +79 -0
  274. package/templates/rts/src/render/heightFog.ts +118 -0
  275. package/templates/rts/src/render/lighting.ts +26 -1
  276. package/templates/rts/src/render/materialAssignments.ts +160 -0
  277. package/templates/rts/src/render/materialLighting.ts +155 -0
  278. package/templates/rts/src/render/postprocessing.ts +8 -2
  279. package/templates/rts/src/render/quality.ts +61 -2
  280. package/templates/rts/src/render/sky.ts +21 -1
  281. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  282. package/templates/rts/src/scenes/Play.ts +54 -3
  283. package/templates/rts/src/sim/ai.ts +0 -1
  284. package/templates/rts/src/sim/terrain.ts +0 -4
  285. package/templates/rts/vite.config.ts +10 -2
  286. package/templates/runner/AGENTS.md +10 -8
  287. package/templates/runner/CLAUDE.md +10 -8
  288. package/templates/runner/package.json +11 -9
  289. package/templates/runner/playtests/performance.playtest.json +10 -1
  290. package/templates/runner/src/physics.ts +0 -1
  291. package/templates/runner/src/render/autoExposure.ts +225 -0
  292. package/templates/runner/src/render/backlightControls.ts +66 -0
  293. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  294. package/templates/runner/src/render/environmentContribution.ts +188 -0
  295. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  296. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  297. package/templates/runner/src/render/environmentSampling.ts +193 -0
  298. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  299. package/templates/runner/src/render/exposure.ts +111 -0
  300. package/templates/runner/src/render/exposureGraph.ts +178 -0
  301. package/templates/runner/src/render/exposureReadback.ts +79 -0
  302. package/templates/runner/src/render/heightFog.ts +118 -0
  303. package/templates/runner/src/render/lighting.ts +26 -1
  304. package/templates/runner/src/render/materialAssignments.ts +160 -0
  305. package/templates/runner/src/render/materialLighting.ts +155 -0
  306. package/templates/runner/src/render/postprocessing.ts +17 -2
  307. package/templates/runner/src/render/quality.ts +61 -2
  308. package/templates/runner/src/render/sky.ts +21 -1
  309. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  310. package/templates/runner/src/scenes/Run.ts +67 -2
  311. package/templates/runner/threenative.config.ts +3 -0
  312. package/templates/runner/vite.config.ts +10 -2
  313. package/templates/sailing/AGENTS.md +14 -13
  314. package/templates/sailing/CLAUDE.md +14 -13
  315. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  316. package/templates/sailing/package.json +11 -9
  317. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  318. package/templates/sailing/src/entities/Ship.ts +38 -18
  319. package/templates/sailing/src/render/autoExposure.ts +225 -0
  320. package/templates/sailing/src/render/backlightControls.ts +66 -0
  321. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  322. package/templates/sailing/src/render/camera.ts +12 -4
  323. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  324. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  325. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  327. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  328. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  329. package/templates/sailing/src/render/exposure.ts +111 -0
  330. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  331. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  332. package/templates/sailing/src/render/heightFog.ts +118 -0
  333. package/templates/sailing/src/render/lighting.ts +26 -1
  334. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  335. package/templates/sailing/src/render/materialLighting.ts +155 -0
  336. package/templates/sailing/src/render/ocean.ts +71 -53
  337. package/templates/sailing/src/render/postprocessing.ts +16 -2
  338. package/templates/sailing/src/render/props.ts +0 -45
  339. package/templates/sailing/src/render/quality.ts +61 -1
  340. package/templates/sailing/src/render/sky.ts +21 -1
  341. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  342. package/templates/sailing/src/scenes/Boot.ts +12 -1
  343. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  344. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  345. package/templates/sailing/threenative.config.ts +3 -0
  346. package/templates/sailing/vite.config.ts +10 -2
  347. package/templates/shooter/AGENTS.md +8 -6
  348. package/templates/shooter/CLAUDE.md +8 -6
  349. package/templates/shooter/package.json +11 -9
  350. package/templates/shooter/playtests/performance.playtest.json +7 -1
  351. package/templates/shooter/src/entities/Enemy.ts +0 -15
  352. package/templates/shooter/src/entities/Rifle.ts +38 -1
  353. package/templates/shooter/src/render/autoExposure.ts +225 -0
  354. package/templates/shooter/src/render/backlightControls.ts +66 -0
  355. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  356. package/templates/shooter/src/render/camera.ts +1 -12
  357. package/templates/shooter/src/render/decals.ts +299 -5
  358. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  359. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  360. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  361. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  362. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  363. package/templates/shooter/src/render/exposure.ts +111 -0
  364. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  365. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  366. package/templates/shooter/src/render/gunfx.ts +0 -1
  367. package/templates/shooter/src/render/heightFog.ts +118 -0
  368. package/templates/shooter/src/render/lighting.ts +26 -1
  369. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  370. package/templates/shooter/src/render/materialLighting.ts +155 -0
  371. package/templates/shooter/src/render/postprocessing.ts +17 -2
  372. package/templates/shooter/src/render/quality.ts +61 -2
  373. package/templates/shooter/src/render/scale.ts +2 -93
  374. package/templates/shooter/src/render/sky.ts +21 -1
  375. package/templates/shooter/src/render/vehicles.ts +0 -17
  376. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  377. package/templates/shooter/src/scenes/Play.ts +64 -2
  378. package/templates/shooter/vite.config.ts +10 -2
  379. package/templates/snow/.codex/config.toml +19 -0
  380. package/templates/snow/.cursor/mcp.json +32 -0
  381. package/templates/snow/.gemini/settings.json +32 -0
  382. package/templates/snow/.mcp.json +32 -0
  383. package/templates/snow/.vscode/mcp.json +36 -0
  384. package/templates/snow/.zed/settings.json +36 -0
  385. package/templates/snow/AGENTS.md +90 -0
  386. package/templates/snow/CLAUDE.md +92 -0
  387. package/templates/snow/README.md +26 -0
  388. package/templates/snow/assets/crunch.wav +0 -0
  389. package/templates/snow/assets/wind.wav +0 -0
  390. package/templates/snow/index.html +12 -0
  391. package/templates/snow/kit.json +7 -0
  392. package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
  393. package/templates/snow/native-playtests/survives.playtest.json +47 -0
  394. package/templates/snow/opencode.json +41 -0
  395. package/templates/snow/package.json +60 -0
  396. package/templates/snow/playtests/footsteps.playtest.json +95 -0
  397. package/templates/snow/playtests/performance.playtest.json +36 -0
  398. package/templates/snow/playtests/snow-physics.playtest.json +154 -0
  399. package/templates/snow/playtests/survives.playtest.json +56 -0
  400. package/templates/snow/playtests/touch-controls.playtest.json +71 -0
  401. package/templates/snow/playtests/weather.playtest.json +119 -0
  402. package/templates/snow/public/favicon.svg +5 -0
  403. package/templates/snow/src/audio.ts +58 -0
  404. package/templates/snow/src/commands.ts +8 -0
  405. package/templates/snow/src/entities/Explorer.ts +279 -0
  406. package/templates/snow/src/game.ts +69 -0
  407. package/templates/snow/src/main.ts +15 -0
  408. package/templates/snow/src/render/autoExposure.ts +225 -0
  409. package/templates/snow/src/render/backlightControls.ts +66 -0
  410. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  411. package/templates/snow/src/render/bootPrint.ts +50 -0
  412. package/templates/snow/src/render/camera.ts +84 -0
  413. package/templates/snow/src/render/environmentContribution.ts +188 -0
  414. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  415. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  416. package/templates/snow/src/render/environmentSampling.ts +193 -0
  417. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  418. package/templates/snow/src/render/explorer.ts +321 -0
  419. package/templates/snow/src/render/exposure.ts +111 -0
  420. package/templates/snow/src/render/exposureGraph.ts +178 -0
  421. package/templates/snow/src/render/exposureReadback.ts +79 -0
  422. package/templates/snow/src/render/heightFog.ts +118 -0
  423. package/templates/snow/src/render/lighting.ts +82 -0
  424. package/templates/snow/src/render/loading.ts +325 -0
  425. package/templates/snow/src/render/materialAssignments.ts +160 -0
  426. package/templates/snow/src/render/materialLighting.ts +155 -0
  427. package/templates/snow/src/render/materials.ts +36 -0
  428. package/templates/snow/src/render/palette.ts +17 -0
  429. package/templates/snow/src/render/postprocessing.ts +58 -0
  430. package/templates/snow/src/render/props.ts +42 -0
  431. package/templates/snow/src/render/quality.ts +193 -0
  432. package/templates/snow/src/render/scenery.ts +244 -0
  433. package/templates/snow/src/render/sky.ts +76 -0
  434. package/templates/snow/src/render/snowSurface.ts +259 -0
  435. package/templates/snow/src/render/touch-controls.ts +143 -0
  436. package/templates/snow/src/render/weather.ts +279 -0
  437. package/templates/snow/src/render/worldEnvironment.ts +1212 -0
  438. package/templates/snow/src/scenes/Boot.ts +12 -0
  439. package/templates/snow/src/scenes/Snow.ts +663 -0
  440. package/templates/snow/src/state.ts +46 -0
  441. package/templates/snow/src/style.css +143 -0
  442. package/templates/snow/src/terrain.ts +64 -0
  443. package/templates/snow/src/ui/App.tsx +15 -0
  444. package/templates/snow/src/ui/Controls.tsx +322 -0
  445. package/templates/snow/src/ui/GameUi.tsx +354 -0
  446. package/templates/snow/src/ui/icons.tsx +54 -0
  447. package/templates/snow/src/ui/main.tsx +7 -0
  448. package/templates/snow/tailwind.config.ts +2 -0
  449. package/templates/snow/threenative.config.ts +54 -0
  450. package/templates/snow/tsconfig.json +17 -0
  451. package/templates/snow/vite.config.ts +45 -0
  452. package/templates/starter/AGENTS.md +11 -16
  453. package/templates/starter/CLAUDE.md +11 -16
  454. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  455. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  456. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  457. package/templates/starter/package.json +11 -9
  458. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  459. package/templates/starter/playtests/movement.playtest.json +192 -0
  460. package/templates/starter/playtests/play.playtest.json +18 -2
  461. package/templates/starter/playtests/production-readiness.playtest.json +1 -1
  462. package/templates/starter/public/grade.cube +735 -0
  463. package/templates/starter/src/entities/Crate.ts +4 -0
  464. package/templates/starter/src/entities/Player.ts +79 -18
  465. package/templates/starter/src/game.ts +1 -0
  466. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  467. package/templates/starter/src/render/autoExposure.ts +225 -0
  468. package/templates/starter/src/render/backlightControls.ts +66 -0
  469. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  470. package/templates/starter/src/render/environmentContribution.ts +188 -0
  471. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  472. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  473. package/templates/starter/src/render/environmentSampling.ts +193 -0
  474. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  475. package/templates/starter/src/render/exposure.ts +111 -0
  476. package/templates/starter/src/render/exposureGraph.ts +178 -0
  477. package/templates/starter/src/render/exposureReadback.ts +79 -0
  478. package/templates/starter/src/render/grade.ts +157 -0
  479. package/templates/starter/src/render/heightFog.ts +118 -0
  480. package/templates/starter/src/render/lighting.ts +26 -1
  481. package/templates/starter/src/render/materialAssignments.ts +160 -0
  482. package/templates/starter/src/render/materialLighting.ts +155 -0
  483. package/templates/starter/src/render/postprocessing.ts +84 -4
  484. package/templates/starter/src/render/quality.ts +80 -8
  485. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  486. package/templates/starter/src/render/rendererGate.ts +36 -0
  487. package/templates/starter/src/render/sky.ts +23 -1
  488. package/templates/starter/src/render/temporalAA.ts +197 -0
  489. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  490. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  491. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  492. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  493. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  494. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  495. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  496. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  497. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  498. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  499. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  500. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  501. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  502. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  503. package/templates/starter/src/render/temporalResolve.ts +139 -0
  504. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  505. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  506. package/templates/starter/src/render/volumetricFog.ts +124 -0
  507. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  508. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  509. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  510. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  511. package/templates/starter/src/scenes/Play.ts +110 -1
  512. package/templates/starter/src/state.ts +1 -0
  513. package/templates/starter/src/ui/Hud.tsx +1 -1
  514. package/templates/starter/src/ui/Menu.tsx +1 -1
  515. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  516. package/templates/starter/vite.config.ts +10 -2
  517. package/templates/tower-defense/AGENTS.md +10 -9
  518. package/templates/tower-defense/CLAUDE.md +10 -9
  519. package/templates/tower-defense/package.json +11 -9
  520. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  521. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  522. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  523. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  524. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  525. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  526. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  527. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  528. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  529. package/templates/tower-defense/src/render/exposure.ts +111 -0
  530. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  531. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  532. package/templates/tower-defense/src/render/lighting.ts +33 -1
  533. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  534. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  535. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  536. package/templates/tower-defense/src/render/quality.ts +61 -2
  537. package/templates/tower-defense/src/render/shapes.ts +0 -3
  538. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  539. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  540. package/templates/tower-defense/vite.config.ts +10 -2
  541. package/templates/minimal/src/scenes/Boot.ts +0 -5
@@ -3,7 +3,7 @@
3
3
 
4
4
  # Capability reference
5
5
 
6
- Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:starter`, and `three`,
6
+ Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
7
7
  generated from the doc tags the engine itself compiles, so this page cannot disagree with
8
8
  the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
9
9
  MCP server is available.
@@ -427,7 +427,7 @@ export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, ind
427
427
 
428
428
  - **Use when:** add hundreds of built objects to the scene without one multi-second frame · stream a detail tier in behind a loading curtain without the page looking hung
429
429
  - **Constraints:** the objects, and where each one goes, stay the game's; this decides only when each joins the graph · input order is the attach order and cannot be changed · a false `while` stops the run and is reported as `stopped`, never thrown
430
- - **Overrides:** sliceSize defaults to 256; `marker: false` silences the TN_ADD_SLICES line, not the report
430
+ - **Overrides:** 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
431
431
 
432
432
  ```ts
433
433
  const report = await addInSlices(objects, (object) => ctx.add(object), {
@@ -531,6 +531,22 @@ import { alwaysRender } from "@threenative/core";
531
531
  alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
532
532
  ```
533
533
 
534
+ ### `AnimationComposer`
535
+
536
+ `class` — Compose game-authored locomotion and masked actions on one Three.js mixer.
537
+
538
+ ```ts
539
+ export class AnimationComposer { … }
540
+ ```
541
+
542
+ - **Use when:** synchronize walk/run/strafe clips with different durations · reload with the upper body while locomotion continues · apply an additive recoil clip with an explicit reference pose · route root motion through collision-aware character movement
543
+ - **Constraints:** one base phase, one masked override, at most two additive layers and eight actions · root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK · root motion excludes velocity-driven stride sync; unsupported parent transforms throw · source clips remain immutable; dispose at scene exit
544
+
545
+ ```ts
546
+ const animation = new AnimationComposer({ root: rig, clips, samples: ["walk", "run"] });
547
+ animation.setWeights([0.5, 0.5]); animation.update(dt);
548
+ ```
549
+
534
550
  ### `AnimationPlayer`
535
551
 
536
552
  `class` — Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
@@ -618,8 +634,8 @@ model.step(1 / 60, { turn: -1, pitch: 0.4 });
618
634
  export class AudioBus { … }
619
635
  ```
620
636
 
621
- - **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · play cannon, wave, and ship sound effects
622
- - **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only
637
+ - **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · hold a loud mix below clipping with a compressor on the bus · play cannon, wave, and ship sound effects
638
+ - **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only · compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum
623
639
  - **Supersedes (writing this fails `pnpm budgets`):** new Audio(
624
640
 
625
641
  ```ts
@@ -671,6 +687,36 @@ const billboard = new Billboard3D(label, { camera });
671
687
  billboard.update();
672
688
  ```
673
689
 
690
+ ### `BlendSpace1D`
691
+
692
+ `class` — Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
693
+
694
+ ```ts
695
+ export class BlendSpace1D { … }
696
+ ```
697
+
698
+ - **Use when:** calculate 1D walk/run blend weights from speed · calculate 2D locomotion weights from forward and strafe intent
699
+ - **Constraints:** duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization · outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
700
+
701
+ ```ts
702
+ const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
703
+ ```
704
+
705
+ ### `BlendSpace2D`
706
+
707
+ `class` — Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
708
+
709
+ ```ts
710
+ export class BlendSpace2D { … }
711
+ ```
712
+
713
+ - **Use when:** calculate 1D walk/run blend weights from speed · calculate 2D locomotion weights from forward and strafe intent
714
+ - **Constraints:** duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization · outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
715
+
716
+ ```ts
717
+ const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
718
+ ```
719
+
674
720
  ### `boneContact`
675
721
 
676
722
  `function` — Measure whether a named bone reaches the object it is supposed to be touching, in metres.
@@ -1170,6 +1216,24 @@ ctx.add(field);
1170
1216
  field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
1171
1217
  ```
1172
1218
 
1219
+ ### `FluidParticles3D`
1220
+
1221
+ `class` — 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.
1222
+
1223
+ ```ts
1224
+ export class FluidParticles3D extends Group { … }
1225
+ ```
1226
+
1227
+ - **Use when:** pour, splash, or dam-break water that fills a container and flows around obstacles · simulate water or another liquid as particles in a fluid simulation · drop a ball or box into liquid and let it displace and float on the water · emit a stream or waterfall of particle fluid and drain it somewhere else · sample particle-fluid density or surface height in a game-owned render node
1228
+ - **Constraints:** add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic · a renderer without WebGPU compute throws a named error at attach; it never draws nothing · `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity · `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
1229
+ - **Overrides:** iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
1230
+
1231
+ ```ts
1232
+ const water = new FluidParticles3D({ capacity: 6000 });
1233
+ ctx.add(water);
1234
+ water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
1235
+ ```
1236
+
1173
1237
  ### `formatSceneWarning`
1174
1238
 
1175
1239
  `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
@@ -1200,6 +1264,22 @@ export function formatSpansWindow(window: ISpanWindow): string { … }
1200
1264
  if (spansRequested()) setSpanRecorder(new SpanRecorder());
1201
1265
  ```
1202
1266
 
1267
+ ### `formatUnlitFoliageWarning`
1268
+
1269
+ `function` — 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.
1270
+
1271
+ ```ts
1272
+ export function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string { … }
1273
+ ```
1274
+
1275
+ - **Use when:** catch the "why does my forest look like cardboard" question before a human plays it · audit a scene a game built from imported GLB foliage
1276
+ - **Constraints:** derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material · it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
1277
+ - **Overrides:** `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
1278
+
1279
+ ```ts
1280
+ defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
1281
+ ```
1282
+
1203
1283
  ### `formatValidationReport`
1204
1284
 
1205
1285
  `function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
@@ -1223,8 +1303,8 @@ if (renderListValidationRequested()) console.log(formatValidationReport(report))
1223
1303
  export class FrameBudget { … }
1224
1304
  ```
1225
1305
 
1226
- - **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass
1227
- - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
1306
+ - **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass · retain every asynchronous GPU render frame for a complete paired benchmark
1307
+ - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero · `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 · 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 · `stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement
1228
1308
 
1229
1309
  ```ts
1230
1310
  defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
@@ -1284,11 +1364,13 @@ if (isMobile()) showTouchControls();
1284
1364
  export class GPUParticles3D extends Sprite implements IComputeDriven { … }
1285
1365
  ```
1286
1366
 
1287
- - **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
1288
- - **Constraints:** geometry, color, and timing remain supplied by the game
1367
+ - **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles · splash spray droplets with lifetime and gravity · spawn water droplets, mist, or foam bubbles above a fluid surface · falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard · kick up a spray of powder snow or dust where a foot or a ball lands · 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 · emitParticle a burst of GPU particles at a world position with its own free slots
1368
+ - **Constraints:** geometry, color, and timing remain supplied by the game · 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 · a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent · requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option · the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view · a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view · when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget
1369
+ - **Overrides:** localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring · onCull: "clear" restarts a returning effect, the default "pause" resumes it with buffers intact · bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence · graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling
1289
1370
 
1290
1371
  ```ts
1291
1372
  const particles = new GPUParticles3D(particleOptions);
1373
+ particles.emitParticle({ count: 220, origin: hit.position });
1292
1374
  ```
1293
1375
 
1294
1376
  ### `GPUReadback`
@@ -1377,9 +1459,9 @@ const uninstall = installSpanProbes(renderer.raw, scene);
1377
1459
  export class InstancedBatch { … }
1378
1460
  ```
1379
1461
 
1380
- - **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
1381
- - **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed
1382
- - **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
1462
+ - **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · automatically select instanced prop detail from projected screen error using baked AutoLOD chains · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
1463
+ - **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed · 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 · unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE
1464
+ - **Overrides:** 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 · castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
1383
1465
 
1384
1466
  ```ts
1385
1467
  const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
@@ -1931,6 +2013,21 @@ export class RenderListValidator { … }
1931
2013
  if (renderListValidationRequested()) console.log(formatValidationReport(report));
1932
2014
  ```
1933
2015
 
2016
+ ### `renderTrapAudit`
2017
+
2018
+ `function` — 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.
2019
+
2020
+ ```ts
2021
+ export function renderTrapAudit(scene: Object3D & { … }
2022
+ ```
2023
+
2024
+ - **Use when:** audit an equirectangular sky too narrow for three's WebGPU PMREM · find visible opaque materials whose authored opacity is ignored
2025
+ - **Constraints:** structural scene reads only, one visible-tree walk per entry, at most five material examples · the audit itself changes no scene state; the game loop's opacity convention is the only writer
2026
+
2027
+ ```ts
2028
+ renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array
2029
+ ```
2030
+
1934
2031
  ### `replay`
1935
2032
 
1936
2033
  `function` — Record or replay deterministic game input and state.
@@ -2093,7 +2190,7 @@ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
2093
2190
  export class Scheduler { … }
2094
2191
  ```
2095
2192
 
2096
- - **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
2193
+ - **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve · a countdown timer: end the level when its time limit runs out
2097
2194
  - **Constraints:** dispose returned handles when the owning scene exits · ease receives progress in the range 0 to 1 and its return value is the interpolation factor
2098
2195
 
2099
2196
  ```ts
@@ -2358,7 +2455,7 @@ invalidateStatic(drawbridge);
2358
2455
  export class TracerPool3D { … }
2359
2456
  ```
2360
2457
 
2361
- - **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
2458
+ - **Use when:** show where a hitscan round went · show each round a weapon fires, one tracer per trigger press · draw incoming fire without spawning projectiles
2362
2459
  - **Constraints:** the surface comes from the game; pooling, travel, and fading belong to the engine · update once per frame and dispose with the owning scene
2363
2460
 
2364
2461
  ```ts
@@ -2366,6 +2463,22 @@ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
2366
2463
  tracers.spawn(muzzle, shotDirection, hit.distance);
2367
2464
  ```
2368
2465
 
2466
+ ### `unlitFoliageWarning`
2467
+
2468
+ `function` — 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.
2469
+
2470
+ ```ts
2471
+ export function unlitFoliageWarning( scene: Object3D & { … }
2472
+ ```
2473
+
2474
+ - **Use when:** catch the "why does my forest look like cardboard" question before a human plays it · audit a scene a game built from imported GLB foliage
2475
+ - **Constraints:** derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material · it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
2476
+ - **Overrides:** `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
2477
+
2478
+ ```ts
2479
+ defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
2480
+ ```
2481
+
2369
2482
  ### `unmarkStatic`
2370
2483
 
2371
2484
  `function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
@@ -2494,8 +2607,8 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
2494
2607
  ```
2495
2608
 
2496
2609
  - **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
2497
- - **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · 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 · 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
2498
- - **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
2610
+ - **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left · `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region · call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
2611
+ - **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
2499
2612
 
2500
2613
  ```ts
2501
2614
  const sun = new DirectionalLight(0xffffff, 3);
@@ -2525,12 +2638,12 @@ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) })
2525
2638
  export class WaterSurface3D { … }
2526
2639
  ```
2527
2640
 
2528
- - **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame
2529
- - **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only · on a crowded scene the mirrored pass is draw-bound: name reflection.layers or pay twice · reflection.refreshInterval is in presented frames; 1 is every frame, and the default · the mirror plane is level, from level alone; do not parent target to a scaled mesh
2641
+ - **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame · automatically reflect terrain and large casters without redrawing instanced small props
2642
+ - **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only · 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 · reflection.refreshInterval is in presented frames; 1 is every frame, and the default · the mirror plane is level, from level alone; do not parent target to a scaled mesh
2643
+ - **Overrides:** 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
2530
2644
 
2531
2645
  ```ts
2532
- const REFLECTED = 1; // the layer the big silhouettes sit on
2533
- const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });
2646
+ const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
2534
2647
  material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
2535
2648
  ```
2536
2649
 
@@ -2741,6 +2854,24 @@ export function View(props: IViewProps): ReactNode { … }
2741
2854
  <View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>
2742
2855
  ```
2743
2856
 
2857
+ ## `@threenative/core/react-css`
2858
+
2859
+ ### `createCssUiRoot`
2860
+
2861
+ `function` — Mount React into a native CSS engine.
2862
+
2863
+ ```ts
2864
+ export function createCssUiRoot(options: ICssUiRootOptions = { … }
2865
+ ```
2866
+
2867
+ - **Use when:** mount a React HUD on the desktop host with no DOM in the runtime · write one React component and run it on the web and on the desktop host
2868
+ - **Constraints:** 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 · import `react`, never `react-dom`, from a native entry · styling is CSS resolved by the native engine; JS only mirrors the element tree
2869
+
2870
+ ```ts
2871
+ const root = createCssUiRoot();
2872
+ root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
2873
+ ```
2874
+
2744
2875
  ## `@threenative/core/ui-layer`
2745
2876
 
2746
2877
  ### `connectUiBridge`
@@ -2874,7 +3005,7 @@ const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackI
2874
3005
  export class Heightfield extends Group implements IComputeDriven { … }
2875
3006
  ```
2876
3007
 
2877
- - **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain
3008
+ - **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain · keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)
2878
3009
  - **Constraints:** sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output · rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
2879
3010
  - **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
2880
3011
 
@@ -2899,18 +3030,18 @@ const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorld
2899
3030
 
2900
3031
  ### `loadTerrainSplat`
2901
3032
 
2902
- `function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Nothing here is a look choice: textures, tiles, tints, thresholds and noise scales all come from the package's table, which the game authors once and its DCC shares.
3033
+ `function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.
2903
3034
 
2904
3035
  ```ts
2905
3036
  export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }
2906
3037
  ```
2907
3038
 
2908
3039
  - **Use when:** terrain textured by splat masks exported from Blender with the world package · the game's terrain should match the DCC's terrain material without a second copy
2909
- - **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `export_terrain_layers.py` recipe · WebGPU allows 16 sampled textures per stage: planes + diffuse maps + normal maps must fit
3040
+ - **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe · WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
2910
3041
  - **Overrides:** every value comes from the package's table; the returned material is the game's to adjust
2911
3042
 
2912
3043
  ```ts
2913
- const surface = await loadTerrainSplat({ assets: ctx.assets, url: "world/world.json" });
3044
+ const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
2914
3045
  const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
2915
3046
  ```
2916
3047
 
@@ -2929,6 +3060,43 @@ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
2929
3060
  const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
2930
3061
  ```
2931
3062
 
3063
+ ### `snowDiscFootprint`
3064
+
3065
+ `function` — A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.
3066
+
3067
+ ```ts
3068
+ export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }
3069
+ ```
3070
+
3071
+ - **Use when:** press a ball, wheel or probe into snow · give a sphere a physically sized snow contact instead of a boot shape
3072
+ - **Constraints:** radius is metres; the footprint never grows with load, only deeper
3073
+ - **Overrides:** softness widens the eased edge without changing the contact radius
3074
+
3075
+ ```ts
3076
+ const footprint = snowDiscFootprint(0.25);
3077
+ ```
3078
+
3079
+ ### `SnowField`
3080
+
3081
+ `class` — 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.
3082
+
3083
+ ```ts
3084
+ export class SnowField { … }
3085
+ ```
3086
+
3087
+ - **Use when:** leave footprints, tracks and tyre ruts in snow that persist and fill in over time · let a pushed sphere carve a connected track and a dropped one settle into a crater · store snow deformation that rendered geometry and collision both read · reset a snowfield between rounds or change its depth at runtime · show how packed the snow is where people have walked or objects have rested
3088
+ - **Constraints:** the field composes onto a Heightfield; construct the terrain first and let this own the surface · zero depth is bare ground: contacts register no indentation at all · out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros
3089
+ - **Requires:** @threenative/core/world Heightfield as the canonical terrain and surface
3090
+ - **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
3091
+
3092
+ ```ts
3093
+ import { Heightfield } from "@threenative/core/world";
3094
+ const 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 });
3095
+ const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
3096
+ snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
3097
+ snow.recover(1 / 60, 0.0012, 0.4);
3098
+ ```
3099
+
2932
3100
  ### `TerrainTiles`
2933
3101
 
2934
3102
  `class` — 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.
@@ -2939,7 +3107,7 @@ export class TerrainTiles extends Object3D implements IComputeDriven { … }
2939
3107
 
2940
3108
  - **Use when:** stream terrain without cracks · keep generated terrain resident around a moving player · put a generated terrain tile into a game-owned physics world
2941
3109
  - **Constraints:** sampleHeight and surface are required game choices; no landform or surface preset is installed · residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws · 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
2942
- - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets
3110
+ - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets
2943
3111
 
2944
3112
  ```ts
2945
3113
  const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
@@ -2980,15 +3148,15 @@ const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer
2980
3148
 
2981
3149
  ### `WorldCells`
2982
3150
 
2983
- `class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, per-asset `maxDistance` filtering, 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 whose package entry names no `lods` is drawn at the levels its own model carries a baked AutoLOD chain for: the levels an instanced draw cannot reach by itself, switched at the distance their error projects over the `autoLod` viewport. Authored `lods` win; a chain is only a fallback.
3151
+ `class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.
2984
3152
 
2985
3153
  ```ts
2986
3154
  export class WorldCells extends Group implements IComputeDriven { … }
2987
3155
  ```
2988
3156
 
2989
3157
  - **Use when:** stream a large Blender-authored world by cell instead of one huge GLB · keep scattered props and hand-placed chunks resident around a moving player · honour per-asset draw distances and hard streaming budgets without a mid-frame throw
2990
- - **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with authored `lods` never consults it · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
2991
- - **Overrides:** 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
3158
+ - **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts · eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
3159
+ - **Overrides:** `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
2992
3160
 
2993
3161
  ```ts
2994
3162
  const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
@@ -3094,12 +3262,47 @@ export class Area3D { … }
3094
3262
 
3095
3263
  - **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
3096
3264
  - **Constraints:** add the area to the physics context before stepping the world
3265
+ - **Requires:** npm i @threenative/physics
3097
3266
  - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated.
3098
3267
 
3099
3268
  ```ts
3100
3269
  const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });
3101
3270
  ```
3102
3271
 
3272
+ ### `attachSnowPhysics`
3273
+
3274
+ `function` — 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.
3275
+
3276
+ ```ts
3277
+ export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }
3278
+ ```
3279
+
3280
+ - **Use when:** leave footprints and tracks where physical bodies actually touch snow · let a dropped or pushed sphere carve and settle into deformable snow · make a crate, capsule or ball compress the surface it rests on
3281
+ - **Constraints:** register `rapier()` before attaching, and call `step` once per fixed step after the physics step · the backend must expose persistent solved contacts and in-place shape refresh; one that does not fails at attach · verified on browser WebGPU and the native Linux desktop host; Android and iOS share the native seam but have not run it · automatic profiles cover sphere, box and capsule; any other shape needs an explicit footprint
3282
+ - **Requires:** @threenative/core/world SnowField as the surface it deforms
3283
+ - **Overrides:** loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour
3284
+
3285
+ ```ts
3286
+ const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });
3287
+ afterPhysics(ctx, (dt) => snowPhysics.step(dt));
3288
+ ```
3289
+
3290
+ ### `boxFootprint`
3291
+
3292
+ `function` — 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.
3293
+
3294
+ ```ts
3295
+ export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }
3296
+ ```
3297
+
3298
+ - **Use when:** let a crate, platform or plank press a rectangular pit into snow · imprint a box's own footprint rather than a circle around it
3299
+ - **Constraints:** halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint
3300
+ - **Requires:** npm i @threenative/physics
3301
+
3302
+ ```ts
3303
+ const footprint = boxFootprint(0.4, 0.25);
3304
+ ```
3305
+
3103
3306
  ### `buildStaticColliders`
3104
3307
 
3105
3308
  `function` — Build fixed trimesh bodies from the meshes a game authored in a scene root.
@@ -3110,6 +3313,7 @@ export function buildStaticColliders( context: IStaticColliderContext, root: Obj
3110
3313
 
3111
3314
  - **Use when:** make the level I built stop the player · turn a cathedral or map scene into static collision
3112
3315
  - **Constraints:** supply the game-owned predicate for decorative meshes; the helper throws when it selects nothing · generated bodies use trimesh geometry and world-space instance transforms
3316
+ - **Requires:** npm i @threenative/physics
3113
3317
 
3114
3318
  ```ts
3115
3319
  const colliders = buildStaticColliders(ctx, level, { predicate: (object) => object.name.startsWith("wall") });
@@ -3125,12 +3329,29 @@ export class Buoyancy3D { … }
3125
3329
 
3126
3330
  - **Use when:** float a boat on waves · keep a hull above a moving water surface
3127
3331
  - **Constraints:** supply hull points, density, drag, and the height source
3332
+ - **Requires:** npm i @threenative/physics
3128
3333
  - **Overrides:** buoyancy disables force application while submergedFraction remains measured
3129
3334
 
3130
3335
  ```ts
3131
3336
  new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
3132
3337
  ```
3133
3338
 
3339
+ ### `capsuleFootprint`
3340
+
3341
+ `function` — 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.
3342
+
3343
+ ```ts
3344
+ export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }
3345
+ ```
3346
+
3347
+ - **Use when:** let a fallen capsule, limb or barrel leave a linear imprint in snow · give a capsule a shape-appropriate snow contact instead of a sphere's dot
3348
+ - **Constraints:** radius and halfHeight are metres and never grow with load
3349
+ - **Requires:** npm i @threenative/physics
3350
+
3351
+ ```ts
3352
+ const footprint = capsuleFootprint(0.5, 0.2);
3353
+ ```
3354
+
3134
3355
  ### `CharacterBody3D`
3135
3356
 
3136
3357
  `class` — Move a character body with collision-aware sliding.
@@ -3141,6 +3362,7 @@ export class CharacterBody3D { … }
3141
3362
 
3142
3363
  - **Use when:** move an enemy or player through a level · keep a character from walking through walls
3143
3364
  - **Constraints:** use moveAndSlide inside the physics update
3365
+ - **Requires:** npm i @threenative/physics
3144
3366
  - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
3145
3367
 
3146
3368
  ```ts
@@ -3157,6 +3379,7 @@ export class CollisionShape3D { … }
3157
3379
 
3158
3380
  - **Use when:** add a capsule or box collider to a character · configure the shape used by a rigid body
3159
3381
  - **Constraints:** create shapes through the owning physics context
3382
+ - **Requires:** npm i @threenative/physics
3160
3383
 
3161
3384
  ```ts
3162
3385
  const shape = CollisionShape3D.capsule(0.5, 0.35);
@@ -3171,6 +3394,7 @@ export function interactionGroups(layer: number, mask: number): number { … }
3171
3394
  ```
3172
3395
 
3173
3396
  - **Use when:** make an enemy collide with the world but not pickups · configure which physics layers interact
3397
+ - **Requires:** npm i @threenative/physics
3174
3398
 
3175
3399
  ```ts
3176
3400
  const groups = interactionGroups(1, 3);
@@ -3186,6 +3410,7 @@ export class Joint3D { … }
3186
3410
 
3187
3411
  - **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism · swing a pendulum, wrecking ball, or hinged door on a joint
3188
3412
  - **Constraints:** both bodies must belong to the same physics context
3413
+ - **Requires:** npm i @threenative/physics
3189
3414
  - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated.
3190
3415
 
3191
3416
  ```ts
@@ -3202,6 +3427,7 @@ export class PhysicsDirectSpaceState3D { … }
3202
3427
 
3203
3428
  - **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
3204
3429
  - **Constraints:** query results are bounded by the configured result limit
3430
+ - **Requires:** npm i @threenative/physics
3205
3431
 
3206
3432
  ```ts
3207
3433
  const space = new PhysicsDirectSpaceState3D(context);
@@ -3217,6 +3443,7 @@ export function rapier(options: IPhysicsOptions = { … }
3217
3443
 
3218
3444
  - **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
3219
3445
  - **Constraints:** place rapier() before recast() in the plugin list
3446
+ - **Requires:** npm i @threenative/physics
3220
3447
 
3221
3448
  ```ts
3222
3449
  const game = defineGame({ plugins: [rapier()] });
@@ -3232,6 +3459,7 @@ export class RigidBody3D { … }
3232
3459
 
3233
3460
  - **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
3234
3461
  - **Constraints:** register rapier() in the game plugin list before using bodies
3462
+ - **Requires:** npm i @threenative/physics
3235
3463
  - **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
3236
3464
  - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated.
3237
3465
 
@@ -3249,6 +3477,7 @@ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyC
3249
3477
 
3250
3478
  - **Use when:** stop a cloth flag, cape, or curtain at an existing physics wall · collide SoftBody3D with fixed box bodies
3251
3479
  - **Constraints:** every body must use CollisionShape3D.box and retain its Three.js object transform · rotated boxes become conservative cloth-local axis-aligned bounds
3480
+ - **Requires:** npm i @threenative/physics
3252
3481
 
3253
3482
  ```ts
3254
3483
  const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
@@ -3264,6 +3493,7 @@ export class VehicleBody3D extends RigidBody3D { … }
3264
3493
 
3265
3494
  - **Use when:** drive a car, truck or bike around a track · make a vehicle roll over kerbs, brake into a corner or stop at a wall
3266
3495
  - **Constraints:** write engineForce, brake and steering every physics update; a car with no input does not move · suspensionStiffness is a frequency squared, not newtons per metre; 100 is a road car and 20 bottoms out
3496
+ - **Requires:** npm i @threenative/physics
3267
3497
  - **Overrides:** a wheel ray never hits the chassis it hangs from, and it honours the chassis collision mask · continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall
3268
3498
 
3269
3499
  ```ts
@@ -3282,6 +3512,7 @@ export class NavigationAgent3D { … }
3282
3512
 
3283
3513
  - **Use when:** enemy walks around a wall · enemy patrols a level and chases the player · enemy walks around a patrol path and chases the player when it sees them · enemy patrols and chases while avoiding obstacles · enemy chases the player with line of sight and obstacle avoidance · NPC walks to a destination · move crew around a ship deck
3284
3514
  - **Constraints:** import NavigationAgent3D from exactly `@threenative/physics/navigation`; `@threenative/physics` is not a valid import for this symbol; use this capability instead of hand-written A*; requires recast() after rapier(), plus a baked NavigationRegion3D
3515
+ - **Requires:** npm i @threenative/physics
3285
3516
 
3286
3517
  ```ts
3287
3518
  import { NavigationAgent3D } from "@threenative/physics/navigation";
@@ -3302,6 +3533,7 @@ export class NavigationObstacle3D { … }
3302
3533
 
3303
3534
  - **Use when:** keep navigation agents away from a blocking prop · make a stationary character affect crowd avoidance
3304
3535
  - **Constraints:** create it after recast() and dispose it with the scene
3536
+ - **Requires:** npm i @threenative/physics
3305
3537
 
3306
3538
  ```ts
3307
3539
  const obstacle = new NavigationObstacle3D({ navigation, object });
@@ -3317,6 +3549,7 @@ export class NavigationRegion3D { … }
3317
3549
 
3318
3550
  - **Use when:** let enemies walk around level geometry · create the baked navmesh required by NavigationAgent3D
3319
3551
  - **Constraints:** bake before creating agents or obstacles
3552
+ - **Requires:** npm i @threenative/physics
3320
3553
 
3321
3554
  ```ts
3322
3555
  const region = new NavigationRegion3D({ navigation, meshes: [floor] });
@@ -3332,6 +3565,7 @@ export function recast(): NavigationPlugin { … }
3332
3565
 
3333
3566
  - **Use when:** enemy walks around a wall · NPC patrols a level and chases a player
3334
3567
  - **Constraints:** requires rapier() earlier in the plugins array
3568
+ - **Requires:** npm i @threenative/physics
3335
3569
 
3336
3570
  ```ts
3337
3571
  const game = defineGame({ plugins: [rapier(), recast()] });
@@ -3674,6 +3908,21 @@ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrame
3674
3908
  assertCaptureNotBlank(png, "first frame");
3675
3909
  ```
3676
3910
 
3911
+ ### `assertDesktopCaptureNotBlank`
3912
+
3913
+ `function` — 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.
3914
+
3915
+ ```ts
3916
+ export function assertDesktopCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }
3917
+ ```
3918
+
3919
+ - **Use when:** guard a native desktop capture of a 3D scene
3920
+ - **Constraints:** keeps the uniform-frame checks and replaces only the bright-pixel floor
3921
+
3922
+ ```ts
3923
+ assertDesktopCaptureNotBlank(png, "panned-culled.png");
3924
+ ```
3925
+
3677
3926
  ### `assertFrameShowsSomething`
3678
3927
 
3679
3928
  `function` — Fail closed when a screenshot is blank or uniform.
@@ -3703,6 +3952,21 @@ export class CaptureGuardError extends Error { … }
3703
3952
  throw new CaptureGuardError("menu", "no bright pixels");
3704
3953
  ```
3705
3954
 
3955
+ ### `collectRegionalTone`
3956
+
3957
+ `function` — Collect opt-in regional tone observations from the same acquired PNG.
3958
+
3959
+ ```ts
3960
+ export function collectRegionalTone( png: Buffer, assertions: readonly IPlaytestToneAssertion[], label: string, atStep?: string, ): IPlaytestRegionalToneObservation[] { … }
3961
+ ```
3962
+
3963
+ - **Use when:** measure a specified pixel crop in a captured playtest frame
3964
+ - **Constraints:** does not acquire another screenshot or alter frame timing
3965
+
3966
+ ```ts
3967
+ collectRegionalTone(png, assertions, "character", "posed");
3968
+ ```
3969
+
3706
3970
  ### `inspectFrame`
3707
3971
 
3708
3972
  `function` — Inspect a PNG frame for visible pixels and luminance variation.
@@ -3748,6 +4012,21 @@ export function jsonByteLength(value: JsonValue): number { … }
3748
4012
  const bytes = jsonByteLength(observation);
3749
4013
  ```
3750
4014
 
4015
+ ### `requestedPlaytestClockMode`
4016
+
4017
+ `function` — 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.
4018
+
4019
+ ```ts
4020
+ export function requestedPlaytestClockMode(): PlaytestClockMode | undefined { … }
4021
+ ```
4022
+
4023
+ - **Use when:** report which clock a playtest producer is really running on, before judging its ticks
4024
+ - **Constraints:** throws on an unrecognised value instead of falling back to a fixed-step run
4025
+
4026
+ ```ts
4027
+ if (requestedPlaytestClockMode() === "wall-clock") host.pumpDrivesTheSimulation();
4028
+ ```
4029
+
3751
4030
  ## `@threenative/playtest/runner`
3752
4031
 
3753
4032
  ### `AdbAndroidDriver`
@@ -3770,7 +4049,7 @@ const adb = discoverAdb(process.env);
3770
4049
  `function` — Execute scenario steps, assertions, and evidence capture.
3771
4050
 
3772
4051
  ```ts
3773
- export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, ): Promise<void> { … }
4052
+ export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, render = false, ): Promise<void> { … }
3774
4053
  ```
3775
4054
 
3776
4055
  - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
@@ -3947,6 +4226,21 @@ const lane = decideDisplayStrategy({ env: process.env, platform: "linux" });
3947
4226
  if (lane.kind === "private-xvfb") throw new Error("refuse to judge this frame rate");
3948
4227
  ```
3949
4228
 
4229
+ ### `desktopConsoleType`
4230
+
4231
+ `function` — Drive a local desktop playtest mailbox.
4232
+
4233
+ ```ts
4234
+ export function desktopConsoleType(stream: "stderr" | "stdout", line: string): string { … }
4235
+ ```
4236
+
4237
+ - **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
4238
+ - **Constraints:** the mailbox lifecycle must be disposed after the run
4239
+
4240
+ ```ts
4241
+ const driver = new DesktopPlaytestDriver(options);
4242
+ ```
4243
+
3950
4244
  ### `DesktopPlaytestDriver`
3951
4245
 
3952
4246
  `class` — Drive a local desktop playtest mailbox.
@@ -4869,6 +5163,122 @@ export class ThreePlaytestPhysicsRecorder { … }
4869
5163
  const physics = new ThreePlaytestPhysicsRecorder(worldPhysics);
4870
5164
  ```
4871
5165
 
5166
+ ## `@threenative/procedural-animals`
5167
+
5168
+ ### `createAnimalActor`
5169
+
5170
+ `function` — Own one actor's pose/lifetime, accepting the completed physics state as its only root writer.
5171
+
5172
+ ```ts
5173
+ export function createAnimalActor(bake: IAnimalBake, options: IAnimalActorOptions) { … }
5174
+ ```
5175
+
5176
+ - **Use when:** follow a baked animal from accepted fixed-step Rapier state
5177
+ - **Constraints:** identity parent required; material and motion are editable game source; no move/Mixer/composer writer exists
5178
+ - **Requires:** npm i @threenative/procedural-animals
5179
+
5180
+ ```ts
5181
+ const wolf = createAnimalActor(bake, { motion, material, ground });
5182
+ ```
5183
+
5184
+ ### `createAnimalGeometry`
5185
+
5186
+ `function` — Validates all bytes before constructing geometry with the bake's skin and rig attributes.
5187
+
5188
+ ```ts
5189
+ export function createAnimalGeometry(buffer: ArrayBuffer): { … }
5190
+ ```
5191
+
5192
+ - **Use when:** construct a Three.js geometry from a validated procedural wolf bake
5193
+ - **Constraints:** this creates bind geometry only; game-owned DQS material and animated bounds remain required
5194
+ - **Requires:** npm i @threenative/procedural-animals
5195
+
5196
+ ```ts
5197
+ const { bake, geometry } = createAnimalGeometry(bytes);
5198
+ ```
5199
+
5200
+ ### `loadAnimalBake`
5201
+
5202
+ `function` — Resolves and loads a prebuilt wolf through the game's ordinary asset resolver.
5203
+
5204
+ ```ts
5205
+ export async function loadAnimalBake( assets: IAnimalAssetResolver, logicalPath: string, options: { … }
5206
+ ```
5207
+
5208
+ - **Use when:** load a cooked animal from ctx.assets without runtime generation
5209
+ - **Constraints:** a corrupt served bake rejects rather than falling back to a different file
5210
+ - **Requires:** npm i @threenative/procedural-animals
5211
+
5212
+ ```ts
5213
+ const bake = await loadAnimalBake(ctx.assets, "wolf.animal");
5214
+ ```
5215
+
5216
+ ### `parseAnimalBake`
5217
+
5218
+ `function` — Validates a pinned wolf PANM bake before constructing any renderer resource.
5219
+
5220
+ ```ts
5221
+ export function parseAnimalBake(buffer: ArrayBuffer): IAnimalBake { … }
5222
+ ```
5223
+
5224
+ - **Use when:** validate a baked procedural animal before allocating geometry
5225
+ - **Constraints:** unknown revisions, malformed sections, indices and skin weights throw by name
5226
+ - **Requires:** npm i @threenative/procedural-animals
5227
+
5228
+ ```ts
5229
+ const bake = parseAnimalBake(bytes);
5230
+ ```
5231
+
5232
+ ## `@threenative/procedural-animals/build`
5233
+
5234
+ ### `animalBakePass`
5235
+
5236
+ `function` — Validate staged PANM sources inside the existing asset compiler; it owns the hashed manifest.
5237
+
5238
+ ```ts
5239
+ export function animalBakePass() { … }
5240
+ ```
5241
+
5242
+ - **Use when:** cook staged animal bakes through the ordinary asset pipeline
5243
+ - **Constraints:** only .animal inputs are interpreted; corruption fails the cook, without regeneration
5244
+ - **Requires:** npm i @threenative/procedural-animals
5245
+
5246
+ ```ts
5247
+ await compileAssets({ passes: [animalBakePass()] });
5248
+ ```
5249
+
5250
+ ### `bakeWolf`
5251
+
5252
+ `function` — Bake the pinned wolf on the build machine, never on the portable runtime path.
5253
+
5254
+ ```ts
5255
+ export async function bakeWolf(options: IWolfBakeOptions): Promise<ArrayBuffer> { … }
5256
+ ```
5257
+
5258
+ - **Use when:** bake high and crowd wolf geometry before the ordinary asset cook
5259
+ - **Constraints:** exact pinned Node runtime, donor revision, options and generated bytes are validated; no worker is created
5260
+ - **Requires:** npm i @threenative/procedural-animals
5261
+
5262
+ ```ts
5263
+ const bytes = await bakeWolf({ seed: 7, tier: "crowd" });
5264
+ ```
5265
+
5266
+ ### `bakeWolfToFile`
5267
+
5268
+ `function` — Stage a validated source bake with a same-directory atomic rename, then use compileAssets.
5269
+
5270
+ ```ts
5271
+ export async function bakeWolfToFile( options: IWolfBakeOptions, destination: string, ): Promise<string> { … }
5272
+ ```
5273
+
5274
+ - **Use when:** publish a generated wolf without replacing the last valid bake on interruption
5275
+ - **Constraints:** validation and generation complete before the destination is touched; temporary files are removed on failure
5276
+ - **Requires:** npm i @threenative/procedural-animals
5277
+
5278
+ ```ts
5279
+ await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
5280
+ ```
5281
+
4872
5282
  ## `@threenative/raw-unreal`
4873
5283
 
4874
5284
  ### `createThreeGeometry`
@@ -5258,82 +5668,825 @@ function sparkle
5258
5668
  sparkle(...)
5259
5669
  ```
5260
5670
 
5261
- ## `@threenative/ueformat`
5671
+ ## `@threenative/terrain`
5262
5672
 
5263
- ### `createThreeGeometry`
5673
+ ### `applyPlacementOverrides`
5264
5674
 
5265
- `function` — Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.
5675
+ `function` — Attach manual transforms to raw evaluated candidates and report orphan keys.
5266
5676
 
5267
5677
  ```ts
5268
- export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }
5678
+ export function applyPlacementOverrides(state: ITerrainState, value: unknown): ITerrainState { … }
5269
5679
  ```
5270
5680
 
5271
- - **Use when:** convert one Unreal mesh LOD into a three.js BufferGeometry by hand · build custom scene objects from Unreal mesh data instead of a whole model
5272
- - **Constraints:** rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed
5273
- - **Requires:** npm i @threenative/ueformat
5681
+ - **Use when:** retain manual prop transforms across terrain scatter re-evaluation
5682
+ - **Constraints:** headless authoring; game applies transforms against its model bounds and actual terrain surface
5683
+ - **Requires:** npm i -D @threenative/terrain
5684
+ - **Overrides:** transform.grounding=false preserves requested Y while the game still measures clearance
5274
5685
 
5275
5686
  ```ts
5276
- const geometry = createThreeGeometry(model.lods[0]);
5687
+ const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
5277
5688
  ```
5278
5689
 
5279
- ### `createThreeObject`
5690
+ ### `bakeMesh`
5280
5691
 
5281
- `function` — Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.
5692
+ `function` — Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
5282
5693
 
5283
5694
  ```ts
5284
- export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }
5695
+ export function bakeMesh( state: ITerrainState, { … }
5285
5696
  ```
5286
5697
 
5287
- - **Use when:** put a mesh exported from an Unreal package on screen · load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry
5288
- - **Constraints:** every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial · parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job
5289
- - **Requires:** npm i @threenative/ueformat
5698
+ - **Use when:** bake an authored terrain into portable indexed mesh arrays
5699
+ - **Constraints:** no material is chosen; vertex colours exist only with a caller-supplied palette
5700
+ - **Requires:** npm i @threenative/terrain
5701
+ - **Overrides:** step, chunk bounds, skirtDepth and palette belong to the caller
5290
5702
 
5291
5703
  ```ts
5292
- const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });
5704
+ const mesh = bakeMesh(new Terrain({ resolution: 17 }).evaluate());
5293
5705
  ```
5294
5706
 
5295
- ### `parseUEModel`
5707
+ ### `bakeTerrain`
5296
5708
 
5297
- `function` — Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.
5709
+ `function` — Bakes finite LOD chunks, the same collision samples and resolved placements.
5298
5710
 
5299
5711
  ```ts
5300
- export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }
5712
+ export function bakeTerrain( state: ITerrainState, { … }
5301
5713
  ```
5302
5714
 
5303
- - **Use when:** parse a mesh exported from an Unreal package without Unreal installed · inspect the LODs, skeleton, sockets, and collision inside a .uemodel file
5304
- - **Constraints:** only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset · ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation
5305
- - **Requires:** npm i @threenative/ueformat
5715
+ - **Use when:** prepare terrain arrays and collision before a game starts
5716
+ - **Constraints:** collision origin is the southwest corner; engine Heightfield origin is its centre
5717
+ - **Requires:** npm i @threenative/terrain
5718
+ - **Overrides:** chunkCells, lodSteps, skirtDepth and palette are explicit authoring choices
5306
5719
 
5307
5720
  ```ts
5308
- const model = parseUEModel(await file.arrayBuffer());
5721
+ const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCells: 64 });
5309
5722
  ```
5310
5723
 
5311
- ### `summarizeUEModel`
5724
+ ### `bakeWorldPackage`
5312
5725
 
5313
- `function` — Summarizes a parsed `.uemodel` — LOD, material, skeleton, collision, and unknown-attribute counts — without dumping vertex arrays, for logs, validation, and build reports.
5726
+ `function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
5314
5727
 
5315
5728
  ```ts
5316
- export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }
5729
+ export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }
5317
5730
  ```
5318
5731
 
5319
- - **Use when:** report what a UEFormat model contains without dumping its vertex data · validate a .uemodel file before building geometry from it
5320
- - **Constraints:** the summary reflects one already-parsed model; it does not read files itself
5321
- - **Requires:** npm i @threenative/ueformat
5732
+ - **Use when:** hand an evaluated Strata terrain to a game without a Blender round trip
5733
+ - **Constraints:** headless authoring; no three, no DOM, and nothing here decides how the world looks
5734
+ - **Requires:** npm i -D @threenative/terrain
5735
+ - **Overrides:** every asset path, bound, LOD distance and cell size comes from the caller's options
5322
5736
 
5323
5737
  ```ts
5324
- const summary = summarizeUEModel(parseUEModel(buffer));
5738
+ const { manifest, files } = bakeWorldPackage(state, { assets });
5325
5739
  ```
5326
5740
 
5327
- ### `UEFormatError`
5741
+ ### `createSegmentIndex`
5328
5742
 
5329
- `class` — The error thrown for every malformed, truncated, or unsupported `.uemodel` input, carrying a stable `code` and the byte offset where validation stopped.
5743
+ `function` — Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
5330
5744
 
5331
5745
  ```ts
5332
- export class UEFormatError extends Error { … }
5746
+ export function createSegmentIndex<T>( segments: readonly IWaterSegment<T>[], cellSize: number, ): ISegmentIndex<T> { … }
5333
5747
  ```
5334
5748
 
5335
- - **Use when:** tell why a .uemodel file failed to load · report a malformed Unreal export with its byte offset instead of a generic error
5336
- - **Constraints:** every parse and geometry failure surfaces as this error; nothing malformed is silently skipped
5749
+ - **Use when:** test scatter candidates or terrain vertices against rivers and lakes without scanning every segment · find which river stations can reach a heightfield vertex when baking a wet margin
5750
+ - **Constraints:** returns candidates only; the caller applies its own exact distance and level test
5751
+ - **Requires:** npm i @threenative/terrain
5752
+
5753
+ ```ts
5754
+ const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);
5755
+ ```
5756
+
5757
+ ### `decodeHeightPNG`
5758
+
5759
+ `function` — CRC-checked bounded non-interlaced grayscale PNG height decoder.
5760
+
5761
+ ```ts
5762
+ export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options: IDecodeHeightPngOptions = { … }
5763
+ ```
5764
+
5765
+ - **Use when:** import numerical PNG8 or PNG16 terrain elevations
5766
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5767
+ - **Requires:** npm i @threenative/terrain
5768
+
5769
+ ```ts
5770
+ const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);
5771
+ ```
5772
+
5773
+ ### `decodeRAW16`
5774
+
5775
+ `function` — Validates dimensions and range before decoding numerical height samples.
5776
+
5777
+ ```ts
5778
+ export function decodeRAW16( input: Uint8Array | ArrayBuffer, { … }
5779
+ ```
5780
+
5781
+ - **Use when:** import a RAW16 terrain height buffer with explicit dimensions
5782
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5783
+ - **Requires:** npm i @threenative/terrain
5784
+
5785
+ ```ts
5786
+ const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });
5787
+ ```
5788
+
5789
+ ### `encodeGLB`
5790
+
5791
+ `function` — Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.
5792
+
5793
+ ```ts
5794
+ export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }
5795
+ ```
5796
+
5797
+ - **Use when:** export baked terrain geometry without engine extensions
5798
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5799
+ - **Requires:** npm i @threenative/terrain
5800
+
5801
+ ```ts
5802
+ const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
5803
+ ```
5804
+
5805
+ ### `encodeHeightPNG`
5806
+
5807
+ `function` — Encodes numerical grayscale PNG16 with embedded elevation range.
5808
+
5809
+ ```ts
5810
+ export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }
5811
+ ```
5812
+
5813
+ - **Use when:** export a terrain heightmap without an eight-bit colour conversion
5814
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5815
+ - **Requires:** npm i @threenative/terrain
5816
+
5817
+ ```ts
5818
+ const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());
5819
+ ```
5820
+
5821
+ ### `encodeRAW16`
5822
+
5823
+ `function` — Encodes finite metre elevations as an explicit-range RAW16 buffer.
5824
+
5825
+ ```ts
5826
+ export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }
5827
+ ```
5828
+
5829
+ - **Use when:** export terrain heights with a numerical range sidecar
5830
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5831
+ - **Requires:** npm i @threenative/terrain
5832
+
5833
+ ```ts
5834
+ const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });
5835
+ ```
5836
+
5837
+ ### `encodeSplatPNGs`
5838
+
5839
+ `function` — Encodes the eight linear material-weight channels as two RGBA images.
5840
+
5841
+ ```ts
5842
+ export async function encodeSplatPNGs(state: ITerrainState) { … }
5843
+ ```
5844
+
5845
+ - **Use when:** export terrain splat weights as linear data
5846
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5847
+ - **Requires:** npm i @threenative/terrain
5848
+
5849
+ ```ts
5850
+ const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());
5851
+ ```
5852
+
5853
+ ### `encodeZIP`
5854
+
5855
+ `function` — Deterministic store-method ZIP with safe unique relative filenames.
5856
+
5857
+ ```ts
5858
+ export function encodeZIP(files: readonly IExportFile[]) { … }
5859
+ ```
5860
+
5861
+ - **Use when:** archive derived terrain files without another dependency
5862
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5863
+ - **Requires:** npm i @threenative/terrain
5864
+
5865
+ ```ts
5866
+ const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
5867
+ ```
5868
+
5869
+ ### `gradientAt`
5870
+
5871
+ `function` — World-space height gradient from the canonical samples.
5872
+
5873
+ ```ts
5874
+ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }
5875
+ ```
5876
+
5877
+ - **Use when:** measure an authored terrain gradient in metres
5878
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5879
+ - **Requires:** npm i @threenative/terrain
5880
+
5881
+ ```ts
5882
+ const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
5883
+ ```
5884
+
5885
+ ### `makeExport`
5886
+
5887
+ `function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
5888
+
5889
+ ```ts
5890
+ export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }
5891
+ ```
5892
+
5893
+ - **Use when:** export a terrain recipe and its numerical runtime data
5894
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5895
+ - **Requires:** npm i @threenative/terrain
5896
+
5897
+ ```ts
5898
+ const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
5899
+ ```
5900
+
5901
+ ### `sampleHeight`
5902
+
5903
+ `function` — Bilinear query of canonical height samples; triangle sampling is a separate contract.
5904
+
5905
+ ```ts
5906
+ 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, )
5907
+ ```
5908
+
5909
+ - **Use when:** query an authored heightfield at world coordinates
5910
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5911
+ - **Requires:** npm i @threenative/terrain
5912
+
5913
+ ```ts
5914
+ const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
5915
+ ```
5916
+
5917
+ ### `slopeAtIndex`
5918
+
5919
+ `function` — Slope in degrees at a heightfield sample.
5920
+
5921
+ ```ts
5922
+ export function slopeAtIndex(grid: ISampledGrid, i: number): number { … }
5923
+ ```
5924
+
5925
+ - **Use when:** measure terrain slope for authoring diagnostics
5926
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5927
+ - **Requires:** npm i @threenative/terrain
5928
+
5929
+ ```ts
5930
+ const slope = slopeAtIndex(new Terrain({ resolution: 17 }).evaluate(), 0);
5931
+ ```
5932
+
5933
+ ### `slopeQuantile`
5934
+
5935
+ `function` — 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.
5936
+
5937
+ ```ts
5938
+ export function slopeQuantile(grid: ISampledGrid, quantile: number): number { … }
5939
+ ```
5940
+
5941
+ - **Use when:** place rocks or cliffs on a terrain's own steepest ground instead of a fixed slope in degrees
5942
+ - **Constraints:** interior vertices only (edges have one-sided differences); quantile must be in [0, 1]
5943
+ - **Requires:** npm i @threenative/terrain
5944
+
5945
+ ```ts
5946
+ const steep = slopeQuantile(grid, 0.98); if (slopeAt(x, z) > Math.min(30, steep)) placeRock(x, z);
5947
+ ```
5948
+
5949
+ ### `splinePoints`
5950
+
5951
+ `function` — Recovered horizontal Catmull–Rom and vertically linear profile sampler.
5952
+
5953
+ ```ts
5954
+ export function splinePoints( points: readonly (readonly [number, number, number])[], step = 3, smooth = true, ): [number, number, number][] { … }
5955
+ ```
5956
+
5957
+ - **Use when:** sample a road or river profile without vertical overshoot
5958
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
5959
+ - **Requires:** npm i @threenative/terrain
5960
+
5961
+ ```ts
5962
+ const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
5963
+ ```
5964
+
5965
+ ### `Terrain`
5966
+
5967
+ `class` — Ordered, stable-ID terrain authoring with synchronous atomic transactions.
5968
+
5969
+ ```ts
5970
+ export class Terrain { … }
5971
+ ```
5972
+
5973
+ - **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game
5974
+ - **Constraints:** authoring stays outside the game's steady-play graph; no renderer or physics is created · units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin · `resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025 · `seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays · `evaluate()` is synchronous on the calling thread: run it in a build script, never per frame · no art is chosen or shipped: materials, models and texture paths belong to the game
5975
+ - **Requires:** npm i @threenative/terrain
5976
+ - **Overrides:** size, resolution, seed and all layer parameters are caller choices
5977
+
5978
+ ```ts
5979
+ const terrain = new Terrain({ size: 512, resolution: 257, seed: 73 }).noise({ id: "hills", amplitude: 35 });
5980
+ ```
5981
+
5982
+ ### `TerrainEvaluator`
5983
+
5984
+ `class` — Recovered prefix-caching authoring evaluator. Returned buffers belong to the caller.
5985
+
5986
+ ```ts
5987
+ export class TerrainEvaluator { … }
5988
+ ```
5989
+
5990
+ - **Use when:** reuse terrain evaluation prefixes while authoring a finite heightfield
5991
+ - **Constraints:** evaluates authoring documents only; games consume pre-baked arrays
5992
+ - **Requires:** npm i @threenative/terrain
5993
+ - **Overrides:** cacheMB bounds retained prefix data
5994
+
5995
+ ```ts
5996
+ const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());
5997
+ ```
5998
+
5999
+ ### `validateDocument`
6000
+
6001
+ `function` — Validates the recovered recipe schema, operation allow-lists and numeric bounds.
6002
+
6003
+ ```ts
6004
+ export function validateDocument(doc: ITerrainDocument): void { … }
6005
+ ```
6006
+
6007
+ - **Use when:** validate a terrain document before accepting an authoring write
6008
+ - **Constraints:** authoring data only; the game owns appearance, physics and rendering
6009
+ - **Requires:** npm i @threenative/terrain
6010
+
6011
+ ```ts
6012
+ validateDocument(new Terrain({ resolution: 17 }).toJSON());
6013
+ ```
6014
+
6015
+ ### `validatePlacementOverrides`
6016
+
6017
+ `function` — Validate and clone stable-key placement transforms before saving or previewing them.
6018
+
6019
+ ```ts
6020
+ export function validatePlacementOverrides( value: unknown = { … }
6021
+ ```
6022
+
6023
+ - **Use when:** validate finite positive manual prop transforms before a terrain authoring transaction
6024
+ - **Constraints:** grounding defaults on only when omitted; position and scale have three components and quaternion is unit length
6025
+ - **Requires:** npm i -D @threenative/terrain
6026
+ - **Overrides:** grounding=false preserves authored Y and keeps clearance observable
6027
+
6028
+ ```ts
6029
+ const transforms = validatePlacementOverrides(document.placementOverrides);
6030
+ ```
6031
+
6032
+ ## `@threenative/terrain/editor`
6033
+
6034
+ ### `checkEnvironmentAssets`
6035
+
6036
+ `function` — Check that the images an environment names are registered environment or image assets. @summary Validate the assets a preview environment refers to
6037
+
6038
+ ```ts
6039
+ export function checkEnvironmentAssets( environment: IEnvironment, assets: readonly { … }
6040
+ ```
6041
+
6042
+ - **Use when:** refuse a saved environment whose sky or lighting image is not a registered file
6043
+ - **Constraints:** throws by name; HDR/EXR environment files and ordinary images are accepted, models are not
6044
+ - **Requires:** npm i -D @threenative/terrain
6045
+ - **Overrides:** the project owns which images it registers
6046
+
6047
+ ```ts
6048
+ checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
6049
+ ```
6050
+
6051
+ ### `focusCamera`
6052
+
6053
+ `function` — Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera
6054
+
6055
+ ```ts
6056
+ export function focusCamera( camera: ISavedCamera, request: IFocusRequest, resolve: IFocusResolver, ): IFocusOutcome { … }
6057
+ ```
6058
+
6059
+ - **Use when:** frame one selected prop, a registered landmark, a terrain region or a local point
6060
+ - **Constraints:** framing only; an unknown target returns a named diagnostic and no camera
6061
+ - **Requires:** npm i -D @threenative/terrain
6062
+ - **Overrides:** the view supplies target bounds, the live aspect and the camera to keep
6063
+
6064
+ ```ts
6065
+ const outcome = focusCamera(camera, { target: { kind: "prop", id: "pine-3" }, aspect: 16 / 9 }, resolve);
6066
+ ```
6067
+
6068
+ ### `inspectImage`
6069
+
6070
+ `function` — 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
6071
+
6072
+ ```ts
6073
+ export function inspectImage( bytes: Uint8Array, format: string, limits: { … }
6074
+ ```
6075
+
6076
+ - **Use when:** check an imported surface or environment image for damage and for the project's size limit
6077
+ - **Constraints:** headers and checksums only; throws by name for a damaged, truncated or oversize file
6078
+ - **Requires:** npm i -D @threenative/terrain
6079
+ - **Overrides:** the project sets the dimension limit
6080
+
6081
+ ```ts
6082
+ const report = inspectImage(bytes, "png", { maxDimension: 8192 });
6083
+ ```
6084
+
6085
+ ### `inspectSpatial`
6086
+
6087
+ `function` — Read-only spatial inspection of one evaluated terrain revision.
6088
+
6089
+ ```ts
6090
+ export function inspectSpatial( state: ITerrainState, revision: string, query: ISpatialQuery, ): ISpatialObservation { … }
6091
+ ```
6092
+
6093
+ - **Use when:** measure a point, profile a transect or score a saved reference against the world
6094
+ - **Constraints:** authoring data only; queries outside the extent or without observations throw
6095
+ - **Requires:** npm i -D @threenative/terrain
6096
+ - **Overrides:** the caller owns the revision identity and the evaluated state being inspected
6097
+
6098
+ ```ts
6099
+ const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
6100
+ ```
6101
+
6102
+ ### `mountTerrainEditor`
6103
+
6104
+ `function` — Mount recovered terrain controls around the project-owned ThreeNative view.
6105
+
6106
+ ```ts
6107
+ export async function mountTerrainEditor(options: { … }
6108
+ ```
6109
+
6110
+ - **Use when:** open the terrain brush and layer GUI around game-owned rendering
6111
+ - **Constraints:** browser authoring only; createView and materialColours are required game choices
6112
+ - **Requires:** npm i -D @threenative/terrain
6113
+ - **Overrides:** createView owns the renderer scene, materials, lighting and camera
6114
+
6115
+ ```ts
6116
+ await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
6117
+ ```
6118
+
6119
+ ### `probeTerrain`
6120
+
6121
+ `function` — Probe the evaluated surface at one world point, separating bilinear from triangle values.
6122
+
6123
+ ```ts
6124
+ export function probeTerrain( state: ITerrainState, revision: string, at: readonly number[], ): IPointObservation { … }
6125
+ ```
6126
+
6127
+ - **Use when:** measure an authored terrain point with provenance and a revision identity
6128
+ - **Constraints:** authoring data only; non-finite, malformed and out-of-extent queries throw
6129
+ - **Requires:** npm i -D @threenative/terrain
6130
+ - **Overrides:** the caller owns the revision identity and the evaluated state being inspected
6131
+
6132
+ ```ts
6133
+ const probe = probeTerrain(state, revision, [12, -4]);
6134
+ ```
6135
+
6136
+ ### `runCameraOperation`
6137
+
6138
+ `function` — Run one create / get / list / update / delete / activate operation over saved cameras. @summary Apply an editor camera operation to a saved camera set
6139
+
6140
+ ```ts
6141
+ export function runCameraOperation(set: ICameraSet, operation: unknown): ICameraResult { … }
6142
+ ```
6143
+
6144
+ - **Use when:** drive the terrain editor camera list from an agent or the GUI through one shared dispatch
6145
+ - **Constraints:** pure: the input set is never mutated, an unknown id throws, and deleting the live camera falls back
6146
+ - **Requires:** npm i -D @threenative/terrain
6147
+ - **Overrides:** the caller persists the returned set against its own revision
6148
+
6149
+ ```ts
6150
+ const next = runCameraOperation(set, { op: "activate", id: "survey" });
6151
+ ```
6152
+
6153
+ ### `runEnvironmentOperation`
6154
+
6155
+ `function` — Apply one get / patch / reset against the saved environment overrides; the caller commits it. @summary Run one preview-environment operation
6156
+
6157
+ ```ts
6158
+ export function runEnvironmentOperation( current: IEnvironment, operation: unknown, ): IEnvironmentResult { … }
6159
+ ```
6160
+
6161
+ - **Use when:** patch sun, haze, exposure or sea overrides from a controller or the editor GUI
6162
+ - **Constraints:** authoring metadata only; a null field returns to the project's own value
6163
+ - **Requires:** npm i -D @threenative/terrain
6164
+ - **Overrides:** the project's render source decides what each value does
6165
+
6166
+ ```ts
6167
+ const result = runEnvironmentOperation({}, { op: "patch", values: { sun: { elevation: 25 } } });
6168
+ ```
6169
+
6170
+ ### `sniff`
6171
+
6172
+ `function` — 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
6173
+
6174
+ ```ts
6175
+ export function sniff( bytes: Uint8Array, ): { … }
6176
+ ```
6177
+
6178
+ - **Use when:** decide whether a dropped or downloaded file is a model, surface image or environment image
6179
+ - **Constraints:** reads only the first bytes; a file it cannot name returns undefined and must be refused
6180
+ - **Requires:** npm i -D @threenative/terrain
6181
+ - **Overrides:** the caller decides what to do with an unknown file
6182
+
6183
+ ```ts
6184
+ const kind = sniff(new Uint8Array(await file.arrayBuffer()))?.kind;
6185
+ ```
6186
+
6187
+ ### `surfaceSpace`
6188
+
6189
+ `function` — 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
6190
+
6191
+ ```ts
6192
+ export function surfaceSpace(input: string): "srgb" | "linear" { … }
6193
+ ```
6194
+
6195
+ - **Use when:** decide how an imported image bound to a named surface input must be sampled
6196
+ - **Constraints:** throws by name for an input that is not <surface>.<channel> with a known channel
6197
+ - **Requires:** npm i -D @threenative/terrain
6198
+ - **Overrides:** the project owns which surface inputs exist
6199
+
6200
+ ```ts
6201
+ const space = surfaceSpace("bark.normal");
6202
+ ```
6203
+
6204
+ ### `TerrainEditorController`
6205
+
6206
+ `class` — HTTP controller for the project-local terrain editor.
6207
+
6208
+ ```ts
6209
+ export class TerrainEditorController { … }
6210
+ ```
6211
+
6212
+ - **Use when:** inspect and atomically edit the terrain editor from an agent
6213
+ - **Constraints:** optional tooling; only subscribe/mount touches DOM; stale revisions fail explicitly
6214
+ - **Requires:** npm i -D @threenative/terrain
6215
+ - **Overrides:** editorUrl is the activation-returned project URL
6216
+
6217
+ ```ts
6218
+ const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
6219
+ ```
6220
+
6221
+ ### `validateAsset`
6222
+
6223
+ `function` — Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry
6224
+
6225
+ ```ts
6226
+ export function validateAsset(input: unknown): IProjectAsset { … }
6227
+ ```
6228
+
6229
+ - **Use when:** check a model, image or environment asset entry before saving it in the authoring document
6230
+ - **Constraints:** authoring metadata only; ids, content-hashed paths, bounds and unit adjustments are checked, files are not read
6231
+ - **Requires:** npm i -D @threenative/terrain
6232
+ - **Overrides:** the project owns its asset directory and which entries it keeps
6233
+
6234
+ ```ts
6235
+ const asset = validateAsset({ id: "oak", kind: "model", name: "oak.glb", path: "models/0123456789ab-oak.glb", sha256: "0123456789ab".padEnd(64, "0"), bytes: 2180, status: "ready" });
6236
+ ```
6237
+
6238
+ ### `validateAssets`
6239
+
6240
+ `function` — Validate the whole asset list of an authoring document. @summary Validate the registered terrain-editor assets
6241
+
6242
+ ```ts
6243
+ export function validateAssets(input: unknown): IProjectAsset[] { … }
6244
+ ```
6245
+
6246
+ - **Use when:** check every registered model, image and environment entry together, with unique ids
6247
+ - **Constraints:** at most 64 entries; unique ids; each entry as validateAsset
6248
+ - **Requires:** npm i -D @threenative/terrain
6249
+ - **Overrides:** the project owns its asset directory and which entries it keeps
6250
+
6251
+ ```ts
6252
+ const assets = validateAssets(document.assets ?? []);
6253
+ ```
6254
+
6255
+ ### `validateCamera`
6256
+
6257
+ `function` — Normalise and validate one saved camera, exactly as a document commit would store it. @summary Validate an editor observation camera bookmark
6258
+
6259
+ ```ts
6260
+ export function validateCamera( input: unknown, existing: readonly ISavedCamera[] = [], ): ISavedCamera { … }
6261
+ ```
6262
+
6263
+ - **Use when:** create or update a named terrain-editor camera in the shared authoring document
6264
+ - **Constraints:** authoring metadata only; finite noncoincident poses, usable up, valid projection, ordered planes
6265
+ - **Requires:** npm i -D @threenative/terrain
6266
+ - **Overrides:** the caller owns the document revision and the live viewport aspect
6267
+
6268
+ ```ts
6269
+ 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 });
6270
+ ```
6271
+
6272
+ ### `validateCameras`
6273
+
6274
+ `function` — Validate a document's saved camera list, keeping ids unique across it. @summary Validate the saved editor camera list of an authoring document
6275
+
6276
+ ```ts
6277
+ export function validateCameras(input: unknown): ISavedCamera[] { … }
6278
+ ```
6279
+
6280
+ - **Use when:** reject a disk document whose saved cameras are malformed or duplicated
6281
+ - **Constraints:** authoring metadata only; the same validation the camera operations apply
6282
+ - **Requires:** npm i -D @threenative/terrain
6283
+ - **Overrides:** the document owns how many cameras it keeps; the list bound is the editor's own
6284
+
6285
+ ```ts
6286
+ const cameras = validateCameras(JSON.parse(saved).cameras ?? []);
6287
+ ```
6288
+
6289
+ ### `validateEnvironment`
6290
+
6291
+ `function` — Validate a complete overrides object exactly as a document commit stores it. @summary Validate preview environment overrides
6292
+
6293
+ ```ts
6294
+ export function validateEnvironment(input: unknown): IEnvironment { … }
6295
+ ```
6296
+
6297
+ - **Use when:** save sun, sky, haze, exposure or ocean overrides in the shared authoring document
6298
+ - **Constraints:** authoring metadata only; unknown fields and unsupported fog modes are refused by name
6299
+ - **Requires:** npm i -D @threenative/terrain
6300
+ - **Overrides:** the project's render source defines what each value does; absent fields keep its own
6301
+
6302
+ ```ts
6303
+ const environment = validateEnvironment({ sun: { elevation: 25, intensity: 3 } });
6304
+ ```
6305
+
6306
+ ### `validateSpatialReference`
6307
+
6308
+ `function` — Normalise and validate one saved reference, exactly as a document commit would store it.
6309
+
6310
+ ```ts
6311
+ export function validateSpatialReference(input: unknown): ISavedSpatialReference { … }
6312
+ ```
6313
+
6314
+ - **Use when:** accept a bounded local reference image registration into the shared document
6315
+ - **Constraints:** authoring metadata only; rejects unknown fields, malformed points and unknown scale
6316
+ - **Requires:** npm i -D @threenative/terrain
6317
+ - **Overrides:** a project owns the image file; only its hash and provenance travel in the document
6318
+
6319
+ ```ts
6320
+ const reference = validateSpatialReference(JSON.parse(saved));
6321
+ ```
6322
+
6323
+ ### `validateSurfaces`
6324
+
6325
+ `function` — Validate surface mappings against the registered images they name. @summary Validate terrain-editor surface image mappings
6326
+
6327
+ ```ts
6328
+ export function validateSurfaces( input: unknown, assets: readonly IProjectAsset[], ): ISurfaceMappings { … }
6329
+ ```
6330
+
6331
+ - **Use when:** save which imported PBR image replaces which named surface input of the project's render source
6332
+ - **Constraints:** authoring metadata only; each input is <surface>.<channel>; every asset must be a registered image
6333
+ - **Requires:** npm i -D @threenative/terrain
6334
+ - **Overrides:** the project's render source defines which surface inputs exist and what they draw
6335
+
6336
+ ```ts
6337
+ const surfaces = validateSurfaces({ "bark.normal": { asset: "my-normal" } }, document.assets ?? []);
6338
+ ```
6339
+
6340
+ ## `@threenative/terrain/editor/server`
6341
+
6342
+ ### `terrainEditor`
6343
+
6344
+ `function` — Mount the optional terrain document API on an existing loopback Vite server.
6345
+
6346
+ ```ts
6347
+ export function terrainEditor(options: { … }
6348
+ ```
6349
+
6350
+ - **Use when:** share terrain recipe edits between an agent and the live terrain editor
6351
+ - **Constraints:** dev tooling only; serve a project-owned /terrain-editor/index.html; no runtime import
6352
+ - **Requires:** npm i -D @threenative/terrain vite
6353
+ - **Overrides:** documentPath and optional configured viewerUrl belong to the project
6354
+
6355
+ ```ts
6356
+ const editor = terrainEditor({ documentPath: resolve("terrain/world.json") });
6357
+ ```
6358
+
6359
+ ### `TerrainEditorDocument`
6360
+
6361
+ `class` — Project-local terrain document authority; no renderer or game dependency.
6362
+
6363
+ ```ts
6364
+ export class TerrainEditorDocument { … }
6365
+ ```
6366
+
6367
+ - **Use when:** validate atomic revision-based project-local terrain document edits
6368
+ - **Constraints:** Node authoring only; documentPath is a configured absolute regular file; input is bounded to 64 MiB
6369
+ - **Requires:** npm i -D @threenative/terrain
6370
+ - **Overrides:** the project chooses its document path; revisions come from validated content
6371
+
6372
+ ```ts
6373
+ const document = new TerrainEditorDocument("/project/terrain/world.json"); const snapshot = document.snapshot();
6374
+ ```
6375
+
6376
+ ## `@threenative/terrain/export`
6377
+
6378
+ ### `exportWorldGLB`
6379
+
6380
+ `function` — Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.
6381
+
6382
+ ```ts
6383
+ export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }
6384
+ ```
6385
+
6386
+ - **Use when:** export terrain, resolved models and final manual placement transforms as a portable GLB · export the whole terrain world as one glb for another three.js project
6387
+ - **Constraints:** browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless
6388
+ - **Requires:** npm i -D @threenative/terrain
6389
+ - **Overrides:** actual static models, final matrices and baked PBR maps are supplied by the game
6390
+
6391
+ ```ts
6392
+ const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });
6393
+ ```
6394
+
6395
+ ## `@threenative/terrain/three`
6396
+
6397
+ ### `toGeometry`
6398
+
6399
+ `function` — Converts baked arrays to ordinary geometry using the consumer's installed Three.js.
6400
+
6401
+ ```ts
6402
+ export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }
6403
+ ```
6404
+
6405
+ - **Use when:** put an authored terrain mesh in a game-owned Three.js scene
6406
+ - **Constraints:** creates only geometry; the caller owns its material, scene and disposal
6407
+ - **Requires:** npm i @threenative/terrain
6408
+ - **Overrides:** every surface choice remains in game source
6409
+
6410
+ ```ts
6411
+ const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
6412
+ ```
6413
+
6414
+ ## `@threenative/ueformat`
6415
+
6416
+ ### `createThreeGeometry`
6417
+
6418
+ `function` — Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.
6419
+
6420
+ ```ts
6421
+ export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }
6422
+ ```
6423
+
6424
+ - **Use when:** convert one Unreal mesh LOD into a three.js BufferGeometry by hand · build custom scene objects from Unreal mesh data instead of a whole model
6425
+ - **Constraints:** rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed
6426
+ - **Requires:** npm i @threenative/ueformat
6427
+
6428
+ ```ts
6429
+ const geometry = createThreeGeometry(model.lods[0]);
6430
+ ```
6431
+
6432
+ ### `createThreeObject`
6433
+
6434
+ `function` — Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.
6435
+
6436
+ ```ts
6437
+ export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }
6438
+ ```
6439
+
6440
+ - **Use when:** put a mesh exported from an Unreal package on screen · load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry
6441
+ - **Constraints:** every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial · parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job
6442
+ - **Requires:** npm i @threenative/ueformat
6443
+
6444
+ ```ts
6445
+ const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });
6446
+ ```
6447
+
6448
+ ### `parseUEModel`
6449
+
6450
+ `function` — Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.
6451
+
6452
+ ```ts
6453
+ export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }
6454
+ ```
6455
+
6456
+ - **Use when:** parse a mesh exported from an Unreal package without Unreal installed · inspect the LODs, skeleton, sockets, and collision inside a .uemodel file
6457
+ - **Constraints:** only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset · ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation
6458
+ - **Requires:** npm i @threenative/ueformat
6459
+
6460
+ ```ts
6461
+ const model = parseUEModel(await file.arrayBuffer());
6462
+ ```
6463
+
6464
+ ### `summarizeUEModel`
6465
+
6466
+ `function` — Summarizes a parsed `.uemodel` — LOD, material, skeleton, collision, and unknown-attribute counts — without dumping vertex arrays, for logs, validation, and build reports.
6467
+
6468
+ ```ts
6469
+ export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }
6470
+ ```
6471
+
6472
+ - **Use when:** report what a UEFormat model contains without dumping its vertex data · validate a .uemodel file before building geometry from it
6473
+ - **Constraints:** the summary reflects one already-parsed model; it does not read files itself
6474
+ - **Requires:** npm i @threenative/ueformat
6475
+
6476
+ ```ts
6477
+ const summary = summarizeUEModel(parseUEModel(buffer));
6478
+ ```
6479
+
6480
+ ### `UEFormatError`
6481
+
6482
+ `class` — The error thrown for every malformed, truncated, or unsupported `.uemodel` input, carrying a stable `code` and the byte offset where validation stopped.
6483
+
6484
+ ```ts
6485
+ export class UEFormatError extends Error { … }
6486
+ ```
6487
+
6488
+ - **Use when:** tell why a .uemodel file failed to load · report a malformed Unreal export with its byte offset instead of a generic error
6489
+ - **Constraints:** every parse and geometry failure surfaces as this error; nothing malformed is silently skipped
5337
6490
  - **Requires:** npm i @threenative/ueformat
5338
6491
 
5339
6492
  ```ts
@@ -5368,6 +6521,7 @@ export function DebugOverlay() { … }
5368
6521
 
5369
6522
  - **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene · find out which scene object is submitting the frame's triangles · tell a cheap foreground character from an expensive distant prop
5370
6523
  - **Constraints:** the Geometry tab captures only on an explicit press; nothing is collected while idle · per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden
6524
+ - **Requires:** npm i @threenative/ui
5371
6525
 
5372
6526
  ```ts
5373
6527
  <DebugOverlay />
@@ -5383,6 +6537,7 @@ export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( {
5383
6537
 
5384
6538
  - **Use when:** add a game viewport to a React application · connect a game canvas to the web UI shell
5385
6539
  - **Constraints:** keep the portable game entry free of React DOM code
6540
+ - **Requires:** npm i @threenative/ui
5386
6541
 
5387
6542
  ```ts
5388
6543
  <GameCanvas game={game} />
@@ -5398,6 +6553,7 @@ export function UiLayer( { … }
5398
6553
 
5399
6554
  - **Use when:** write one HUD that looks the same on the web build and on a phone · mount a React UI over the game surface on Android or iOS
5400
6555
  - **Constraints:** mark every control the player touches with data-tn-interactive
6556
+ - **Requires:** npm i @threenative/ui
5401
6557
 
5402
6558
  ```ts
5403
6559
  <UiLayer><Hud /></UiLayer>
@@ -5413,6 +6569,7 @@ export function useGameState<TState extends Record<string, unknown>, TPhysics, T
5413
6569
 
5414
6570
  - **Use when:** bind a HUD component to game state · select a slice of state for a React panel
5415
6571
  - **Constraints:** use this hook only from the web UI entry
6572
+ - **Requires:** npm i @threenative/ui
5416
6573
 
5417
6574
  ```ts
5418
6575
  const score = useGameState(game, (state) => state.score);
@@ -5428,6 +6585,7 @@ export function useUiIntent(): (intent: string, payload?: unknown) => void { …
5428
6585
 
5429
6586
  - **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu rendered over its surface
5430
6587
  - **Constraints:** the game decides what each intent name means; it may ignore one
6588
+ - **Requires:** npm i @threenative/ui
5431
6589
 
5432
6590
  ```ts
5433
6591
  const send = useUiIntent(); send("restart");
@@ -5443,11 +6601,29 @@ export function useUiState<TState extends object>(): TState | undefined;
5443
6601
 
5444
6602
  - **Use when:** bind a HUD to game state on web and native alike · show score or health in a UI rendered over the game surface
5445
6603
  - **Constraints:** returns undefined until the game publishes its first state
6604
+ - **Requires:** npm i @threenative/ui
5446
6605
 
5447
6606
  ```ts
5448
6607
  const score = useUiState<GameState, number>((state) => state.score);
5449
6608
  ```
5450
6609
 
6610
+ ## `src/audio/storm.ts`
6611
+
6612
+ ### `createStormAudio`
6613
+
6614
+ `function` — 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.
6615
+
6616
+ ```ts
6617
+ createStormAudio(ctx: ICtx<GameState>): IStormAudio
6618
+ ```
6619
+
6620
+ - **Use when:** rain hiss, wind bed, thunder, a storm you can hear · delay thunder by the distance it was struck · sound that follows pause, mute and tab visibility · audio that queues strikes instead of cutting each other off
6621
+ - **Constraints:** `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. · 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. · `update(state)` is the frame's truth and is called once per frame after the simulation advances; `debug()` is what a playtest reads back. · The caller owns entity registration, updates and disposal; creating the helper does not register it. · Audio begins only after a user gesture — the bus's unlock error is surfaced rather than swallowed. · 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. · 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. · 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. · 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.
6622
+
6623
+ ```ts
6624
+ src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene
6625
+ ```
6626
+
5451
6627
  ## `src/game.ts`
5452
6628
 
5453
6629
  ### `renderer.matrixWorld`
@@ -5498,6 +6674,74 @@ renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }
5498
6674
  renderer: { projection: false } // in threenative.config.ts
5499
6675
  ```
5500
6676
 
6677
+ ## `src/render/lightning.ts`
6678
+
6679
+ ### `createStormLightning`
6680
+
6681
+ `function` — 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.
6682
+
6683
+ ```ts
6684
+ createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning
6685
+ ```
6686
+
6687
+ - **Use when:** generate branching lightning ribbon geometry · a lightning strike that lights the scene and the clouds · a camera-facing ribbon or beam that stays the same pixel width at any distance · a flash envelope that stutters rather than fades once
6688
+ - **Constraints:** Pass the game's seeded random so a strike is reproducible; a non-finite position or random value throws rather than drawing NaN geometry. · 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. · `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. · It depth-tests against the coast's written depth, so a bolt behind the headland is hidden by it. · 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.
6689
+
6690
+ ```ts
6691
+ src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay
6692
+ ```
6693
+
6694
+ ## `src/render/noise-volume.ts`
6695
+
6696
+ ### `createNoiseVolume`
6697
+
6698
+ `function` — 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.
6699
+
6700
+ ```ts
6701
+ createNoiseVolume(): INoiseVolume
6702
+ ```
6703
+
6704
+ - **Use when:** generate a 3D noise volume instead of shipping one as an asset · rebuild the storm's clouds procedurally at startup · tileable 3D noise that does not crease at the edges · four octave scales packed into one texture
6705
+ - **Constraints:** 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. · 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. · 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. · 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. · 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.
6706
+
6707
+ ```ts
6708
+ src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there
6709
+ ```
6710
+
6711
+ ## `src/render/rain.ts`
6712
+
6713
+ ### `createStormRain`
6714
+
6715
+ `function` — 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.
6716
+
6717
+ ```ts
6718
+ createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain
6719
+ ```
6720
+
6721
+ - **Use when:** rain streaks around the camera · thousands of falling drops in one draw · rain that leans with the wind and lights up in a lightning flash
6722
+ - **Constraints:** The drawn count is `round(rainBudget × weather.rain)` for the tier, read back from `geometry.instanceCount` (`instanceCount`), not from the budget. · 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. · Register it with `alwaysRender`: the vertex stage places every drop, so the geometry's own bounds do not. · 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.
6723
+
6724
+ ```ts
6725
+ src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget
6726
+ ```
6727
+
6728
+ ## `src/render/world.ts`
6729
+
6730
+ ### `createWeatherWorld`
6731
+
6732
+ `function` — 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() }`.
6733
+
6734
+ ```ts
6735
+ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
6736
+ ```
6737
+
6738
+ - **Use when:** a procedural storm, sea, coastline or open horizon drawn from maths rather than geometry · rain and wind that change how a scene looks without swapping a mesh · a lightning flash that lights the coast and the sky at once · wet reflections on a ground plane · sky that darkens as cloud cover rises
6739
+ - **Constraints:** `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`. · 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. · 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. · 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. · The quad has `frustumCulled = false`, because its two-metre bounds would otherwise be culled the moment the camera looks along the coast. · 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`. · 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.
6740
+
6741
+ ```ts
6742
+ src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
6743
+ ```
6744
+
5501
6745
  ## `src/render/worldEnvironment.ts`
5502
6746
 
5503
6747
  ### `WorldEnvironment`