create-threenative 0.2.6 → 0.2.8

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 (756) hide show
  1. package/README.md +5 -3
  2. package/agent-docs/references/build-profiles.md +126 -0
  3. package/agent-docs/references/capability-reference.md +607 -26
  4. package/agent-docs/references/performance-basics.md +8 -5
  5. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  6. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  7. package/agent-docs/references/visual-baseline.md +8 -4
  8. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +5 -5
  10. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/threenative-context/SKILL.md +1 -1
  12. package/agent-files/.agents/skills/threenative-performance/SKILL.md +3 -3
  13. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  14. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  15. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  16. package/capabilities.json +801 -24
  17. package/dist/index.d.ts +30 -1
  18. package/dist/index.js +300 -56
  19. package/dist/threenative.js +717 -156
  20. package/package.json +6 -6
  21. package/template-assets/assets/mannequin-combat.glb +0 -0
  22. package/template-assets/assets/mannequin.glb +0 -0
  23. package/template-assets/assets/player-viewmodel.glb +0 -0
  24. package/template-assets/assets/sky.jpg +0 -0
  25. package/template-assets/clearwater/README.md +141 -0
  26. package/template-assets/clearwater/install.mjs +50 -0
  27. package/template-assets/clearwater/src/clearwater.ts +180 -0
  28. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  29. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  30. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  31. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  32. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  33. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  34. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  35. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  36. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  37. package/template-assets/patches/three@0.185.1.patch +2101 -138
  38. package/template-assets/worldEnvironment.ts +52 -1
  39. package/templates/action-rpg/AGENTS.md +42 -42
  40. package/templates/action-rpg/CLAUDE.md +42 -42
  41. package/templates/action-rpg/kit.json +1 -1
  42. package/templates/action-rpg/package.json +13 -7
  43. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  44. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  45. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  46. package/templates/action-rpg/src/conventions.ts +24 -18
  47. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  48. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  49. package/templates/action-rpg/src/entities/Player.ts +102 -32
  50. package/templates/action-rpg/src/game.ts +3 -3
  51. package/templates/action-rpg/src/render/camera.ts +18 -16
  52. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  53. package/templates/action-rpg/src/render/lighting.ts +45 -28
  54. package/templates/action-rpg/src/render/loading.ts +4 -4
  55. package/templates/action-rpg/src/render/materials.ts +191 -47
  56. package/templates/action-rpg/src/render/palette.ts +14 -13
  57. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  58. package/templates/action-rpg/src/render/props.ts +117 -0
  59. package/templates/action-rpg/src/render/quality.ts +40 -82
  60. package/templates/action-rpg/src/render/sky.ts +36 -13
  61. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  62. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  63. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  64. package/templates/action-rpg/src/style.css +9 -7
  65. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  66. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  67. package/templates/action-rpg/threenative.config.ts +14 -1
  68. package/templates/action-rpg/vite.config.ts +4 -1
  69. package/templates/minimal/AGENTS.md +10 -10
  70. package/templates/minimal/CLAUDE.md +10 -10
  71. package/templates/minimal/package.json +12 -6
  72. package/templates/minimal/playtests/play.playtest.json +6 -5
  73. package/templates/minimal/playtests/sky.playtest.json +27 -0
  74. package/templates/minimal/src/conventions.ts +6 -3
  75. package/templates/minimal/src/entities/Player.ts +73 -27
  76. package/templates/minimal/src/main.ts +2 -3
  77. package/templates/minimal/src/render/camera.ts +22 -4
  78. package/templates/minimal/src/render/lighting.ts +24 -48
  79. package/templates/minimal/src/render/materials.ts +158 -13
  80. package/templates/minimal/src/render/palette.ts +10 -7
  81. package/templates/minimal/src/render/postprocessing.ts +12 -25
  82. package/templates/minimal/src/render/quality.ts +35 -69
  83. package/templates/minimal/src/render/sky.ts +35 -54
  84. package/templates/minimal/src/render/touch-controls.ts +1 -1
  85. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  86. package/templates/minimal/src/scenes/Play.ts +121 -111
  87. package/templates/minimal/src/state.ts +0 -4
  88. package/templates/minimal/src/style.css +0 -10
  89. package/templates/minimal/threenative.config.ts +14 -1
  90. package/templates/minimal/vite.config.ts +4 -1
  91. package/templates/platformer/AGENTS.md +18 -56
  92. package/templates/platformer/CLAUDE.md +18 -56
  93. package/templates/platformer/kit.json +2 -2
  94. package/templates/platformer/package.json +13 -9
  95. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  96. package/templates/platformer/playtests/collect.playtest.json +8 -34
  97. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  98. package/templates/platformer/playtests/damage.playtest.json +40 -15
  99. package/templates/platformer/playtests/hud.playtest.json +34 -0
  100. package/templates/platformer/playtests/move.playtest.json +24 -0
  101. package/templates/platformer/playtests/performance.playtest.json +24 -7
  102. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  103. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  104. package/templates/platformer/playtests/survives.playtest.json +3 -19
  105. package/templates/platformer/playtests/world.playtest.json +26 -0
  106. package/templates/platformer/src/entities/Fox.ts +273 -0
  107. package/templates/platformer/src/entities/Pickup.ts +43 -60
  108. package/templates/platformer/src/entities/Walker.ts +88 -0
  109. package/templates/platformer/src/game.ts +11 -8
  110. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  111. package/templates/platformer/src/level/Stage.ts +469 -0
  112. package/templates/platformer/src/render/blocks.ts +94 -0
  113. package/templates/platformer/src/render/camera.ts +28 -3
  114. package/templates/platformer/src/render/fox.ts +196 -0
  115. package/templates/platformer/src/render/lighting.ts +42 -33
  116. package/templates/platformer/src/render/materials.ts +115 -5
  117. package/templates/platformer/src/render/palette.ts +68 -53
  118. package/templates/platformer/src/render/pickups.ts +142 -0
  119. package/templates/platformer/src/render/postprocessing.ts +12 -2
  120. package/templates/platformer/src/render/props.ts +147 -0
  121. package/templates/platformer/src/render/quality.ts +47 -99
  122. package/templates/platformer/src/render/scenery.ts +172 -0
  123. package/templates/platformer/src/render/sky.ts +120 -31
  124. package/templates/platformer/src/render/touch-controls.ts +5 -2
  125. package/templates/platformer/src/render/walkers.ts +96 -0
  126. package/templates/platformer/src/render/waterfall.ts +85 -0
  127. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  128. package/templates/platformer/src/scenes/Boot.ts +3 -4
  129. package/templates/platformer/src/scenes/Play.ts +362 -0
  130. package/templates/platformer/src/state.ts +16 -14
  131. package/templates/platformer/src/style.css +9 -8
  132. package/templates/platformer/src/ui/Hud.tsx +62 -29
  133. package/templates/platformer/src/ui/Menu.tsx +2 -2
  134. package/templates/platformer/threenative.config.ts +14 -1
  135. package/templates/platformer/vite.config.ts +4 -1
  136. package/templates/puzzle/AGENTS.md +19 -20
  137. package/templates/puzzle/CLAUDE.md +19 -20
  138. package/templates/puzzle/assets/native-proof.glb +0 -0
  139. package/templates/puzzle/assets/native-proof.png +0 -0
  140. package/templates/puzzle/kit.json +1 -1
  141. package/templates/puzzle/package.json +13 -7
  142. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  143. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  144. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  145. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  146. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  147. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  148. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  149. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  150. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  151. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  152. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  153. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  154. package/templates/puzzle/src/entities/Crate.ts +99 -42
  155. package/templates/puzzle/src/entities/Seal.ts +69 -0
  156. package/templates/puzzle/src/entities/Warden.ts +135 -0
  157. package/templates/puzzle/src/game.ts +15 -11
  158. package/templates/puzzle/src/render/camera.ts +66 -31
  159. package/templates/puzzle/src/render/crateShape.ts +70 -0
  160. package/templates/puzzle/src/render/lighting.ts +41 -41
  161. package/templates/puzzle/src/render/loading.ts +4 -4
  162. package/templates/puzzle/src/render/materials.ts +131 -27
  163. package/templates/puzzle/src/render/palette.ts +19 -29
  164. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  165. package/templates/puzzle/src/render/quality.ts +71 -80
  166. package/templates/puzzle/src/render/shapes.ts +109 -108
  167. package/templates/puzzle/src/render/sky.ts +18 -10
  168. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  169. package/templates/puzzle/src/render/vault.ts +315 -0
  170. package/templates/puzzle/src/render/warden.ts +46 -0
  171. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  172. package/templates/puzzle/src/scenes/Play.ts +793 -0
  173. package/templates/puzzle/src/state.ts +55 -24
  174. package/templates/puzzle/src/style.css +7 -8
  175. package/templates/puzzle/src/ui/App.tsx +2 -2
  176. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  177. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  178. package/templates/puzzle/threenative.config.ts +14 -1
  179. package/templates/puzzle/vite.config.ts +4 -1
  180. package/templates/racing/AGENTS.md +19 -20
  181. package/templates/racing/CLAUDE.md +19 -20
  182. package/templates/racing/package.json +13 -7
  183. package/templates/racing/playtests/boost.playtest.json +33 -12
  184. package/templates/racing/playtests/outcome.playtest.json +32 -50
  185. package/templates/racing/playtests/performance.playtest.json +2 -1
  186. package/templates/racing/playtests/ranking.playtest.json +5 -14
  187. package/templates/racing/playtests/rescue.playtest.json +2 -2
  188. package/templates/racing/playtests/reverse.playtest.json +30 -8
  189. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  190. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  191. package/templates/racing/src/entities/CarBody.ts +327 -0
  192. package/templates/racing/src/entities/LineDriver.ts +220 -0
  193. package/templates/racing/src/entities/RacingCar.ts +150 -89
  194. package/templates/racing/src/entities/Rival.ts +61 -24
  195. package/templates/racing/src/game.ts +5 -0
  196. package/templates/racing/src/render/camera.ts +49 -7
  197. package/templates/racing/src/render/lighting.ts +36 -37
  198. package/templates/racing/src/render/materials.ts +239 -19
  199. package/templates/racing/src/render/palette.ts +19 -21
  200. package/templates/racing/src/render/postprocessing.ts +12 -2
  201. package/templates/racing/src/render/quality.ts +43 -82
  202. package/templates/racing/src/render/shapes.ts +20 -6
  203. package/templates/racing/src/render/sky.ts +47 -39
  204. package/templates/racing/src/render/touch-controls.ts +1 -1
  205. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  206. package/templates/racing/src/scenes/Race.ts +107 -54
  207. package/templates/racing/src/state.ts +2 -0
  208. package/templates/racing/src/track/Checkline.ts +22 -7
  209. package/templates/racing/src/track/Lap.ts +64 -36
  210. package/templates/racing/src/track/Ranking.ts +20 -11
  211. package/templates/racing/src/track/Track.ts +809 -361
  212. package/templates/racing/src/track/TrackSector.ts +40 -11
  213. package/templates/racing/src/track/circuit.ts +477 -0
  214. package/templates/racing/src/track/rescue.ts +16 -4
  215. package/templates/racing/threenative.config.ts +14 -1
  216. package/templates/racing/vite.config.ts +4 -1
  217. package/templates/rain/AGENTS.md +96 -0
  218. package/templates/rain/CLAUDE.md +98 -0
  219. package/templates/rain/assets/rain-loop.wav +0 -0
  220. package/templates/rain/assets/thunder.wav +0 -0
  221. package/templates/rain/assets/wind-loop.wav +0 -0
  222. package/templates/rain/index.html +18 -0
  223. package/templates/rain/kit.json +7 -0
  224. package/templates/rain/native-playtests/boot.playtest.json +13 -0
  225. package/templates/rain/native-playtests/lightning.playtest.json +173 -0
  226. package/templates/rain/package.json +56 -0
  227. package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
  228. package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
  229. package/templates/rain/playtests/automation.playtest.json +133 -0
  230. package/templates/rain/playtests/cinematic.playtest.json +59 -0
  231. package/templates/rain/playtests/flash.playtest.json +27 -0
  232. package/templates/rain/playtests/fly.playtest.json +54 -0
  233. package/templates/rain/playtests/lightning.playtest.json +220 -0
  234. package/templates/rain/playtests/loading.playtest.json +57 -0
  235. package/templates/rain/playtests/paused.playtest.json +59 -0
  236. package/templates/rain/playtests/performance.playtest.json +22 -0
  237. package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
  238. package/templates/rain/playtests/simulation.playtest.json +20 -0
  239. package/templates/rain/playtests/storm.playtest.json +150 -0
  240. package/templates/rain/playtests/survives.playtest.json +58 -0
  241. package/templates/rain/playtests/tiers.playtest.json +179 -0
  242. package/templates/rain/playtests/weather.playtest.json +77 -0
  243. package/templates/rain/public/favicon.svg +5 -0
  244. package/templates/rain/src/audio/storm.ts +314 -0
  245. package/templates/rain/src/game.ts +114 -0
  246. package/templates/rain/src/render/bloom-shader.ts +65 -0
  247. package/templates/rain/src/render/camera.ts +160 -0
  248. package/templates/rain/src/render/clouds-shader.ts +242 -0
  249. package/templates/rain/src/render/clouds.ts +142 -0
  250. package/templates/rain/src/render/lighting.ts +39 -0
  251. package/templates/rain/src/render/lightning.ts +360 -0
  252. package/templates/rain/src/render/loading.ts +327 -0
  253. package/templates/rain/src/render/materials.ts +19 -0
  254. package/templates/rain/src/render/noise-volume.ts +159 -0
  255. package/templates/rain/src/render/palette.ts +18 -0
  256. package/templates/rain/src/render/post-shader.ts +178 -0
  257. package/templates/rain/src/render/postprocessing.ts +226 -0
  258. package/templates/rain/src/render/quality.ts +135 -0
  259. package/templates/rain/src/render/rain.ts +299 -0
  260. package/templates/rain/src/render/sky.ts +28 -0
  261. package/templates/rain/src/render/world-shader.ts +680 -0
  262. package/templates/rain/src/render/world.ts +146 -0
  263. package/templates/{defense → rain}/src/render/worldEnvironment.ts +52 -1
  264. package/templates/rain/src/scenes/Boot.ts +334 -0
  265. package/templates/rain/src/state.ts +257 -0
  266. package/templates/rain/src/style.css +1160 -0
  267. package/templates/rain/src/ui/App.tsx +29 -0
  268. package/templates/rain/src/ui/GameUi.tsx +187 -0
  269. package/templates/rain/src/ui/Hud.tsx +327 -0
  270. package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
  271. package/templates/rain/src/ui/Menu.tsx +370 -0
  272. package/templates/rain/src/ui/automation.ts +60 -0
  273. package/templates/rain/src/ui/main.tsx +7 -0
  274. package/templates/rain/src/ui/tempest.ts +149 -0
  275. package/templates/rain/tailwind.config.ts +2 -0
  276. package/templates/rain/threenative.config.ts +66 -0
  277. package/templates/rain/tools/generate-shaders.mjs +656 -0
  278. package/templates/rain/tools/make-storm-audio.mjs +387 -0
  279. package/templates/rain/tools/storm-dsp.mjs +177 -0
  280. package/templates/rain/tools/tempest-bloom.frag +10 -0
  281. package/templates/rain/tools/tempest-clouds.frag +86 -0
  282. package/templates/rain/tools/tempest-post.frag +47 -0
  283. package/templates/rain/tools/tempest-world.frag +210 -0
  284. package/templates/rain/tools/verify-noise-volume.mjs +61 -0
  285. package/templates/rain/tsconfig.json +17 -0
  286. package/templates/rain/vite.config.ts +37 -0
  287. package/templates/rts/.codex/config.toml +19 -0
  288. package/templates/rts/.cursor/mcp.json +32 -0
  289. package/templates/rts/.gemini/settings.json +32 -0
  290. package/templates/rts/.mcp.json +32 -0
  291. package/templates/rts/.vscode/mcp.json +36 -0
  292. package/templates/rts/.zed/settings.json +36 -0
  293. package/templates/rts/AGENTS.md +96 -0
  294. package/templates/rts/CLAUDE.md +98 -0
  295. package/templates/rts/kit.json +7 -0
  296. package/templates/rts/opencode.json +41 -0
  297. package/templates/{defense → rts}/package.json +13 -7
  298. package/templates/rts/playtests/performance.playtest.json +41 -0
  299. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  300. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  301. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  302. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  303. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  304. package/templates/rts/playtests/survives.playtest.json +58 -0
  305. package/templates/rts/public/favicon.svg +4 -0
  306. package/templates/rts/src/game.ts +64 -0
  307. package/templates/rts/src/main.ts +15 -0
  308. package/templates/rts/src/orders.ts +22 -0
  309. package/templates/rts/src/render/army.ts +346 -0
  310. package/templates/rts/src/render/camera.ts +123 -0
  311. package/templates/rts/src/render/lighting.ts +61 -0
  312. package/templates/rts/src/render/loading.ts +33 -0
  313. package/templates/rts/src/render/materials.ts +152 -0
  314. package/templates/rts/src/render/models.ts +705 -0
  315. package/templates/rts/src/render/palette.ts +17 -0
  316. package/templates/rts/src/render/picking.ts +93 -0
  317. package/templates/rts/src/render/postprocessing.ts +46 -0
  318. package/templates/rts/src/render/quality.ts +128 -0
  319. package/templates/rts/src/render/resources.ts +141 -0
  320. package/templates/rts/src/render/sky.ts +44 -0
  321. package/templates/rts/src/render/terrain.ts +116 -0
  322. package/templates/rts/src/render/worldEnvironment.ts +809 -0
  323. package/templates/rts/src/scenes/Play.ts +650 -0
  324. package/templates/rts/src/sim/ai.ts +1140 -0
  325. package/templates/rts/src/sim/combat.ts +416 -0
  326. package/templates/rts/src/sim/construction.ts +374 -0
  327. package/templates/rts/src/sim/economy.ts +167 -0
  328. package/templates/rts/src/sim/game.ts +1082 -0
  329. package/templates/rts/src/sim/movement.ts +371 -0
  330. package/templates/rts/src/sim/nav.ts +276 -0
  331. package/templates/rts/src/sim/production.ts +180 -0
  332. package/templates/rts/src/sim/terrain.ts +170 -0
  333. package/templates/rts/src/sim/types.ts +647 -0
  334. package/templates/rts/src/sim/vision.ts +46 -0
  335. package/templates/rts/src/state.ts +100 -0
  336. package/templates/{defense → rts}/src/style.css +21 -8
  337. package/templates/rts/src/ui/App.tsx +21 -0
  338. package/templates/rts/src/ui/Commands.tsx +129 -0
  339. package/templates/rts/src/ui/GameUi.tsx +22 -0
  340. package/templates/rts/src/ui/Hud.tsx +165 -0
  341. package/templates/rts/src/ui/Minimap.tsx +84 -0
  342. package/templates/rts/tailwind.config.ts +2 -0
  343. package/templates/rts/threenative.config.ts +56 -0
  344. package/templates/rts/tsconfig.json +17 -0
  345. package/templates/{defense → rts}/vite.config.ts +4 -1
  346. package/templates/runner/AGENTS.md +6 -10
  347. package/templates/runner/CLAUDE.md +6 -10
  348. package/templates/runner/README.md +3 -3
  349. package/templates/runner/package.json +13 -7
  350. package/templates/runner/playtests/performance.playtest.json +2 -2
  351. package/templates/runner/src/conventions.ts +4 -3
  352. package/templates/runner/src/entities/Runner.ts +54 -7
  353. package/templates/runner/src/game.ts +2 -0
  354. package/templates/runner/src/render/camera.ts +4 -2
  355. package/templates/runner/src/render/dust.ts +5 -2
  356. package/templates/runner/src/render/lighting.ts +41 -45
  357. package/templates/runner/src/render/loading.ts +2 -2
  358. package/templates/runner/src/render/materials.ts +165 -25
  359. package/templates/runner/src/render/palette.ts +17 -28
  360. package/templates/runner/src/render/postprocessing.ts +12 -2
  361. package/templates/runner/src/render/quality.ts +42 -96
  362. package/templates/runner/src/render/shapes.ts +59 -37
  363. package/templates/runner/src/render/sky.ts +32 -41
  364. package/templates/runner/src/render/touch-controls.ts +1 -1
  365. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  366. package/templates/runner/src/scenes/Run.ts +26 -6
  367. package/templates/runner/src/track.ts +6 -1
  368. package/templates/runner/threenative.config.ts +14 -1
  369. package/templates/runner/vite.config.ts +4 -1
  370. package/templates/sailing/AGENTS.md +12 -12
  371. package/templates/sailing/CLAUDE.md +12 -12
  372. package/templates/sailing/assets/ship.glb +0 -0
  373. package/templates/sailing/package.json +13 -7
  374. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  375. package/templates/sailing/playtests/sails.playtest.json +33 -0
  376. package/templates/sailing/playtests/win.playtest.json +156 -8
  377. package/templates/sailing/src/conventions.ts +29 -2
  378. package/templates/sailing/src/entities/Ship.ts +381 -57
  379. package/templates/sailing/src/game.ts +14 -0
  380. package/templates/sailing/src/render/camera.ts +63 -9
  381. package/templates/sailing/src/render/lighting.ts +49 -27
  382. package/templates/sailing/src/render/materials.ts +50 -15
  383. package/templates/sailing/src/render/ocean.ts +647 -60
  384. package/templates/sailing/src/render/palette.ts +16 -12
  385. package/templates/sailing/src/render/postprocessing.ts +12 -2
  386. package/templates/sailing/src/render/props.ts +316 -442
  387. package/templates/sailing/src/render/quality.ts +14 -4
  388. package/templates/sailing/src/render/sky.ts +116 -23
  389. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  390. package/templates/sailing/src/scenes/Boot.ts +21 -0
  391. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  392. package/templates/sailing/src/state.ts +6 -0
  393. package/templates/sailing/src/ui/Hud.tsx +41 -9
  394. package/templates/sailing/threenative.config.ts +14 -1
  395. package/templates/sailing/vite.config.ts +4 -1
  396. package/templates/shooter/AGENTS.md +27 -42
  397. package/templates/shooter/CLAUDE.md +27 -42
  398. package/templates/shooter/index.html +1 -0
  399. package/templates/shooter/package.json +13 -7
  400. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  401. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  402. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  403. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  404. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  405. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  406. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  407. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  408. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  409. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  410. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  411. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  412. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  413. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  414. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  415. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  416. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  417. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  418. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  419. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  420. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  421. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  422. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  423. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  424. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  425. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  426. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  427. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  428. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  429. package/templates/shooter/playtests/performance.playtest.json +62 -26
  430. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  431. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  432. package/templates/shooter/playtests/survives.playtest.json +36 -30
  433. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  434. package/templates/shooter/src/entities/Breakables.ts +412 -0
  435. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  436. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  437. package/templates/shooter/src/entities/Rifle.ts +442 -0
  438. package/templates/shooter/src/entities/Target.ts +199 -83
  439. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  440. package/templates/shooter/src/game.ts +75 -41
  441. package/templates/shooter/src/main.ts +0 -1
  442. package/templates/shooter/src/postPhysics.ts +36 -0
  443. package/templates/shooter/src/render/camera.ts +78 -74
  444. package/templates/shooter/src/render/decals.ts +142 -82
  445. package/templates/shooter/src/render/facade.ts +1373 -0
  446. package/templates/shooter/src/render/gunfx.ts +704 -0
  447. package/templates/shooter/src/render/lighting.ts +52 -38
  448. package/templates/shooter/src/render/loading.ts +2 -2
  449. package/templates/shooter/src/render/materials.ts +100 -88
  450. package/templates/shooter/src/render/occlusion.ts +108 -0
  451. package/templates/shooter/src/render/palette.ts +10 -10
  452. package/templates/shooter/src/render/palm.ts +455 -0
  453. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  454. package/templates/shooter/src/render/postprocessing.ts +15 -3
  455. package/templates/shooter/src/render/quality.ts +40 -82
  456. package/templates/shooter/src/render/scale.ts +148 -15
  457. package/templates/shooter/src/render/shapes.ts +138 -613
  458. package/templates/shooter/src/render/sky.ts +35 -35
  459. package/templates/shooter/src/render/town-schematic.ts +120 -0
  460. package/templates/shooter/src/render/town.ts +986 -0
  461. package/templates/shooter/src/render/townMaterials.ts +160 -0
  462. package/templates/shooter/src/render/vehicles.ts +741 -0
  463. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  464. package/templates/shooter/src/scenes/Play.ts +727 -650
  465. package/templates/shooter/src/state.ts +26 -41
  466. package/templates/shooter/src/style.css +207 -11
  467. package/templates/shooter/src/surfaces.ts +131 -0
  468. package/templates/shooter/src/ui/App.tsx +9 -10
  469. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  470. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  471. package/templates/shooter/src/ui/Hud.tsx +428 -39
  472. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  473. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  474. package/templates/shooter/src/ui/main.tsx +2 -3
  475. package/templates/shooter/threenative.config.ts +14 -1
  476. package/templates/shooter/vite.config.ts +4 -1
  477. package/templates/snow/.codex/config.toml +19 -0
  478. package/templates/snow/.cursor/mcp.json +32 -0
  479. package/templates/snow/.gemini/settings.json +32 -0
  480. package/templates/snow/.mcp.json +32 -0
  481. package/templates/snow/.vscode/mcp.json +36 -0
  482. package/templates/snow/.zed/settings.json +36 -0
  483. package/templates/snow/AGENTS.md +88 -0
  484. package/templates/snow/CLAUDE.md +90 -0
  485. package/templates/snow/README.md +26 -0
  486. package/templates/snow/assets/crunch.wav +0 -0
  487. package/templates/snow/assets/wind.wav +0 -0
  488. package/templates/snow/index.html +12 -0
  489. package/templates/snow/kit.json +7 -0
  490. package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
  491. package/templates/snow/native-playtests/survives.playtest.json +47 -0
  492. package/templates/snow/opencode.json +41 -0
  493. package/templates/snow/package.json +58 -0
  494. package/templates/snow/playtests/footsteps.playtest.json +95 -0
  495. package/templates/{defense → snow}/playtests/performance.playtest.json +4 -7
  496. package/templates/snow/playtests/snow-physics.playtest.json +154 -0
  497. package/templates/{defense → snow}/playtests/survives.playtest.json +26 -6
  498. package/templates/snow/playtests/touch-controls.playtest.json +71 -0
  499. package/templates/snow/playtests/weather.playtest.json +119 -0
  500. package/templates/snow/public/favicon.svg +5 -0
  501. package/templates/snow/src/audio.ts +58 -0
  502. package/templates/snow/src/commands.ts +8 -0
  503. package/templates/snow/src/entities/Explorer.ts +279 -0
  504. package/templates/snow/src/game.ts +69 -0
  505. package/templates/snow/src/main.ts +15 -0
  506. package/templates/snow/src/render/bootPrint.ts +50 -0
  507. package/templates/snow/src/render/camera.ts +84 -0
  508. package/templates/snow/src/render/explorer.ts +321 -0
  509. package/templates/snow/src/render/lighting.ts +50 -0
  510. package/templates/snow/src/render/loading.ts +325 -0
  511. package/templates/snow/src/render/materials.ts +36 -0
  512. package/templates/snow/src/render/palette.ts +17 -0
  513. package/templates/{defense → snow}/src/render/postprocessing.ts +12 -2
  514. package/templates/snow/src/render/props.ts +42 -0
  515. package/templates/{defense → snow}/src/render/quality.ts +37 -72
  516. package/templates/snow/src/render/scenery.ts +244 -0
  517. package/templates/snow/src/render/sky.ts +57 -0
  518. package/templates/snow/src/render/snowSurface.ts +259 -0
  519. package/templates/snow/src/render/touch-controls.ts +143 -0
  520. package/templates/snow/src/render/weather.ts +279 -0
  521. package/templates/snow/src/render/worldEnvironment.ts +809 -0
  522. package/templates/{defense → snow}/src/scenes/Boot.ts +4 -4
  523. package/templates/snow/src/scenes/Snow.ts +635 -0
  524. package/templates/snow/src/state.ts +46 -0
  525. package/templates/snow/src/style.css +143 -0
  526. package/templates/snow/src/terrain.ts +64 -0
  527. package/templates/snow/src/ui/App.tsx +15 -0
  528. package/templates/snow/src/ui/Controls.tsx +322 -0
  529. package/templates/snow/src/ui/GameUi.tsx +354 -0
  530. package/templates/snow/src/ui/icons.tsx +54 -0
  531. package/templates/snow/src/ui/main.tsx +7 -0
  532. package/templates/snow/tailwind.config.ts +2 -0
  533. package/templates/snow/threenative.config.ts +51 -0
  534. package/templates/snow/tsconfig.json +17 -0
  535. package/templates/snow/vite.config.ts +37 -0
  536. package/templates/starter/AGENTS.md +17 -17
  537. package/templates/starter/CLAUDE.md +17 -17
  538. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  539. package/templates/starter/package.json +13 -7
  540. package/templates/starter/playtests/play.playtest.json +2 -1
  541. package/templates/starter/playtests/survives.playtest.json +1 -1
  542. package/templates/starter/src/conventions.ts +6 -3
  543. package/templates/starter/src/entities/Goal.ts +35 -42
  544. package/templates/starter/src/entities/Player.ts +99 -16
  545. package/templates/starter/src/render/arena.ts +131 -0
  546. package/templates/starter/src/render/lighting.ts +27 -44
  547. package/templates/starter/src/render/materials.ts +164 -35
  548. package/templates/starter/src/render/palette.ts +16 -16
  549. package/templates/starter/src/render/postprocessing.ts +6 -7
  550. package/templates/starter/src/render/quality.ts +43 -101
  551. package/templates/starter/src/render/shapes.ts +1 -1
  552. package/templates/starter/src/render/sky.ts +39 -45
  553. package/templates/starter/src/render/touch-controls.ts +3 -1
  554. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  555. package/templates/starter/src/scenes/Play.ts +82 -81
  556. package/templates/starter/threenative.config.ts +14 -1
  557. package/templates/starter/vite.config.ts +4 -1
  558. package/templates/tower-defense/.codex/config.toml +19 -0
  559. package/templates/tower-defense/.cursor/mcp.json +32 -0
  560. package/templates/tower-defense/.gemini/settings.json +32 -0
  561. package/templates/tower-defense/.mcp.json +32 -0
  562. package/templates/tower-defense/.vscode/mcp.json +36 -0
  563. package/templates/tower-defense/.zed/settings.json +36 -0
  564. package/templates/{defense → tower-defense}/AGENTS.md +14 -12
  565. package/templates/{defense → tower-defense}/CLAUDE.md +14 -12
  566. package/templates/tower-defense/README.md +16 -0
  567. package/templates/tower-defense/index.html +12 -0
  568. package/templates/tower-defense/kit.json +7 -0
  569. package/templates/tower-defense/opencode.json +41 -0
  570. package/templates/tower-defense/package.json +56 -0
  571. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  572. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  573. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  574. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  575. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  576. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  577. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  578. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  579. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  580. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  581. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  582. package/templates/tower-defense/src/balance.ts +187 -0
  583. package/templates/tower-defense/src/board/Board.ts +100 -0
  584. package/templates/tower-defense/src/board/Route.ts +84 -0
  585. package/templates/tower-defense/src/camera-rig.ts +62 -0
  586. package/templates/tower-defense/src/economy.ts +64 -0
  587. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  588. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  589. package/templates/tower-defense/src/game.ts +72 -0
  590. package/templates/tower-defense/src/intents.ts +21 -0
  591. package/templates/tower-defense/src/main.ts +15 -0
  592. package/templates/tower-defense/src/physics.ts +6 -0
  593. package/templates/tower-defense/src/render/camera.ts +38 -0
  594. package/templates/tower-defense/src/render/lighting.ts +42 -0
  595. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  596. package/templates/tower-defense/src/render/materials.ts +103 -0
  597. package/templates/tower-defense/src/render/palette.ts +58 -0
  598. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  599. package/templates/tower-defense/src/render/quality.ts +128 -0
  600. package/templates/tower-defense/src/render/shapes.ts +550 -0
  601. package/templates/tower-defense/src/render/sky.ts +27 -0
  602. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  603. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  604. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  605. package/templates/tower-defense/src/state.ts +88 -0
  606. package/templates/tower-defense/src/style.css +137 -0
  607. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  608. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  609. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  610. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  611. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  612. package/templates/tower-defense/src/ui/main.tsx +14 -0
  613. package/templates/tower-defense/src/waves.ts +90 -0
  614. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  615. package/templates/tower-defense/vite.config.ts +41 -0
  616. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  617. package/agent-files/.claude/skills/ponytail/SKILL.md +0 -68
  618. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  619. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -53
  620. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  621. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -65
  622. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -58
  623. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  624. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  625. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  626. package/agent-files/AGENT-ROLES.md +0 -26
  627. package/templates/action-rpg/src/render/shapes.ts +0 -269
  628. package/templates/action-rpg/src/render/types.ts +0 -3
  629. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  630. package/templates/defense/README.md +0 -10
  631. package/templates/defense/kit.json +0 -7
  632. package/templates/defense/playtests/leak.playtest.json +0 -23
  633. package/templates/defense/playtests/placement.playtest.json +0 -40
  634. package/templates/defense/playtests/scan.playtest.json +0 -20
  635. package/templates/defense/playtests/survive.playtest.json +0 -45
  636. package/templates/defense/src/attackers/Attacker.ts +0 -120
  637. package/templates/defense/src/board/Route.ts +0 -94
  638. package/templates/defense/src/conventions.ts +0 -18
  639. package/templates/defense/src/economy.ts +0 -36
  640. package/templates/defense/src/entities/Player.ts +0 -52
  641. package/templates/defense/src/game.ts +0 -51
  642. package/templates/defense/src/physics.ts +0 -13
  643. package/templates/defense/src/placement/Buildable.ts +0 -49
  644. package/templates/defense/src/render/camera.ts +0 -16
  645. package/templates/defense/src/render/lighting.ts +0 -37
  646. package/templates/defense/src/render/materials.ts +0 -22
  647. package/templates/defense/src/render/palette.ts +0 -28
  648. package/templates/defense/src/render/shapes.ts +0 -246
  649. package/templates/defense/src/render/sky.ts +0 -45
  650. package/templates/defense/src/scenes/Defense.ts +0 -231
  651. package/templates/defense/src/state.ts +0 -56
  652. package/templates/defense/src/towers/Tower.ts +0 -95
  653. package/templates/defense/src/towers/targeting.ts +0 -53
  654. package/templates/defense/src/ui/Hud.tsx +0 -62
  655. package/templates/defense/src/ui/Menu.tsx +0 -7
  656. package/templates/defense/src/waves.ts +0 -40
  657. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  658. package/templates/minimal/src/render/hud.ts +0 -69
  659. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  660. package/templates/platformer/playtests/chase.playtest.json +0 -21
  661. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  662. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  663. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  664. package/templates/platformer/playtests/physics.playtest.json +0 -14
  665. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  666. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  667. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  668. package/templates/platformer/src/conventions.ts +0 -18
  669. package/templates/platformer/src/entities/Character.ts +0 -286
  670. package/templates/platformer/src/entities/Chaser.ts +0 -118
  671. package/templates/platformer/src/entities/Patrol.ts +0 -93
  672. package/templates/platformer/src/level/Platform.ts +0 -46
  673. package/templates/platformer/src/render/rig.ts +0 -60
  674. package/templates/platformer/src/render/terrain.ts +0 -31
  675. package/templates/platformer/src/scenes/Level.ts +0 -241
  676. package/templates/puzzle/README.md +0 -43
  677. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  678. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  679. package/templates/puzzle/src/conventions.ts +0 -25
  680. package/templates/puzzle/src/entities/Ball.ts +0 -70
  681. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  682. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  683. package/templates/puzzle/src/physics.ts +0 -19
  684. package/templates/puzzle/src/room.ts +0 -83
  685. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  686. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  687. package/templates/shooter/playtests/combat.playtest.json +0 -48
  688. package/templates/shooter/playtests/fail.playtest.json +0 -31
  689. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  690. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  691. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  692. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  693. package/templates/shooter/src/combat/damage.ts +0 -40
  694. package/templates/shooter/src/conventions.ts +0 -51
  695. package/templates/shooter/src/entities/Pickup.ts +0 -70
  696. package/templates/shooter/src/entities/Player.ts +0 -310
  697. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  698. package/templates/shooter/src/playtest-events.ts +0 -15
  699. package/templates/shooter/src/render/touch-controls.ts +0 -305
  700. package/templates/shooter/src/render/types.ts +0 -3
  701. package/templates/shooter/src/render/ui.css +0 -330
  702. package/templates/shooter/src/render/ui.ts +0 -75
  703. package/templates/shooter/src/render/vfx.ts +0 -215
  704. package/templates/shooter/src/ui/Menu.tsx +0 -41
  705. package/templates/shooter/src/waves.ts +0 -50
  706. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  707. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  708. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  709. package/templates/starter/playtests/assets.playtest.json +0 -65
  710. package/templates/starter/playtests/buffer.playtest.json +0 -79
  711. package/templates/starter/playtests/cloth.playtest.json +0 -113
  712. package/templates/starter/playtests/coyote.playtest.json +0 -87
  713. package/templates/starter/playtests/gameover.playtest.json +0 -66
  714. package/templates/starter/playtests/goal.playtest.json +0 -67
  715. package/templates/starter/playtests/look.playtest.json +0 -175
  716. package/templates/starter/playtests/models-baseline.png +0 -0
  717. package/templates/starter/playtests/models.playtest.json +0 -74
  718. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  719. package/templates/starter/playtests/odometer.playtest.json +0 -54
  720. package/templates/starter/playtests/restart.playtest.json +0 -91
  721. package/templates/starter/playtests/seed.playtest.json +0 -54
  722. package/templates/starter/playtests/textures-baseline.png +0 -0
  723. package/templates/starter/playtests/textures.playtest.json +0 -74
  724. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  725. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  726. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  727. package/templates/starter/src/render/coast.ts +0 -199
  728. package/templates/starter/src/render/hero.ts +0 -88
  729. package/templates/starter/src/render/implicitSurface.ts +0 -199
  730. package/templates/starter/src/render/kuwahara.ts +0 -174
  731. package/templates/starter/src/render/outline.ts +0 -141
  732. package/templates/starter/src/render/painterly.ts +0 -86
  733. package/templates/starter/src/render/rockRidge.ts +0 -198
  734. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  735. package/templates/starter/src/render/scenery.ts +0 -40
  736. package/templates/starter/src/render/textureLifetime.ts +0 -53
  737. package/templates/starter/src/render/water.ts +0 -38
  738. package/templates/starter/src/render/watercolor.ts +0 -85
  739. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  740. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  741. /package/templates/{defense → rain}/.codex/config.toml +0 -0
  742. /package/templates/{defense → rain}/.cursor/mcp.json +0 -0
  743. /package/templates/{defense → rain}/.gemini/settings.json +0 -0
  744. /package/templates/{defense → rain}/.mcp.json +0 -0
  745. /package/templates/{defense → rain}/.vscode/mcp.json +0 -0
  746. /package/templates/{defense → rain}/.zed/settings.json +0 -0
  747. /package/templates/{defense → rain}/opencode.json +0 -0
  748. /package/templates/{defense → rain}/src/main.ts +0 -0
  749. /package/templates/{defense → rts}/index.html +0 -0
  750. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  751. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  752. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  753. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  754. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  755. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  756. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
@@ -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/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/raw-unreal`, `@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.
@@ -618,8 +618,8 @@ model.step(1 / 60, { turn: -1, pitch: 0.4 });
618
618
  export class AudioBus { … }
619
619
  ```
620
620
 
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
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 · hold a loud mix below clipping with a compressor on the bus · 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 · compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum
623
623
  - **Supersedes (writing this fails `pnpm budgets`):** new Audio(
624
624
 
625
625
  ```ts
@@ -720,6 +720,21 @@ import { boneLengths } from "@threenative/core";
720
720
  const baseline = boneLengths(character);
721
721
  ```
722
722
 
723
+ ### `bvhIntersectFirstHit`
724
+
725
+ `function` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
726
+
727
+ ```ts
728
+ bvhIntersectFirstHit = upstream.bvhIntersectFirstHit
729
+ ```
730
+
731
+ - **Use when:** trace thousands of scene rays inside a TSL kernel · build a contact-occlusion or visibility query over loaded meshes
732
+ - **Constraints:** call rebuild() after a scene transform or geometry change; the snapshot is static by default · rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray
733
+
734
+ ```ts
735
+ const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
736
+ ```
737
+
723
738
  ### `CameraShake`
724
739
 
725
740
  `class` — Produce a game-authored camera shake offset for a template-owned camera rig.
@@ -749,6 +764,21 @@ export class CanvasLayer { … }
749
764
  const hud = new CanvasLayer(ctx.viewport);
750
765
  ```
751
766
 
767
+ ### `captureMouse`
768
+
769
+ `function` — Lock the pointer to the game's surface: the capture every first-person mouse look needs. A browser grants capture only from a user gesture, so call it from a click or a pointerdown handler. A relative binding such as `look: { pointerRelative: true }` already requests capture on the first canvas click; this is the same request for a game that starts capture from another named gesture, and `ctx.input.captureMouse()` is the map's own way to ask.
770
+
771
+ ```ts
772
+ export function captureMouse(target: EventTarget): Promise<void> | undefined { … }
773
+ ```
774
+
775
+ - **Use when:** lock the mouse pointer so first-person mouse look keeps the cursor out of the way · stop the cursor leaving the window in the middle of a turn
776
+ - **Constraints:** the browser grants capture only from a user gesture and a refusal is reported, never swallowed · a relative binding requests capture on canvas click unless `captureOnClick: false` opts out
777
+
778
+ ```ts
779
+ canvas.addEventListener("click", () => captureMouse(canvas));
780
+ ```
781
+
752
782
  ### `clipBoneCoverage`
753
783
 
754
784
  `function` — Report which bones of a character a clip does not drive.
@@ -907,7 +937,7 @@ const capture = game.runtime.pipelineCensus?.();
907
937
  export function createRandom(seed?: number): IRandom { … }
908
938
  ```
909
939
 
910
- - **Use when:** seed enemy patrol choices · reproduce the same procedural level in a playtest
940
+ - **Use when:** get a seeded deterministic random number generator — the same mulberry32 a game would hand-roll · seed enemy patrol choices · reproduce the same procedural level in a playtest
911
941
  - **Constraints:** use the returned source instead of Math.random for replayable behavior
912
942
  - **Supersedes (writing this fails `pnpm budgets`):** Math.random(
913
943
 
@@ -930,6 +960,39 @@ export function createReplayDriver( recording: Recording, target: EventTarget, p
930
960
  const driver = createReplayDriver(recording, ctx.renderer.domElement);
931
961
  ```
932
962
 
963
+ ### `Daylight`
964
+
965
+ `class` — An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye, hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.
966
+
967
+ ```ts
968
+ export class Daylight extends Group implements IComputeDriven { … }
969
+ ```
970
+
971
+ - **Use when:** daytime sky, sun and shadows for a large outdoor map · distant terrain should fade into the sky instead of a coloured wall · match a Blender look-dev scene's sun, sky and exposure in the game
972
+ - **Constraints:** every value is required; there is no default sun, sky, haze or exposure · `skySize` must keep the sky box's corners inside the camera's far plane · shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
973
+ - **Overrides:** sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
974
+
975
+ ```ts
976
+ const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });
977
+ ctx.add(daylight);
978
+ ```
979
+
980
+ ### `debugFlag`
981
+
982
+ `function` — Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.
983
+
984
+ ```ts
985
+ export function debugFlag(name: string): boolean { … }
986
+ ```
987
+
988
+ - **Use when:** read a debug toggle from the URL or an environment variable
989
+ - **Constraints:** a name in camelCase becomes UPPER_SNAKE: `debugFlag("freeCam")` reads `?freeCam` or `TN_DEBUG_FREE_CAM` · `0` and `false` are off, so a saved URL cannot turn a switch back on
990
+
991
+ ```ts
992
+ import { debugFlag } from "@threenative/core";
993
+ if (debugFlag("freeCam")) camera.flyMode = true;
994
+ ```
995
+
933
996
  ### `defineGame`
934
997
 
935
998
  `function` — Define the portable game entry shared by web and native.
@@ -1056,6 +1119,23 @@ renderer.render(scene, camera);
1056
1119
  tracker.commit(scene);
1057
1120
  ```
1058
1121
 
1122
+ ### `exposeDebug`
1123
+
1124
+ `function` — Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
1125
+
1126
+ ```ts
1127
+ export function exposeDebug(name: string, value: unknown): void { … }
1128
+ ```
1129
+
1130
+ - **Use when:** expose a game object to a capture script or the console in dev builds
1131
+ - **Constraints:** development builds only; a production build publishes nothing
1132
+
1133
+ ```ts
1134
+ import { exposeDebug } from "@threenative/core";
1135
+ exposeDebug("player", player);
1136
+ // then from the console: __THREENATIVE__.debug.player
1137
+ ```
1138
+
1059
1139
  ### `FlightModel`
1060
1140
 
1061
1141
  `class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
@@ -1143,7 +1223,7 @@ if (renderListValidationRequested()) console.log(formatValidationReport(report))
1143
1223
  export class FrameBudget { … }
1144
1224
  ```
1145
1225
 
1146
- - **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass
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
1147
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
1148
1228
 
1149
1229
  ```ts
@@ -1204,7 +1284,7 @@ if (isMobile()) showTouchControls();
1204
1284
  export class GPUParticles3D extends Sprite implements IComputeDriven { … }
1205
1285
  ```
1206
1286
 
1207
- - **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
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 · 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
1208
1288
  - **Constraints:** geometry, color, and timing remain supplied by the game
1209
1289
 
1210
1290
  ```ts
@@ -1258,6 +1338,22 @@ import { GroundSnap } from "@threenative/core";
1258
1338
  const snap = new GroundSnap(character, { enabled: true });
1259
1339
  ```
1260
1340
 
1341
+ ### `InputMap`
1342
+
1343
+ `class` — The map a game reads input through: named actions, 2D vectors and scalar axes resolved from keyboard, gamepad, mouse, wheel, pinch and touch. `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual route is a binding in the config and `ctx.input.axis("move")` in the update. Construct one directly to drive a menu, a replay or a test outside a running game.
1344
+
1345
+ ```ts
1346
+ export class InputMap { … }
1347
+ ```
1348
+
1349
+ - **Use when:** map WASD keys to a movement axis instead of reading the held key set in the update loop · read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together · read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks
1350
+ - **Constraints:** `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it · scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own
1351
+
1352
+ ```ts
1353
+ const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: ["KeyA"], right: ["KeyD"] } }, scenes: { Play } });
1354
+ // inside the scene, per frame: ctx.input.axis("move") is 0 at rest and 1 at full tilt
1355
+ ```
1356
+
1261
1357
  ### `installSpanProbes`
1262
1358
 
1263
1359
  `function` — Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's `sort`, the per-draw submission, and the scene-graph walk. Installed for you when `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.
@@ -1303,7 +1399,7 @@ export function invalidateStatic(object: Object3D): number | undefined { … }
1303
1399
  - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1304
1400
 
1305
1401
  ```ts
1306
- markStatic(island); invalidateStatic(drawbridge);
1402
+ invalidateStatic(drawbridge);
1307
1403
  ```
1308
1404
 
1309
1405
  ### `isMobile`
@@ -1348,7 +1444,7 @@ export function isStatic(root: Object3D): boolean { … }
1348
1444
  - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1349
1445
 
1350
1446
  ```ts
1351
- markStatic(island); invalidateStatic(drawbridge);
1447
+ invalidateStatic(drawbridge);
1352
1448
  ```
1353
1449
 
1354
1450
  ### `isTouchscreenAvailable`
@@ -1397,16 +1493,31 @@ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TI
1397
1493
  const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
1398
1494
  ```
1399
1495
 
1496
+ ### `lodPixelScale`
1497
+
1498
+ `function` — The screen pixels one world unit covers at `depth` for this camera and viewport. Perspective divides the projected scale by the depth; orthographic has no depth term and uses the frustum height instead. This is the number a level of detail is chosen against: multiply a level's world-space error by it and you have the on-screen error a player can see, which is the comparison `updateModelLods` makes from the baked chain.
1499
+
1500
+ ```ts
1501
+ export function lodPixelScale(camera: Camera, viewportHeight: number, depth: number): number { … }
1502
+ ```
1503
+
1504
+ - **Use when:** pick a level of detail from an object's projected size in pixels on screen · know how many screen pixels a world-space error covers at a given distance
1505
+ - **Constraints:** a non-positive viewport height, a non-positive frustum height or an unprojectable camera throws · a non-positive depth has no projected scale and returns Infinity
1506
+
1507
+ ```ts
1508
+ const pixels = lodPixelScale(camera, canvas.clientHeight, mesh.position.distanceTo(camera.position));
1509
+ ```
1510
+
1400
1511
  ### `markStatic`
1401
1512
 
1402
- `function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
1513
+ `function` — Freeze a subtree nobody moves: `markStatic(root)` composes its transforms once and stops the per-frame recompose. It is the call a game makes on scenery, terrain, buildings and props. The engine re-arms a root whose own transform the game changes; a write deeper inside a frozen subtree is announced with `invalidateStatic(object)`.
1403
1514
 
1404
1515
  ```ts
1405
1516
  export function markStatic(root: Object3D): number { … }
1406
1517
  ```
1407
1518
 
1408
- - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
1409
- - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1519
+ - **Use when:** freeze a static mesh or subtree so its matrices are not recomputed every frame · stop the engine recomposing the transforms of props, terrain and buildings each frame
1520
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1410
1521
 
1411
1522
  ```ts
1412
1523
  markStatic(island); invalidateStatic(drawbridge);
@@ -1420,7 +1531,7 @@ markStatic(island); invalidateStatic(drawbridge);
1420
1531
  export class MatrixWorldPass { … }
1421
1532
  ```
1422
1533
 
1423
- - **Use when:** the per-frame world matrix walk is hot in a profile · stop multiplying matrices for hidden models, LOD levels and merged stand-ins · a game needs every node walked, exactly as three's own updateMatrixWorld does
1534
+ - **Use when:** update the world matrices of the visible objects each frame instead of the whole scene · the per-frame world matrix walk is hot in a profile · stop multiplying matrices for hidden models, LOD levels and merged stand-ins · a game needs every node walked, exactly as three's own updateMatrixWorld does
1424
1535
  - **Constraints:** a game that reads a hidden object's matrixWorld directly must use getWorldPosition or updateWorldMatrix(true, false) first · `renderer.matrixWorld: "all"` visits every node; `TN_PROJECTION` reports the visited count either way
1425
1536
  - **Overrides:** renderer.matrixWorld: "all" runs three's full walk instead of the visible-only default
1426
1537
 
@@ -1444,6 +1555,24 @@ export function measureThreePose( object: Object3D, options: IMeasureThreePoseOp
1444
1555
  const measurement = measureThreePose(model);
1445
1556
  ```
1446
1557
 
1558
+ ### `mergeByMaterial`
1559
+
1560
+ `function` — Bake a hierarchy's static meshes into one mesh per material, with their transforms baked in. already made; nothing here decides appearance tree: add them to root and remove the sources yourself, or both draw vertices are not its own to bake texture mapping; a missing normal is recomputed
1561
+
1562
+ ```ts
1563
+ export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[] { … }
1564
+ ```
1565
+
1566
+ - **Use when:** collapse a building or ship of dozens of boxes into one draw call per material · consolidate the static parts of a group before adding it to the scene
1567
+ - **Constraints:** the material is the game's own instance and the split follows the materials the game · the meshes come back in root's local space and unparented, with the originals still in the · a skinned or instanced mesh, and a mesh with several materials, is left out — its · a group where only some meshes carry uv throws naming the label rather than losing the
1568
+ - **Overrides:** skip leaves one mesh out of its group and out of the result
1569
+
1570
+ ```ts
1571
+ const [hull, deck] = mergeByMaterial(ship, { label: "ship" });
1572
+ // a piece that must keep moving at run time:
1573
+ const [steady] = mergeByMaterial(ship, { label: "ship", skip: (mesh) => mesh.name === "radar" });
1574
+ ```
1575
+
1447
1576
  ### `mergeParts`
1448
1577
 
1449
1578
  `function` — Merge pieces a game authored out of primitives into one buffer, keeping each piece's own look. `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that never move relative to each other — a building, a ship, a character built from boxes, or the static parts of an imported glTF model. Two things go wrong every time and neither is about how any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing, and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other primitive is indexed, so the merge fails at the first piece and the scene never loads. And a merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat `color` attribute written before the merge. Both are mechanical. By default every part is stripped to position and the normals are recomputed from the merged buffer; pass `preserve` to keep authored normals and texture UVs while baking each part's object transform. Geometry, placement, colour and the surface it draws with all stay the game's.
@@ -1754,7 +1883,7 @@ export function refreshStaticTransforms(): void { … }
1754
1883
  - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1755
1884
 
1756
1885
  ```ts
1757
- markStatic(island); invalidateStatic(drawbridge);
1886
+ invalidateStatic(drawbridge);
1758
1887
  ```
1759
1888
 
1760
1889
  ### `RenderChain`
@@ -1843,7 +1972,7 @@ export function resetStaticTransforms(): void { … }
1843
1972
  - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1844
1973
 
1845
1974
  ```ts
1846
- markStatic(island); invalidateStatic(drawbridge);
1975
+ invalidateStatic(drawbridge);
1847
1976
  ```
1848
1977
 
1849
1978
  ### `resolveAtmosphereLutResolutions`
@@ -1876,6 +2005,21 @@ export function resolveAtmosphereParameters( options: IAtmosphereParameters, ):
1876
2005
  const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
1877
2006
  ```
1878
2007
 
2008
+ ### `resolveTargetFps`
2009
+
2010
+ `function` — Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.
2011
+
2012
+ ```ts
2013
+ export function resolveTargetFps( config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number, ): ITargetFps { … }
2014
+ ```
2015
+
2016
+ - **Use when:** my game does frame-rate-dependent work and must not hardcode 60
2017
+ - **Constraints:** pass the measured display rate when you have one; without it the answer is the 60 fallback and says so
2018
+
2019
+ ```ts
2020
+ resolveTargetFps(config, getPlatform()).targetFps;
2021
+ ```
2022
+
1879
2023
  ### `RippleField`
1880
2024
 
1881
2025
  `class` — Propagate a disturbance across a patch of water surface and let it fade. step is 1/60s or the CFL stability limit for the given resolution and speed, whichever is smaller
@@ -1949,7 +2093,7 @@ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1949
2093
  export class Scheduler { … }
1950
2094
  ```
1951
2095
 
1952
- - **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
2096
+ - **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
1953
2097
  - **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
1954
2098
 
1955
2099
  ```ts
@@ -2025,6 +2169,21 @@ import { skeletonBones } from "@threenative/core";
2025
2169
  const bones = skeletonBones(character);
2026
2170
  ```
2027
2171
 
2172
+ ### `snapRefreshRate`
2173
+
2174
+ `function` — Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.
2175
+
2176
+ ```ts
2177
+ export function snapRefreshRate(refreshHz: number): number { … }
2178
+ ```
2179
+
2180
+ - **Use when:** my game does frame-rate-dependent work and must not hardcode 60
2181
+ - **Constraints:** pass the measured display rate when you have one; without it the answer is the 60 fallback and says so
2182
+
2183
+ ```ts
2184
+ resolveTargetFps(config, getPlatform()).targetFps;
2185
+ ```
2186
+
2028
2187
  ### `SoftBody3D`
2029
2188
 
2030
2189
  `class` — Simulate an ordinary game-authored triangle mesh as cloth on the existing fixed-step GPU lane. The mesh supplies every visible choice. This class welds exporter duplicates, owns spring and position buffers, and replaces only the cloned material's position node. It adds no material, colour, texture, wind, stiffness, damping, or pinning default.
@@ -2188,7 +2347,7 @@ export function staticTransformCensus(): IStaticTransformCensus { … }
2188
2347
  - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
2189
2348
 
2190
2349
  ```ts
2191
- markStatic(island); invalidateStatic(drawbridge);
2350
+ invalidateStatic(drawbridge);
2192
2351
  ```
2193
2352
 
2194
2353
  ### `TracerPool3D`
@@ -2199,7 +2358,7 @@ markStatic(island); invalidateStatic(drawbridge);
2199
2358
  export class TracerPool3D { … }
2200
2359
  ```
2201
2360
 
2202
- - **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
2361
+ - **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
2203
2362
  - **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
2204
2363
 
2205
2364
  ```ts
@@ -2219,7 +2378,7 @@ export function unmarkStatic(root: Object3D): void { … }
2219
2378
  - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
2220
2379
 
2221
2380
  ```ts
2222
- markStatic(island); invalidateStatic(drawbridge);
2381
+ invalidateStatic(drawbridge);
2223
2382
  ```
2224
2383
 
2225
2384
  ### `updateAtmosphereParameters`
@@ -2335,7 +2494,7 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
2335
2494
  ```
2336
2495
 
2337
2496
  - **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
2338
- - **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
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
2339
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
2340
2499
 
2341
2500
  ```ts
@@ -2676,6 +2835,21 @@ const mirror = subscribeUiState(bridge);
2676
2835
 
2677
2836
  ## `@threenative/core/world`
2678
2837
 
2838
+ ### `cellPlacements`
2839
+
2840
+ `function` — Borrow the run's placement records as a live view over the placement buffer.
2841
+
2842
+ ```ts
2843
+ export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }
2844
+ ```
2845
+
2846
+ - **Use when:** feed one cell's instance transforms into a batch without copying
2847
+ - **Constraints:** the returned view aliases the caller's buffer; writing to it mutates the source
2848
+
2849
+ ```ts
2850
+ const records = cellPlacements(buffer, { asset: "tree", offset: 0, count: 120 });
2851
+ ```
2852
+
2679
2853
  ### `getWorldCapabilities`
2680
2854
 
2681
2855
  `function` — Resolve the active world-generation path from host capability facts. The function accepts the adapter facts instead of reaching through a renderer-specific global, so browser and native hosts can report the same object. Missing limits are not treated as infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback. GPU generation remains unavailable until a GPU readback can own the canonical field; a host adapter report therefore never upgrades a CPU fallback into a GPU generation claim.
@@ -2700,7 +2874,7 @@ const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackI
2700
2874
  export class Heightfield extends Group implements IComputeDriven { … }
2701
2875
  ```
2702
2876
 
2703
- - **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
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 · keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)
2704
2878
  - **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
2705
2879
  - **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
2706
2880
 
@@ -2708,6 +2882,90 @@ export class Heightfield extends Group implements IComputeDriven { … }
2708
2882
  const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
2709
2883
  ```
2710
2884
 
2885
+ ### `heightSamplerFromHeightmap`
2886
+
2887
+ `function` — Build a game-usable `sampleHeight` from a raw v1 heightmap. The returned function interpolates bilinearly in world units and clamps to the map edges, so it plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
2888
+
2889
+ ```ts
2890
+ export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWorldExtent, data: Uint16Array, ): (x: number, z: number) => number { … }
2891
+ ```
2892
+
2893
+ - **Use when:** turn an exported raw heightmap into terrain collision and rendering · query ground height from a Blender-authored world package
2894
+ - **Constraints:** the sampler reads the game's data; the framework never selects a terrain shape
2895
+
2896
+ ```ts
2897
+ const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
2898
+ ```
2899
+
2900
+ ### `loadTerrainSplat`
2901
+
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.
2903
+
2904
+ ```ts
2905
+ export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }
2906
+ ```
2907
+
2908
+ - **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
2910
+ - **Overrides:** every value comes from the package's table; the returned material is the game's to adjust
2911
+
2912
+ ```ts
2913
+ const surface = await loadTerrainSplat({ assets: ctx.assets, url: "world/world.json" });
2914
+ const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
2915
+ ```
2916
+
2917
+ ### `loadWorldHeightmap`
2918
+
2919
+ `function` — Fetch a raw little-endian uint16 heightmap and expose it as samples.
2920
+
2921
+ ```ts
2922
+ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> { … }
2923
+ ```
2924
+
2925
+ - **Use when:** load a world package's heightmap once before building terrain
2926
+ - **Constraints:** a non-OK response throws; bytes are byte-swapped only on a big-endian host
2927
+
2928
+ ```ts
2929
+ const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
2930
+ ```
2931
+
2932
+ ### `snowDiscFootprint`
2933
+
2934
+ `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.
2935
+
2936
+ ```ts
2937
+ export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }
2938
+ ```
2939
+
2940
+ - **Use when:** press a ball, wheel or probe into snow · give a sphere a physically sized snow contact instead of a boot shape
2941
+ - **Constraints:** radius is metres; the footprint never grows with load, only deeper
2942
+ - **Overrides:** softness widens the eased edge without changing the contact radius
2943
+
2944
+ ```ts
2945
+ const footprint = snowDiscFootprint(0.25);
2946
+ ```
2947
+
2948
+ ### `SnowField`
2949
+
2950
+ `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.
2951
+
2952
+ ```ts
2953
+ export class SnowField { … }
2954
+ ```
2955
+
2956
+ - **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
2957
+ - **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
2958
+ - **Requires:** @threenative/core/world Heightfield as the canonical terrain and surface
2959
+ - **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
2960
+
2961
+ ```ts
2962
+ import { Heightfield } from "@threenative/core/world";
2963
+ 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 });
2964
+ const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
2965
+ snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
2966
+ snow.recover(1 / 60, 0.0012, 0.4);
2967
+ ```
2968
+
2711
2969
  ### `TerrainTiles`
2712
2970
 
2713
2971
  `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.
@@ -2717,13 +2975,150 @@ export class TerrainTiles extends Object3D implements IComputeDriven { … }
2717
2975
  ```
2718
2976
 
2719
2977
  - **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
2720
- - **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
2721
- - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets
2978
+ - **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
2979
+ - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets
2722
2980
 
2723
2981
  ```ts
2724
2982
  const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
2725
2983
  ```
2726
2984
 
2985
+ ### `terrainValidationRequested`
2986
+
2987
+ `function` — Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.
2988
+
2989
+ ```ts
2990
+ export function terrainValidationRequested(): boolean { … }
2991
+ ```
2992
+
2993
+ - **Use when:** turn terrain's per-frame seam, LOD pop and vertex checks on for one run · assert the terrain geometry a game streams before it ships
2994
+ - **Constraints:** off by default: it is the work it checks, every frame
2995
+
2996
+ ```ts
2997
+ // Reads its own the way `renderListValidationRequested` does: a native launch sets the
2998
+ // environment variable, a browser asks with the query string, a test or harness sets the
2999
+ // global. `0` and `false` are off, so a saved URL that enabled it still says "off".
3000
+ const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
3001
+ ```
3002
+
3003
+ ### `validateWorldPackage`
3004
+
3005
+ `function` — Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.
3006
+
3007
+ ```ts
3008
+ export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }
3009
+ ```
3010
+
3011
+ - **Use when:** check a Blender-exported world package before the runtime attaches anything · report why a world package cannot be streamed
3012
+ - **Constraints:** validation only checks structure and ranges; it never fetches the heightmap or GLBs
3013
+
3014
+ ```ts
3015
+ const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
3016
+ ```
3017
+
3018
+ ### `WorldCells`
3019
+
3020
+ `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.
3021
+
3022
+ ```ts
3023
+ export class WorldCells extends Group implements IComputeDriven { … }
3024
+ ```
3025
+
3026
+ - **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
3027
+ - **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
3028
+ - **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
3029
+
3030
+ ```ts
3031
+ const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
3032
+ scene.add(world);
3033
+ world.update();
3034
+ ```
3035
+
3036
+ ## `@threenative/metahuman`
3037
+
3038
+ ### `assertAssetPath`
3039
+
3040
+ `function` — Keeps a caller-supplied asset path inside the asset directory.
3041
+
3042
+ ```ts
3043
+ export function assertAssetPath(path: string): string { … }
3044
+ ```
3045
+
3046
+ - **Use when:** reject a MetaHuman asset path that would read outside the game's asset root
3047
+ - **Constraints:** absolute paths, Windows drive letters, backslashes and any `..` segment throw MetaHumanAssetError with TN_MH_PATH_ESCAPE before the path is joined onto a root
3048
+ - **Requires:** npm i @threenative/metahuman
3049
+
3050
+ ```ts
3051
+ assertAssetPath("metahuman/specimen.glb");
3052
+ ```
3053
+
3054
+ ### `loadMetaHuman`
3055
+
3056
+ `function` — Load a prepared MetaHuman head and drive its expression from the browser's WASM evaluator: declared faceboard controls in, joint deltas and morph weights out, applied to an ordinary Three.js object graph. two characters never write each other's face and nothing is disposed that `ctx.assets` still owns switch re-evaluates the current controls before the replacement mesh is shown `dispose()` throw, each with a stable `code`; nothing is clamped or coerced `diagnostics().backend` reads "native"; the game code does not change
3057
+
3058
+ ```ts
3059
+ loadMetaHuman = (options: ILoadMetaHumanOptions): Promise<IMetaHuman> => createMetaHuman( { … }
3060
+ ```
3061
+
3062
+ - **Use when:** put a MetaHuman head in a browser game without an Unreal import or a baked clip
3063
+ - **Constraints:** the model is loaded through the game's own asset loader and cloned per instance, so · the rig's own GUI-to-raw mapping runs; the adapter never re-derives it, and a LOD · an undeclared control, an out-of-domain value, an undeclared LOD and any call after · in a native host that installed the MetaHuman resident the C++ evaluator runs and
3064
+ - **Requires:** npm i @threenative/metahuman
3065
+
3066
+ ```ts
3067
+ const human = await loadMetaHuman({ assets: ctx.assets, model: "metahuman/head.glb",
3068
+ dna: "metahuman/head.dna", bindings: "metahuman/bindings.json" });
3069
+ human.setControls({ jawOpen: 0.4 });
3070
+ // in the scene update, after any body animation
3071
+ human.update();
3072
+ ```
3073
+
3074
+ ### `MetaHumanAssetError`
3075
+
3076
+ `class` — The rejection every check in this package raises, carrying a stable machine-readable code.
3077
+
3078
+ ```ts
3079
+ export class MetaHumanAssetError extends Error { … }
3080
+ ```
3081
+
3082
+ - **Use when:** branch on why a MetaHuman asset or evaluator call was refused
3083
+ - **Constraints:** `code` is part of the public surface; renaming one is a breaking change
3084
+ - **Requires:** npm i @threenative/metahuman
3085
+
3086
+ ```ts
3087
+ if (error instanceof MetaHumanAssetError && error.code === "TN_MH_HASH_MISMATCH") refetch();
3088
+ ```
3089
+
3090
+ ### `RigEvaluator`
3091
+
3092
+ `class` — One MetaHuman head rig over the checksum-verified browser WASM build of the shared OpenRigLogic ABI: faceboard GUI controls in, joint deltas, blend shape weights and animated map weights out. instantiated, and nothing is fetched from a CDN evaluator throws instead of reading freed memory `create` and the WASM is never fetched; `RigEvaluator.backend()` says which one runs
3093
+
3094
+ ```ts
3095
+ export class RigEvaluator implements IRigEvaluator { … }
3096
+ ```
3097
+
3098
+ - **Use when:** drive a prepared MetaHuman head's expression from the browser without an Unreal import
3099
+ - **Constraints:** the binary's SHA-256 is checked against the shipped manifest before it is · every returned array is a copy, so no view survives a memory growth; a disposed · a native host that installed the MetaHuman resident gets its C++ evaluator from
3100
+ - **Requires:** npm i @threenative/metahuman
3101
+
3102
+ ```ts
3103
+ const rig = await RigEvaluator.create(dna); rig.setGuiControls(gui); rig.evaluate(true); rig.jointOutputs();
3104
+ ```
3105
+
3106
+ ### `validateMetaHumanAssets`
3107
+
3108
+ `function` — Checks one prepared specimen — bindings sidecar, DNA and GLB — against the rig it claims to drive, and returns the bindings only when every name, index, domain and hash holds up. channels, morph targets or LODs the loaded files do not contain disk and an index past the end of its array are rejections, each with a stable code cannot pass a hand-written sidecar the rig cannot drive
3109
+
3110
+ ```ts
3111
+ export function validateMetaHumanAssets(input: IMetaHumanAssetInput): IMetaHumanBindings { … }
3112
+ ```
3113
+
3114
+ - **Use when:** refuse a MetaHuman specimen whose bindings point at joints, nodes, blend shape
3115
+ - **Constraints:** fails closed: a missing key, a wrong type, a hash that differs from the bytes on · reads the rig's real names and the GLB's real node, mesh and target counts, so it
3116
+ - **Requires:** npm i @threenative/metahuman
3117
+
3118
+ ```ts
3119
+ const bindings = validateMetaHumanAssets({ bindings: parsed, dnaSha256, glbSha256, rig, gltf });
3120
+ ```
3121
+
2727
3122
  ## `@threenative/physics`
2728
3123
 
2729
3124
  ### `Area3D`
@@ -2736,11 +3131,45 @@ export class Area3D { … }
2736
3131
 
2737
3132
  - **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
2738
3133
  - **Constraints:** add the area to the physics context before stepping the world
3134
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated.
2739
3135
 
2740
3136
  ```ts
2741
3137
  const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });
2742
3138
  ```
2743
3139
 
3140
+ ### `attachSnowPhysics`
3141
+
3142
+ `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.
3143
+
3144
+ ```ts
3145
+ export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }
3146
+ ```
3147
+
3148
+ - **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
3149
+ - **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
3150
+ - **Requires:** @threenative/core/world SnowField as the surface it deforms
3151
+ - **Overrides:** loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour
3152
+
3153
+ ```ts
3154
+ const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });
3155
+ afterPhysics(ctx, (dt) => snowPhysics.step(dt));
3156
+ ```
3157
+
3158
+ ### `boxFootprint`
3159
+
3160
+ `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.
3161
+
3162
+ ```ts
3163
+ export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }
3164
+ ```
3165
+
3166
+ - **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
3167
+ - **Constraints:** halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint
3168
+
3169
+ ```ts
3170
+ const footprint = boxFootprint(0.4, 0.25);
3171
+ ```
3172
+
2744
3173
  ### `buildStaticColliders`
2745
3174
 
2746
3175
  `function` — Build fixed trimesh bodies from the meshes a game authored in a scene root.
@@ -2772,6 +3201,21 @@ export class Buoyancy3D { … }
2772
3201
  new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
2773
3202
  ```
2774
3203
 
3204
+ ### `capsuleFootprint`
3205
+
3206
+ `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.
3207
+
3208
+ ```ts
3209
+ export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }
3210
+ ```
3211
+
3212
+ - **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
3213
+ - **Constraints:** radius and halfHeight are metres and never grow with load
3214
+
3215
+ ```ts
3216
+ const footprint = capsuleFootprint(0.5, 0.2);
3217
+ ```
3218
+
2775
3219
  ### `CharacterBody3D`
2776
3220
 
2777
3221
  `class` — Move a character body with collision-aware sliding.
@@ -2782,6 +3226,7 @@ export class CharacterBody3D { … }
2782
3226
 
2783
3227
  - **Use when:** move an enemy or player through a level · keep a character from walking through walls
2784
3228
  - **Constraints:** use moveAndSlide inside the physics update
3229
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
2785
3230
 
2786
3231
  ```ts
2787
3232
  const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });
@@ -2826,6 +3271,7 @@ export class Joint3D { … }
2826
3271
 
2827
3272
  - **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
2828
3273
  - **Constraints:** both bodies must belong to the same physics context
3274
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated.
2829
3275
 
2830
3276
  ```ts
2831
3277
  const hinge = Joint3D.hinge({ physics: ctx.physics, bodyA: beam, bodyB: bob, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: 0, y: 2.4, z: 0 }, axis: { x: 1, y: 0, z: 0 } });
@@ -2872,6 +3318,7 @@ export class RigidBody3D { … }
2872
3318
  - **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
2873
3319
  - **Constraints:** register rapier() in the game plugin list before using bodies
2874
3320
  - **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
3321
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated.
2875
3322
 
2876
3323
  ```ts
2877
3324
  const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
@@ -2892,6 +3339,22 @@ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyC
2892
3339
  const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
2893
3340
  ```
2894
3341
 
3342
+ ### `VehicleBody3D`
3343
+
3344
+ `class` — Drive a car on ray-cast suspension instead of faking speed and heading.
3345
+
3346
+ ```ts
3347
+ export class VehicleBody3D extends RigidBody3D { … }
3348
+ ```
3349
+
3350
+ - **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
3351
+ - **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
3352
+ - **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
3353
+
3354
+ ```ts
3355
+ const car = new VehicleBody3D({ object: chassis, physics: ctx.physics, shape: CollisionShape3D.box(1.6, 0.5, 3.6), mass: 900, wheels: [{ position: { x: 0.8, y: -0.15, z: -1.2 }, wheelRadius: 0.34, suspensionRestLength: 0.3, suspensionStiffness: 100, dampingCompression: 2.3, dampingRelaxation: 4.4, wheelFrictionSlip: 10.5, maxSuspensionTravel: 0.3, useAsSteering: true, useAsTraction: false }] });
3356
+ ```
3357
+
2895
3358
  ## `@threenative/physics/navigation`
2896
3359
 
2897
3360
  ### `NavigationAgent3D`
@@ -3296,6 +3759,21 @@ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrame
3296
3759
  assertCaptureNotBlank(png, "first frame");
3297
3760
  ```
3298
3761
 
3762
+ ### `assertFrameShowsSomething`
3763
+
3764
+ `function` — Fail closed when a screenshot is blank or uniform.
3765
+
3766
+ ```ts
3767
+ assertFrameShowsSomething = assertCaptureNotBlank
3768
+ ```
3769
+
3770
+ - **Use when:** guard a visual playtest against a blank frame · prove a screenshot contains more than a loading surface
3771
+ - **Constraints:** the assertion throws instead of returning a false pass
3772
+
3773
+ ```ts
3774
+ assertFrameShowsSomething(png, "first frame");
3775
+ ```
3776
+
3299
3777
  ### `CaptureGuardError`
3300
3778
 
3301
3779
  `class` — Explain why a captured frame failed the non-blank guard.
@@ -3537,6 +4015,23 @@ export async function connectPlaytestBridgeTransport( transport: IBridgeTranspor
3537
4015
  const bridge = await connectPlaytestBridge(page, scenario);
3538
4016
  ```
3539
4017
 
4018
+ ### `decideDisplayStrategy`
4019
+
4020
+ `function` — Decide which display a pixel-producing run paints on, the same decision the runner makes.
4021
+
4022
+ ```ts
4023
+ export function decideDisplayStrategy(input: IDisplayDecisionInput): IDisplayStrategy { … }
4024
+ ```
4025
+
4026
+ - **Use when:** judge whether a measured frame rate came from a display that can carry one
4027
+ - **Constraints:** a private Xvfb is software, so a rate read there measures the X server
4028
+
4029
+ ```ts
4030
+ import { decideDisplayStrategy } from "@threenative/playtest/runner";
4031
+ const lane = decideDisplayStrategy({ env: process.env, platform: "linux" });
4032
+ if (lane.kind === "private-xvfb") throw new Error("refuse to judge this frame rate");
4033
+ ```
4034
+
3540
4035
  ### `DesktopPlaytestDriver`
3541
4036
 
3542
4037
  `class` — Drive a local desktop playtest mailbox.
@@ -5038,6 +5533,23 @@ export function useUiState<TState extends object>(): TState | undefined;
5038
5533
  const score = useUiState<GameState, number>((state) => state.score);
5039
5534
  ```
5040
5535
 
5536
+ ## `src/audio/storm.ts`
5537
+
5538
+ ### `createStormAudio`
5539
+
5540
+ `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.
5541
+
5542
+ ```ts
5543
+ createStormAudio(ctx: ICtx<GameState>): IStormAudio
5544
+ ```
5545
+
5546
+ - **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
5547
+ - **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.
5548
+
5549
+ ```ts
5550
+ src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene
5551
+ ```
5552
+
5041
5553
  ## `src/game.ts`
5042
5554
 
5043
5555
  ### `renderer.matrixWorld`
@@ -5074,19 +5586,88 @@ renderer: { minimumProjectedPixels: 2 } // in threenative.config.ts
5074
5586
 
5075
5587
  ### `renderer.projection`
5076
5588
 
5077
- `function` — The engine's scene-render projection — an internal mirror that collapses repeated draws — on by default. Set `renderer.projection: false` to decline it.
5589
+ `function` — The engine's scene-render projection — an internal mirror that collapses repeated draws, including animated skinned rigs that share a geometry and material into one palette draw per pass — on by default. Set `renderer.projection: false` to decline it, or `projection: { materialChecks: 'everyFrame' }` to keep it and pay for a per-material check on every frame.
5078
5590
 
5079
5591
  ```ts
5080
- renderer.projection?: boolean
5592
+ renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }
5081
5593
  ```
5082
5594
 
5083
- - **Use when:** the game got slower after the projection engaged · turn off the render projection, batching, or the instanced mirror · draw count fell but frame time did not · a multi-second freeze when the mirror first engages · opt out of an engine render optimizer
5084
- - **Constraints:** Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it. · An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame. · TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines.
5595
+ - **Use when:** a crowd of animated characters draws slowly · many SkinnedMesh copies of one rig, each its own draw call · the game got slower after the projection engaged · turn off the render projection, batching, or the instanced mirror · draw count fell but frame time did not · a multi-second freeze when the mirror first engages · opt out of an engine render optimizer · thousands of props each with their own material, one colour apart · a material edit takes a few frames to show up · check every batched material every frame anyway
5596
+ - **Constraints:** Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it. · An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame. · TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines. · `materialChecks: 'spread'` is the default: a bounded slice of the batched materials is proved per frame instead of all of them, so a frame of 4,096 colour-only materials costs 512 checks rather than 4,096. A base-colour edit is never delayed — that write is O(1) per member. · The price of `spread` is staleness on every other material edit: a material that gains a roughness, a map or a define still leaves its group and is drawn exactly, up to `materialCheckStaleFrames` frames later. TN_RENDER_PROJECTION reports that bound; `materialChecks: 'everyFrame'` sets it to 0 and restores the per-member, per-frame check. · Any other `materialChecks` value throws at startup rather than falling back to a default.
5597
+ - **Overrides:** renderer.projection: false declines the whole mirror and costs nothing to decline · renderer: { projection: { materialChecks: 'everyFrame' } } proves every batched material every frame instead of the default bounded slice
5085
5598
 
5086
5599
  ```ts
5087
5600
  renderer: { projection: false } // in threenative.config.ts
5088
5601
  ```
5089
5602
 
5603
+ ## `src/render/lightning.ts`
5604
+
5605
+ ### `createStormLightning`
5606
+
5607
+ `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.
5608
+
5609
+ ```ts
5610
+ createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning
5611
+ ```
5612
+
5613
+ - **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
5614
+ - **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.
5615
+
5616
+ ```ts
5617
+ src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay
5618
+ ```
5619
+
5620
+ ## `src/render/noise-volume.ts`
5621
+
5622
+ ### `createNoiseVolume`
5623
+
5624
+ `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.
5625
+
5626
+ ```ts
5627
+ createNoiseVolume(): INoiseVolume
5628
+ ```
5629
+
5630
+ - **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
5631
+ - **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.
5632
+
5633
+ ```ts
5634
+ src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there
5635
+ ```
5636
+
5637
+ ## `src/render/rain.ts`
5638
+
5639
+ ### `createStormRain`
5640
+
5641
+ `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.
5642
+
5643
+ ```ts
5644
+ createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain
5645
+ ```
5646
+
5647
+ - **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
5648
+ - **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.
5649
+
5650
+ ```ts
5651
+ src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget
5652
+ ```
5653
+
5654
+ ## `src/render/world.ts`
5655
+
5656
+ ### `createWeatherWorld`
5657
+
5658
+ `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() }`.
5659
+
5660
+ ```ts
5661
+ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
5662
+ ```
5663
+
5664
+ - **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
5665
+ - **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.
5666
+
5667
+ ```ts
5668
+ src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
5669
+ ```
5670
+
5090
5671
  ## `src/render/worldEnvironment.ts`
5091
5672
 
5092
5673
  ### `WorldEnvironment`