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
package/capabilities.json CHANGED
@@ -794,7 +794,8 @@
794
794
  "aliases": [],
795
795
  "constraints": [
796
796
  "create buses before playing clips and dispose them with the game",
797
- "refDistance and rolloffFactor tune positional falloff and apply to playAt only"
797
+ "refDistance and rolloffFactor tune positional falloff and apply to playAt only",
798
+ "compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum"
798
799
  ],
799
800
  "example": "const effects = new AudioBus({ camera });",
800
801
  "importPath": "@threenative/core",
@@ -806,6 +807,7 @@
806
807
  "play a sound effect with a volume bus",
807
808
  "mute or adjust a category of game audio",
808
809
  "keep a gunshot audible at 20 metres by tuning positional falloff",
810
+ "hold a loud mix below clipping with a compressor on the bus",
809
811
  "play cannon, wave, and ship sound effects"
810
812
  ],
811
813
  "summary": "Route effects through a named audio bus.",
@@ -930,6 +932,26 @@
930
932
  "supersedes": [],
931
933
  "symbol": "boneLengths"
932
934
  },
935
+ {
936
+ "aliases": [],
937
+ "constraints": [
938
+ "call rebuild() after a scene transform or geometry change; the snapshot is static by default",
939
+ "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"
940
+ ],
941
+ "example": "const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));",
942
+ "importPath": "@threenative/core",
943
+ "kind": "function",
944
+ "overrides": [],
945
+ "package": "@threenative/core",
946
+ "signature": "bvhIntersectFirstHit = upstream.bvhIntersectFirstHit",
947
+ "situations": [
948
+ "trace thousands of scene rays inside a TSL kernel",
949
+ "build a contact-occlusion or visibility query over loaded meshes"
950
+ ],
951
+ "summary": "Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.",
952
+ "supersedes": [],
953
+ "symbol": "bvhIntersectFirstHit"
954
+ },
933
955
  {
934
956
  "aliases": [],
935
957
  "constraints": [
@@ -967,6 +989,26 @@
967
989
  "supersedes": [],
968
990
  "symbol": "CanvasLayer"
969
991
  },
992
+ {
993
+ "aliases": [],
994
+ "constraints": [
995
+ "the browser grants capture only from a user gesture and a refusal is reported, never swallowed",
996
+ "a relative binding requests capture on canvas click unless `captureOnClick: false` opts out"
997
+ ],
998
+ "example": "canvas.addEventListener(\"click\", () => captureMouse(canvas));",
999
+ "importPath": "@threenative/core",
1000
+ "kind": "function",
1001
+ "overrides": [],
1002
+ "package": "@threenative/core",
1003
+ "signature": "export function captureMouse(target: EventTarget): Promise<void> | undefined { … }",
1004
+ "situations": [
1005
+ "lock the mouse pointer so first-person mouse look keeps the cursor out of the way",
1006
+ "stop the cursor leaving the window in the middle of a turn"
1007
+ ],
1008
+ "summary": "Lock the pointer to the game's surface: the capture every first-person mouse look needs. A browser grants capture only from a user gesture, so call it from a click or a pointerdown handler. A relative binding such as `look: { pointerRelative: true }` already requests capture on the first canvas click; this is the same request for a game that starts capture from another named gesture, and `ctx.input.captureMouse()` is the map's own way to ask.",
1009
+ "supersedes": [],
1010
+ "symbol": "captureMouse"
1011
+ },
970
1012
  {
971
1013
  "aliases": [],
972
1014
  "constraints": ["a track that binds nothing counts as driving nothing"],
@@ -1164,6 +1206,7 @@
1164
1206
  "package": "@threenative/core",
1165
1207
  "signature": "export function createRandom(seed?: number): IRandom { … }",
1166
1208
  "situations": [
1209
+ "get a seeded deterministic random number generator — the same mulberry32 a game would hand-roll",
1167
1210
  "seed enemy patrol choices",
1168
1211
  "reproduce the same procedural level in a playtest"
1169
1212
  ],
@@ -1190,6 +1233,47 @@
1190
1233
  "supersedes": [],
1191
1234
  "symbol": "createReplayDriver"
1192
1235
  },
1236
+ {
1237
+ "aliases": [],
1238
+ "constraints": [
1239
+ "every value is required; there is no default sun, sky, haze or exposure",
1240
+ "`skySize` must keep the sky box's corners inside the camera's far plane",
1241
+ "shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing"
1242
+ ],
1243
+ "example": "const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });\nctx.add(daylight);",
1244
+ "importPath": "@threenative/core",
1245
+ "kind": "class",
1246
+ "overrides": [
1247
+ "sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`"
1248
+ ],
1249
+ "package": "@threenative/core",
1250
+ "signature": "export class Daylight extends Group implements IComputeDriven { … }",
1251
+ "situations": [
1252
+ "daytime sky, sun and shadows for a large outdoor map",
1253
+ "distant terrain should fade into the sky instead of a coloured wall",
1254
+ "match a Blender look-dev scene's sun, sky and exposure in the game"
1255
+ ],
1256
+ "summary": "An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye, hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.",
1257
+ "supersedes": [],
1258
+ "symbol": "Daylight"
1259
+ },
1260
+ {
1261
+ "aliases": [],
1262
+ "constraints": [
1263
+ "a name in camelCase becomes UPPER_SNAKE: `debugFlag(\"freeCam\")` reads `?freeCam` or `TN_DEBUG_FREE_CAM`",
1264
+ "`0` and `false` are off, so a saved URL cannot turn a switch back on"
1265
+ ],
1266
+ "example": "import { debugFlag } from \"@threenative/core\";\nif (debugFlag(\"freeCam\")) camera.flyMode = true;",
1267
+ "importPath": "@threenative/core",
1268
+ "kind": "function",
1269
+ "overrides": [],
1270
+ "package": "@threenative/core",
1271
+ "signature": "export function debugFlag(name: string): boolean { … }",
1272
+ "situations": ["read a debug toggle from the URL or an environment variable"],
1273
+ "summary": "Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.",
1274
+ "supersedes": [],
1275
+ "symbol": "debugFlag"
1276
+ },
1193
1277
  {
1194
1278
  "aliases": [
1195
1279
  "firing line nearest target crosshair",
@@ -1353,6 +1437,20 @@
1353
1437
  "supersedes": [],
1354
1438
  "symbol": "ensureVelocityOutput"
1355
1439
  },
1440
+ {
1441
+ "aliases": [],
1442
+ "constraints": ["development builds only; a production build publishes nothing"],
1443
+ "example": "import { exposeDebug } from \"@threenative/core\";\nexposeDebug(\"player\", player);\n// then from the console: __THREENATIVE__.debug.player",
1444
+ "importPath": "@threenative/core",
1445
+ "kind": "function",
1446
+ "overrides": [],
1447
+ "package": "@threenative/core",
1448
+ "signature": "export function exposeDebug(name: string, value: unknown): void { … }",
1449
+ "situations": ["expose a game object to a capture script or the console in dev builds"],
1450
+ "summary": "Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.",
1451
+ "supersedes": [],
1452
+ "symbol": "exposeDebug"
1453
+ },
1356
1454
  {
1357
1455
  "aliases": [],
1358
1456
  "constraints": [
@@ -1478,6 +1576,7 @@
1478
1576
  "package": "@threenative/core",
1479
1577
  "signature": "export class FrameBudget { … }",
1480
1578
  "situations": [
1579
+ "show an on-screen frame time meter with p50, p95 and p99 percentiles",
1481
1580
  "find out why a game runs slowly on a phone",
1482
1581
  "attribute a frame to present wait, simulation, three.js render, or overlay",
1483
1582
  "tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp",
@@ -1565,7 +1664,9 @@
1565
1664
  "update many small visual particles",
1566
1665
  "trail dust, exhaust, or spray behind a moving object",
1567
1666
  "emit cannon smoke and muzzle flash particles",
1568
- "fire a cannonball projectile with cannon smoke particles"
1667
+ "fire a cannonball projectile with cannon smoke particles",
1668
+ "falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard",
1669
+ "kick up a spray of powder snow or dust where a foot or a ball lands"
1569
1670
  ],
1570
1671
  "summary": "Dispatch a game-owned particle surface and process function through a pooled system.",
1571
1672
  "supersedes": [],
@@ -1635,6 +1736,27 @@
1635
1736
  "supersedes": [],
1636
1737
  "symbol": "GroundSnap"
1637
1738
  },
1739
+ {
1740
+ "aliases": [],
1741
+ "constraints": [
1742
+ "`buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it",
1743
+ "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"
1744
+ ],
1745
+ "example": "const game = defineGame({ input: { move: { up: [\"KeyW\"], down: [\"KeyS\"], left: [\"KeyA\"], right: [\"KeyD\"] } }, scenes: { Play } });\n// inside the scene, per frame: ctx.input.axis(\"move\") is 0 at rest and 1 at full tilt",
1746
+ "importPath": "@threenative/core",
1747
+ "kind": "class",
1748
+ "overrides": [],
1749
+ "package": "@threenative/core",
1750
+ "signature": "export class InputMap { … }",
1751
+ "situations": [
1752
+ "map WASD keys to a movement axis instead of reading the held key set in the update loop",
1753
+ "read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together",
1754
+ "read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks"
1755
+ ],
1756
+ "summary": "The map a game reads input through: named actions, 2D vectors and scalar axes resolved from keyboard, gamepad, mouse, wheel, pinch and touch. `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual route is a binding in the config and `ctx.input.axis(\"move\")` in the update. Construct one directly to drive a menu, a replay or a test outside a running game.",
1757
+ "supersedes": [],
1758
+ "symbol": "InputMap"
1759
+ },
1638
1760
  {
1639
1761
  "aliases": [],
1640
1762
  "constraints": [
@@ -1688,7 +1810,7 @@
1688
1810
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
1689
1811
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
1690
1812
  ],
1691
- "example": "markStatic(island); invalidateStatic(drawbridge);",
1813
+ "example": "invalidateStatic(drawbridge);",
1692
1814
  "importPath": "@threenative/core",
1693
1815
  "kind": "function",
1694
1816
  "overrides": [],
@@ -1751,7 +1873,7 @@
1751
1873
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
1752
1874
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
1753
1875
  ],
1754
- "example": "markStatic(island); invalidateStatic(drawbridge);",
1876
+ "example": "invalidateStatic(drawbridge);",
1755
1877
  "importPath": "@threenative/core",
1756
1878
  "kind": "function",
1757
1879
  "overrides": [],
@@ -1829,11 +1951,30 @@
1829
1951
  "supersedes": [],
1830
1952
  "symbol": "loadAll"
1831
1953
  },
1954
+ {
1955
+ "aliases": [],
1956
+ "constraints": [
1957
+ "a non-positive viewport height, a non-positive frustum height or an unprojectable camera throws",
1958
+ "a non-positive depth has no projected scale and returns Infinity"
1959
+ ],
1960
+ "example": "const pixels = lodPixelScale(camera, canvas.clientHeight, mesh.position.distanceTo(camera.position));",
1961
+ "importPath": "@threenative/core",
1962
+ "kind": "function",
1963
+ "overrides": [],
1964
+ "package": "@threenative/core",
1965
+ "signature": "export function lodPixelScale(camera: Camera, viewportHeight: number, depth: number): number { … }",
1966
+ "situations": [
1967
+ "pick a level of detail from an object's projected size in pixels on screen",
1968
+ "know how many screen pixels a world-space error covers at a given distance"
1969
+ ],
1970
+ "summary": "The screen pixels one world unit covers at `depth` for this camera and viewport. Perspective divides the projected scale by the depth; orthographic has no depth term and uses the frustum height instead. This is the number a level of detail is chosen against: multiply a level's world-space error by it and you have the on-screen error a player can see, which is the comparison `updateModelLods` makes from the baked chain.",
1971
+ "supersedes": [],
1972
+ "symbol": "lodPixelScale"
1973
+ },
1832
1974
  {
1833
1975
  "aliases": [],
1834
1976
  "constraints": [
1835
1977
  "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
1836
- "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
1837
1978
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
1838
1979
  ],
1839
1980
  "example": "markStatic(island); invalidateStatic(drawbridge);",
@@ -1843,10 +1984,10 @@
1843
1984
  "package": "@threenative/core",
1844
1985
  "signature": "export function markStatic(root: Object3D): number { … }",
1845
1986
  "situations": [
1846
- "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
1847
- "keep a frozen subtree correct when the game does move it after all"
1987
+ "freeze a static mesh or subtree so its matrices are not recomputed every frame",
1988
+ "stop the engine recomposing the transforms of props, terrain and buildings each frame"
1848
1989
  ],
1849
- "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
1990
+ "summary": "Freeze a subtree nobody moves: `markStatic(root)` composes its transforms once and stops the per-frame recompose. It is the call a game makes on scenery, terrain, buildings and props. The engine re-arms a root whose own transform the game changes; a write deeper inside a frozen subtree is announced with `invalidateStatic(object)`.",
1850
1991
  "supersedes": [],
1851
1992
  "symbol": "markStatic"
1852
1993
  },
@@ -1865,6 +2006,7 @@
1865
2006
  "package": "@threenative/core",
1866
2007
  "signature": "export class MatrixWorldPass { … }",
1867
2008
  "situations": [
2009
+ "update the world matrices of the visible objects each frame instead of the whole scene",
1868
2010
  "the per-frame world matrix walk is hot in a profile",
1869
2011
  "stop multiplying matrices for hidden models, LOD levels and merged stand-ins",
1870
2012
  "a game needs every node walked, exactly as three's own updateMatrixWorld does"
@@ -1887,6 +2029,28 @@
1887
2029
  "supersedes": [],
1888
2030
  "symbol": "measureThreePose"
1889
2031
  },
2032
+ {
2033
+ "aliases": [],
2034
+ "constraints": [
2035
+ "the material is the game's own instance and the split follows the materials the game",
2036
+ "the meshes come back in root's local space and unparented, with the originals still in the",
2037
+ "a skinned or instanced mesh, and a mesh with several materials, is left out — its",
2038
+ "a group where only some meshes carry uv throws naming the label rather than losing the"
2039
+ ],
2040
+ "example": "const [hull, deck] = mergeByMaterial(ship, { label: \"ship\" });\n// a piece that must keep moving at run time:\nconst [steady] = mergeByMaterial(ship, { label: \"ship\", skip: (mesh) => mesh.name === \"radar\" });",
2041
+ "importPath": "@threenative/core",
2042
+ "kind": "function",
2043
+ "overrides": ["skip leaves one mesh out of its group and out of the result"],
2044
+ "package": "@threenative/core",
2045
+ "signature": "export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[] { … }",
2046
+ "situations": [
2047
+ "collapse a building or ship of dozens of boxes into one draw call per material",
2048
+ "consolidate the static parts of a group before adding it to the scene"
2049
+ ],
2050
+ "summary": "Bake a hierarchy's static meshes into one mesh per material, with their transforms baked in. already made; nothing here decides appearance tree: add them to root and remove the sources yourself, or both draw vertices are not its own to bake texture mapping; a missing normal is recomputed",
2051
+ "supersedes": [],
2052
+ "symbol": "mergeByMaterial"
2053
+ },
1890
2054
  {
1891
2055
  "aliases": [],
1892
2056
  "constraints": [
@@ -2247,7 +2411,7 @@
2247
2411
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2248
2412
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2249
2413
  ],
2250
- "example": "markStatic(island); invalidateStatic(drawbridge);",
2414
+ "example": "invalidateStatic(drawbridge);",
2251
2415
  "importPath": "@threenative/core",
2252
2416
  "kind": "function",
2253
2417
  "overrides": [],
@@ -2366,7 +2530,7 @@
2366
2530
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2367
2531
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2368
2532
  ],
2369
- "example": "markStatic(island); invalidateStatic(drawbridge);",
2533
+ "example": "invalidateStatic(drawbridge);",
2370
2534
  "importPath": "@threenative/core",
2371
2535
  "kind": "function",
2372
2536
  "overrides": [],
@@ -2412,6 +2576,22 @@
2412
2576
  "supersedes": [],
2413
2577
  "symbol": "resolveAtmosphereParameters"
2414
2578
  },
2579
+ {
2580
+ "aliases": [],
2581
+ "constraints": [
2582
+ "pass the measured display rate when you have one; without it the answer is the 60 fallback and says so"
2583
+ ],
2584
+ "example": "resolveTargetFps(config, getPlatform()).targetFps;",
2585
+ "importPath": "@threenative/core",
2586
+ "kind": "function",
2587
+ "overrides": [],
2588
+ "package": "@threenative/core",
2589
+ "signature": "export function resolveTargetFps( config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number, ): ITargetFps { … }",
2590
+ "situations": ["my game does frame-rate-dependent work and must not hardcode 60"],
2591
+ "summary": "Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.",
2592
+ "supersedes": [],
2593
+ "symbol": "resolveTargetFps"
2594
+ },
2415
2595
  {
2416
2596
  "aliases": [],
2417
2597
  "constraints": [
@@ -2510,7 +2690,8 @@
2510
2690
  "situations": [
2511
2691
  "delay an enemy patrol transition",
2512
2692
  "run a callback every simulation tick",
2513
- "tween a numeric property with a game-owned curve"
2693
+ "tween a numeric property with a game-owned curve",
2694
+ "a countdown timer: end the level when its time limit runs out"
2514
2695
  ],
2515
2696
  "summary": "Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.",
2516
2697
  "supersedes": [],
@@ -2602,6 +2783,22 @@
2602
2783
  "supersedes": [],
2603
2784
  "symbol": "skeletonBones"
2604
2785
  },
2786
+ {
2787
+ "aliases": [],
2788
+ "constraints": [
2789
+ "pass the measured display rate when you have one; without it the answer is the 60 fallback and says so"
2790
+ ],
2791
+ "example": "resolveTargetFps(config, getPlatform()).targetFps;",
2792
+ "importPath": "@threenative/core",
2793
+ "kind": "function",
2794
+ "overrides": [],
2795
+ "package": "@threenative/core",
2796
+ "signature": "export function snapRefreshRate(refreshHz: number): number { … }",
2797
+ "situations": ["my game does frame-rate-dependent work and must not hardcode 60"],
2798
+ "summary": "Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.",
2799
+ "supersedes": [],
2800
+ "symbol": "snapRefreshRate"
2801
+ },
2605
2802
  {
2606
2803
  "aliases": [],
2607
2804
  "constraints": [
@@ -2822,7 +3019,7 @@
2822
3019
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2823
3020
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2824
3021
  ],
2825
- "example": "markStatic(island); invalidateStatic(drawbridge);",
3022
+ "example": "invalidateStatic(drawbridge);",
2826
3023
  "importPath": "@threenative/core",
2827
3024
  "kind": "function",
2828
3025
  "overrides": [],
@@ -2850,6 +3047,7 @@
2850
3047
  "signature": "export class TracerPool3D { … }",
2851
3048
  "situations": [
2852
3049
  "show where a hitscan round went",
3050
+ "show each round a weapon fires, one tracer per trigger press",
2853
3051
  "draw incoming fire without spawning projectiles"
2854
3052
  ],
2855
3053
  "summary": "Pool travelling bullet-streak meshes for hitscan shots.",
@@ -2863,7 +3061,7 @@
2863
3061
  "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
2864
3062
  "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
2865
3063
  ],
2866
- "example": "markStatic(island); invalidateStatic(drawbridge);",
3064
+ "example": "invalidateStatic(drawbridge);",
2867
3065
  "importPath": "@threenative/core",
2868
3066
  "kind": "function",
2869
3067
  "overrides": [],
@@ -2999,7 +3197,8 @@
2999
3197
  "constraints": [
3000
3198
  "the light must be a DirectionalLight with `castShadow` and a target in the scene",
3001
3199
  "clipExtents are half-widths in world units, finest first, strictly increasing",
3002
- "call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves"
3200
+ "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",
3201
+ "call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does"
3003
3202
  ],
3004
3203
  "example": "const sun = new DirectionalLight(0xffffff, 3);\nsun.castShadow = true;\nsun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });",
3005
3204
  "importPath": "@threenative/core",
@@ -3409,6 +3608,22 @@
3409
3608
  "supersedes": [],
3410
3609
  "symbol": "subscribeUiState"
3411
3610
  },
3611
+ {
3612
+ "aliases": [],
3613
+ "constraints": [
3614
+ "the returned view aliases the caller's buffer; writing to it mutates the source"
3615
+ ],
3616
+ "example": "const records = cellPlacements(buffer, { asset: \"tree\", offset: 0, count: 120 });",
3617
+ "importPath": "@threenative/core/world",
3618
+ "kind": "function",
3619
+ "overrides": [],
3620
+ "package": "@threenative/core",
3621
+ "signature": "export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }",
3622
+ "situations": ["feed one cell's instance transforms into a batch without copying"],
3623
+ "summary": "Borrow the run's placement records as a live view over the placement buffer.",
3624
+ "supersedes": [],
3625
+ "symbol": "cellPlacements"
3626
+ },
3412
3627
  {
3413
3628
  "aliases": [],
3414
3629
  "constraints": [
@@ -3449,23 +3664,124 @@
3449
3664
  "generate a terrain a player can walk across",
3450
3665
  "query the same ground height or normal that a player sees and collides with",
3451
3666
  "ask how high the ground is here",
3452
- "build islands and coastlines from terrain"
3667
+ "build islands and coastlines from terrain",
3668
+ "keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)"
3453
3669
  ],
3454
3670
  "summary": "One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.",
3455
3671
  "supersedes": [],
3456
3672
  "symbol": "Heightfield"
3457
3673
  },
3674
+ {
3675
+ "aliases": [],
3676
+ "constraints": [
3677
+ "the sampler reads the game's data; the framework never selects a terrain shape"
3678
+ ],
3679
+ "example": "const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));",
3680
+ "importPath": "@threenative/core/world",
3681
+ "kind": "function",
3682
+ "overrides": [],
3683
+ "package": "@threenative/core",
3684
+ "signature": "export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWorldExtent, data: Uint16Array, ): (x: number, z: number) => number { … }",
3685
+ "situations": [
3686
+ "turn an exported raw heightmap into terrain collision and rendering",
3687
+ "query ground height from a Blender-authored world package"
3688
+ ],
3689
+ "summary": "Build a game-usable `sampleHeight` from a raw v1 heightmap. The returned function interpolates bilinearly in world units and clamps to the map edges, so it plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.",
3690
+ "supersedes": [],
3691
+ "symbol": "heightSamplerFromHeightmap"
3692
+ },
3693
+ {
3694
+ "aliases": [],
3695
+ "constraints": [
3696
+ "the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `export_terrain_layers.py` recipe",
3697
+ "WebGPU allows 16 sampled textures per stage: planes + diffuse maps + normal maps must fit"
3698
+ ],
3699
+ "example": "const surface = await loadTerrainSplat({ assets: ctx.assets, url: \"world/world.json\" });\nconst world = await WorldCells.load({ assets: ctx.assets, url: \"world/world.json\", surface, follow, ring: 2 });",
3700
+ "importPath": "@threenative/core/world",
3701
+ "kind": "function",
3702
+ "overrides": [
3703
+ "every value comes from the package's table; the returned material is the game's to adjust"
3704
+ ],
3705
+ "package": "@threenative/core",
3706
+ "signature": "export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }",
3707
+ "situations": [
3708
+ "terrain textured by splat masks exported from Blender with the world package",
3709
+ "the game's terrain should match the DCC's terrain material without a second copy"
3710
+ ],
3711
+ "summary": "The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. 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.",
3712
+ "supersedes": [],
3713
+ "symbol": "loadTerrainSplat"
3714
+ },
3715
+ {
3716
+ "aliases": [],
3717
+ "constraints": ["a non-OK response throws; bytes are byte-swapped only on a big-endian host"],
3718
+ "example": "const data = await loadWorldHeightmap(\"/world/terrain/heightmap.u16\");",
3719
+ "importPath": "@threenative/core/world",
3720
+ "kind": "function",
3721
+ "overrides": [],
3722
+ "package": "@threenative/core",
3723
+ "signature": "export async function loadWorldHeightmap(url: string): Promise<Uint16Array> { … }",
3724
+ "situations": ["load a world package's heightmap once before building terrain"],
3725
+ "summary": "Fetch a raw little-endian uint16 heightmap and expose it as samples.",
3726
+ "supersedes": [],
3727
+ "symbol": "loadWorldHeightmap"
3728
+ },
3729
+ {
3730
+ "aliases": [],
3731
+ "constraints": ["radius is metres; the footprint never grows with load, only deeper"],
3732
+ "example": "const footprint = snowDiscFootprint(0.25);",
3733
+ "importPath": "@threenative/core/world",
3734
+ "kind": "function",
3735
+ "overrides": ["softness widens the eased edge without changing the contact radius"],
3736
+ "package": "@threenative/core",
3737
+ "signature": "export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }",
3738
+ "situations": [
3739
+ "press a ball, wheel or probe into snow",
3740
+ "give a sphere a physically sized snow contact instead of a boot shape"
3741
+ ],
3742
+ "summary": "A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.",
3743
+ "supersedes": [],
3744
+ "symbol": "snowDiscFootprint"
3745
+ },
3746
+ {
3747
+ "aliases": [],
3748
+ "constraints": [
3749
+ "the field composes onto a Heightfield; construct the terrain first and let this own the surface",
3750
+ "zero depth is bare ground: contacts register no indentation at all",
3751
+ "out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros"
3752
+ ],
3753
+ "example": "import { Heightfield } from \"@threenative/core/world\";\nconst terrain = Heightfield.fromSampler({ rows: 129, columns: 129, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: (x, z) => Math.sin(x * 0.1) * 0.5 });\nconst snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });\nsnow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });\nsnow.recover(1 / 60, 0.0012, 0.4);",
3754
+ "importPath": "@threenative/core/world",
3755
+ "kind": "class",
3756
+ "overrides": [
3757
+ "depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients"
3758
+ ],
3759
+ "package": "@threenative/core",
3760
+ "requires": ["@threenative/core/world Heightfield as the canonical terrain and surface"],
3761
+ "signature": "export class SnowField { … }",
3762
+ "situations": [
3763
+ "leave footprints, tracks and tyre ruts in snow that persist and fill in over time",
3764
+ "let a pushed sphere carve a connected track and a dropped one settle into a crater",
3765
+ "store snow deformation that rendered geometry and collision both read",
3766
+ "reset a snowfield between rounds or change its depth at runtime",
3767
+ "show how packed the snow is where people have walked or objects have rested"
3768
+ ],
3769
+ "summary": "Persistent snow deformation over one canonical heightfield. Snow keeps four channels per cell — indentation, displaced bank, compaction and disturbance — and writes the combined surface (`terrain + depth + bank - indent`) back into the heightfield it was given. Queries, rendered geometry and collider export therefore all read one surface, and no second terrain representation exists. The field is numeric only: it never chooses a boot, a tread, a particle, a material or a camera. Games supply terrain heights, the snow depth, the contact profile and the response coefficients; this class owns the storage, the load-dependent penetration and the bounded recovery. It is a heightfield approximation — not granular snow, displaced-volume conservation, avalanches, melting or a calibrated material law.",
3770
+ "supersedes": [],
3771
+ "symbol": "SnowField"
3772
+ },
3458
3773
  {
3459
3774
  "aliases": ["stream terrain across chunks"],
3460
3775
  "constraints": [
3461
3776
  "sampleHeight and surface are required game choices; no landform or surface preset is installed",
3462
- "residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws"
3777
+ "residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws",
3778
+ "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"
3463
3779
  ],
3464
3780
  "example": "const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });",
3465
3781
  "importPath": "@threenative/core/world",
3466
3782
  "kind": "class",
3467
3783
  "overrides": [
3468
- "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets"
3784
+ "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets"
3469
3785
  ],
3470
3786
  "package": "@threenative/core",
3471
3787
  "signature": "export class TerrainTiles extends Object3D implements IComputeDriven { … }",
@@ -3478,9 +3794,177 @@
3478
3794
  "supersedes": [],
3479
3795
  "symbol": "TerrainTiles"
3480
3796
  },
3797
+ {
3798
+ "aliases": [],
3799
+ "constraints": ["off by default: it is the work it checks, every frame"],
3800
+ "example": "// Reads its own the way `renderListValidationRequested` does: a native launch sets the\n// environment variable, a browser asks with the query string, a test or harness sets the\n// global. `0` and `false` are off, so a saved URL that enabled it still says \"off\".\nconst tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });",
3801
+ "importPath": "@threenative/core/world",
3802
+ "kind": "function",
3803
+ "overrides": [],
3804
+ "package": "@threenative/core",
3805
+ "signature": "export function terrainValidationRequested(): boolean { … }",
3806
+ "situations": [
3807
+ "turn terrain's per-frame seam, LOD pop and vertex checks on for one run",
3808
+ "assert the terrain geometry a game streams before it ships"
3809
+ ],
3810
+ "summary": "Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.",
3811
+ "supersedes": [],
3812
+ "symbol": "terrainValidationRequested"
3813
+ },
3814
+ {
3815
+ "aliases": [],
3816
+ "constraints": [
3817
+ "validation only checks structure and ranges; it never fetches the heightmap or GLBs"
3818
+ ],
3819
+ "example": "const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });",
3820
+ "importPath": "@threenative/core/world",
3821
+ "kind": "function",
3822
+ "overrides": [],
3823
+ "package": "@threenative/core",
3824
+ "signature": "export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }",
3825
+ "situations": [
3826
+ "check a Blender-exported world package before the runtime attaches anything",
3827
+ "report why a world package cannot be streamed"
3828
+ ],
3829
+ "summary": "Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.",
3830
+ "supersedes": [],
3831
+ "symbol": "validateWorldPackage"
3832
+ },
3833
+ {
3834
+ "aliases": [],
3835
+ "constraints": [
3836
+ "surface is the game's; this class creates no material, colour or geometry",
3837
+ "budgets are hard caps that report pressure instead of over-committing",
3838
+ "model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell",
3839
+ "refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first",
3840
+ "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",
3841
+ "SkinnedMesh parts are skipped; an instanced copy would draw one rest pose",
3842
+ "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",
3843
+ "`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",
3844
+ "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",
3845
+ "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",
3846
+ "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",
3847
+ "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",
3848
+ "`shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed"
3849
+ ],
3850
+ "example": "const world = await WorldCells.load({ url: \"/world/world.json\", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });\nscene.add(world);\nworld.update();",
3851
+ "importPath": "@threenative/core/world",
3852
+ "kind": "class",
3853
+ "overrides": [
3854
+ "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"
3855
+ ],
3856
+ "package": "@threenative/core",
3857
+ "signature": "export class WorldCells extends Group implements IComputeDriven { … }",
3858
+ "situations": [
3859
+ "stream a large Blender-authored world by cell instead of one huge GLB",
3860
+ "keep scattered props and hand-placed chunks resident around a moving player",
3861
+ "honour per-asset draw distances and hard streaming budgets without a mid-frame throw"
3862
+ ],
3863
+ "summary": "Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, 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.",
3864
+ "supersedes": [],
3865
+ "symbol": "WorldCells"
3866
+ },
3867
+ {
3868
+ "aliases": [],
3869
+ "constraints": [
3870
+ "absolute paths, Windows drive letters, backslashes and any `..` segment throw MetaHumanAssetError with TN_MH_PATH_ESCAPE before the path is joined onto a root"
3871
+ ],
3872
+ "example": "assertAssetPath(\"metahuman/specimen.glb\");",
3873
+ "importPath": "@threenative/metahuman",
3874
+ "kind": "function",
3875
+ "overrides": [],
3876
+ "package": "@threenative/metahuman",
3877
+ "requires": ["npm i @threenative/metahuman"],
3878
+ "signature": "export function assertAssetPath(path: string): string { … }",
3879
+ "situations": ["reject a MetaHuman asset path that would read outside the game's asset root"],
3880
+ "summary": "Keeps a caller-supplied asset path inside the asset directory.",
3881
+ "supersedes": [],
3882
+ "symbol": "assertAssetPath"
3883
+ },
3884
+ {
3885
+ "aliases": [],
3886
+ "constraints": [
3887
+ "the model is loaded through the game's own asset loader and cloned per instance, so",
3888
+ "the rig's own GUI-to-raw mapping runs; the adapter never re-derives it, and a LOD",
3889
+ "an undeclared control, an out-of-domain value, an undeclared LOD and any call after",
3890
+ "in a native host that installed the MetaHuman resident the C++ evaluator runs and"
3891
+ ],
3892
+ "example": "const human = await loadMetaHuman({ assets: ctx.assets, model: \"metahuman/head.glb\",\n dna: \"metahuman/head.dna\", bindings: \"metahuman/bindings.json\" });\n human.setControls({ jawOpen: 0.4 });\n// in the scene update, after any body animation\n human.update();",
3893
+ "importPath": "@threenative/metahuman",
3894
+ "kind": "function",
3895
+ "overrides": [],
3896
+ "package": "@threenative/metahuman",
3897
+ "requires": ["npm i @threenative/metahuman"],
3898
+ "signature": "loadMetaHuman = (options: ILoadMetaHumanOptions): Promise<IMetaHuman> => createMetaHuman( { … }",
3899
+ "situations": [
3900
+ "put a MetaHuman head in a browser game without an Unreal import or a baked clip"
3901
+ ],
3902
+ "summary": "Load a prepared MetaHuman head and drive its expression from the browser's WASM evaluator: declared faceboard controls in, joint deltas and morph weights out, applied to an ordinary Three.js object graph. two characters never write each other's face and nothing is disposed that `ctx.assets` still owns switch re-evaluates the current controls before the replacement mesh is shown `dispose()` throw, each with a stable `code`; nothing is clamped or coerced `diagnostics().backend` reads \"native\"; the game code does not change",
3903
+ "supersedes": [],
3904
+ "symbol": "loadMetaHuman"
3905
+ },
3906
+ {
3907
+ "aliases": [],
3908
+ "constraints": ["`code` is part of the public surface; renaming one is a breaking change"],
3909
+ "example": "if (error instanceof MetaHumanAssetError && error.code === \"TN_MH_HASH_MISMATCH\") refetch();",
3910
+ "importPath": "@threenative/metahuman",
3911
+ "kind": "class",
3912
+ "overrides": [],
3913
+ "package": "@threenative/metahuman",
3914
+ "requires": ["npm i @threenative/metahuman"],
3915
+ "signature": "export class MetaHumanAssetError extends Error { … }",
3916
+ "situations": ["branch on why a MetaHuman asset or evaluator call was refused"],
3917
+ "summary": "The rejection every check in this package raises, carrying a stable machine-readable code.",
3918
+ "supersedes": [],
3919
+ "symbol": "MetaHumanAssetError"
3920
+ },
3921
+ {
3922
+ "aliases": [],
3923
+ "constraints": [
3924
+ "the binary's SHA-256 is checked against the shipped manifest before it is",
3925
+ "every returned array is a copy, so no view survives a memory growth; a disposed",
3926
+ "a native host that installed the MetaHuman resident gets its C++ evaluator from"
3927
+ ],
3928
+ "example": "const rig = await RigEvaluator.create(dna); rig.setGuiControls(gui); rig.evaluate(true); rig.jointOutputs();",
3929
+ "importPath": "@threenative/metahuman",
3930
+ "kind": "class",
3931
+ "overrides": [],
3932
+ "package": "@threenative/metahuman",
3933
+ "requires": ["npm i @threenative/metahuman"],
3934
+ "signature": "export class RigEvaluator implements IRigEvaluator { … }",
3935
+ "situations": [
3936
+ "drive a prepared MetaHuman head's expression from the browser without an Unreal import"
3937
+ ],
3938
+ "summary": "One MetaHuman head rig over the checksum-verified browser WASM build of the shared OpenRigLogic ABI: faceboard GUI controls in, joint deltas, blend shape weights and animated map weights out. instantiated, and nothing is fetched from a CDN evaluator throws instead of reading freed memory `create` and the WASM is never fetched; `RigEvaluator.backend()` says which one runs",
3939
+ "supersedes": [],
3940
+ "symbol": "RigEvaluator"
3941
+ },
3942
+ {
3943
+ "aliases": [],
3944
+ "constraints": [
3945
+ "fails closed: a missing key, a wrong type, a hash that differs from the bytes on",
3946
+ "reads the rig's real names and the GLB's real node, mesh and target counts, so it"
3947
+ ],
3948
+ "example": "const bindings = validateMetaHumanAssets({ bindings: parsed, dnaSha256, glbSha256, rig, gltf });",
3949
+ "importPath": "@threenative/metahuman",
3950
+ "kind": "function",
3951
+ "overrides": [],
3952
+ "package": "@threenative/metahuman",
3953
+ "requires": ["npm i @threenative/metahuman"],
3954
+ "signature": "export function validateMetaHumanAssets(input: IMetaHumanAssetInput): IMetaHumanBindings { … }",
3955
+ "situations": [
3956
+ "refuse a MetaHuman specimen whose bindings point at joints, nodes, blend shape"
3957
+ ],
3958
+ "summary": "Checks one prepared specimen — bindings sidecar, DNA and GLB — against the rig it claims to drive, and returns the bindings only when every name, index, domain and hash holds up. channels, morph targets or LODs the loaded files do not contain disk and an index past the end of its array are rejections, each with a stable code cannot pass a hand-written sidecar the rig cannot drive",
3959
+ "supersedes": [],
3960
+ "symbol": "validateMetaHumanAssets"
3961
+ },
3481
3962
  {
3482
3963
  "aliases": ["pick up item"],
3483
3964
  "constraints": ["add the area to the physics context before stepping the world"],
3965
+ "deprecated": [
3966
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated."
3967
+ ],
3484
3968
  "example": "const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });",
3485
3969
  "importPath": "@threenative/physics",
3486
3970
  "kind": "class",
@@ -3495,6 +3979,51 @@
3495
3979
  "supersedes": [],
3496
3980
  "symbol": "Area3D"
3497
3981
  },
3982
+ {
3983
+ "aliases": [],
3984
+ "constraints": [
3985
+ "register `rapier()` before attaching, and call `step` once per fixed step after the physics step",
3986
+ "the backend must expose persistent solved contacts and in-place shape refresh; one that does not fails at attach",
3987
+ "verified on browser WebGPU and the native Linux desktop host; Android and iOS share the native seam but have not run it",
3988
+ "automatic profiles cover sphere, box and capsule; any other shape needs an explicit footprint"
3989
+ ],
3990
+ "example": "const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });\nafterPhysics(ctx, (dt) => snowPhysics.step(dt));",
3991
+ "importPath": "@threenative/physics",
3992
+ "kind": "function",
3993
+ "overrides": [
3994
+ "loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour"
3995
+ ],
3996
+ "package": "@threenative/physics",
3997
+ "requires": ["@threenative/core/world SnowField as the surface it deforms"],
3998
+ "signature": "export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }",
3999
+ "situations": [
4000
+ "leave footprints and tracks where physical bodies actually touch snow",
4001
+ "let a dropped or pushed sphere carve and settle into deformable snow",
4002
+ "make a crate, capsule or ball compress the surface it rests on"
4003
+ ],
4004
+ "summary": "Drive a `SnowField` from real solved contacts. The binding creates the snow surface collider from the field's own canonical samples and keeps it in step with them, so a body lands on the surface a query would report. Each fixed step it reads the solver's persistent contacts — not collision start/stop events, which carry no point or load — deforms the snow only where a contact is supported and loaded downward, then republishes the surface before the next step. Airborne bodies, side contacts and unrelated colliders never deform anything. A dropped sphere settles on the surface it made; a pushed one rotates and carves a connected track without its transform being copied anywhere. Footprints come from the body's own collision shape and orientation unless the game supplies one. Contact load is `impulse / deltaTime * loadScale`: a solver impulse over a step, which estimates a contact force and is not measured. `observe().loadProvenance` says so.",
4005
+ "supersedes": [],
4006
+ "symbol": "attachSnowPhysics"
4007
+ },
4008
+ {
4009
+ "aliases": [],
4010
+ "constraints": [
4011
+ "halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint"
4012
+ ],
4013
+ "example": "const footprint = boxFootprint(0.4, 0.25);",
4014
+ "importPath": "@threenative/physics",
4015
+ "kind": "function",
4016
+ "overrides": [],
4017
+ "package": "@threenative/physics",
4018
+ "signature": "export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }",
4019
+ "situations": [
4020
+ "let a crate, platform or plank press a rectangular pit into snow",
4021
+ "imprint a box's own footprint rather than a circle around it"
4022
+ ],
4023
+ "summary": "A rectangular contact: the face a box rests on, in the contact's own frame. Coverage is full across the face and fades just outside it; the bank rises beyond that.",
4024
+ "supersedes": [],
4025
+ "symbol": "boxFootprint"
4026
+ },
3498
4027
  {
3499
4028
  "aliases": [],
3500
4029
  "constraints": [
@@ -3529,6 +4058,23 @@
3529
4058
  "supersedes": [],
3530
4059
  "symbol": "Buoyancy3D"
3531
4060
  },
4061
+ {
4062
+ "aliases": [],
4063
+ "constraints": ["radius and halfHeight are metres and never grow with load"],
4064
+ "example": "const footprint = capsuleFootprint(0.5, 0.2);",
4065
+ "importPath": "@threenative/physics",
4066
+ "kind": "function",
4067
+ "overrides": [],
4068
+ "package": "@threenative/physics",
4069
+ "signature": "export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }",
4070
+ "situations": [
4071
+ "let a fallen capsule, limb or barrel leave a linear imprint in snow",
4072
+ "give a capsule a shape-appropriate snow contact instead of a sphere's dot"
4073
+ ],
4074
+ "summary": "A stadium contact: a rectangle of half-length `halfHeight` and half-width `radius`, capped by two half-discs of `radius`. The shape a capsule lies on, so a knocked-over body sinks along a line instead of at a point. Coverage is full across the body's own width and fades just outside it, so the body's edge never rests on a half-pressed rim; the bank rises beyond that.",
4075
+ "supersedes": [],
4076
+ "symbol": "capsuleFootprint"
4077
+ },
3532
4078
  {
3533
4079
  "aliases": [
3534
4080
  "raised platform gap hazard restart",
@@ -3538,6 +4084,9 @@
3538
4084
  "run jump coins goal"
3539
4085
  ],
3540
4086
  "constraints": ["use moveAndSlide inside the physics update"],
4087
+ "deprecated": [
4088
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated."
4089
+ ],
3541
4090
  "example": "const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });",
3542
4091
  "importPath": "@threenative/physics",
3543
4092
  "kind": "class",
@@ -3589,6 +4138,9 @@
3589
4138
  {
3590
4139
  "aliases": [],
3591
4140
  "constraints": ["both bodies must belong to the same physics context"],
4141
+ "deprecated": [
4142
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated."
4143
+ ],
3592
4144
  "example": "const hinge = Joint3D.hinge({ physics: ctx.physics, bodyA: beam, bodyB: bob, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: 0, y: 2.4, z: 0 }, axis: { x: 1, y: 0, z: 0 } });",
3593
4145
  "importPath": "@threenative/physics",
3594
4146
  "kind": "class",
@@ -3641,6 +4193,9 @@
3641
4193
  {
3642
4194
  "aliases": [],
3643
4195
  "constraints": ["register rapier() in the game plugin list before using bodies"],
4196
+ "deprecated": [
4197
+ "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated."
4198
+ ],
3644
4199
  "example": "const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });",
3645
4200
  "importPath": "@threenative/physics",
3646
4201
  "kind": "class",
@@ -3680,6 +4235,34 @@
3680
4235
  "supersedes": [],
3681
4236
  "symbol": "softBodyCollision"
3682
4237
  },
4238
+ {
4239
+ "aliases": [
4240
+ "racing car racing kart drift vehicle go-kart",
4241
+ "suspension wheel traction tyre grip",
4242
+ "accelerator pedal handbrake steering wheel",
4243
+ "rescue respawn flip back on track"
4244
+ ],
4245
+ "constraints": [
4246
+ "write engineForce, brake and steering every physics update; a car with no input does not move",
4247
+ "suspensionStiffness is a frequency squared, not newtons per metre; 100 is a road car and 20 bottoms out"
4248
+ ],
4249
+ "example": "const car = new VehicleBody3D({ object: chassis, physics: ctx.physics, shape: CollisionShape3D.box(1.6, 0.5, 3.6), mass: 900, wheels: [{ position: { x: 0.8, y: -0.15, z: -1.2 }, wheelRadius: 0.34, suspensionRestLength: 0.3, suspensionStiffness: 100, dampingCompression: 2.3, dampingRelaxation: 4.4, wheelFrictionSlip: 10.5, maxSuspensionTravel: 0.3, useAsSteering: true, useAsTraction: false }] });",
4250
+ "importPath": "@threenative/physics",
4251
+ "kind": "class",
4252
+ "overrides": [
4253
+ "a wheel ray never hits the chassis it hangs from, and it honours the chassis collision mask",
4254
+ "continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall"
4255
+ ],
4256
+ "package": "@threenative/physics",
4257
+ "signature": "export class VehicleBody3D extends RigidBody3D { … }",
4258
+ "situations": [
4259
+ "drive a car, truck or bike around a track",
4260
+ "make a vehicle roll over kerbs, brake into a corner or stop at a wall"
4261
+ ],
4262
+ "summary": "Drive a car on ray-cast suspension instead of faking speed and heading.",
4263
+ "supersedes": [],
4264
+ "symbol": "VehicleBody3D"
4265
+ },
3683
4266
  {
3684
4267
  "aliases": ["close engagement range"],
3685
4268
  "constraints": [
@@ -4139,6 +4722,23 @@
4139
4722
  "supersedes": [],
4140
4723
  "symbol": "assertCaptureNotBlank"
4141
4724
  },
4725
+ {
4726
+ "aliases": [],
4727
+ "constraints": ["the assertion throws instead of returning a false pass"],
4728
+ "example": "assertFrameShowsSomething(png, \"first frame\");",
4729
+ "importPath": "@threenative/playtest/capture",
4730
+ "kind": "function",
4731
+ "overrides": [],
4732
+ "package": "@threenative/playtest",
4733
+ "signature": "assertFrameShowsSomething = assertCaptureNotBlank",
4734
+ "situations": [
4735
+ "guard a visual playtest against a blank frame",
4736
+ "prove a screenshot contains more than a loading surface"
4737
+ ],
4738
+ "summary": "Fail closed when a screenshot is blank or uniform.",
4739
+ "supersedes": [],
4740
+ "symbol": "assertFrameShowsSomething"
4741
+ },
4142
4742
  {
4143
4743
  "aliases": [],
4144
4744
  "constraints": [],
@@ -4409,6 +5009,20 @@
4409
5009
  "supersedes": [],
4410
5010
  "symbol": "connectPlaytestBridgeTransport"
4411
5011
  },
5012
+ {
5013
+ "aliases": [],
5014
+ "constraints": ["a private Xvfb is software, so a rate read there measures the X server"],
5015
+ "example": "import { decideDisplayStrategy } from \"@threenative/playtest/runner\";\nconst lane = decideDisplayStrategy({ env: process.env, platform: \"linux\" });\nif (lane.kind === \"private-xvfb\") throw new Error(\"refuse to judge this frame rate\");",
5016
+ "importPath": "@threenative/playtest/runner",
5017
+ "kind": "function",
5018
+ "overrides": [],
5019
+ "package": "@threenative/playtest",
5020
+ "signature": "export function decideDisplayStrategy(input: IDisplayDecisionInput): IDisplayStrategy { … }",
5021
+ "situations": ["judge whether a measured frame rate came from a display that can carry one"],
5022
+ "summary": "Decide which display a pixel-producing run paints on, the same decision the runner makes.",
5023
+ "supersedes": [],
5024
+ "symbol": "decideDisplayStrategy"
5025
+ },
4412
5026
  {
4413
5027
  "aliases": [],
4414
5028
  "constraints": ["the mailbox lifecycle must be disposed after the run"],
@@ -6125,6 +6739,35 @@
6125
6739
  "supersedes": [],
6126
6740
  "symbol": "useUiState"
6127
6741
  },
6742
+ {
6743
+ "symbol": "createStormAudio",
6744
+ "package": "template:rain",
6745
+ "importPath": "src/audio/storm.ts",
6746
+ "kind": "function",
6747
+ "signature": "createStormAudio(ctx: ICtx<GameState>): IStormAudio",
6748
+ "summary": "The storm's sound as generated source, mixed through the engine's own `AudioBus`: a rain hiss, a wind bed, and thunder queued strike by strike and delayed and filtered by how far away it was struck.",
6749
+ "situations": [
6750
+ "rain hiss, wind bed, thunder, a storm you can hear",
6751
+ "delay thunder by the distance it was struck",
6752
+ "sound that follows pause, mute and tab visibility",
6753
+ "audio that queues strikes instead of cutting each other off"
6754
+ ],
6755
+ "example": "src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene",
6756
+ "constraints": [
6757
+ "`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.",
6758
+ "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.",
6759
+ "`update(state)` is the frame's truth and is called once per frame after the simulation advances; `debug()` is what a playtest reads back.",
6760
+ "The caller owns entity registration, updates and disposal; creating the helper does not register it.",
6761
+ "Audio begins only after a user gesture — the bus's unlock error is surfaced rather than swallowed.",
6762
+ "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.",
6763
+ "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.",
6764
+ "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.",
6765
+ "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."
6766
+ ],
6767
+ "overrides": [],
6768
+ "supersedes": [],
6769
+ "aliases": []
6770
+ },
6128
6771
  {
6129
6772
  "symbol": "renderer.matrixWorld",
6130
6773
  "package": "@threenative/core",
@@ -6190,20 +6833,132 @@
6190
6833
  "package": "@threenative/core",
6191
6834
  "importPath": "src/game.ts",
6192
6835
  "kind": "function",
6193
- "signature": "renderer.projection?: boolean",
6194
- "summary": "The engine's scene-render projection — an internal mirror that collapses repeated draws — on by default. Set `renderer.projection: false` to decline it.",
6836
+ "signature": "renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }",
6837
+ "summary": "The engine's scene-render projection — an internal mirror that collapses repeated draws, including animated skinned rigs that share a geometry and material into one palette draw per pass — on by default. Set `renderer.projection: false` to decline it, or `projection: { materialChecks: 'everyFrame' }` to keep it and pay for a per-material check on every frame.",
6195
6838
  "situations": [
6839
+ "a crowd of animated characters draws slowly",
6840
+ "many SkinnedMesh copies of one rig, each its own draw call",
6196
6841
  "the game got slower after the projection engaged",
6197
6842
  "turn off the render projection, batching, or the instanced mirror",
6198
6843
  "draw count fell but frame time did not",
6199
6844
  "a multi-second freeze when the mirror first engages",
6200
- "opt out of an engine render optimizer"
6845
+ "opt out of an engine render optimizer",
6846
+ "thousands of props each with their own material, one colour apart",
6847
+ "a material edit takes a few frames to show up",
6848
+ "check every batched material every frame anyway"
6201
6849
  ],
6202
6850
  "example": "renderer: { projection: false } // in threenative.config.ts",
6203
6851
  "constraints": [
6204
6852
  "Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it.",
6205
6853
  "An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame.",
6206
- "TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines."
6854
+ "TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines.",
6855
+ "`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.",
6856
+ "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.",
6857
+ "Any other `materialChecks` value throws at startup rather than falling back to a default."
6858
+ ],
6859
+ "overrides": [
6860
+ "renderer.projection: false declines the whole mirror and costs nothing to decline",
6861
+ "renderer: { projection: { materialChecks: 'everyFrame' } } proves every batched material every frame instead of the default bounded slice"
6862
+ ],
6863
+ "supersedes": [],
6864
+ "aliases": []
6865
+ },
6866
+ {
6867
+ "symbol": "createStormLightning",
6868
+ "package": "template:rain",
6869
+ "importPath": "src/render/lightning.ts",
6870
+ "kind": "function",
6871
+ "signature": "createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning",
6872
+ "summary": "A branching lightning bolt as generated Rain source: `makeBolt(end, random)` walks a 30-segment channel down from the cloud deck with side branches, and one additive camera-facing ribbon draw (gaussian core inside a wide halo) shows it while the caller's flash envelope is above zero. `strike(position, random)` returns where the bolt entered the sky.",
6873
+ "situations": [
6874
+ "generate branching lightning ribbon geometry",
6875
+ "a lightning strike that lights the scene and the clouds",
6876
+ "a camera-facing ribbon or beam that stays the same pixel width at any distance",
6877
+ "a flash envelope that stutters rather than fades once"
6878
+ ],
6879
+ "example": "src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay",
6880
+ "constraints": [
6881
+ "Pass the game's seeded random so a strike is reproducible; a non-finite position or random value throws rather than drawing NaN geometry.",
6882
+ "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.",
6883
+ "`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.",
6884
+ "It depth-tests against the coast's written depth, so a bolt behind the headland is hidden by it.",
6885
+ "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."
6886
+ ],
6887
+ "overrides": [],
6888
+ "supersedes": [],
6889
+ "aliases": []
6890
+ },
6891
+ {
6892
+ "symbol": "createNoiseVolume",
6893
+ "package": "template:rain",
6894
+ "importPath": "src/render/noise-volume.ts",
6895
+ "kind": "function",
6896
+ "signature": "createNoiseVolume(): INoiseVolume",
6897
+ "summary": "The 64³ RGBA cloud noise volume as generated Rain source: `{ data: Uint8Array, texture: Data3DTexture }`. Its authored seed, octave weights and source-exact generator define the storm's cloud shapes.",
6898
+ "situations": [
6899
+ "generate a 3D noise volume instead of shipping one as an asset",
6900
+ "rebuild the storm's clouds procedurally at startup",
6901
+ "tileable 3D noise that does not crease at the edges",
6902
+ "four octave scales packed into one texture"
6903
+ ],
6904
+ "example": "src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there",
6905
+ "constraints": [
6906
+ "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.",
6907
+ "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.",
6908
+ "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.",
6909
+ "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.",
6910
+ "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."
6911
+ ],
6912
+ "overrides": [],
6913
+ "supersedes": [],
6914
+ "aliases": []
6915
+ },
6916
+ {
6917
+ "symbol": "createStormRain",
6918
+ "package": "template:rain",
6919
+ "importPath": "src/render/rain.ts",
6920
+ "kind": "function",
6921
+ "signature": "createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain",
6922
+ "summary": "Camera-anchored falling rain as generated Rain source: one instanced draw whose vertex stage hashes each drop from its index, wraps it in a 66 × 30 × 66 m cell that follows the camera in 12 m steps, and projects a quad stretched along its own fall — no particle simulation, no texture.",
6923
+ "situations": [
6924
+ "rain streaks around the camera",
6925
+ "thousands of falling drops in one draw",
6926
+ "rain that leans with the wind and lights up in a lightning flash"
6927
+ ],
6928
+ "example": "src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget",
6929
+ "constraints": [
6930
+ "The drawn count is `round(rainBudget × weather.rain)` for the tier, read back from `geometry.instanceCount` (`instanceCount`), not from the budget.",
6931
+ "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.",
6932
+ "Register it with `alwaysRender`: the vertex stage places every drop, so the geometry's own bounds do not.",
6933
+ "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."
6934
+ ],
6935
+ "overrides": [],
6936
+ "supersedes": [],
6937
+ "aliases": []
6938
+ },
6939
+ {
6940
+ "symbol": "createWeatherWorld",
6941
+ "package": "template:rain",
6942
+ "importPath": "src/render/world.ts",
6943
+ "kind": "function",
6944
+ "signature": "createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld",
6945
+ "summary": "The raymarched coastal storm as generated source: one screen quad whose TSL shader draws the sky, the sea, the coast, the road, the forest and the lamps, and whose wet ground reflects them, written from the uniforms the game feeds it each frame. The sky it samples is the live cloud pass this call builds, not a stand-in gradient. Returns `{ quad, update(options), dispose() }`.",
6946
+ "situations": [
6947
+ "a procedural storm, sea, coastline or open horizon drawn from maths rather than geometry",
6948
+ "rain and wind that change how a scene looks without swapping a mesh",
6949
+ "a lightning flash that lights the coast and the sky at once",
6950
+ "wet reflections on a ground plane",
6951
+ "sky that darkens as cloud cover rises"
6952
+ ],
6953
+ "example": "src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts",
6954
+ "constraints": [
6955
+ "`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`.",
6956
+ "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.",
6957
+ "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.",
6958
+ "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.",
6959
+ "The quad has `frustumCulled = false`, because its two-metre bounds would otherwise be culled the moment the camera looks along the coast.",
6960
+ "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`.",
6961
+ "This entry describes the Rain starter scaffold's own generated `src/render/world.ts`, not a `@threenative/` or three export — there is no installed package to import it from. Appearance lives in that source with no package import at all; nothing in packages/ decides how this storm looks."
6207
6962
  ],
6208
6963
  "overrides": [],
6209
6964
  "supersedes": [],
@@ -6520,7 +7275,7 @@
6520
7275
  ],
6521
7276
  "notOwned": [
6522
7277
  {
6523
- "guidance": "The framework owns no save/load system. Write a save module in your project's src/ using your own plain state shape (for example, ctx.state), and read agent-docs/gameplay-recipes.md for the template recipe.",
7278
+ "guidance": "The framework owns no save/load system. Write a save module in your project's src/ using your own plain state shape (for example, ctx.state), and read node_modules/create-threenative/agent-docs/references/gameplay-recipes.md for the template recipe.",
6524
7279
  "id": "save-load",
6525
7280
  "situations": [
6526
7281
  "persist a player's progress between sessions",
@@ -6529,12 +7284,12 @@
6529
7284
  ]
6530
7285
  },
6531
7286
  {
6532
- "guidance": "The framework owns no inventory system. Write inventory state in your project's src/ with plain objects under ctx.state, and read agent-docs/gameplay-recipes.md for the template recipe.",
7287
+ "guidance": "The framework owns no inventory system. Write inventory state in your project's src/ with plain objects under ctx.state, and read node_modules/create-threenative/agent-docs/references/gameplay-recipes.md for the template recipe.",
6533
7288
  "id": "inventory",
6534
7289
  "situations": ["inventory system", "manage inventory contents"]
6535
7290
  },
6536
7291
  {
6537
- "guidance": "The framework owns no dialogue system. Write the conversation data and state in your project's src/; render it with the template UI (starter uses src/ui/), and read agent-docs/gameplay-recipes.md.",
7292
+ "guidance": "The framework owns no dialogue system. Write the conversation data and state in your project's src/; render it with the template UI (starter uses src/ui/), and read node_modules/create-threenative/agent-docs/references/gameplay-recipes.md.",
6538
7293
  "id": "dialogue",
6539
7294
  "situations": ["NPC dialogue system", "write conversation choices for an NPC"]
6540
7295
  },
@@ -6542,6 +7297,28 @@
6542
7297
  "guidance": "The framework owns the optional authenticated transport seam at @threenative/core/net. Import connect with an HTTPS endpoint and a game-issued credential; it validates channels, message sizes, and bounded queues, but reliable overflow returns false and native qualification depends on the installed bridge (iOS remains unverified). Write authoritative replication, snapshots, prediction, interpolation, and rejoin policy in your project's src/ and server code.",
6543
7298
  "id": "networked-multiplayer",
6544
7299
  "situations": ["authoritative replication", "client prediction"]
7300
+ },
7301
+ {
7302
+ "guidance": "The framework owns no vegetation system. Copy the MIT source in examples/integrations/vegetation/src/ (https://github.com/ThreeNativeHQ/threenative/tree/develop/examples/integrations/vegetation) into your src/ and follow its README: generate seeded, vertex-budgeted EZ Tree variants offline (tree.ts, from the pinned ez-tree source, not the npm 1.1.0 bundle), write them with treeToGlb into assets/, cook them with assets.models.passes.prune: false (prune strips the uv and _WIND weight your materials read), load with ctx.assets.model and re-material by glTF material name. render/wind.ts is editable TSL wind in world metres; call expandBounds(geometry, minWorldScale) per variant geometry. assets.lod bakes bark levels and keeps alpha-masked leaves at LOD0. Worked sample: the grove game in github.com/ThreeNativeHQ/examples.",
7303
+ "id": "procedural-vegetation",
7304
+ "situations": [
7305
+ "procedural trees",
7306
+ "swaying trees",
7307
+ "tree foliage wind sway",
7308
+ "generate a forest of trees"
7309
+ ]
7310
+ },
7311
+ {
7312
+ "guidance": "The framework owns no IK system. Copy the MIT source in examples/integrations/ik/src/ (https://github.com/ThreeNativeHQ/threenative/tree/develop/examples/integrations/ik) into your src/ and follow its README: it needs the closed-chain-ik/core dependency its own package.json pins, three keeps the only rendered pose, and new ConstrainedIK({root, joints: [{bone, axes, min, max}], effectors: [{bone, orientation?}], iterations, positionTolerance, rotationTolerance}) admits direct Bone hierarchies under rigid or positive-uniform-scale parents (shear, reflection, non-uniform or singular scale throws before the pose is touched). Call ik.update(targets) once per frame after AnimationPlayer/mixer and before render, with one world-space metre position per effector in order plus an optional quaternion only where the effector declared orientation: true; it never starts a loop, never moves the root and installs no bone translation or root-motion controller. Joint limits are X/Y/Z offsets relative to the animation pose supplied that call, so reapply the animation pose before solving to avoid accumulation, and the solver only rotates: bone lengths hold to under 1e-15 m. Iterations are 1-128; an unreachable goal returns converged false with finite residuals and never throws, a solver failure restores the original pose, and dispose() at scene teardown. Worked demo: the rifle grip game in examples/constrained-ik/, which plays on web, desktop native and Android.",
7313
+ "id": "constrained-ik",
7314
+ "situations": [
7315
+ "two-handed grip on a prop",
7316
+ "grip shared by two hands",
7317
+ "rifle grip follows sway",
7318
+ "inverse kinematics for a hand on a target",
7319
+ "hand IK pose correction",
7320
+ "elbow limits during an aiming pose"
7321
+ ]
6545
7322
  }
6546
7323
  ],
6547
7324
  "version": 2