create-threenative 0.2.17 → 0.2.20

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 (387) hide show
  1. package/agent-docs/kit-mcp.md +1 -1
  2. package/agent-docs/kit-router.md +1 -1
  3. package/agent-docs/references/assertion-reference.md +54 -110
  4. package/agent-docs/references/capability-reference.md +790 -24
  5. package/agent-docs/references/conventions.md +28 -0
  6. package/agent-docs/references/kit-racing.md +4 -2
  7. package/agent-docs/references/performance-basics.md +10 -5
  8. package/agent-docs/references/terrain-authoring.md +21 -7
  9. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  10. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  11. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +7 -4
  12. package/agent-files/.claude/hooks/discovery-gate.mjs +2 -2
  13. package/dist/index.d.ts +97 -6
  14. package/dist/index.js +1040 -529
  15. package/dist/quality.d.ts +5 -1
  16. package/dist/quality.js +75 -6
  17. package/dist/terrain-kit.js +1 -1
  18. package/dist/threenative.js +98 -17
  19. package/dist/web-engine-ccd-ik-solver.js +127 -0
  20. package/dist/web-engine-gltf-loader.js +52 -14
  21. package/dist/web-engine-post-effects.js +11 -10
  22. package/dist/web-engine-runtime.js +3638 -361
  23. package/package.json +8 -7
  24. package/template-assets/assets/floor-fern-0.glb +0 -0
  25. package/template-assets/assets/floor-litter-0.glb +0 -0
  26. package/template-assets/assets/floor-log-0.glb +0 -0
  27. package/template-assets/assets/floor-log-1.glb +0 -0
  28. package/template-assets/assets/floor-stump-0.glb +0 -0
  29. package/template-assets/assets/floor-twig-0.glb +0 -0
  30. package/template-assets/clearwater/README.md +1 -1
  31. package/template-assets/patches/manifest.json +18 -0
  32. package/template-assets/quality/eslint.config.js +1 -1
  33. package/templates/action-rpg/AGENTS.md +8 -4
  34. package/templates/action-rpg/CLAUDE.md +8 -4
  35. package/templates/action-rpg/package.json +7 -7
  36. package/templates/action-rpg/src/game.ts +1 -1
  37. package/templates/action-rpg/src/loot/drops.ts +3 -7
  38. package/templates/action-rpg/src/render/atmosphere.ts +6 -0
  39. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  40. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  41. package/templates/action-rpg/src/render/camera.ts +2 -2
  42. package/templates/action-rpg/src/render/clouds.ts +16 -1
  43. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  44. package/templates/action-rpg/src/render/materials.ts +3 -2
  45. package/templates/action-rpg/src/render/quality.ts +7 -32
  46. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  47. package/templates/action-rpg/src/scenes/Play.ts +5 -16
  48. package/templates/action-rpg/src/style.css +4 -0
  49. package/templates/action-rpg/vite.config.ts +2 -0
  50. package/templates/adventure/AGENTS.md +10 -5
  51. package/templates/adventure/CLAUDE.md +10 -5
  52. package/templates/adventure/kit.json +5 -1
  53. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  54. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  55. package/templates/adventure/package.json +7 -7
  56. package/templates/adventure/playtests/grass.playtest.json +61 -0
  57. package/templates/adventure/playtests/performance.playtest.json +1 -1
  58. package/templates/adventure/playtests/survives.playtest.json +2 -2
  59. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  60. package/templates/adventure/src/entities/LockOn.ts +42 -4
  61. package/templates/adventure/src/entities/Warden.ts +4 -1
  62. package/templates/adventure/src/game.ts +1 -1
  63. package/templates/adventure/src/level/Vale.ts +241 -16
  64. package/templates/adventure/src/render/camera.ts +2 -2
  65. package/templates/adventure/src/render/foliage.ts +64 -20
  66. package/templates/adventure/src/render/grass.ts +325 -0
  67. package/templates/adventure/src/render/materials.ts +3 -2
  68. package/templates/adventure/src/render/palette.ts +3 -0
  69. package/templates/adventure/src/render/touch-controls.ts +4 -1
  70. package/templates/adventure/src/scenes/Play.ts +96 -1
  71. package/templates/adventure/src/style.css +4 -0
  72. package/templates/adventure/tsconfig.json +1 -1
  73. package/templates/adventure/vite.config.ts +2 -0
  74. package/templates/collectathon/AGENTS.md +7 -2
  75. package/templates/collectathon/CLAUDE.md +7 -2
  76. package/templates/collectathon/package.json +7 -7
  77. package/templates/collectathon/src/game.ts +1 -1
  78. package/templates/collectathon/src/level/Course.ts +55 -14
  79. package/templates/collectathon/src/level/terrain.ts +29 -7
  80. package/templates/collectathon/src/main.ts +1 -0
  81. package/templates/collectathon/src/render/camera.ts +2 -2
  82. package/templates/collectathon/src/render/foliage.ts +359 -98
  83. package/templates/collectathon/src/render/ground.ts +4 -4
  84. package/templates/collectathon/src/render/hero.ts +1 -1
  85. package/templates/collectathon/src/render/materials.ts +0 -1
  86. package/templates/collectathon/src/render/sky.ts +80 -15
  87. package/templates/collectathon/src/render/water.ts +32 -10
  88. package/templates/collectathon/src/scenes/Play.ts +18 -5
  89. package/templates/collectathon/src/style.css +4 -0
  90. package/templates/collectathon/tsconfig.json +1 -1
  91. package/templates/collectathon/vite.config.ts +2 -0
  92. package/templates/kart/AGENTS.md +7 -2
  93. package/templates/kart/CLAUDE.md +7 -2
  94. package/templates/kart/package.json +6 -6
  95. package/templates/kart/src/entities/Kart.ts +2 -1
  96. package/templates/kart/src/game.ts +1 -1
  97. package/templates/kart/src/main.ts +1 -0
  98. package/templates/kart/src/render/course.ts +2 -1
  99. package/templates/kart/src/style.css +4 -0
  100. package/templates/kart/src/track/Course.ts +3 -1
  101. package/templates/kart/tsconfig.json +1 -1
  102. package/templates/kart/vite.config.ts +2 -0
  103. package/templates/minimal/AGENTS.md +8 -3
  104. package/templates/minimal/CLAUDE.md +8 -3
  105. package/templates/minimal/package.json +6 -6
  106. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  107. package/templates/minimal/src/game.ts +1 -1
  108. package/templates/minimal/src/render/atmosphere.ts +6 -0
  109. package/templates/minimal/src/render/backlightControls.ts +10 -0
  110. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  111. package/templates/minimal/src/render/camera.ts +14 -3
  112. package/templates/minimal/src/render/clouds.ts +16 -1
  113. package/templates/minimal/src/render/lighting.ts +4 -2
  114. package/templates/minimal/src/render/materialLighting.ts +5 -5
  115. package/templates/minimal/src/render/materials.ts +13 -2
  116. package/templates/minimal/src/render/quality.ts +7 -32
  117. package/templates/minimal/src/render/touch-controls.ts +7 -6
  118. package/templates/minimal/src/scenes/Play.ts +4 -1
  119. package/templates/minimal/vite.config.ts +7 -1
  120. package/templates/platformer/AGENTS.md +9 -4
  121. package/templates/platformer/CLAUDE.md +9 -4
  122. package/templates/platformer/index.html +1 -1
  123. package/templates/platformer/main.html +12 -0
  124. package/templates/platformer/package.json +7 -7
  125. package/templates/platformer/playtests/collect.playtest.json +4 -1
  126. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  127. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  128. package/templates/platformer/src/entities/Fox.ts +21 -6
  129. package/templates/platformer/src/game.ts +1 -1
  130. package/templates/platformer/src/level/Stage.ts +2 -6
  131. package/templates/platformer/src/main.ts +1 -0
  132. package/templates/platformer/src/render/backlightControls.ts +10 -0
  133. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  134. package/templates/platformer/src/render/materialLighting.ts +5 -5
  135. package/templates/platformer/src/render/quality.ts +7 -32
  136. package/templates/platformer/src/scenes/Play.ts +4 -2
  137. package/templates/platformer/src/style.css +4 -0
  138. package/templates/platformer/src/worker-page.ts +29 -0
  139. package/templates/platformer/src/worker.ts +5 -0
  140. package/templates/platformer/tsconfig.json +1 -1
  141. package/templates/platformer/vite.config.ts +4 -0
  142. package/templates/puzzle/AGENTS.md +7 -2
  143. package/templates/puzzle/CLAUDE.md +7 -2
  144. package/templates/puzzle/package.json +7 -7
  145. package/templates/puzzle/src/entities/Warden.ts +3 -3
  146. package/templates/puzzle/src/game.ts +1 -1
  147. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  148. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  149. package/templates/puzzle/src/render/camera.ts +2 -2
  150. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  151. package/templates/puzzle/src/render/quality.ts +7 -32
  152. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  153. package/templates/puzzle/src/scenes/Play.ts +1 -1
  154. package/templates/puzzle/src/style.css +4 -0
  155. package/templates/puzzle/tsconfig.json +1 -1
  156. package/templates/puzzle/vite.config.ts +2 -0
  157. package/templates/racing/AGENTS.md +9 -4
  158. package/templates/racing/CLAUDE.md +9 -4
  159. package/templates/racing/CREDITS.md +29 -0
  160. package/templates/racing/assets/engine-loop.wav +0 -0
  161. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  162. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  163. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  164. package/templates/racing/assets/nitro-burst.wav +0 -0
  165. package/templates/racing/assets/tyre-squeal.wav +0 -0
  166. package/templates/racing/package.json +7 -7
  167. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  168. package/templates/racing/playtests/drift.playtest.json +100 -0
  169. package/templates/racing/playtests/hud.playtest.json +117 -0
  170. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  171. package/templates/racing/playtests/nitro.playtest.json +158 -0
  172. package/templates/racing/playtests/outcome.playtest.json +4 -4
  173. package/templates/racing/playtests/performance.playtest.json +1 -1
  174. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  175. package/templates/racing/src/audio/engine.ts +138 -0
  176. package/templates/racing/src/entities/CarBody.ts +83 -10
  177. package/templates/racing/src/entities/Drift.ts +243 -0
  178. package/templates/racing/src/entities/LineDriver.ts +2 -2
  179. package/templates/racing/src/entities/Nitro.ts +72 -0
  180. package/templates/racing/src/entities/RacingCar.ts +86 -21
  181. package/templates/racing/src/entities/Rival.ts +35 -21
  182. package/templates/racing/src/game.ts +7 -1
  183. package/templates/racing/src/gauges.ts +74 -0
  184. package/templates/racing/src/render/atmosphere.ts +6 -0
  185. package/templates/racing/src/render/backlightControls.ts +10 -0
  186. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  187. package/templates/racing/src/render/camera.ts +29 -4
  188. package/templates/racing/src/render/clouds.ts +16 -1
  189. package/templates/racing/src/render/effects.ts +244 -0
  190. package/templates/racing/src/render/materialLighting.ts +5 -5
  191. package/templates/racing/src/render/materials.ts +43 -8
  192. package/templates/racing/src/render/quality.ts +7 -32
  193. package/templates/racing/src/render/shapes.ts +37 -0
  194. package/templates/racing/src/render/skids.ts +84 -0
  195. package/templates/racing/src/render/touch-controls.ts +10 -10
  196. package/templates/racing/src/scenes/Race.ts +281 -26
  197. package/templates/racing/src/state.ts +35 -0
  198. package/templates/racing/src/style.css +7 -0
  199. package/templates/racing/src/track/Track.ts +132 -58
  200. package/templates/racing/src/track/TrackSector.ts +19 -1
  201. package/templates/racing/src/track/circuit.ts +21 -15
  202. package/templates/racing/src/ui/GameUi.tsx +0 -2
  203. package/templates/racing/src/ui/Hud.tsx +417 -50
  204. package/templates/racing/threenative.config.ts +15 -0
  205. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  206. package/templates/racing/tsconfig.json +1 -1
  207. package/templates/racing/vite.config.ts +2 -0
  208. package/templates/rain/AGENTS.md +6 -2
  209. package/templates/rain/CLAUDE.md +6 -2
  210. package/templates/rain/package.json +6 -6
  211. package/templates/rain/src/game.ts +1 -1
  212. package/templates/rain/src/render/noise-volume.ts +2 -1
  213. package/templates/rain/src/state.ts +3 -1
  214. package/templates/rain/src/ui/GameUi.tsx +1 -1
  215. package/templates/rain/src/ui/automation.ts +10 -8
  216. package/templates/rain/src/ui/tempest.ts +3 -4
  217. package/templates/rain/vite.config.ts +6 -0
  218. package/templates/rts/AGENTS.md +6 -2
  219. package/templates/rts/CLAUDE.md +6 -2
  220. package/templates/rts/package.json +6 -6
  221. package/templates/rts/src/game.ts +1 -1
  222. package/templates/rts/src/render/backlightControls.ts +10 -0
  223. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  224. package/templates/rts/src/render/materialLighting.ts +5 -5
  225. package/templates/rts/src/render/quality.ts +7 -31
  226. package/templates/rts/src/scenes/Play.ts +1 -1
  227. package/templates/rts/src/sim/terrain.ts +1 -0
  228. package/templates/rts/src/sim/types.ts +1 -0
  229. package/templates/rts/src/style.css +4 -0
  230. package/templates/rts/vite.config.ts +2 -0
  231. package/templates/runner/AGENTS.md +7 -2
  232. package/templates/runner/CLAUDE.md +7 -2
  233. package/templates/runner/package.json +7 -7
  234. package/templates/runner/src/game.ts +1 -1
  235. package/templates/runner/src/render/atmosphere.ts +6 -0
  236. package/templates/runner/src/render/backlightControls.ts +10 -0
  237. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  238. package/templates/runner/src/render/clouds.ts +16 -1
  239. package/templates/runner/src/render/materialLighting.ts +5 -5
  240. package/templates/runner/src/render/materials.ts +3 -2
  241. package/templates/runner/src/render/quality.ts +7 -32
  242. package/templates/runner/src/render/touch-controls.ts +7 -6
  243. package/templates/runner/src/scenes/Run.ts +8 -10
  244. package/templates/runner/src/style.css +4 -0
  245. package/templates/runner/tsconfig.json +1 -1
  246. package/templates/runner/vite.config.ts +2 -0
  247. package/templates/sailing/AGENTS.md +7 -2
  248. package/templates/sailing/CLAUDE.md +7 -2
  249. package/templates/sailing/package.json +7 -7
  250. package/templates/sailing/src/game.ts +1 -1
  251. package/templates/sailing/src/render/backlightControls.ts +10 -0
  252. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  253. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  254. package/templates/sailing/src/render/materialLighting.ts +5 -5
  255. package/templates/sailing/src/render/quality.ts +7 -32
  256. package/templates/sailing/src/render/touch-controls.ts +7 -6
  257. package/templates/sailing/src/style.css +5 -0
  258. package/templates/sailing/vite.config.ts +6 -0
  259. package/templates/shooter/AGENTS.md +6 -2
  260. package/templates/shooter/CLAUDE.md +6 -2
  261. package/templates/shooter/package.json +7 -7
  262. package/templates/shooter/src/game.ts +3 -2
  263. package/templates/shooter/src/render/atmosphere.ts +6 -0
  264. package/templates/shooter/src/render/backlightControls.ts +10 -0
  265. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  266. package/templates/shooter/src/render/clouds.ts +16 -1
  267. package/templates/shooter/src/render/materialLighting.ts +5 -5
  268. package/templates/shooter/src/render/quality.ts +7 -32
  269. package/templates/shooter/src/scenes/Play.ts +4 -1
  270. package/templates/shooter/src/style.css +4 -0
  271. package/templates/shooter/vite.config.ts +2 -0
  272. package/templates/snow/AGENTS.md +7 -2
  273. package/templates/snow/CLAUDE.md +7 -2
  274. package/templates/snow/package.json +7 -7
  275. package/templates/snow/src/entities/Explorer.ts +6 -12
  276. package/templates/snow/src/game.ts +1 -1
  277. package/templates/snow/src/render/backlightControls.ts +10 -0
  278. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  279. package/templates/snow/src/render/bootPrint.ts +3 -1
  280. package/templates/snow/src/render/camera.ts +3 -2
  281. package/templates/snow/src/render/materialLighting.ts +5 -5
  282. package/templates/snow/src/render/quality.ts +7 -32
  283. package/templates/snow/src/render/scenery.ts +3 -3
  284. package/templates/snow/src/render/touch-controls.ts +7 -6
  285. package/templates/snow/src/render/weather.ts +3 -5
  286. package/templates/snow/src/style.css +5 -0
  287. package/templates/snow/src/terrain.ts +2 -1
  288. package/templates/snow/vite.config.ts +6 -0
  289. package/templates/starter/AGENTS.md +8 -3
  290. package/templates/starter/CLAUDE.md +8 -3
  291. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  292. package/templates/starter/package.json +7 -7
  293. package/templates/starter/src/entities/Crate.ts +5 -2
  294. package/templates/starter/src/entities/Player.ts +10 -2
  295. package/templates/starter/src/game.ts +4 -3
  296. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  297. package/templates/starter/src/render/atmosphere.ts +6 -0
  298. package/templates/starter/src/render/backlightControls.ts +10 -0
  299. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  300. package/templates/starter/src/render/camera.ts +2 -2
  301. package/templates/starter/src/render/clouds.ts +16 -1
  302. package/templates/starter/src/render/contactShadow.ts +1 -1
  303. package/templates/starter/src/render/materialLighting.ts +5 -5
  304. package/templates/starter/src/render/materials.ts +3 -2
  305. package/templates/starter/src/render/postprocessing.ts +11 -10
  306. package/templates/starter/src/render/quality.ts +14 -1
  307. package/templates/starter/src/render/touch-controls.ts +7 -6
  308. package/templates/starter/src/scenes/Play.ts +13 -17
  309. package/templates/starter/src/state.ts +2 -0
  310. package/templates/starter/src/style.css +4 -0
  311. package/templates/starter/src/ui/Menu.tsx +5 -1
  312. package/templates/starter/vite.config.ts +2 -0
  313. package/templates/tower-defense/AGENTS.md +7 -2
  314. package/templates/tower-defense/CLAUDE.md +7 -2
  315. package/templates/tower-defense/package.json +7 -7
  316. package/templates/tower-defense/src/game.ts +1 -1
  317. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  318. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  319. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  320. package/templates/tower-defense/src/render/quality.ts +7 -32
  321. package/templates/tower-defense/src/render/shapes.ts +1 -2
  322. package/templates/tower-defense/src/scenes/Battle.ts +4 -9
  323. package/templates/tower-defense/src/style.css +4 -0
  324. package/templates/tower-defense/tsconfig.json +1 -1
  325. package/templates/tower-defense/vite.config.ts +2 -0
  326. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  327. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  328. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  329. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  330. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  331. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  332. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  333. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  334. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  335. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  336. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  337. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  338. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  339. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  340. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  341. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  342. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  343. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  344. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  345. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  346. package/templates/racing/src/render/environmentContribution.ts +0 -188
  347. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  348. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  349. package/templates/racing/src/render/environmentSampling.ts +0 -193
  350. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  351. package/templates/racing/src/ui/Menu.tsx +0 -7
  352. package/templates/rts/src/render/environmentContribution.ts +0 -188
  353. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  354. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  355. package/templates/rts/src/render/environmentSampling.ts +0 -193
  356. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  357. package/templates/runner/src/render/environmentContribution.ts +0 -188
  358. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  359. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  360. package/templates/runner/src/render/environmentSampling.ts +0 -193
  361. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  362. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  363. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  364. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  365. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  366. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  367. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  368. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  369. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  370. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  371. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  372. package/templates/snow/src/render/environmentContribution.ts +0 -188
  373. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  374. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  375. package/templates/snow/src/render/environmentSampling.ts +0 -193
  376. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  377. package/templates/starter/src/render/environmentContribution.ts +0 -188
  378. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  379. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  380. package/templates/starter/src/render/environmentSampling.ts +0 -193
  381. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  382. package/templates/starter/src/render/rendererGate.ts +0 -36
  383. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  384. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  385. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  386. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  387. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -0,0 +1,388 @@
1
+ // Bakes the racing kit's three clips into `assets/`, and proves them before it writes.
2
+ //
3
+ // node tools/make-racing-audio.mjs # write assets/*.wav and self-check them
4
+ // node tools/make-racing-audio.mjs --check # measure the committed clips, write nothing
5
+ //
6
+ // Why synthesised rather than recorded: an engine loop is pitched from 0.62× to 2.05× on the fly
7
+ // (`src/audio/engine.ts`), so it has to be a *tonal* loop with an exactly periodic seam — the one
8
+ // thing a recording of a real engine is not. The asset sources this kit can reach carry no engine,
9
+ // tyre or boost recording (the catalogue's curated packs are UI and jingles; the professional
10
+ // bundles are multi-gigabyte archives), so the sound is authored here, from maths, the way the snow
11
+ // and rain kits author theirs. Nothing is sampled from anyone, so `CREDITS.md` credits the tool.
12
+ //
13
+ // The bake is deterministic: one seeded generator, no clock, no environment, no arguments. It
14
+ // re-runs itself and compares hashes before it writes, so "two runs are byte-identical" is a
15
+ // measured fact rather than a hope.
16
+ //
17
+ // **The loops are exactly periodic, by construction rather than by cross-fade.** Every frequency in
18
+ // the engine bed is a whole number of cycles per second over a one-second loop, so sample 0 and
19
+ // sample N are the same point of the same waveform; the tyre squeal is band-limited noise run
20
+ // through its own filter over the *periodic* extension of the noise, so the filter's steady state
21
+ // is what lands in the file. The seam gate in `@threenative/assets`' audio pass then has something
22
+ // true to measure, instead of a hole papered over with a cross-fade.
23
+
24
+ import { createHash } from "node:crypto";
25
+ import { readFileSync, writeFileSync } from "node:fs";
26
+ import path from "node:path";
27
+ import { fileURLToPath } from "node:url";
28
+
29
+ const SAMPLE_RATE = 44100;
30
+ const CHANNELS = 1;
31
+ const BITS = 32;
32
+ const BYTES_PER_SAMPLE = BITS / 8;
33
+ const BLOCK_ALIGN = CHANNELS * BYTES_PER_SAMPLE;
34
+ const WAVE_FORMAT_IEEE_FLOAT = 3;
35
+
36
+ /** The seed every draw comes from. Changing it changes the files; it is not a tuning knob. */
37
+ const SEED = 0x5eed_c0de;
38
+
39
+ const CLIPS = {
40
+ // Frames are whole samples, not seconds: 0.7 s is 30 869.999… samples in a double, and a clip
41
+ // that is one frame short is a clip whose loop point is a frame off.
42
+ engine: { file: "engine-loop.wav", frames: SAMPLE_RATE },
43
+ squeal: { file: "tyre-squeal.wav", frames: SAMPLE_RATE * 1.5 },
44
+ nitro: { file: "nitro-burst.wav", frames: (SAMPLE_RATE * 7) / 10 },
45
+ };
46
+
47
+ const here = path.dirname(fileURLToPath(import.meta.url));
48
+ const assetsDir = path.resolve(here, "..", "assets");
49
+
50
+ // --- dsp ------------------------------------------------------------------------------------
51
+
52
+ /** The one generator. `mulberry32` so a run is a repeatable draw, not a nicer random. */
53
+ function mulberry32(seed) {
54
+ let a = seed >>> 0;
55
+ return () => {
56
+ a = (a + 0x6d2b79f5) >>> 0;
57
+ let t = a;
58
+ t = Math.imul(t ^ (t >>> 15), t | 1);
59
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
60
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
61
+ };
62
+ }
63
+
64
+ /** RBJ cookbook biquad coefficients, as `@threenative/assets`' own audio pass computes them. */
65
+ function biquad(kind, hz, q = Math.SQRT1_2) {
66
+ const w0 = (2 * Math.PI * hz) / SAMPLE_RATE;
67
+ const alpha = Math.sin(w0) / (2 * q);
68
+ const cos = Math.cos(w0);
69
+ const a0 = 1 + alpha;
70
+ const norm = (value) => value / a0;
71
+ const shared = { b1: norm(kind === "highpass" ? -2 * cos : 2 * cos), a1: norm(-2 * cos) };
72
+ if (kind === "lowpass")
73
+ return {
74
+ b0: norm((1 - cos) / 2),
75
+ b1: shared.b1,
76
+ b2: norm((1 - cos) / 2),
77
+ a1: shared.a1,
78
+ a2: norm(1 - alpha),
79
+ };
80
+ return {
81
+ b0: norm((1 + cos) / 2),
82
+ b1: shared.b1,
83
+ b2: norm((1 + cos) / 2),
84
+ a1: shared.a1,
85
+ a2: norm(1 - alpha),
86
+ };
87
+ }
88
+
89
+ /**
90
+ * A biquad over a **periodic** signal: `samples` is one period, and the filter is started
91
+ * `preroll` samples before its first sample on the signal's own wrap-around tail.
92
+ *
93
+ * That is the whole trick behind a noise loop with no click. Cross-fading the end into the start
94
+ * leaves a seam that is quieter but still a seam; running the filter's transient to completion on
95
+ * the periodic extension means the waveform at sample 0 is the one at sample N, whatever the
96
+ * filter is.
97
+ */
98
+ function filterPeriodic(samples, coefficients, preroll = SAMPLE_RATE * 2) {
99
+ const { b0, b1, b2, a1, a2 } = coefficients;
100
+ const length = samples.length;
101
+ let x1 = 0;
102
+ let x2 = 0;
103
+ let y1 = 0;
104
+ let y2 = 0;
105
+ const step = (index) => {
106
+ const x0 = samples[((index % length) + length) % length];
107
+ const y0 = b0 * x0 + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
108
+ x2 = x1;
109
+ x1 = x0;
110
+ y2 = y1;
111
+ y1 = y0;
112
+ return y0;
113
+ };
114
+ for (let index = -preroll; index < 0; index += 1) step(index);
115
+ const out = new Float32Array(length);
116
+ for (let index = 0; index < length; index += 1) out[index] = step(index);
117
+ return out;
118
+ }
119
+
120
+ function encodeWav(samples) {
121
+ const frames = samples.length;
122
+ const dataBytes = frames * BLOCK_ALIGN;
123
+ const buffer = Buffer.alloc(44 + dataBytes);
124
+ buffer.write("RIFF", 0, "ascii");
125
+ buffer.writeUInt32LE(36 + dataBytes, 4);
126
+ buffer.write("WAVE", 8, "ascii");
127
+ buffer.write("fmt ", 12, "ascii");
128
+ buffer.writeUInt32LE(16, 16);
129
+ buffer.writeUInt16LE(WAVE_FORMAT_IEEE_FLOAT, 20);
130
+ buffer.writeUInt16LE(CHANNELS, 22);
131
+ buffer.writeUInt32LE(SAMPLE_RATE, 24);
132
+ buffer.writeUInt32LE(SAMPLE_RATE * BLOCK_ALIGN, 28);
133
+ buffer.writeUInt16LE(BLOCK_ALIGN, 32);
134
+ buffer.writeUInt16LE(BITS, 34);
135
+ buffer.write("data", 36, "ascii");
136
+ buffer.writeUInt32LE(dataBytes, 40);
137
+ for (let index = 0; index < frames; index += 1)
138
+ buffer.writeFloatLE(samples[index], 44 + index * BLOCK_ALIGN);
139
+ return buffer;
140
+ }
141
+
142
+ // --- the three voices -----------------------------------------------------------------------
143
+
144
+ /**
145
+ * The engine bed: a firing frequency and its harmonics, with the lope of a four-cylinder at idle.
146
+ *
147
+ * 42 Hz is the firing rate at playback rate 1.0 — about 1 300 rpm, where a small four-cylinder
148
+ * sits — and the game's rate law takes it to 90 Hz at the rev limit. Forty harmonics rather than a
149
+ * handful, because pitch-shifting a pure tone up 2× keeps it a pure tone while an exhaust keeps its
150
+ * buzz; `1 / k ** 0.8` is bright enough to still be an engine two octaves up.
151
+ */
152
+ function engineBody() {
153
+ const length = CLIPS.engine.frames;
154
+ const firingHz = 42;
155
+ const harmonics = 40;
156
+ const out = new Float32Array(length);
157
+ for (let index = 0; index < length; index += 1) {
158
+ const time = index / SAMPLE_RATE;
159
+ let body = 0;
160
+ for (let k = 1; k <= harmonics; k += 1) {
161
+ // A fixed golden-angle phase spread: it keeps the partials from summing into one spike at
162
+ // t = 0 in every period, which is what a naive all-zero-phase series does (it sounds like a
163
+ // click 44 times a second).
164
+ body += Math.sin(2 * Math.PI * k * firingHz * time + k * 2.399963229728653) / k ** 0.8;
165
+ }
166
+ // 11 Hz and 22 Hz are whole numbers of cycles in a one-second loop, so the lope wraps too.
167
+ const lope = 0.74 + 0.26 * Math.sin(2 * Math.PI * 11 * time);
168
+ const rumble = 0.3 * Math.sin(2 * Math.PI * 22 * time);
169
+ out[index] = Math.tanh(1.5 * (0.42 * body * lope + rumble));
170
+ }
171
+ return normalise(out, 0.7);
172
+ }
173
+
174
+ /**
175
+ * The tyre squeal: band-limited noise under a narrow tone with vibrato, at a slow swell.
176
+ *
177
+ * A sliding tyre is stick-slip, which is a squeal with a pitch in it rather than hiss. The noise
178
+ * carries the grit (800..3400 Hz) and the tone carries the pitch (1 250 Hz, ±40 Hz at 2 Hz); the
179
+ * vibrato is phase-integrated so it too wraps exactly at the loop point.
180
+ */
181
+ function squealBody() {
182
+ const length = CLIPS.squeal.frames;
183
+ const seconds = length / SAMPLE_RATE;
184
+ // Whole cycles per loop, or the modulation leaves a step at the wrap.
185
+ const vibratoCycles = 3;
186
+ const swellCycles = 2;
187
+ const toneHz = 1250;
188
+ const vibratoHz = 40;
189
+ const rng = mulberry32(SEED);
190
+ const noise = new Float32Array(length);
191
+ for (let index = 0; index < length; index += 1) noise[index] = rng() * 2 - 1;
192
+ const grit = filterPeriodic(
193
+ filterPeriodic(noise, biquad("highpass", 800)),
194
+ biquad("lowpass", 3400),
195
+ );
196
+ const out = new Float32Array(length);
197
+ for (let index = 0; index < length; index += 1) {
198
+ const time = index / SAMPLE_RATE;
199
+ const phase =
200
+ 2 * Math.PI * toneHz * time +
201
+ (vibratoHz / (vibratoCycles / seconds)) *
202
+ Math.cos(2 * Math.PI * (vibratoCycles / seconds) * time);
203
+ const swell =
204
+ 0.78 + 0.22 * Math.sin(2 * Math.PI * (swellCycles / seconds) * time - Math.PI / 2);
205
+ out[index] = swell * (0.8 * grit[index] * 1.6 + 0.22 * Math.sin(phase));
206
+ }
207
+ return normalise(out, 0.62);
208
+ }
209
+
210
+ /**
211
+ * The nitro burst: a pressure wave falling away, with a hiss on top. One shot, so it is allowed
212
+ * not to loop and is declared `loop: false` in `threenative.config.ts`.
213
+ */
214
+ function nitroBody() {
215
+ const length = CLIPS.nitro.frames;
216
+ const rng = mulberry32(SEED ^ 0x9e37_79b9);
217
+ const noise = new Float32Array(length);
218
+ for (let index = 0; index < length; index += 1) noise[index] = rng() * 2 - 1;
219
+ const hiss = filterPeriodic(noise, biquad("highpass", 900));
220
+ const out = new Float32Array(length);
221
+ let phase = 0;
222
+ for (let index = 0; index < length; index += 1) {
223
+ const time = index / SAMPLE_RATE;
224
+ // 10 ms attack, exponential release: a valve opening and a tank emptying.
225
+ const attack = Math.min(1, time / 0.01);
226
+ const release = Math.exp(-time * 5.2);
227
+ const sweepHz = 900 * Math.exp(-time * 3.4) + 120;
228
+ phase += (2 * Math.PI * sweepHz) / SAMPLE_RATE;
229
+ out[index] = attack * release * (0.55 * Math.sin(phase) + 0.5 * hiss[index] * 0.9);
230
+ }
231
+ return normalise(out, 0.66);
232
+ }
233
+
234
+ /** Scales a clip to a peak, so the mix law in `src/audio/engine.ts` is the only level control. */
235
+ function normalise(samples, peak) {
236
+ let loudest = 0;
237
+ for (const value of samples) loudest = Math.max(loudest, Math.abs(value));
238
+ if (loudest === 0) throw new Error("TN_RACING_AUDIO_INVALID: a clip baked as silence.");
239
+ const scale = peak / loudest;
240
+ for (let index = 0; index < samples.length; index += 1) samples[index] *= scale;
241
+ return samples;
242
+ }
243
+
244
+ // --- the checks -----------------------------------------------------------------------------
245
+
246
+ function bake() {
247
+ return {
248
+ engine: engineBody(),
249
+ nitro: nitroBody(),
250
+ squeal: squealBody(),
251
+ };
252
+ }
253
+
254
+ function fail(what) {
255
+ throw new Error(`TN_RACING_AUDIO_INVALID: ${what}`);
256
+ }
257
+
258
+ function assert(what, condition) {
259
+ if (!condition) fail(what);
260
+ }
261
+
262
+ /** Peak, RMS, and the count of samples that are not finite. */
263
+ function measure(samples) {
264
+ let peak = 0;
265
+ let sum = 0;
266
+ let bad = 0;
267
+ for (const value of samples) {
268
+ if (!Number.isFinite(value)) bad += 1;
269
+ else peak = Math.max(peak, Math.abs(value));
270
+ sum += value * value;
271
+ }
272
+ return { bad, peak, rms: Math.sqrt(sum / samples.length) };
273
+ }
274
+
275
+ /**
276
+ * The wrap step against the largest ordinary step near it — the ratio
277
+ * `packages/assets/src/passes/audio.ts` fails a build on, computed the same way so this tool and
278
+ * the cooker cannot disagree about whether a loop is clean.
279
+ */
280
+ function seamRatio(samples) {
281
+ const wrap = Math.abs(samples[0] - samples[samples.length - 1]);
282
+ const steps = [];
283
+ for (let index = 1; index < samples.length; index += 1)
284
+ steps.push(Math.abs(samples[index] - samples[index - 1]));
285
+ steps.sort((a, b) => a - b);
286
+ const near = steps[Math.floor(steps.length * 0.99)];
287
+ return near <= 0 ? (wrap <= 0 ? 0 : Number.POSITIVE_INFINITY) : wrap / near;
288
+ }
289
+
290
+ /**
291
+ * The magnitude of one exact DFT bin, in Hz.
292
+ *
293
+ * A one-second loop has integer-Hz bins, so the engine's fundamental lands exactly on the bin it
294
+ * is asked about. Autocorrelation is the wrong probe here: the bed's own 11 Hz lope is a quarter
295
+ * of a cycle off at a one-period lag, and a genuine pitch then measures as noise.
296
+ */
297
+ function bin(samples, hz) {
298
+ let real = 0;
299
+ let imaginary = 0;
300
+ for (let index = 0; index < samples.length; index += 1) {
301
+ const angle = (2 * Math.PI * hz * index) / SAMPLE_RATE;
302
+ real += samples[index] * Math.cos(angle);
303
+ imaginary += samples[index] * Math.sin(angle);
304
+ }
305
+ return Math.hypot(real, imaginary) / samples.length;
306
+ }
307
+
308
+ const LOOP_SLACK = 0.75;
309
+
310
+ function verify(clips) {
311
+ for (const [name, clip] of Object.entries(CLIPS)) {
312
+ const samples = clips[name];
313
+ const stats = measure(samples);
314
+ assert(`${name}: non-finite samples`, stats.bad === 0);
315
+ assert(`${name}: silent`, stats.peak > 0.1);
316
+ assert(`${name}: peak over full scale (${stats.peak.toFixed(3)})`, stats.peak <= 1);
317
+ assert(`${name}: sample count`, samples.length === clip.frames);
318
+ if (name === "nitro") continue;
319
+ // The seam ratio is the gate the asset pass applies at cook time; it is measured here too, so
320
+ // a bake that would fail a build fails before the file is written.
321
+ const ratio = seamRatio(samples);
322
+ assert(
323
+ `${name}: seam step is ${ratio.toFixed(2)}× the local step, which the cook would reject`,
324
+ ratio <= LOOP_SLACK,
325
+ );
326
+ }
327
+ // The engine's pitch: one firing period is 1/44 s, and a bed with a body in it correlates with
328
+ // itself there. Without this the file could be shaped noise and every other check would pass.
329
+ // The bed's pitch: 42 Hz and its third harmonic stand well clear of the bins between them, which
330
+ // is what "an engine and not shaped noise" means in the file rather than in the source.
331
+ const fundamental = bin(clips.engine, 42);
332
+ const between = (bin(clips.engine, 43) + bin(clips.engine, 62) + bin(clips.engine, 85)) / 3;
333
+ assert(
334
+ `engine: no 42 Hz body (bin ${fundamental.toFixed(4)} against ${between.toFixed(4)} between the partials)`,
335
+ fundamental > between * 8,
336
+ );
337
+ assert("engine: no third harmonic", bin(clips.engine, 126) > between * 4);
338
+ }
339
+
340
+ /** The hash of a bake, taken from the samples rather than the bytes, so it is container-free. */
341
+ function digest(clips) {
342
+ const hash = createHash("sha256");
343
+ for (const name of Object.keys(CLIPS).sort()) {
344
+ for (const value of clips[name]) hash.update(Float32Array.of(value));
345
+ }
346
+ return hash.digest("hex");
347
+ }
348
+
349
+ function report(clips) {
350
+ const rows = Object.entries(CLIPS).map(([name, clip]) => {
351
+ const stats = measure(clips[name]);
352
+ return {
353
+ clip: clip.file,
354
+ seconds: Number((clip.frames / SAMPLE_RATE).toFixed(2)),
355
+ peak: Number(stats.peak.toFixed(3)),
356
+ rms: Number(stats.rms.toFixed(3)),
357
+ seam: name === "nitro" ? "one shot" : seamRatio(clips[name]).toFixed(2),
358
+ };
359
+ });
360
+ console.table(rows);
361
+ }
362
+
363
+ // --- main -----------------------------------------------------------------------------------
364
+
365
+ const checking = process.argv.includes("--check");
366
+ const clips = bake();
367
+ verify(clips);
368
+ const again = bake();
369
+ assert("the bake is not deterministic", digest(clips) === digest(again));
370
+
371
+ if (checking) {
372
+ for (const [name, clip] of Object.entries(CLIPS)) {
373
+ const committed = readFileSync(path.join(assetsDir, clip.file));
374
+ assert(
375
+ `${clip.file} is stale: run node tools/make-racing-audio.mjs`,
376
+ Buffer.compare(committed, encodeWav(bake()[name])) === 0,
377
+ );
378
+ }
379
+ report(clips);
380
+ console.log("committed clips match the bake");
381
+ } else {
382
+ for (const [name, clip] of Object.entries(CLIPS))
383
+ writeFileSync(path.join(assetsDir, clip.file), encodeWav(clips[name]));
384
+ report(clips);
385
+ console.log(
386
+ `baked ${Object.keys(CLIPS).length} clips into assets/ (sha256 ${digest(clips).slice(0, 16)})`,
387
+ );
388
+ }
@@ -13,5 +13,5 @@
13
13
  "verbatimModuleSyntax": true,
14
14
  "isolatedModules": true
15
15
  },
16
- "include": ["src/**/*.ts", "src/**/*.tsx", "*.ts"]
16
+ "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "*.ts"]
17
17
  }
@@ -2,6 +2,7 @@ import tailwindcss from "@tailwindcss/vite";
2
2
  import { watchAssets } from "@threenative/assets";
3
3
  import react from "@vitejs/plugin-react";
4
4
  import {
5
+ createEngineCatalogPlugin,
5
6
  createEngineFreshnessPlugin,
6
7
  createWebBrandPlugin,
7
8
  webRuntimeDecoders,
@@ -36,6 +37,7 @@ export default defineConfig({
36
37
  plugins: [
37
38
  createEngineFreshnessPlugin(),
38
39
  createWebBrandPlugin(),
40
+ createEngineCatalogPlugin(),
39
41
  react(),
40
42
  tailwindcss(),
41
43
  assetsWatchPlugin(),
@@ -11,7 +11,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
11
11
 
12
12
  1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
13
13
  2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
14
- 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
14
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
15
15
  4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
16
16
  5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
17
17
  6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
@@ -30,7 +30,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
30
30
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
31
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
32
  - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
33
- - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
33
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
34
34
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
35
  <!-- /shared -->
36
36
 
@@ -54,6 +54,7 @@ pnpm dev # play in the browser
54
54
  pnpm test # typecheck, lint, format, then every playtest
55
55
  pnpm build --target desktop # also: web, android, ios
56
56
  npx threenative doctor # build, import, device or blank-frame failure
57
+ npx threenative doctor --fix # refresh agent files
57
58
  ```
58
59
  <!-- /shared -->
59
60
 
@@ -84,12 +85,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
84
85
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
85
86
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
86
87
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
88
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
87
89
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
88
90
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
91
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
89
92
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
90
93
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
91
94
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
92
95
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
96
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
93
97
  <!-- /shared -->
94
98
 
95
99
  <!-- shared: kit-stuck -->
@@ -13,7 +13,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
13
13
 
14
14
  1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
15
15
  2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
16
- 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
17
  4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
18
18
  5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
19
19
  6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
@@ -32,7 +32,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
32
32
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
33
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
34
  - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
35
- - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
36
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
37
  <!-- /shared -->
38
38
 
@@ -56,6 +56,7 @@ pnpm dev # play in the browser
56
56
  pnpm test # typecheck, lint, format, then every playtest
57
57
  pnpm build --target desktop # also: web, android, ios
58
58
  npx threenative doctor # build, import, device or blank-frame failure
59
+ npx threenative doctor --fix # refresh agent files
59
60
  ```
60
61
  <!-- /shared -->
61
62
 
@@ -86,12 +87,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
86
87
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
87
88
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
88
89
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
90
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
89
91
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
90
92
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
93
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
91
94
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
92
95
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
93
96
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
94
97
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
98
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
95
99
  <!-- /shared -->
96
100
 
97
101
  <!-- shared: kit-stuck -->
@@ -18,8 +18,8 @@
18
18
  "format:check": "biome format src"
19
19
  },
20
20
  "dependencies": {
21
- "@threenative/core": "0.3.12",
22
- "@threenative/ui": "0.3.12",
21
+ "@threenative/core": ">=0.3.15",
22
+ "@threenative/ui": ">=0.3.15",
23
23
  "react": "19.2.0",
24
24
  "react-dom": "19.2.0",
25
25
  "react-reconciler": "0.33.0",
@@ -27,13 +27,13 @@
27
27
  },
28
28
  "devDependencies": {
29
29
  "@tailwindcss/vite": "4.3.3",
30
- "@threenative/assets": "0.3.13",
31
- "@threenative/playtest": "0.3.12",
30
+ "@threenative/assets": ">=0.3.16",
31
+ "@threenative/playtest": ">=0.3.15",
32
32
  "@types/react": "19.2.0",
33
33
  "@types/react-dom": "19.2.0",
34
34
  "@types/three": "0.187.0",
35
35
  "@vitejs/plugin-react": "6.0.5",
36
- "create-threenative": "0.2.17",
36
+ "create-threenative": "0.2.20",
37
37
  "esbuild": "0.27.0",
38
38
  "playwright": "1.62.1",
39
39
  "tailwindcss": "4.3.3",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.12"
48
+ "@threenative/runtime-native": ">=0.3.15"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -33,7 +33,7 @@ const game = defineGame<GameState>({
33
33
  },
34
34
  plugins: [playtest()],
35
35
  display: config.display,
36
- render: config.renderer,
36
+ renderer: config.renderer,
37
37
  scenes: { coast: Coast },
38
38
  seed: 607,
39
39
  start: "coast",
@@ -4,6 +4,7 @@
4
4
  import {
5
5
  Data3DTexture,
6
6
  LinearFilter,
7
+ MathUtils,
7
8
  NoColorSpace,
8
9
  RGBAFormat,
9
10
  RepeatWrapping,
@@ -76,7 +77,7 @@ function sampleLattice(lattice: ILattice, x: number, y: number, z: number): numb
76
77
  values[((c % n) * n + (b % n)) * n + (a % n)] as number;
77
78
  const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
78
79
  const blend = (fx: number, fy: number, fz: number): number => {
79
- const smooth = (f: number): number => f * f * (3 - 2 * f);
80
+ const smooth = (f: number): number => MathUtils.smoothstep(f, 0, 1);
80
81
  const tx = smooth(fx);
81
82
  const ty = smooth(fy);
82
83
  const tz = smooth(fz);
@@ -6,6 +6,8 @@
6
6
  * they live here rather than in a package.
7
7
  */
8
8
 
9
+ import { MathUtils } from "three";
10
+
9
11
  export const WEATHER_KEYS = ["rain", "cloud", "wind", "fog", "exposure", "wet"] as const;
10
12
 
11
13
  export type WeatherKey = (typeof WEATHER_KEYS)[number];
@@ -74,7 +76,7 @@ export function sanitizeWeather(
74
76
 
75
77
  /** Exponential ease towards the target, independent of frame rate because `dt` is real seconds. */
76
78
  export function easeWeather(current: Weather, target: Weather, dt: number): Weather {
77
- const k = 1 - Math.exp(-dt / EASE_TAU);
79
+ const k = MathUtils.damp(0, 1, 1 / EASE_TAU, dt);
78
80
  const next = { ...current };
79
81
  for (const key of WEATHER_KEYS) next[key] = current[key] + (target[key] - current[key]) * k;
80
82
  return next;
@@ -154,7 +154,7 @@ function RainInterface() {
154
154
  return;
155
155
  qualityChosen.current = true;
156
156
  // An operator asking for high on a phone or software adapter keeps that explicit choice.
157
- const asked = automationRequest(window.location.search).quality;
157
+ const asked = automationRequest().quality;
158
158
  if (asked !== undefined) {
159
159
  send("setQuality", asked);
160
160
  return;
@@ -7,10 +7,11 @@
7
7
  * whole mapping. A name in neither list throws: a typo must not silently pick a tier and report
8
8
  * success.
9
9
  *
10
- * Query reading takes a search string rather than reaching for `location`, so the rules are the
11
- * same on every target and a test can hold one.
10
+ * Query reading goes through the engine's debug seam when no search string is given, so the same
11
+ * rule reads the URL on the web and `TN_DEBUG_*` on a native launch; a test can still hold one.
12
12
  */
13
13
 
14
+ import { debugFlag, debugValue } from "@threenative/core";
14
15
  import type { QualityName } from "../state.js";
15
16
 
16
17
  /** The four engine tiers, plus the four names the source study published for them. */
@@ -48,13 +49,14 @@ export interface IAutomationRequest {
48
49
  * What the query asks for. An unreadable tier is named in `rejectedQuality` instead of thrown: a
49
50
  * URL is a place somebody typed, and the page still has to open.
50
51
  */
51
- export function automationRequest(search: string): IAutomationRequest {
52
- const query = new URLSearchParams(search);
53
- const asked = query.get("quality");
54
- if (asked === null) return { still: query.has("still") };
52
+ export function automationRequest(search?: string): IAutomationRequest {
53
+ const query = search === undefined ? undefined : new URLSearchParams(search);
54
+ const asked = query === undefined ? debugValue("quality") : query.get("quality");
55
+ const still = query === undefined ? debugFlag("still") : query.has("still");
56
+ if (asked === null || asked === undefined) return { still };
55
57
  try {
56
- return { still: query.has("still"), quality: qualityTier(asked) };
58
+ return { still, quality: qualityTier(asked) };
57
59
  } catch {
58
- return { still: query.has("still"), rejectedQuality: asked };
60
+ return { still, rejectedQuality: asked };
59
61
  }
60
62
  }
@@ -13,7 +13,7 @@
13
13
  * browser APIs. `src/game.ts` stays portable: this sends the same validated intents the buttons do.
14
14
  */
15
15
 
16
- import type { IGame } from "@threenative/core";
16
+ import { type IGame, debugFlag } from "@threenative/core";
17
17
  import { connectUiBridge, sendUiIntent, subscribeUiState } from "@threenative/core/ui-layer";
18
18
  import type { GameState, PresetName, WeatherKey } from "../state.js";
19
19
  import type { ICaptureResult, ISceneSizes } from "./Hud.js";
@@ -78,15 +78,14 @@ export function installTempest(game: IGame<GameState>): ITempestApi {
78
78
  const send = (intent: IntentName, payload?: unknown): void => {
79
79
  sendUiIntent(bridge, intent, payload);
80
80
  };
81
- const query = new URLSearchParams(window.location.search);
82
- const request = automationRequest(window.location.search);
81
+ const request = automationRequest();
83
82
  if (request.rejectedQuality !== undefined) {
84
83
  say(
85
84
  `?quality=${request.rejectedQuality} is not a tier: expected low, balanced, high or cinematic`,
86
85
  );
87
86
  }
88
87
  if (request.quality !== undefined) send("setQuality", request.quality);
89
- if (query.has("offline")) {
88
+ if (debugFlag("offline")) {
90
89
  // The source's offline WebGL2 adapter stood in for a Three.js build it could not load from a
91
90
  // CDN. This build installs Three locally and never reaches for one, so there is no fallback
92
91
  // to select and nothing here pretends otherwise.