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
@@ -11,6 +11,7 @@ import {
11
11
  EquirectangularReflectionMapping,
12
12
  FogExp2,
13
13
  LinearFilter,
14
+ MathUtils,
14
15
  RGBAFormat,
15
16
  SRGBColorSpace,
16
17
  type Scene,
@@ -39,8 +40,8 @@ const LATTICE = (() => {
39
40
  function noise(x: number, y: number): number {
40
41
  const i = Math.floor(x);
41
42
  const j = Math.floor(y);
42
- const fx = (x - i) * (x - i) * (3 - 2 * (x - i));
43
- const fy = (y - j) * (y - j) * (3 - 2 * (y - j));
43
+ const fx = MathUtils.smoothstep(x - i, 0, 1);
44
+ const fy = MathUtils.smoothstep(y - j, 0, 1);
44
45
  const i0 = i & 255;
45
46
  const i1 = (i + 1) & 255;
46
47
  const j0 = (j & 255) << 8;
@@ -79,7 +80,7 @@ function density(x: number, y: number): number {
79
80
 
80
81
  const smooth = (from: number, to: number, value: number): number => {
81
82
  const t = Math.min(1, Math.max(0, (value - from) / (to - from)));
82
- return t * t * (3 - 2 * t);
83
+ return MathUtils.smoothstep(t, 0, 1);
83
84
  };
84
85
 
85
86
  /**
@@ -92,7 +93,7 @@ const smooth = (from: number, to: number, value: number): number => {
92
93
  * flatten toward the horizon. Each is lit by where its density climbs: a texel whose deck is
93
94
  * denser toward the sun, or above it on screen, is on the cloud's shaded side or its flat base.
94
95
  */
95
- export function skyTexture(saturation = 1, width = 2048): DataTexture {
96
+ export function skyPixels(saturation = 1, width = 2048): Uint8Array {
96
97
  // three's PMREM sizes its cube from width / 4 and needs at least 16: keep width >= 64.
97
98
  const height = width / 2;
98
99
  const data = new Uint8Array(width * height * 4);
@@ -109,6 +110,14 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
109
110
  let baseR = 0;
110
111
  let baseG = 0;
111
112
  let baseB = 0;
113
+ // Each column's azimuth terms, once: the same numbers every row reads.
114
+ const cosAzimuth = new Float64Array(width);
115
+ const sinAzimuth = new Float64Array(width);
116
+ for (let column = 0; column < width; column += 1) {
117
+ const azimuth = (column / width - 0.5) * Math.PI * 2;
118
+ cosAzimuth[column] = Math.cos(azimuth);
119
+ sinAzimuth[column] = Math.sin(azimuth);
120
+ }
112
121
  // Pass 1: the deck's density under every cloud-band texel, once (the shading reads neighbours).
113
122
  const deck = new Float32Array(width * height);
114
123
  const bands = new Float32Array(height);
@@ -120,8 +129,10 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
120
129
  // Flattened less than a true deck would be: cumulus heaps stand tall, they are not a sheet.
121
130
  const reach = (1 / (Math.tan(elevation) + 0.1)) ** 0.7 * 0.75;
122
131
  for (let column = 0; column < width; column += 1) {
123
- const azimuth = (column / width - 0.5) * Math.PI * 2;
124
- deck[row * width + column] = density(Math.cos(azimuth) * reach, Math.sin(azimuth) * reach);
132
+ deck[row * width + column] = density(
133
+ (cosAzimuth[column] as number) * reach,
134
+ (sinAzimuth[column] as number) * reach,
135
+ );
125
136
  }
126
137
  }
127
138
  // The cumulus banks over the far hills, per column: where a bank stands (`cluster`), its heaped
@@ -142,6 +153,12 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
142
153
  const step = Math.max(1, Math.round(width / 512));
143
154
  const sunAzimuth = Math.atan2(SUN_DIRECTION.z, SUN_DIRECTION.x);
144
155
  const sunElevation = Math.asin(SUN_DIRECTION.y);
156
+ // Which way the sun lies from each column, once.
157
+ const sunward = new Int8Array(width);
158
+ for (let column = 0; column < width; column += 1) {
159
+ const azimuth = (column / width - 0.5) * Math.PI * 2;
160
+ sunward[column] = Math.sin(sunAzimuth - azimuth) > 0 ? 1 : -1;
161
+ }
145
162
  for (let row = 0; row < height; row += 1) {
146
163
  const elevation = (row / (height - 1) - 0.5) * Math.PI;
147
164
  const up = Math.sin(elevation);
@@ -171,9 +188,10 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
171
188
  );
172
189
  for (let column = 0; column < width; column += 1) {
173
190
  // three's equirectangular u: azimuth from +X toward +Z, u = 0.5 on +X.
174
- const azimuth = (column / width - 0.5) * Math.PI * 2;
175
- const tx = Math.cos(azimuth) * cosE;
176
- const tz = Math.sin(azimuth) * cosE;
191
+ const cosA = cosAzimuth[column] as number;
192
+ const sinA = sinAzimuth[column] as number;
193
+ const tx = cosA * cosE;
194
+ const tz = sinA * cosE;
177
195
  // The sun's halo: a warm glow round its direction, wider than the disc the lens never sees.
178
196
  const sun = Math.max(0, tx * SUN_DIRECTION.x + up * SUN_DIRECTION.y + tz * SUN_DIRECTION.z);
179
197
  const halo = 0.6 * sun ** 32 + 0.22 * sun ** 5;
@@ -183,7 +201,7 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
183
201
  const d = deck[row * width + column] ?? 0;
184
202
  const cover = band > 0 ? smooth(0.43, 0.54, d) * band : 0;
185
203
  if (cover > 0.002) {
186
- const turn = Math.sin(sunAzimuth - azimuth) > 0 ? step : -step;
204
+ const turn = (sunward[column] as number) * step;
187
205
  const towardColumn = (column + turn + width) % width;
188
206
  // Denser a step toward the sun: the far side of a heap. Denser a step up the sky: its base.
189
207
  const toward = (deck[towardRow * width + towardColumn] ?? 0) - d;
@@ -202,8 +220,7 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
202
220
  if (elevation > foot && elevation < top + 0.05) {
203
221
  // Billowed outline: finer noise lifts and bites the heap's top edge.
204
222
  // Elevation moves radially and azimuth round the circle: round puffs, and azimuth wraps.
205
- const puff = (e: number) =>
206
- fbm(Math.cos(azimuth) * (14 + e * 15), Math.sin(azimuth) * (14 + e * 15), 3);
223
+ const puff = (e: number) => fbm(cosA * (14 + e * 15), sinA * (14 + e * 15), 3);
207
224
  const lump = puff(elevation);
208
225
  const below = top + (lump - 0.5) * 0.11 - elevation;
209
226
  const inside = smooth(0, 0.02, below) * smooth(foot, foot + 0.012, elevation);
@@ -225,12 +242,27 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
225
242
  }
226
243
  const grey = r * 0.2126 + g * 0.7152 + b * 0.0722;
227
244
  const i = (row * width + column) * 4;
228
- data[i] = Math.round(255 * linearToSrgb(r + (grey - r) * (1 - saturation)));
229
- data[i + 1] = Math.round(255 * linearToSrgb(g + (grey - g) * (1 - saturation)));
230
- data[i + 2] = Math.round(255 * linearToSrgb(b + (grey - b) * (1 - saturation)));
245
+ data[i] = srgbByte(r + (grey - r) * (1 - saturation));
246
+ data[i + 1] = srgbByte(g + (grey - g) * (1 - saturation));
247
+ data[i + 2] = srgbByte(b + (grey - b) * (1 - saturation));
231
248
  data[i + 3] = 255;
232
249
  }
233
250
  }
251
+ return data;
252
+ }
253
+
254
+ /**
255
+ * The sky as a texture. `data` is `skyPixels(saturation, width)`; the scene passes the copy it kept
256
+ * from the last run (`ctx.assets.memo`), because painting four million texels costs a run ~0.3 s.
257
+ */
258
+ export function skyTexture(
259
+ saturation = 1,
260
+ width = 2048,
261
+ data: Uint8Array = skyPixels(saturation, width),
262
+ ): DataTexture {
263
+ const height = width / 2;
264
+ if (data.length !== width * height * 4)
265
+ throw new Error(`sky pixels are ${data.length} bytes, expected ${width * height * 4}.`);
234
266
  const sky = new DataTexture(data, width, height, RGBAFormat, UnsignedByteType);
235
267
  sky.mapping = EquirectangularReflectionMapping;
236
268
  sky.colorSpace = SRGBColorSpace;
@@ -247,6 +279,39 @@ function linearToSrgb(value: number): number {
247
279
  return v < 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
248
280
  }
249
281
 
282
+ /**
283
+ * `Math.round(255 * linearToSrgb(value))` for millions of texels: the byte only steps up as the
284
+ * value grows, so the smallest value of each step, found once, gives the same byte with no power.
285
+ */
286
+ const SRGB_STEPS = (() => {
287
+ const byte = (value: number) => Math.round(255 * linearToSrgb(value));
288
+ const steps = new Float64Array(256);
289
+ for (let level = 1; level < 256; level += 1) {
290
+ let low = 0;
291
+ let high = 1;
292
+ // Halve until the two ends are adjacent doubles: `high` is then the step's first value.
293
+ for (;;) {
294
+ const middle = low + (high - low) / 2;
295
+ if (middle === low || middle === high) break;
296
+ if (byte(middle) >= level) high = middle;
297
+ else low = middle;
298
+ }
299
+ steps[level] = high;
300
+ }
301
+ return steps;
302
+ })();
303
+
304
+ function srgbByte(value: number): number {
305
+ let low = 0;
306
+ let high = 255;
307
+ while (low < high) {
308
+ const middle = (low + high + 1) >> 1;
309
+ if (value >= (SRGB_STEPS[middle] as number)) low = middle;
310
+ else high = middle - 1;
311
+ }
312
+ return low;
313
+ }
314
+
250
315
  /** `fill` is the environment light: by default the sky itself, in this game `skyTexture(0.3, 128)`. */
251
316
  export function setupSky(scene: Scene, sky: DataTexture, fill: DataTexture = sky): void {
252
317
  scene.background = sky;
@@ -85,12 +85,39 @@ function depthMap(floor: ISeaFloor): DataTexture {
85
85
  }
86
86
 
87
87
  /** Tiling ripples: periodic value noise, its slope in red/green and its height in alpha. */
88
+ const RIPPLE_SIZE = 256;
89
+ let primedRipples: Uint8Array | undefined;
90
+ /** Hand the ripple pixels back from a store (`ctx.assets.memo`), so `seaMaterial` skips painting them. */
91
+ export function primeRipplePixels(pixels: Uint8Array): void {
92
+ if (pixels.length !== RIPPLE_SIZE * RIPPLE_SIZE * 4)
93
+ throw new Error("ripple pixels do not match RIPPLE_SIZE.");
94
+ primedRipples = pixels;
95
+ }
88
96
  function rippleMap(): DataTexture {
89
- const n = 256;
97
+ const n = RIPPLE_SIZE;
98
+ const map = new DataTexture(primedRipples ?? ripplePixels(), n, n);
99
+ map.wrapS = RepeatWrapping;
100
+ map.wrapT = RepeatWrapping;
101
+ map.magFilter = LinearFilter;
102
+ map.minFilter = LinearMipmapLinearFilter;
103
+ map.generateMipmaps = true;
104
+ map.needsUpdate = true;
105
+ return map;
106
+ }
107
+ /** The sea's ripple normal (RG) and height (A), the same every run: no input, no randomness. */
108
+ export function ripplePixels(): Uint8Array {
109
+ const n = RIPPLE_SIZE;
90
110
  const hash = (x: number, z: number): number => {
91
111
  const a = Math.sin(x * 127.1 + z * 311.7) * 43758.5453;
92
112
  return a - Math.floor(a);
93
113
  };
114
+ // Each octave's lattice is k x k whole points, hashed once: a texel reads 64 of them.
115
+ const lattices = new Map<number, Float64Array>();
116
+ for (const k of [8, 16, 32, 64]) {
117
+ const lattice = new Float64Array(k * k);
118
+ for (let x = 0; x < k; x += 1) for (let z = 0; z < k; z += 1) lattice[x * k + z] = hash(x, z);
119
+ lattices.set(k, lattice);
120
+ }
94
121
  const noise = (u: number, v: number, k: number): number => {
95
122
  const x = u * k;
96
123
  const z = v * k;
@@ -100,7 +127,9 @@ function rippleMap(): DataTexture {
100
127
  let b = z - j;
101
128
  a = a * a * a * (a * (a * 6 - 15) + 10);
102
129
  b = b * b * b * (b * (b * 6 - 15) + 10);
103
- const h = (hx: number, hz: number): number => hash(((hx % k) + k) % k, ((hz % k) + k) % k);
130
+ const lattice = lattices.get(k) as Float64Array;
131
+ const h = (hx: number, hz: number): number =>
132
+ lattice[(((hx % k) + k) % k) * k + (((hz % k) + k) % k)] as number;
104
133
  return (
105
134
  (h(i, j) * (1 - a) + h(i + 1, j) * a) * (1 - b) +
106
135
  (h(i, j + 1) * (1 - a) + h(i + 1, j + 1) * a) * b
@@ -126,14 +155,7 @@ function rippleMap(): DataTexture {
126
155
  data[at + 3] = height(u, v) * 255;
127
156
  }
128
157
  }
129
- const map = new DataTexture(data, n, n);
130
- map.wrapS = RepeatWrapping;
131
- map.wrapT = RepeatWrapping;
132
- map.magFilter = LinearFilter;
133
- map.minFilter = LinearMipmapLinearFilter;
134
- map.generateMipmaps = true;
135
- map.needsUpdate = true;
136
- return map;
158
+ return data;
137
159
  }
138
160
 
139
161
  export function seaMaterial(floor: ISeaFloor, swell: ISwell): MeshStandardNodeMaterial {
@@ -25,9 +25,10 @@ import { setupLighting } from "../render/lighting.js";
25
25
  import { createLoadingScreen } from "../render/loading.js";
26
26
  import { postTier, setupPost } from "../render/postprocessing.js";
27
27
  import { GRASS_SHARE } from "../render/quality.js";
28
- import { setupSky, skyTexture } from "../render/sky.js";
28
+ import { setupSky, skyPixels, skyTexture } from "../render/sky.js";
29
29
  import { loadSurfaces, updateSurfaceSampling } from "../render/surface.js";
30
30
  import { TouchControls } from "../render/touch-controls.js";
31
+ import { primeRipplePixels, ripplePixels } from "../render/water.js";
31
32
  import { type GameState, HUD_PILL } from "../state.js";
32
33
 
33
34
  export type { GameCtx };
@@ -90,16 +91,28 @@ export class Play extends Scene<GameState, IPhysicsContext> {
90
91
  this.#loading = createLoadingScreen(ctx);
91
92
  // The HUD is page UI the cover cannot hide, so it waits for the same readiness.
92
93
  void ctx.startup.whenReady().then(() => ctx.state.set({ loaded: true }));
93
- const surfaces = await loadSurfaces(ctx.assets);
94
- this.#sky = skyTexture();
95
- this.#fill = skyTexture(0.3, 128);
94
+ // The sky is the same every run of this build: paint it once, then read the pixels back. A first
95
+ // visit paints it (~600 ms on a laptop) while the surface textures download, not after them.
96
+ const [surfaces, painted] = await Promise.all([
97
+ loadSurfaces(ctx.assets),
98
+ ctx.assets.memo("sky", () => ({
99
+ fill: skyPixels(0.3, 128),
100
+ ripples: ripplePixels(),
101
+ sky: skyPixels(),
102
+ })),
103
+ ]);
104
+ primeRipplePixels(painted.ripples);
105
+ this.#sky = skyTexture(1, 2048, painted.sky);
106
+ this.#fill = skyTexture(0.3, 128, painted.fill);
96
107
  setupSky(ctx.scene, this.#sky, this.#fill);
97
108
  const tier = postTier({
98
109
  gpuClass: ctx.renderer.gpuClass?.class,
99
110
  mobile: isMobile(),
100
111
  software: ctx.renderer.softwareAdapter !== undefined,
101
112
  });
102
- const course = buildCourse(makeRng(6402), surfaces, GRASS_SHARE[tier]);
113
+ // The island is the same every run of this build: the first run draws it, a repeat reads it
114
+ // back from `ctx.assets.memo` (~105 ms of the load on a laptop).
115
+ const course = await buildCourse(makeRng(6402), surfaces, GRASS_SHARE[tier], ctx.assets.memo);
103
116
  this.#course = course;
104
117
  ctx.add(course.group);
105
118
  ctx.entities.add("course", { debug: () => course.audit });
@@ -2,6 +2,10 @@
2
2
 
3
3
  @source "../index.html";
4
4
  @source "./";
5
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
6
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
7
+ profile failure. Tailwind scans what it is told to scan. */
8
+ @source not "./render";
5
9
 
6
10
  @theme {
7
11
  --color-ink: #1d3a5c;
@@ -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 test # typecheck, lint, format, then every playtest
54
54
  pnpm build --target desktop # also: web, android, ios
55
55
  pnpm studio # open the game in Studio
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
 
@@ -63,6 +64,7 @@ npx threenative doctor # build, import, device or blank-frame failure
63
64
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
64
65
 
65
66
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
67
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
66
68
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
67
69
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
68
70
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -80,11 +82,14 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
80
82
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
81
83
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
82
84
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
85
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
83
86
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
84
87
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
88
+ - **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`.
85
89
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
86
90
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
87
91
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
92
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
88
93
  <!-- /shared -->
89
94
 
90
95
  <!-- 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 test # typecheck, lint, format, then every playtest
56
56
  pnpm build --target desktop # also: web, android, ios
57
57
  pnpm studio # open the game in Studio
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
 
@@ -65,6 +66,7 @@ npx threenative doctor # build, import, device or blank-frame failure
65
66
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
66
67
 
67
68
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
69
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
68
70
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
69
71
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
70
72
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -82,11 +84,14 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
82
84
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
83
85
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
84
86
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
87
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
85
88
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
86
89
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
90
+ - **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`.
87
91
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
88
92
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
89
93
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
94
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
90
95
  <!-- /shared -->
91
96
 
92
97
  <!-- shared: kit-stuck -->
@@ -19,8 +19,8 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.12",
23
- "@threenative/ui": "0.3.12",
22
+ "@threenative/core": ">=0.3.15",
23
+ "@threenative/ui": ">=0.3.15",
24
24
  "react": "19.2.0",
25
25
  "react-dom": "19.2.0",
26
26
  "three": "0.187.0"
@@ -29,11 +29,11 @@
29
29
  "@tailwindcss/vite": "4.3.3",
30
30
  "@vitejs/plugin-react": "6.0.5",
31
31
  "@types/three": "0.187.0",
32
- "@threenative/assets": "0.3.13",
33
- "@threenative/playtest": "0.3.12",
32
+ "@threenative/assets": ">=0.3.16",
33
+ "@threenative/playtest": ">=0.3.15",
34
34
  "@types/react": "19.2.0",
35
35
  "@types/react-dom": "19.2.0",
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",
@@ -44,7 +44,7 @@
44
44
  "eslint": "10.13.0"
45
45
  },
46
46
  "optionalDependencies": {
47
- "@threenative/runtime-native": "0.3.12"
47
+ "@threenative/runtime-native": ">=0.3.15"
48
48
  },
49
49
  "overrides": {
50
50
  "sharp": ">=0.35.4",
@@ -1,3 +1,4 @@
1
+ import { MathUtils } from "three";
1
2
  import { type ICourse, SURFACE_DRAG, type Surface } from "../track/Course.js";
2
3
 
3
4
  /**
@@ -327,7 +328,7 @@ export class Kart {
327
328
  Math.max(0, 1 - resist) *
328
329
  (1 + this.boost + this.miniTurbo + this.catchUp);
329
330
  if (brake && this.throttle === 0 && this.speed < 0.5) target = -f.reverse;
330
- this.speed += (target - this.speed) * (1 - Math.exp(-ticks / f.lagTicks));
331
+ this.speed = MathUtils.damp(this.speed, target, 1 / f.lagTicks, ticks);
331
332
  }
332
333
 
333
334
  // Hop and drift. A press while grounded hops; with the stick held and enough speed the hop
@@ -21,7 +21,7 @@ const game = defineGame<GameState>({
21
21
  },
22
22
  plugins: [playtest({ events })],
23
23
  display: config.display,
24
- render: config.renderer,
24
+ renderer: config.renderer,
25
25
  scenes: { race: Race },
26
26
  seed: 734,
27
27
  start: "race",
@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
4
4
  import game from "./game.js";
5
5
  import { App } from "./ui/App.js";
6
6
  import "./style.css";
7
+
7
8
  import.meta.hot?.accept();
8
9
  acceptHotUpdate(game, import.meta.hot);
9
10
  const root = document.getElementById("root");
@@ -15,6 +15,7 @@ import {
15
15
  Group,
16
16
  IcosahedronGeometry,
17
17
  InstancedMesh,
18
+ MathUtils,
18
19
  Matrix4,
19
20
  Mesh,
20
21
  MeshStandardMaterial,
@@ -521,7 +522,7 @@ export function buildCourseView(course: ICourse, seed = 734): ICourseView {
521
522
 
522
523
  function smooth(edge0: number, edge1: number, x: number): number {
523
524
  const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
524
- return t * t * (3 - 2 * t);
525
+ return MathUtils.smoothstep(t, 0, 1);
525
526
  }
526
527
 
527
528
  /** True when x/z is at least `clearance` metres from every sample of the line. */
@@ -2,6 +2,10 @@
2
2
 
3
3
  @source "../index.html";
4
4
  @source "./";
5
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
6
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
7
+ profile failure. Tailwind scans what it is told to scan. */
8
+ @source not "./render";
5
9
 
6
10
  @theme {
7
11
  --color-ink: #1d3a5c;
@@ -10,6 +10,8 @@
10
10
  */
11
11
 
12
12
  /** Metres between samples of the centre line. */
13
+ import { MathUtils } from "three";
14
+
13
15
  export const STEP = 1;
14
16
 
15
17
  /** The lateral profile, in metres from the centre line. */
@@ -69,7 +71,7 @@ function plateau(s: number, at: number, length: number, flat: number, ramp: numb
69
71
 
70
72
  function smooth(edge0: number, edge1: number, x: number): number {
71
73
  const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
72
- return t * t * (3 - 2 * t);
74
+ return MathUtils.smoothstep(t, 0, 1);
73
75
  }
74
76
 
75
77
  export interface ICourse {
@@ -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
 
@@ -38,7 +38,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
38
38
 
39
39
  <!-- shared: kit-files -->
40
40
  Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`.
41
- 6 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
41
+ 7 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
42
  Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
43
43
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-minimal.md`.
44
44
  <!-- /shared -->
@@ -55,6 +55,7 @@ pnpm test # typecheck, lint, format, then every playtest
55
55
  pnpm build --target desktop # also: web, android, ios
56
56
  pnpm studio # open the game in Studio
57
57
  npx threenative doctor # build, import, device or blank-frame failure
58
+ npx threenative doctor --fix # refresh agent files
58
59
  ```
59
60
  <!-- /shared -->
60
61
 
@@ -64,6 +65,7 @@ npx threenative doctor # build, import, device or blank-frame failure
64
65
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
65
66
 
66
67
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
68
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
67
69
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
68
70
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
69
71
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -90,12 +92,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
90
92
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
91
93
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
92
94
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
95
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
93
96
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
94
97
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
98
+ - **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`.
95
99
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
96
100
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
97
101
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
98
102
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
103
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
99
104
  <!-- /shared -->
100
105
 
101
106
  <!-- shared: kit-stuck -->