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,13 @@ Default: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `
11
11
 
12
12
  The default look is `tonemapMode: "filmic"` with metered auto exposure. Lights are in lux, as in Unreal (EV100 exposure): the sun is 6 lux, and while the meter is off the fixed `exposure` is 2.4. `tonemapMode: "aces"` and `autoExposureEnabled: false` with a fixed `exposure` are the overrides. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset; the render log reports the override. The filmic curve and metered auto exposure are on by default here. Set `tonemapMode: "aces"` or `autoExposureEnabled: false` with a fixed `exposure` on the same preset to override the curve or the meter.
13
13
 
14
+ <a id="ao-indirect"></a>
15
+ ## Ambient occlusion
16
+
17
+ Default: darkens indirect light only; the sun keeps its light. Override: `gtaoIndirectOnly: false` (whole frame); `gtaoEnabled: false`. Reports: TN_WORLD_ENVIRONMENT.
18
+
19
+ The contact occlusion (`gtaoEnabled`, on at `high` and `medium`) darkens only the light that reaches a surface from around it: sky, ambient, environment and baked irradiance. A sunlit crease keeps its sunlight, as in Unreal 5.8.3. The owned engine writes each draw's indirect diffuse light to its `indirectDiffuse` target, and the stage takes the occlusion off that share. Set `gtaoIndirectOnly: false` on the quality preset to multiply the whole frame instead. `engine: "threejs"` has no such target, so it needs `gtaoRadius` and multiplies the whole frame.
20
+
14
21
  <a id="quality"></a>
15
22
  ## Quality tier
16
23
 
@@ -205,6 +212,13 @@ Default: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--w
205
212
 
206
213
  Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
207
214
 
215
+ <a id="cpu-priority"></a>
216
+ ## CPU priority
217
+
218
+ Default: game threads first. Override: `display.priority: "normal"`. Reports: TN_PROCESS_PRIORITY.
219
+
220
+ A shipped native game asks the OS for more CPU than other programs: its game, render and present threads take a higher priority (desktop nice -10, Android nice -4 plus an ADPF hint session) and its own background work (shader compiles, workers, HUD processes) yields. It needs no admin rights; a refused raise is reported, not fatal. `TN_PROCESS_PRIORITY` states what the OS applied. Set `display.priority: "normal"` only when the user asks for the OS default; the web build ignores it.
221
+
208
222
  <a id="terrain"></a>
209
223
  ## Terrain
210
224
 
@@ -219,6 +233,13 @@ Default: none; browser-only WASM. Override: import `@threenative/physics/navigat
219
233
 
220
234
  This kit needs no navmesh and imports none, so it runs on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
221
235
 
236
+ <a id="gamepad"></a>
237
+ ## Controller
238
+
239
+ Default: 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. Reports: TN_GAMEPAD.
240
+
241
+ A game binds standard indices and nothing else: `buttons: [0]` is the south face button on an Xbox pad, an 8BitDo and a Steam Deck, `buttons: [6, 7]` are the triggers, and `ctx.input.vector("move")` reads the left stick. A pad the browser reports without a mapping is normalized from a vendor:product row in `@threenative/core`; a pad nothing knows is ignored and reported once as `TN_GAMEPAD … unmapped`, never read with raw indices, because raw index 0 fires whatever action that device happened to number 0. One pad at a time is read, and it is the one the player last claimed: a button press, or a stick travelling past half tilt. A stick resting past the dead zone claims nothing, and one jittering across it claims nothing either, so a worn pad left on the couch, an idle wheel or a paired-but-idle dongle cannot take the input — at boot or in the middle of a move. The claimed pad keeps the slot while idle, which is what lets its releases be read; a pad that disappears or turns unmapped hands over. At `gamepadDeadZone: 0` a noisy stick does produce claims, which is what raw axes mean. Both sticks carry the radial dead zone: a stick resting at `0.08` reads zero, and one past the zone is rescaled so full tilt is still `1`.
242
+
222
243
  <a id="move-axis"></a>
223
244
  ## Move input
224
245
 
@@ -247,6 +268,13 @@ Default: owned C++ engine. Override: `engine: "threejs"` only when the user asks
247
268
 
248
269
  Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error.
249
270
 
271
+ <a id="engine-catalog"></a>
272
+ ## Refused imports
273
+
274
+ Default: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Reports: TN_ENGINE_CATALOG.
275
+
276
+ Refused imports: `createEngineCatalogPlugin()` in `vite.config.ts` reads every `import { … } from "three"`, `"three/webgpu"` and `"three/tsl"` in game source. When the installed Wasm engine refuses a name, the dev overlay and `threenative build` fail at that import line with the code the page would throw at first use (`TN_NATIVE_UNCATALOGUED_<NAME>`, or the catalog entry's own diagnostic). Pick a bound class instead: `engine_search_capabilities` names it. `mode: "warn"` reports instead of failing and prints `TN_ENGINE_CATALOG: warn`. Under `engine: "threejs"` the check is off and prints `TN_ENGINE_CATALOG: off (engine threejs)`. Member and argument gaps of a `partial` entry stay runtime diagnostics.
277
+
250
278
  <a id="general"></a>
251
279
  ## Other portable contracts
252
280
 
@@ -14,7 +14,7 @@ This repository owns the car feel, track, race rules, rescue, HUD, and look; `sr
14
14
 
15
15
  ## Commands and map
16
16
 
17
- `src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller at a constant pace. Keep `playtests/survives.playtest.json` as the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
17
+ `src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller, five of them on a staggered six-car grid (`GRID_SLOTS` in `circuit.ts`), each at its own constant pace from `RIVALS`, the player last. `Drift.ts` is the drift: Shift with the wheel turned at speed kicks the tail out, full lock above `DRIFT.looseSpeed` lets it go by itself, and both lower the rear grip through `VehicleBody3D.setWheelFrictionSlip`. `Nitro.ts` is the tank Space burns, filled by driving and about four times faster by drifting. `gauges.ts` is the gearbox readout — six bands, and Need for Speed: Most Wanted's capped needle fall with a 55/45 blend — and `audio/engine.ts` is the car's sound over one `AudioBus`: the bed pitched from that needle, the tyre squeal opened by the slip angle, a burst on the nitro button. Controls: WASD or arrows drive, Shift drifts and brakes, Space is nitro, P is the autopilot, R restarts. Keep `playtests/survives.playtest.json` as the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
18
18
 
19
19
  **Two things about the vehicle are invisible in the API.** `suspensionStiffness` is a frequency squared, so the strut sags `gravity / (4 * stiffness)` and Godot's default of 20 bottoms it out, and a positive steering angle turns the chassis toward its own `-z` — so the input is negated once and the visual front wheels take that same signed angle. `CarBody.ts` carries every other number.
20
20
 
@@ -23,4 +23,6 @@ This repository owns the car feel, track, race rules, rescue, HUD, and look; `sr
23
23
 
24
24
  Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right.
25
25
 
26
- `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/boost and outcome text so a brighter road or sky does not erase the readouts.
26
+ `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/gear and revs/nitro and outcome text so a brighter road or sky does not erase the readouts; a banked drift's score pops up under it for 1.6 s, keyed on `driftsBanked` so two identical scores in a row still count as two, and counted in **game** seconds by `DRIFT.popupSeconds` — the drift owns that clock and publishes it as `driftPopup`, so a pause freezes the popup instead of ageing it while the car stands still.
27
+
28
+ **Sound is authored, not licensed.** `tools/make-racing-audio.mjs` bakes `assets/engine-loop.wav`, `tyre-squeal.wav` and `nitro-burst.wav` from maths — an engine bed pitched live from 0.62× to 2.05× has to be tonal and exactly periodic, which a recording is not — and `CREDITS.md` records why no downloaded clip fits. Both beds are declared loops with `crossFadeMs: 0` in `threenative.config.ts`, so the asset pass measures their seams and fails the build on a click. One named native gap: the host binds a source's `playbackRate` as a passive parameter, so on native the bed plays at rate 1 with the same volume, squeal and burst. `node tools/make-racing-audio.mjs --check` re-bakes and compares against the committed bytes.
@@ -33,10 +33,14 @@ revisit later is the engine's job, not yours.
33
33
  - **Web threads.** The dev and preview servers send `Cross-Origin-Opener-Policy: same-origin` and
34
34
  `Cross-Origin-Embedder-Policy: require-corp`, and the build writes both into `dist/_headers`, so the
35
35
  page is cross-origin isolated and loads the threaded engine: the world-matrix walk splits over up
36
- to 8 workers. `TN_FRAME_BUDGET` reports `threads: "on (N)"`. The page always loads the threaded
37
- engine and fails closed with `TN_WEB_THREADS_OFF` when it is not cross-origin isolated or the pool
38
- starts no worker, so a host must send the two headers; `TN_WASM_THREADS_MISSING` names a missing
39
- threaded build. A cross-origin asset without a `Cross-Origin-Resource-Policy` header needs
36
+ to 8 workers. `TN_FRAME_BUDGET` reports `threads: "on (N)"`. A host that sends no headers (GitHub
37
+ Pages, a plain static server) gets them from the build's `tn-isolation-sw.js` service worker,
38
+ which reloads the page once; it needs https or localhost. The dev server, playtests and
39
+ conformance fail closed with `TN_WEB_THREADS_OFF` when the page is not isolated or the pool starts
40
+ no worker. A shipped build still loads there: it falls back to the single-thread engine, warns
41
+ `TN_WEB_THREADS_OFF` with the fix, and reports `threads: "off (<reason>)"`. Plain http on a LAN
42
+ address and an itch.io frame without its "SharedArrayBuffer support" option are such pages.
43
+ `TN_WASM_THREADS_MISSING` names a missing threaded build. A cross-origin asset without a `Cross-Origin-Resource-Policy` header needs
40
44
  `credentialless` in place of `require-corp`. `?tnIsolation=0` serves a page without the headers.
41
45
  - **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
42
46
  and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
@@ -130,7 +134,8 @@ change a line.
130
134
  `pnpm check` runs the strict typecheck, ESLint and a Biome format check, and `pnpm test` runs it
131
135
  first. ESLint fails on a floating Promise and on an async callback given to a synchronous slot, and
132
136
  it warns when a `new Vector3()`-style math constructor runs directly inside `Scene.update`,
133
- `Scene.render` or a `ctx.beforeRender` callback. That warning is a prompt to measure, not a
137
+ `Scene.render`, an entity's `update`/`fixedUpdate`/`tick`/`step` method or a `ctx.beforeRender`
138
+ callback. That warning is a prompt to measure, not a
134
139
  finding: reuse an instance the scene owns only if `TN_FRAME_BUDGET` shows allocation pressure.
135
140
  It does not follow helper calls, so a quiet result is not proof a frame allocates nothing. A
136
141
  suppression needs a reason: `// eslint-disable-next-line <rule> -- <why>`. Lint does not prove a
@@ -18,13 +18,26 @@ sky, props and colliders. `@threenative/terrain` ships them under `starter/<worl
18
18
 
19
19
  ```sh
20
20
  cp -r node_modules/@threenative/terrain/starter/forest src/terrain/forest
21
- node src/terrain/forest/bake.mjs --out assets/terrain/forest
21
+ npm install --save-dev tsx
22
+ node src/terrain/forest/bake.mjs
22
23
  ```
23
24
 
24
- Then `await addForest(ctx, player)` in `Scene.load` and `ctx.add(forestDaylight(ctx.camera))` in
25
- `Scene.enter`; the kit's `README.md` says what each file decides. Edit `recipe.json` for layout,
26
- `COLLIDERS` in `world.ts` for what stops the player, `surface.json` and `sky.ts` for the look, and
27
- re-run the bake. The bake writes the engine's `WorldCells` package (`bakeWorldPackage`).
25
+ Then start the game on its scene: `defineGame({ ...FOREST_GAME, plugins: [rapier()], scenes:
26
+ { forest: ForestScene }, start: "forest" })`, both from `./terrain/forest/scene.js`. The kit's
27
+ `README.md` says what each file decides: the landform in `bake.mjs`, what grows where in
28
+ `biome.data.json`, every art path in `world/terrainAssets.ts`, and the look in `render/biomes.ts`.
29
+
30
+ ## Name a region, not just a biome
31
+
32
+ The terrain MCP's `terrain_generate` reads a region word and cooks that region's own world: its real
33
+ ground from a survey, and its plant community — several species, each baked at more than one seed —
34
+ on the starter's own surface, understorey, road and water. The words today are `european` and
35
+ `europe` (a Central European beech wood), `boreal`, `taiga`, `nordic` and `scandinavian`,
36
+ `mediterranean` and `tuscan`, and `pacific northwest` and `cascadia`. The reply's `decided.region`
37
+ names the row behind it, `decided.ground` the survey it stands on with the attribution its source
38
+ requires, and `unused` the words nothing answered to. A tree word in a region request moves that
39
+ species to the front of the canopy and leaves the rest; `kit`, `biome` and `ground` still win over
40
+ the row.
28
41
 
29
42
  ## Generate once, play the bake
30
43
 
@@ -127,8 +140,9 @@ patches. Editor imports, workers, watchers and the document stay out of the game
127
140
  runtime. Bake committed data before handing it to the game. The editor's GLB action and
128
141
  `prepareWorldGLTF` from `@threenative/terrain/export` prepares the resolved world for
129
142
  Node `cookTerrainWorld({ preparedWorld: prepared.json })` from `@threenative/assets` (terrain,
130
- props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. The full
131
- operation list, units and patch rules ship in `node_modules/@threenative/terrain/AGENT_GUIDE.md`.
143
+ props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. Start at
144
+ `node_modules/@threenative/terrain/README.md`; the full operation list, units and patch rules ship in
145
+ `node_modules/@threenative/terrain/docs/authoring/recipes.md`.
132
146
 
133
147
  For individual props, save `placementOverrides` in the authoring document, keyed
134
148
  by evaluated placement `id`. Each entry contains `position: [x,y,z]`, a unit
@@ -26,7 +26,7 @@ problem, not instead of it: read the code the change touches and trace the real
26
26
  flow end to end, then climb. Two rungs work → take the higher one and move on.
27
27
 
28
28
  1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
29
- 2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and inspect hits with `engine_capability_detail`; for a change to an existing game, search for that change (and references for each gameplay mechanic) as the existing-game route in `threenative-capabilities` says, without restarting whole-game discovery or planning. Reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; keep a change's recorded result rather than treating each edit as a new game. Keep installed systems instead of hand-writing replacements.
29
+ 2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and read every row (a row answers; `engine_capability_detail` is only for a symbol the search did not return); for a change to an existing game, search for that change (and references for each gameplay mechanic) as the existing-game route in `threenative-capabilities` says, without restarting whole-game discovery or planning. Reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; keep a change's recorded result rather than treating each edit as a new game. Keep installed systems instead of hand-writing replacements.
30
30
  3. **Already in this game?** Reuse a helper, type, or pattern that already lives in `src/`. Re-implementing what sits a few files over is the most common slop.
31
31
  4. **Stdlib or engine convention does it?** `loadAll`, `addInSlices`, `GroundSnap`, an input vector, a physics query — reach for those before writing your own loop.
32
32
  5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
@@ -29,6 +29,19 @@ and **References**. Each needs a value or explicit `none` with a reason; a blank
29
29
  section blocks approval. Required texture search/download is step 5, after plan approval;
30
30
  record planned asset needs here without claiming assets have already been selected or downloaded.
31
31
 
32
+ List every asset under **Asset slots** in `.agent/prd/PRD.md`, one row each: name, route, status
33
+ (`placeholder` or `final`), and scale with bounding box. Pick the route per slot:
34
+
35
+ - `procedural` (default): terrain, vegetation, simple or repeated shapes, and every first version.
36
+ - `pre-made`: a generic prop that looks the same in any game, such as a wooden chair. Record its licence.
37
+ - `custom`: an identity asset the player remembers this game by, such as the hero or a signature
38
+ vehicle. It is generated, then cleaned up, rigged and baked before it is `final`.
39
+
40
+ The code loads each slot from one stable path, so a swap replaces the file and leaves gameplay code
41
+ alone. Phase 1 (first playable) uses `procedural` and `pre-made` slots only. Phase 2 (polish) replaces
42
+ identity slots with `custom` ones, one at a time, after the user approves the gameplay or when the
43
+ judge's top gap is a placeholder. The visual judge does not score a `placeholder` slot on its looks.
44
+
32
45
  Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
33
46
  `.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
34
47
  bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
@@ -50,3 +63,14 @@ Start implementation only after explicit approval and a clear execution instruct
50
63
  "execute", "implement", "build it", or an equivalent phrase. One message may contain both. After
51
64
  that handoff, execute the approved tasks without silently expanding the scope; repeat capability
52
65
  discovery only when the requested mechanics or target platforms change.
66
+
67
+ ## Execution goal
68
+
69
+ At the handoff, start a `/goal` (or the host's persistent-goal equivalent) so execution continues
70
+ across turns. The goal text always carries both conditions:
71
+
72
+ - **Done:** every task in `.agent/tasks.json` has `"passes": true`.
73
+ - **Stop:** the first of these ends the goal: the visual judge passes its bar, three judge rounds in a
74
+ row show no score gain, the cost cap is reached, or the user says stop or accepts the result.
75
+
76
+ Start a goal only with its Stop condition. A goal without one keeps working after the user is done.
@@ -50,8 +50,10 @@ prompt (`TN_DISCOVERY_GATE=off` opts out).
50
50
  mechanic from pinned `file:line`, never from a video. No network or no tools: record
51
51
  `none: gameplay frames unavailable`.
52
52
  3. **Built-ins** — engine_capabilities built-in discovery, served by the same MCP: call
53
- `engine_search_capabilities` with `scope: "mechanic"` per mechanic, system or symptom; inspect
54
- hits with `engine_capability_detail`. Record installed capabilities and binding constraints. A
53
+ `engine_search_capabilities` with `scope: "mechanic"` per mechanic, system or symptom, and read
54
+ every row — it carries the import path, signature, example, constraints, overrides and
55
+ deprecations, so call `engine_capability_detail` only for a symbol the search did not return.
56
+ Record installed capabilities and binding constraints. A
55
57
  `verdict: "none"` means game-owned behavior in `src/`; do not rephrase until something matches.
56
58
  These role names add no servers.
57
59
  4. **Plan** — hand **Kit**, **Mechanics** and **References** to `prd-creator`. Plan the core loop
@@ -92,8 +94,9 @@ prompt (`TN_DISCOVERY_GATE=off` opts out).
92
94
  A change to an existing game skips step 1 and whole-game planning; do not invoke `prd-creator` just
93
95
  to restart the game plan. For each change, search before you write:
94
96
 
95
- - Step 3 for every change: `engine_search_capabilities` with `scope: "mechanic"`, then
96
- `engine_capability_detail` on each hit, so installed systems are reused.
97
+ - Step 3 for every change: `engine_search_capabilities` with `scope: "mechanic"`, then read every
98
+ row — `engine_capability_detail` only for a symbol the search did not return — so installed
99
+ systems are reused.
97
100
  - Step 2 for each gameplay mechanic the change adds or alters: `engine_search_references`, then
98
101
  `engine_reference_detail`; use `engine_watch_reference` when the motion is the question.
99
102
  - Steps 5-8 for the change, using the existing game, plan and context: apply step 5 to the
@@ -114,12 +114,12 @@ try {
114
114
  log = readFileSync(logFile, "utf8");
115
115
  } catch (error) {
116
116
  deny(
117
- `Discovery gate: cannot read ${path.relative(root, logFile)} (${error.code ?? error.message}), so the engine was not searched in this project. Before you create ${created.join(", ")}, run ${SEARCH} and engine_capability_detail on every hit. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
117
+ `Discovery gate: cannot read ${path.relative(root, logFile)} (${error.code ?? error.message}), so the engine was not searched in this project. Before you create ${created.join(", ")}, run ${SEARCH} and read every row; engine_capability_detail is only for a symbol the search did not return. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
118
118
  );
119
119
  process.exit(0);
120
120
  }
121
121
  const since = Date.parse(state.prompt ?? "") || 0;
122
122
  if (!searchedSince(log, since))
123
123
  deny(
124
- `Discovery gate: no engine_search_capabilities call since the last user prompt. Before you create ${created.join(", ")}, run ${SEARCH}, then engine_capability_detail on every hit, and use what it returns. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
124
+ `Discovery gate: no engine_search_capabilities call since the last user prompt. Before you create ${created.join(", ")}, run ${SEARCH} and read every row — engine_capability_detail is only for a symbol the search did not return — and use what it returns. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
125
125
  );
package/dist/index.d.ts CHANGED
@@ -1,6 +1,41 @@
1
1
  #!/usr/bin/env node
2
2
  import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, IThreeNativeConfig, ThreeNativeUiRenderer, IThreeNativeAudioConfig, IThreeNativeLodConfig, IThreeNativeTexturesConfig } from '@threenative/core';
3
3
 
4
+ interface IEngineCatalogOptions {
5
+ /** "error" (the default) fails the edit and the build; "warn" reports, and the page throws at first use. */
6
+ readonly mode?: "error" | "warn";
7
+ }
8
+ interface ITransformContext {
9
+ error(failure: {
10
+ readonly message: string;
11
+ readonly id: string;
12
+ readonly loc?: {
13
+ readonly file: string;
14
+ readonly line: number;
15
+ readonly column: number;
16
+ };
17
+ }): never;
18
+ warn(message: string): void;
19
+ }
20
+ interface IEngineCatalogVitePlugin {
21
+ readonly name: string;
22
+ readonly enforce: "pre";
23
+ config(): {
24
+ worker: {
25
+ plugins: () => object[];
26
+ };
27
+ };
28
+ configResolved(config: {
29
+ readonly root: string;
30
+ }): Promise<void>;
31
+ transform(this: ITransformContext, code: string, id: string): Promise<null>;
32
+ }
33
+ /**
34
+ * Fails a game file's `import { X } from "three"` when the Wasm engine refuses `X` (PRD-830). Off,
35
+ * and reported once, under `engine: "threejs"` and for the native host's bundle.
36
+ */
37
+ declare function createEngineCatalogPlugin(options?: IEngineCatalogOptions): IEngineCatalogVitePlugin;
38
+
4
39
  interface IEngineFreshnessVitePlugin {
5
40
  readonly name: string;
6
41
  config(config: {
@@ -51,6 +86,7 @@ interface IResolvedThreeNativeConfig {
51
86
  readonly orientation: ThreeNativeOrientation;
52
87
  readonly fullscreen: boolean;
53
88
  readonly keepScreenOn: boolean;
89
+ readonly priority: "game" | "normal";
54
90
  readonly maxFps: number;
55
91
  };
56
92
  readonly window: {
@@ -214,8 +250,11 @@ interface IWebBrandVitePlugin {
214
250
  load(id: string): Promise<string | null>;
215
251
  configResolved(config: {
216
252
  readonly root: string;
253
+ readonly command?: "build" | "serve";
217
254
  }): Promise<void>;
218
- transformIndexHtml(html: string): string;
255
+ transformIndexHtml(html: string, context?: {
256
+ readonly bundle?: Readonly<Record<string, IBundleFile>>;
257
+ }): string;
219
258
  configureServer(server: IMiddlewareServer): void;
220
259
  configurePreviewServer(server: IMiddlewareServer): void;
221
260
  generateBundle(this: {
@@ -237,15 +276,30 @@ interface IMiddlewareServer {
237
276
  use(handler: Middleware): void;
238
277
  };
239
278
  }
279
+ interface IBundleFile {
280
+ readonly fileName: string;
281
+ readonly type: string;
282
+ readonly moduleIds?: readonly string[];
283
+ }
240
284
  declare function renderWebManifest(root: string, config: IResolvedThreeNativeConfig): string;
241
285
  declare function createWebBrandPlugin(): IWebBrandVitePlugin;
242
286
 
243
287
  /**
244
- * The asset decoders the web engine ships: its glTF loader decodes neither KTX2 nor Meshopt (addons/gltf-loader-web.ts), so a
245
- * native-engine game's models are cooked without it, which is also the cooker's default. `engine: "threejs"` names both.
246
- * `threenative build` and each template's dev-server asset watch both read it, so the two cook the same bytes.
288
+ * The asset decoders the web build ships, per format.
289
+ *
290
+ * Meshopt geometry decodes on both engines: on `engine: "threenative"` the engine's own glTF loader
291
+ * decompresses EXT/KHR_meshopt_compression with meshoptimizer, which `pnpm wasm:build` provisions
292
+ * and without which the `tn-native-engine-web` target refuses to link (PRD-861).
293
+ *
294
+ * KTX2 decodes on both engines too: the owned engine transcodes KHR_texture_basisu to BC7 or ETC2
295
+ * and uploads the blocks, or RGBA8 on a device with neither (PRD-867), and three's KTX2Loader runs
296
+ * on it. The web cook keeps an authored WebP a KTX2 cannot undercut, so Midway's KTX2 cook is
297
+ * 98,236,952 B against 125,132,608 B with WebP model textures.
298
+ *
299
+ * `threenative build` and each template's dev-server asset watch both read it, so the two cook the
300
+ * same bytes.
247
301
  */
248
- declare function webRuntimeDecoders(config: {
302
+ declare function webRuntimeDecoders(_config: {
249
303
  readonly engine?: "threejs" | "threenative";
250
304
  }): {
251
305
  readonly ktx2: boolean;
@@ -307,8 +361,19 @@ declare function stampLoadingSource(canonical: string, template: string): string
307
361
  * render-chain plumbing is not: it is the same 600 lines in every kit, and keeping seven copies by
308
362
  * hand let one fall a revision behind without anything failing. A file belongs here only when a
309
363
  * kit editing it would be a mistake rather than a choice.
364
+ *
365
+ * `__tests__/shared-render-drift.spec.ts` fails on any render source that ships byte-identical in
366
+ * two or more kits and is missing here, so a new copy cannot land unrestamped. The environment
367
+ * measure-and-sample mechanism and the backlight used to be seven of these copies; they live in
368
+ * `@threenative/core/render/environment` now (PRD-833).
310
369
  */
311
370
  declare const SHARED_RENDER_SOURCES: readonly string[];
371
+ /**
372
+ * The shared sources `createProject` also writes into a kit that does not ship them. A kit owns its
373
+ * look, so presence is per kit: `starter` ships the temporal detail stage and the collectathon kits
374
+ * do not, and all four still get the same plumbing.
375
+ */
376
+ declare const ADDED_RENDER_SOURCES: readonly string[];
312
377
  declare function canonicalRenderSourcePath(relativePath: string, root?: string): string;
313
378
  /** Re-copies every shared render source into each kit that ships it. */
314
379
  declare function restampSharedRenderCopies(root?: string): Promise<readonly string[]>;
@@ -339,10 +404,36 @@ declare function projectMcpServers(target: string): string[];
339
404
  */
340
405
  declare function referenceDigest(target: string, genre: string, run?: (args: string[]) => string): string;
341
406
  declare function cliHelp(): string;
407
+ interface IAuthoringLayerStatus {
408
+ /** The create-threenative version running this check, which is the one the game installed. */
409
+ readonly installed: string;
410
+ readonly kit?: string;
411
+ /** Why the layer cannot be checked; set instead of `stale`'s meaning. */
412
+ readonly problem?: string;
413
+ /** Layer paths whose bytes differ from the installed package, and dropped files still present. */
414
+ readonly stale: readonly string[];
415
+ readonly stamped?: string;
416
+ }
417
+ interface IAuthoringLayerFix {
418
+ readonly deleted: readonly string[];
419
+ readonly kept: readonly string[];
420
+ readonly written: readonly string[];
421
+ }
422
+ /** How far the game's authoring layer is from what the installed create-threenative renders. */
423
+ declare function authoringLayerStatus(game: string, root?: string): Promise<IAuthoringLayerStatus>;
424
+ /**
425
+ * `threenative doctor --fix` (PRD-829): re-renders the authoring layer from the installed package with
426
+ * the scaffold's writers. A file whose bytes still match the stamp is overwritten, an edited one is
427
+ * kept unless `force`, and a file the package dropped is deleted only when unedited. Without a stamp,
428
+ * every differing file counts as edited.
429
+ */
430
+ declare function fixAuthoringLayer(game: string, options: {
431
+ readonly force: boolean;
432
+ }, root?: string): Promise<IAuthoringLayerFix>;
342
433
  declare function createProject(options: IScaffoldOptions, cwd?: string, root?: string): Promise<IScaffoldResult>;
343
434
  /** The inverse of `scripts/workspace-packages.ts`'s `workspacePackageSourceFlag`; exported so
344
435
  * the pair is gated rather than trusted. */
345
436
  declare function packageNameFromFlag(flag: string): string | undefined;
346
437
  declare function parseArgs(argv: readonly string[]): IScaffoldOptions;
347
438
 
348
- export { type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, projectMcpServers, referenceDigest, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, scaffoldNextSteps, stampLoadingSource, templateForGenre, templateRoot, webRuntimeDecoders };
439
+ export { ADDED_RENDER_SOURCES, type IAuthoringLayerFix, type IAuthoringLayerStatus, type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, authoringLayerStatus, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineCatalogPlugin, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, fixAuthoringLayer, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, projectMcpServers, referenceDigest, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, scaffoldNextSteps, stampLoadingSource, templateForGenre, templateRoot, webRuntimeDecoders };