create-threenative 0.2.15 → 0.2.18

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 (488) hide show
  1. package/agent-docs/kit-mcp.md +10 -0
  2. package/agent-docs/kit-router.md +14 -0
  3. package/agent-docs/kit-stuck.md +7 -0
  4. package/agent-docs/references/assertion-reference.md +54 -110
  5. package/agent-docs/references/capability-reference.md +1740 -254
  6. package/agent-docs/references/conventions.md +299 -0
  7. package/agent-docs/references/kit-action-rpg.md +40 -0
  8. package/agent-docs/references/kit-adventure.md +40 -0
  9. package/agent-docs/references/kit-collectathon.md +38 -0
  10. package/agent-docs/references/kit-kart.md +31 -0
  11. package/agent-docs/references/kit-minimal.md +29 -0
  12. package/agent-docs/references/kit-platformer.md +34 -0
  13. package/agent-docs/references/kit-puzzle.md +22 -0
  14. package/agent-docs/references/kit-racing.md +26 -0
  15. package/agent-docs/references/kit-rain.md +31 -0
  16. package/agent-docs/references/kit-rts.md +34 -0
  17. package/agent-docs/references/kit-runner.md +32 -0
  18. package/agent-docs/references/kit-sailing.md +41 -0
  19. package/agent-docs/references/kit-shooter.md +33 -0
  20. package/agent-docs/references/kit-snow.md +33 -0
  21. package/agent-docs/references/kit-starter.md +55 -0
  22. package/agent-docs/references/kit-tower-defense.md +27 -0
  23. package/agent-docs/references/performance-basics.md +8 -4
  24. package/agent-docs/references/terrain-authoring.md +2 -1
  25. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  26. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  27. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +84 -59
  28. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  29. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  30. package/agent-files/.claude/settings.json +25 -0
  31. package/agent-files/.codex/hooks.json +18 -1
  32. package/dist/index.d.ts +97 -6
  33. package/dist/index.js +899 -271
  34. package/dist/terrain-kit.d.ts +7 -0
  35. package/dist/terrain-kit.js +82 -0
  36. package/dist/threenative.js +114 -16
  37. package/dist/web-engine-ccd-ik-solver.js +127 -0
  38. package/dist/web-engine-gltf-loader.js +71 -20
  39. package/dist/web-engine-post-effects.js +39 -14
  40. package/dist/web-engine-runtime.js +10011 -4101
  41. package/package.json +15 -9
  42. package/template-assets/clearwater/README.md +1 -1
  43. package/template-assets/patches/manifest.json +18 -0
  44. package/template-assets/patches/three@0.187.0.patch +2004 -407
  45. package/template-assets/terrain/alpine/assets.json +12 -0
  46. package/template-assets/terrain/alpine/bake.mjs +6 -0
  47. package/template-assets/terrain/alpine/credits.json +164 -0
  48. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  49. package/template-assets/terrain/alpine/recipe.json +119 -0
  50. package/template-assets/terrain/alpine/surface.json +53 -0
  51. package/template-assets/terrain/coastal/assets.json +11 -0
  52. package/template-assets/terrain/coastal/bake.mjs +6 -0
  53. package/template-assets/terrain/coastal/credits.json +117 -0
  54. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  55. package/template-assets/terrain/coastal/recipe.json +113 -0
  56. package/template-assets/terrain/coastal/surface.json +41 -0
  57. package/template-assets/terrain/desert/assets.json +12 -0
  58. package/template-assets/terrain/desert/bake.mjs +6 -0
  59. package/template-assets/terrain/desert/credits.json +164 -0
  60. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  61. package/template-assets/terrain/desert/recipe.json +108 -0
  62. package/template-assets/terrain/desert/surface.json +54 -0
  63. package/template-assets/terrain/forest/assets.json +65 -0
  64. package/template-assets/terrain/forest/bake.mjs +8 -0
  65. package/template-assets/terrain/forest/credits.json +225 -0
  66. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  67. package/template-assets/terrain/forest/recipe.json +350 -0
  68. package/template-assets/terrain/forest/surface.json +79 -0
  69. package/template-assets/terrain/tundra/assets.json +12 -0
  70. package/template-assets/terrain/tundra/bake.mjs +6 -0
  71. package/template-assets/terrain/tundra/credits.json +164 -0
  72. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  73. package/template-assets/terrain/tundra/recipe.json +277 -0
  74. package/template-assets/terrain/tundra/surface.json +54 -0
  75. package/templates/action-rpg/AGENTS.md +103 -84
  76. package/templates/action-rpg/CLAUDE.md +103 -84
  77. package/templates/action-rpg/kit.json +1 -0
  78. package/templates/action-rpg/package.json +7 -7
  79. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  80. package/templates/action-rpg/src/game.ts +2 -1
  81. package/templates/action-rpg/src/render/atmosphere.ts +11 -16
  82. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  83. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  84. package/templates/action-rpg/src/render/clouds.ts +13 -0
  85. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  86. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  87. package/templates/action-rpg/src/render/quality.ts +10 -33
  88. package/templates/action-rpg/src/scenes/Play.ts +30 -1
  89. package/templates/action-rpg/src/style.css +4 -0
  90. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  91. package/templates/action-rpg/threenative.config.ts +0 -3
  92. package/templates/action-rpg/vite.config.ts +2 -0
  93. package/templates/adventure/AGENTS.md +92 -44
  94. package/templates/adventure/CLAUDE.md +92 -44
  95. package/templates/adventure/kit.json +5 -1
  96. package/templates/adventure/package.json +7 -7
  97. package/templates/adventure/src/game.ts +1 -1
  98. package/templates/adventure/src/style.css +4 -0
  99. package/templates/adventure/tsconfig.json +1 -1
  100. package/templates/adventure/vite.config.ts +2 -0
  101. package/templates/collectathon/AGENTS.md +93 -42
  102. package/templates/collectathon/CLAUDE.md +93 -42
  103. package/templates/collectathon/package.json +7 -7
  104. package/templates/collectathon/src/game.ts +1 -1
  105. package/templates/collectathon/src/level/Course.ts +55 -9
  106. package/templates/collectathon/src/level/terrain.ts +27 -6
  107. package/templates/collectathon/src/main.ts +1 -0
  108. package/templates/collectathon/src/render/foliage.ts +359 -98
  109. package/templates/collectathon/src/render/sky.ts +76 -12
  110. package/templates/collectathon/src/render/water.ts +32 -10
  111. package/templates/collectathon/src/scenes/Play.ts +18 -5
  112. package/templates/collectathon/src/style.css +4 -0
  113. package/templates/collectathon/tsconfig.json +1 -1
  114. package/templates/collectathon/vite.config.ts +2 -0
  115. package/templates/kart/AGENTS.md +87 -42
  116. package/templates/kart/CLAUDE.md +87 -42
  117. package/templates/kart/package.json +6 -6
  118. package/templates/kart/src/game.ts +1 -1
  119. package/templates/kart/src/main.ts +1 -0
  120. package/templates/kart/src/style.css +4 -0
  121. package/templates/kart/tsconfig.json +1 -1
  122. package/templates/kart/vite.config.ts +2 -0
  123. package/templates/minimal/AGENTS.md +105 -84
  124. package/templates/minimal/CLAUDE.md +105 -84
  125. package/templates/minimal/package.json +6 -6
  126. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  127. package/templates/minimal/src/game.ts +1 -1
  128. package/templates/minimal/src/render/atmosphere.ts +11 -16
  129. package/templates/minimal/src/render/backlightControls.ts +10 -0
  130. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  131. package/templates/minimal/src/render/camera.ts +13 -2
  132. package/templates/minimal/src/render/clouds.ts +13 -0
  133. package/templates/minimal/src/render/gpuSky.ts +4 -7
  134. package/templates/minimal/src/render/lighting.ts +4 -2
  135. package/templates/minimal/src/render/materialLighting.ts +5 -5
  136. package/templates/minimal/src/render/materials.ts +10 -0
  137. package/templates/minimal/src/render/quality.ts +7 -32
  138. package/templates/minimal/src/scenes/Play.ts +4 -1
  139. package/templates/minimal/vite.config.ts +7 -1
  140. package/templates/platformer/AGENTS.md +95 -46
  141. package/templates/platformer/CLAUDE.md +95 -46
  142. package/templates/platformer/index.html +1 -1
  143. package/templates/platformer/main.html +12 -0
  144. package/templates/platformer/package.json +7 -7
  145. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  146. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  147. package/templates/platformer/src/entities/Fox.ts +21 -6
  148. package/templates/platformer/src/game.ts +1 -1
  149. package/templates/platformer/src/main.ts +1 -0
  150. package/templates/platformer/src/render/backlightControls.ts +10 -0
  151. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  152. package/templates/platformer/src/render/materialLighting.ts +5 -5
  153. package/templates/platformer/src/render/quality.ts +7 -32
  154. package/templates/platformer/src/scenes/Play.ts +2 -1
  155. package/templates/platformer/src/style.css +4 -0
  156. package/templates/platformer/src/worker-page.ts +29 -0
  157. package/templates/platformer/src/worker.ts +5 -0
  158. package/templates/platformer/tsconfig.json +1 -1
  159. package/templates/platformer/vite.config.ts +4 -0
  160. package/templates/puzzle/AGENTS.md +97 -80
  161. package/templates/puzzle/CLAUDE.md +97 -80
  162. package/templates/puzzle/package.json +7 -7
  163. package/templates/puzzle/src/game.ts +1 -1
  164. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  165. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  166. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  167. package/templates/puzzle/src/render/quality.ts +7 -32
  168. package/templates/puzzle/src/scenes/Play.ts +1 -1
  169. package/templates/puzzle/src/style.css +4 -0
  170. package/templates/puzzle/tsconfig.json +1 -1
  171. package/templates/puzzle/vite.config.ts +2 -0
  172. package/templates/racing/AGENTS.md +100 -82
  173. package/templates/racing/CLAUDE.md +100 -82
  174. package/templates/racing/package.json +7 -7
  175. package/templates/racing/src/game.ts +1 -1
  176. package/templates/racing/src/render/atmosphere.ts +11 -16
  177. package/templates/racing/src/render/backlightControls.ts +10 -0
  178. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  179. package/templates/racing/src/render/clouds.ts +13 -0
  180. package/templates/racing/src/render/gpuSky.ts +4 -7
  181. package/templates/racing/src/render/materialLighting.ts +5 -5
  182. package/templates/racing/src/render/quality.ts +7 -32
  183. package/templates/racing/src/scenes/Race.ts +4 -1
  184. package/templates/racing/src/style.css +4 -0
  185. package/templates/racing/tsconfig.json +1 -1
  186. package/templates/racing/vite.config.ts +2 -0
  187. package/templates/rain/AGENTS.md +96 -84
  188. package/templates/rain/CLAUDE.md +96 -84
  189. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  190. package/templates/rain/package.json +6 -6
  191. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  192. package/templates/rain/src/game.ts +1 -1
  193. package/templates/rain/src/scenes/Boot.ts +1 -0
  194. package/templates/rain/src/state.ts +7 -0
  195. package/templates/rain/src/ui/GameUi.tsx +7 -1
  196. package/templates/rain/vite.config.ts +6 -0
  197. package/templates/rts/AGENTS.md +100 -85
  198. package/templates/rts/CLAUDE.md +100 -85
  199. package/templates/rts/package.json +6 -6
  200. package/templates/rts/src/game.ts +1 -1
  201. package/templates/rts/src/render/backlightControls.ts +10 -0
  202. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  203. package/templates/rts/src/render/materialLighting.ts +5 -5
  204. package/templates/rts/src/render/quality.ts +7 -31
  205. package/templates/rts/src/scenes/Play.ts +1 -1
  206. package/templates/rts/src/style.css +4 -0
  207. package/templates/rts/vite.config.ts +2 -0
  208. package/templates/runner/AGENTS.md +97 -80
  209. package/templates/runner/CLAUDE.md +97 -80
  210. package/templates/runner/package.json +7 -7
  211. package/templates/runner/playtests/performance.playtest.json +1 -1
  212. package/templates/runner/src/game.ts +1 -1
  213. package/templates/runner/src/render/atmosphere.ts +11 -16
  214. package/templates/runner/src/render/backlightControls.ts +10 -0
  215. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  216. package/templates/runner/src/render/clouds.ts +13 -0
  217. package/templates/runner/src/render/gpuSky.ts +4 -7
  218. package/templates/runner/src/render/lighting.ts +53 -11
  219. package/templates/runner/src/render/materialLighting.ts +5 -5
  220. package/templates/runner/src/render/quality.ts +7 -32
  221. package/templates/runner/src/scenes/Run.ts +8 -4
  222. package/templates/runner/src/style.css +4 -0
  223. package/templates/runner/threenative.config.ts +0 -3
  224. package/templates/runner/tsconfig.json +1 -1
  225. package/templates/runner/vite.config.ts +2 -0
  226. package/templates/sailing/AGENTS.md +96 -79
  227. package/templates/sailing/CLAUDE.md +96 -79
  228. package/templates/sailing/package.json +7 -7
  229. package/templates/sailing/playtests/sails.playtest.json +1 -0
  230. package/templates/sailing/src/game.ts +1 -1
  231. package/templates/sailing/src/render/backlightControls.ts +10 -0
  232. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  233. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  234. package/templates/sailing/src/render/materialLighting.ts +5 -5
  235. package/templates/sailing/src/render/quality.ts +7 -32
  236. package/templates/sailing/src/render/sky.ts +4 -0
  237. package/templates/sailing/src/style.css +5 -0
  238. package/templates/sailing/threenative.config.ts +0 -3
  239. package/templates/sailing/vite.config.ts +6 -0
  240. package/templates/shooter/AGENTS.md +97 -68
  241. package/templates/shooter/CLAUDE.md +97 -68
  242. package/templates/shooter/package.json +7 -7
  243. package/templates/shooter/src/game.ts +3 -2
  244. package/templates/shooter/src/render/atmosphere.ts +11 -16
  245. package/templates/shooter/src/render/backlightControls.ts +10 -0
  246. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  247. package/templates/shooter/src/render/clouds.ts +13 -0
  248. package/templates/shooter/src/render/gpuSky.ts +4 -7
  249. package/templates/shooter/src/render/materialLighting.ts +5 -5
  250. package/templates/shooter/src/render/quality.ts +10 -33
  251. package/templates/shooter/src/scenes/Play.ts +4 -1
  252. package/templates/shooter/src/style.css +4 -0
  253. package/templates/shooter/vite.config.ts +2 -0
  254. package/templates/snow/AGENTS.md +95 -76
  255. package/templates/snow/CLAUDE.md +95 -76
  256. package/templates/snow/package.json +7 -7
  257. package/templates/snow/src/game.ts +1 -1
  258. package/templates/snow/src/render/backlightControls.ts +10 -0
  259. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  260. package/templates/snow/src/render/materialLighting.ts +5 -5
  261. package/templates/snow/src/render/quality.ts +7 -32
  262. package/templates/snow/src/style.css +5 -0
  263. package/templates/snow/threenative.config.ts +0 -3
  264. package/templates/snow/vite.config.ts +6 -0
  265. package/templates/starter/AGENTS.md +109 -88
  266. package/templates/starter/CLAUDE.md +109 -88
  267. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  268. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  269. package/templates/starter/package.json +7 -7
  270. package/templates/starter/src/entities/Crate.ts +5 -2
  271. package/templates/starter/src/entities/Player.ts +10 -22
  272. package/templates/starter/src/game.ts +4 -3
  273. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  274. package/templates/starter/src/render/atmosphere.ts +11 -16
  275. package/templates/starter/src/render/backlightControls.ts +10 -0
  276. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  277. package/templates/starter/src/render/clouds.ts +13 -0
  278. package/templates/starter/src/render/contactShadow.ts +1 -1
  279. package/templates/starter/src/render/gpuSky.ts +4 -7
  280. package/templates/starter/src/render/lighting.ts +54 -4
  281. package/templates/starter/src/render/materialLighting.ts +5 -5
  282. package/templates/starter/src/render/postprocessing.ts +11 -10
  283. package/templates/starter/src/render/quality.ts +14 -1
  284. package/templates/starter/src/render/temporalAA.ts +8 -7
  285. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  286. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  287. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  288. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  289. package/templates/starter/src/render/temporalMoire.ts +190 -0
  290. package/templates/starter/src/render/temporalResolve.ts +75 -16
  291. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  292. package/templates/starter/src/scenes/Play.ts +53 -32
  293. package/templates/starter/src/state.ts +2 -0
  294. package/templates/starter/src/style.css +4 -0
  295. package/templates/starter/src/ui/Menu.tsx +5 -1
  296. package/templates/starter/vite.config.ts +2 -0
  297. package/templates/tower-defense/AGENTS.md +97 -81
  298. package/templates/tower-defense/CLAUDE.md +97 -81
  299. package/templates/tower-defense/package.json +7 -7
  300. package/templates/tower-defense/src/game.ts +1 -1
  301. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  302. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  303. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  304. package/templates/tower-defense/src/render/quality.ts +7 -32
  305. package/templates/tower-defense/src/scenes/Battle.ts +1 -1
  306. package/templates/tower-defense/src/style.css +4 -0
  307. package/templates/tower-defense/tsconfig.json +1 -1
  308. package/templates/tower-defense/vite.config.ts +2 -0
  309. package/capabilities.json +0 -9197
  310. package/templates/AGENTS.md +0 -21
  311. package/templates/CLAUDE.md +0 -23
  312. package/templates/action-rpg/.codex/config.toml +0 -23
  313. package/templates/action-rpg/.cursor/mcp.json +0 -38
  314. package/templates/action-rpg/.gemini/settings.json +0 -38
  315. package/templates/action-rpg/.mcp.json +0 -38
  316. package/templates/action-rpg/.vscode/mcp.json +0 -43
  317. package/templates/action-rpg/.zed/settings.json +0 -43
  318. package/templates/action-rpg/opencode.json +0 -49
  319. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  320. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  321. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  322. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  323. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  324. package/templates/adventure/.codex/config.toml +0 -23
  325. package/templates/adventure/.cursor/mcp.json +0 -38
  326. package/templates/adventure/.gemini/settings.json +0 -38
  327. package/templates/adventure/.mcp.json +0 -38
  328. package/templates/adventure/.vscode/mcp.json +0 -43
  329. package/templates/adventure/.zed/settings.json +0 -43
  330. package/templates/adventure/opencode.json +0 -49
  331. package/templates/collectathon/.codex/config.toml +0 -23
  332. package/templates/collectathon/.cursor/mcp.json +0 -38
  333. package/templates/collectathon/.gemini/settings.json +0 -38
  334. package/templates/collectathon/.mcp.json +0 -38
  335. package/templates/collectathon/.vscode/mcp.json +0 -43
  336. package/templates/collectathon/.zed/settings.json +0 -43
  337. package/templates/collectathon/opencode.json +0 -49
  338. package/templates/kart/.codex/config.toml +0 -23
  339. package/templates/kart/.cursor/mcp.json +0 -38
  340. package/templates/kart/.gemini/settings.json +0 -38
  341. package/templates/kart/.mcp.json +0 -38
  342. package/templates/kart/.vscode/mcp.json +0 -43
  343. package/templates/kart/.zed/settings.json +0 -43
  344. package/templates/kart/opencode.json +0 -49
  345. package/templates/minimal/.codex/config.toml +0 -23
  346. package/templates/minimal/.cursor/mcp.json +0 -38
  347. package/templates/minimal/.gemini/settings.json +0 -38
  348. package/templates/minimal/.mcp.json +0 -38
  349. package/templates/minimal/.vscode/mcp.json +0 -43
  350. package/templates/minimal/.zed/settings.json +0 -43
  351. package/templates/minimal/opencode.json +0 -49
  352. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  353. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  354. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  355. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  356. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  357. package/templates/platformer/.codex/config.toml +0 -23
  358. package/templates/platformer/.cursor/mcp.json +0 -38
  359. package/templates/platformer/.gemini/settings.json +0 -38
  360. package/templates/platformer/.mcp.json +0 -38
  361. package/templates/platformer/.vscode/mcp.json +0 -43
  362. package/templates/platformer/.zed/settings.json +0 -43
  363. package/templates/platformer/opencode.json +0 -49
  364. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  365. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  366. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  367. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  368. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  369. package/templates/puzzle/.codex/config.toml +0 -23
  370. package/templates/puzzle/.cursor/mcp.json +0 -38
  371. package/templates/puzzle/.gemini/settings.json +0 -38
  372. package/templates/puzzle/.mcp.json +0 -38
  373. package/templates/puzzle/.vscode/mcp.json +0 -43
  374. package/templates/puzzle/.zed/settings.json +0 -43
  375. package/templates/puzzle/opencode.json +0 -49
  376. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  377. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  378. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  379. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  380. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  381. package/templates/racing/.codex/config.toml +0 -23
  382. package/templates/racing/.cursor/mcp.json +0 -38
  383. package/templates/racing/.gemini/settings.json +0 -38
  384. package/templates/racing/.mcp.json +0 -38
  385. package/templates/racing/.vscode/mcp.json +0 -43
  386. package/templates/racing/.zed/settings.json +0 -43
  387. package/templates/racing/opencode.json +0 -49
  388. package/templates/racing/src/render/environmentContribution.ts +0 -188
  389. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  390. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  391. package/templates/racing/src/render/environmentSampling.ts +0 -193
  392. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  393. package/templates/rain/.codex/config.toml +0 -23
  394. package/templates/rain/.cursor/mcp.json +0 -38
  395. package/templates/rain/.gemini/settings.json +0 -38
  396. package/templates/rain/.mcp.json +0 -38
  397. package/templates/rain/.vscode/mcp.json +0 -43
  398. package/templates/rain/.zed/settings.json +0 -43
  399. package/templates/rain/opencode.json +0 -49
  400. package/templates/rts/.codex/config.toml +0 -23
  401. package/templates/rts/.cursor/mcp.json +0 -38
  402. package/templates/rts/.gemini/settings.json +0 -38
  403. package/templates/rts/.mcp.json +0 -38
  404. package/templates/rts/.vscode/mcp.json +0 -43
  405. package/templates/rts/.zed/settings.json +0 -43
  406. package/templates/rts/opencode.json +0 -49
  407. package/templates/rts/src/render/environmentContribution.ts +0 -188
  408. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  409. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  410. package/templates/rts/src/render/environmentSampling.ts +0 -193
  411. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  412. package/templates/runner/.codex/config.toml +0 -23
  413. package/templates/runner/.cursor/mcp.json +0 -38
  414. package/templates/runner/.gemini/settings.json +0 -38
  415. package/templates/runner/.mcp.json +0 -38
  416. package/templates/runner/.vscode/mcp.json +0 -43
  417. package/templates/runner/.zed/settings.json +0 -43
  418. package/templates/runner/README.md +0 -43
  419. package/templates/runner/opencode.json +0 -49
  420. package/templates/runner/src/render/environmentContribution.ts +0 -188
  421. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  422. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  423. package/templates/runner/src/render/environmentSampling.ts +0 -193
  424. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  425. package/templates/sailing/.codex/config.toml +0 -23
  426. package/templates/sailing/.cursor/mcp.json +0 -38
  427. package/templates/sailing/.gemini/settings.json +0 -38
  428. package/templates/sailing/.mcp.json +0 -38
  429. package/templates/sailing/.vscode/mcp.json +0 -43
  430. package/templates/sailing/.zed/settings.json +0 -43
  431. package/templates/sailing/README.md +0 -28
  432. package/templates/sailing/opencode.json +0 -49
  433. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  434. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  435. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  436. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  437. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  438. package/templates/shooter/.codex/config.toml +0 -23
  439. package/templates/shooter/.cursor/mcp.json +0 -38
  440. package/templates/shooter/.gemini/settings.json +0 -38
  441. package/templates/shooter/.mcp.json +0 -38
  442. package/templates/shooter/.vscode/mcp.json +0 -43
  443. package/templates/shooter/.zed/settings.json +0 -43
  444. package/templates/shooter/opencode.json +0 -49
  445. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  446. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  447. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  448. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  449. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  450. package/templates/snow/.codex/config.toml +0 -23
  451. package/templates/snow/.cursor/mcp.json +0 -38
  452. package/templates/snow/.gemini/settings.json +0 -38
  453. package/templates/snow/.mcp.json +0 -38
  454. package/templates/snow/.vscode/mcp.json +0 -43
  455. package/templates/snow/.zed/settings.json +0 -43
  456. package/templates/snow/README.md +0 -26
  457. package/templates/snow/opencode.json +0 -49
  458. package/templates/snow/src/render/environmentContribution.ts +0 -188
  459. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  460. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  461. package/templates/snow/src/render/environmentSampling.ts +0 -193
  462. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  463. package/templates/starter/.codex/config.toml +0 -23
  464. package/templates/starter/.cursor/mcp.json +0 -38
  465. package/templates/starter/.gemini/settings.json +0 -38
  466. package/templates/starter/.mcp.json +0 -38
  467. package/templates/starter/.vscode/mcp.json +0 -43
  468. package/templates/starter/.zed/settings.json +0 -43
  469. package/templates/starter/opencode.json +0 -49
  470. package/templates/starter/src/render/environmentContribution.ts +0 -188
  471. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  472. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  473. package/templates/starter/src/render/environmentSampling.ts +0 -193
  474. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  475. package/templates/starter/src/render/rendererGate.ts +0 -36
  476. package/templates/tower-defense/.codex/config.toml +0 -23
  477. package/templates/tower-defense/.cursor/mcp.json +0 -38
  478. package/templates/tower-defense/.gemini/settings.json +0 -38
  479. package/templates/tower-defense/.mcp.json +0 -38
  480. package/templates/tower-defense/.vscode/mcp.json +0 -43
  481. package/templates/tower-defense/.zed/settings.json +0 -43
  482. package/templates/tower-defense/README.md +0 -16
  483. package/templates/tower-defense/opencode.json +0 -49
  484. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  485. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  486. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  487. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  488. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -1,5 +1,6 @@
1
1
  import { watchAssets } from "@threenative/assets";
2
2
  import {
3
+ createEngineCatalogPlugin,
3
4
  createEngineFreshnessPlugin,
4
5
  createWebBrandPlugin,
5
6
  webRuntimeDecoders,
@@ -31,7 +32,12 @@ function assetsWatchPlugin(): Plugin {
31
32
  }
32
33
 
33
34
  export default defineConfig({
34
- plugins: [createEngineFreshnessPlugin(), createWebBrandPlugin(), assetsWatchPlugin()],
35
+ plugins: [
36
+ createEngineFreshnessPlugin(),
37
+ createWebBrandPlugin(),
38
+ createEngineCatalogPlugin(),
39
+ assetsWatchPlugin(),
40
+ ],
35
41
  server: {
36
42
  watch: {
37
43
  ignored: ["**/artifacts/**", "**/screenshots/**", "**/playtests/**"],
@@ -1,62 +1,111 @@
1
- # AGENTS.md — __PROJECT_NAME__ platformer
1
+ <!-- shared: kit-identity -->
2
+ # AGENTS.md — __PROJECT_NAME__ (Fox Dash, the platformer kit)
2
3
 
3
- A chibi fox runs ninety-seven metres of floating meadow, rope bridges and stompable walkers to a goal flag: three hearts, five gems, a double jump and a dash. Every model is procedural — no mesh file, no texture, no animation clip. Instructions for the AI agent in this game; `CLAUDE.md` mirrors this file.
4
+ A fox runs ninety-seven metres of floating meadow, rope bridges and stompable walkers to a goal flag, with three hearts, five gems and a double jump. Routing words: platformer. `CLAUDE.md` is a copy of this file.
5
+ <!-- /shared -->
4
6
 
5
- ## Ownership
7
+ <!-- shared: kit-router -->
8
+ ## Authoring flow
6
9
 
7
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the route, the fox's feel, the walkers, the pickups, the HUD, and the look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
10
+ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
8
11
 
9
- ## Start every change
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
+ 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"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
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
+ 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
+ 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.
18
+ 7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
19
+ 8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
10
20
 
11
- 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
12
- 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints, direct the user to review it, and wait for explicit approval plus an instruction to implement it.
13
- 3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this route needs no navigation: it is authored geometry, so the fox collides with exactly the triangles it sees and desktop/native stays honest.
14
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
21
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
22
+ <!-- /shared -->
15
23
 
16
- ## When the framework blocks you, write plain Three.js
17
-
18
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); never stall the game.
19
-
20
- ## Workflow skills
21
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
22
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
23
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
24
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
25
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
26
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
27
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
28
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
29
- ## Commands and map
24
+ <!-- shared: kit-mcp -->
25
+ ## MCP servers
30
26
 
31
- ```sh
32
- pnpm dev
33
- pnpm build
34
- pnpm build --target desktop
35
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
36
- pnpm typecheck
37
- ```
27
+ `.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
38
28
 
39
- `src/entities/Fox.ts` owns movement and feel — the one table of constants the route is balanced around; `Walker.ts` is a stompable patrol, `Pickup.ts` a collectible; `src/level/Stage.ts` builds the route and tags the walkable meshes, `Checkpoints.ts` owns hearts and respawns; `src/render/` is ordinary Three.js and every model in the game; `src/ui/Hud.tsx` is the one HUD. The camera and the sun are written in `afterPhysics`, never in the scene's frame function, because `moveAndSlide` only queues motion. Keep `playtests/survives.playtest.json` as smoke proof and `touch-controls.ts`/`touch-layout.ts` aligned with the native playtest. Collision is the engine's, from your geometry: `buildStaticColliders(ctx, stage.group, { predicate: (object) => object.userData.solid === true })` turns the tagged walkable meshes into fixed trimesh bodies and leaves thousands of decorative ones out of it. A `CollisionShape3D` capsule is centred on the body's origin, so the origin is the fox's waist and its rig is pushed down by `halfHeight + radius`; forget that and the fox floats a body-length above every surface.
29
+ - `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
30
+ - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
+ - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
+ - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
33
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
34
+ - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
+ <!-- /shared -->
40
36
 
41
- ## Portable authoring contracts
42
- Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
37
+ ## This kit
43
38
 
44
- Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. No model here is imported, so there is no authored scale to normalise and the collider is the body: the generated scale-and-snap conventions do not apply to this template. `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
39
+ <!-- shared: kit-files -->
40
+ Source in `src/`: `entities/`, `game.ts`, `level/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `ui/`, `worker-page.ts`, `worker.ts`.
41
+ 20 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
+ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
43
+ Kit notes: `node_modules/create-threenative/agent-docs/references/kit-platformer.md`.
44
+ <!-- /shared -->
45
45
 
46
- WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/sky.ts` builds the gradient background from `palette.ts`; a separate measured environment lights the scene, the background's lower hemisphere matches `skyFloor`, and `SUN_DIRECTION` aims `lighting.ts`'s authored sun. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. The native production collector's explicit `--hosted-software` profile selects the existing `low` preset only when no tier override is passed; `TN_QUALITY_TIER` reports `source=hosted-software`. That smoke tier is not physical performance evidence and does not change an ordinary desktop run. Unknown tiers throw. `high` draws 4x MSAA and `medium` and `low` SMAA; `temporalAA: true` is the named opt-in. Keep state values human-readable; the bridge flushes about 100 ms and per-frame feel stays in scene-owned Three.js.
46
+ `src/entities/Fox.ts` owns movement and feel, the one table of constants the route is balanced around. `src/level/Stage.ts` builds the route and tags walkable meshes; `Checkpoints.ts` owns hearts and respawns.
47
+ The camera and sun are written in `afterPhysics`, never in the scene's frame function. Every model is procedural.
47
48
 
48
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
49
+ <!-- shared: kit-commands -->
50
+ ## Commands
49
51
 
50
- `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
51
-
52
- ## Budget real time for the look
53
- Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
52
+ ```sh
53
+ pnpm dev # play in the browser
54
+ pnpm test # typecheck, lint, format, then every playtest
55
+ pnpm build --target desktop # also: web, android, ios
56
+ pnpm studio # open the game in Studio
57
+ npx threenative doctor # build, import, device or blank-frame failure
58
+ npx threenative doctor --fix # refresh agent files
59
+ ```
60
+ <!-- /shared -->
61
+
62
+ <!-- shared: kit-conventions -->
63
+ ## Conventions
64
+
65
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
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`.
69
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
70
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
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`.
72
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
73
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
74
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
75
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
76
+ - **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
77
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
78
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
79
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
80
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
81
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
82
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
83
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
84
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
85
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
86
+ - **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
87
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
88
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
89
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
90
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
91
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
92
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
93
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
94
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
95
+ - **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`.
96
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
97
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
98
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
99
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
100
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
101
+ <!-- /shared -->
102
+
103
+ <!-- shared: kit-stuck -->
104
+ ## When the framework blocks you, write plain Three.js
54
105
 
55
- For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
106
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
56
107
 
57
- ## Optional multiplayer transport
58
- For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
59
- Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
60
- `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
108
+ ## Stuck
61
109
 
62
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. The generated `quality.ts` uses those core defaults; game exposure policy stays in `src/render/exposure.ts`. `tonemapMode: "aces"` and `autoExposureEnabled: false` with fixed `exposure` are named overrides on the same preset.
110
+ `npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
111
+ <!-- /shared -->
@@ -1,64 +1,113 @@
1
1
  <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
2
 
3
- # AGENTS.md — __PROJECT_NAME__ platformer
3
+ <!-- shared: kit-identity -->
4
+ # AGENTS.md — __PROJECT_NAME__ (Fox Dash, the platformer kit)
4
5
 
5
- A chibi fox runs ninety-seven metres of floating meadow, rope bridges and stompable walkers to a goal flag: three hearts, five gems, a double jump and a dash. Every model is procedural — no mesh file, no texture, no animation clip. Instructions for the AI agent in this game; `CLAUDE.md` mirrors this file.
6
+ A fox runs ninety-seven metres of floating meadow, rope bridges and stompable walkers to a goal flag, with three hearts, five gems and a double jump. Routing words: platformer. `CLAUDE.md` is a copy of this file.
7
+ <!-- /shared -->
6
8
 
7
- ## Ownership
9
+ <!-- shared: kit-router -->
10
+ ## Authoring flow
8
11
 
9
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the route, the fox's feel, the walkers, the pickups, the HUD, and the look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
12
+ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
10
13
 
11
- ## Start every change
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
+ 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"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
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
+ 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
+ 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.
20
+ 7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
21
+ 8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
12
22
 
13
- 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
14
- 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints, direct the user to review it, and wait for explicit approval plus an instruction to implement it.
15
- 3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this route needs no navigation: it is authored geometry, so the fox collides with exactly the triangles it sees and desktop/native stays honest.
16
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
23
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
24
+ <!-- /shared -->
17
25
 
18
- ## When the framework blocks you, write plain Three.js
19
-
20
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); never stall the game.
21
-
22
- ## Workflow skills
23
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
24
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
25
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
26
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
27
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
28
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
29
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
30
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
31
- ## Commands and map
26
+ <!-- shared: kit-mcp -->
27
+ ## MCP servers
32
28
 
33
- ```sh
34
- pnpm dev
35
- pnpm build
36
- pnpm build --target desktop
37
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
38
- pnpm typecheck
39
- ```
29
+ `.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
40
30
 
41
- `src/entities/Fox.ts` owns movement and feel — the one table of constants the route is balanced around; `Walker.ts` is a stompable patrol, `Pickup.ts` a collectible; `src/level/Stage.ts` builds the route and tags the walkable meshes, `Checkpoints.ts` owns hearts and respawns; `src/render/` is ordinary Three.js and every model in the game; `src/ui/Hud.tsx` is the one HUD. The camera and the sun are written in `afterPhysics`, never in the scene's frame function, because `moveAndSlide` only queues motion. Keep `playtests/survives.playtest.json` as smoke proof and `touch-controls.ts`/`touch-layout.ts` aligned with the native playtest. Collision is the engine's, from your geometry: `buildStaticColliders(ctx, stage.group, { predicate: (object) => object.userData.solid === true })` turns the tagged walkable meshes into fixed trimesh bodies and leaves thousands of decorative ones out of it. A `CollisionShape3D` capsule is centred on the body's origin, so the origin is the fox's waist and its rig is pushed down by `halfHeight + radius`; forget that and the fox floats a body-length above every surface.
31
+ - `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
32
+ - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
+ - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
+ - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
+ - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
+ <!-- /shared -->
42
38
 
43
- ## Portable authoring contracts
44
- Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
39
+ ## This kit
45
40
 
46
- Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. No model here is imported, so there is no authored scale to normalise and the collider is the body: the generated scale-and-snap conventions do not apply to this template. `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
41
+ <!-- shared: kit-files -->
42
+ Source in `src/`: `entities/`, `game.ts`, `level/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `ui/`, `worker-page.ts`, `worker.ts`.
43
+ 20 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
44
+ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
45
+ Kit notes: `node_modules/create-threenative/agent-docs/references/kit-platformer.md`.
46
+ <!-- /shared -->
47
47
 
48
- WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/sky.ts` builds the gradient background from `palette.ts`; a separate measured environment lights the scene, the background's lower hemisphere matches `skyFloor`, and `SUN_DIRECTION` aims `lighting.ts`'s authored sun. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. The native production collector's explicit `--hosted-software` profile selects the existing `low` preset only when no tier override is passed; `TN_QUALITY_TIER` reports `source=hosted-software`. That smoke tier is not physical performance evidence and does not change an ordinary desktop run. Unknown tiers throw. `high` draws 4x MSAA and `medium` and `low` SMAA; `temporalAA: true` is the named opt-in. Keep state values human-readable; the bridge flushes about 100 ms and per-frame feel stays in scene-owned Three.js.
48
+ `src/entities/Fox.ts` owns movement and feel, the one table of constants the route is balanced around. `src/level/Stage.ts` builds the route and tags walkable meshes; `Checkpoints.ts` owns hearts and respawns.
49
+ The camera and sun are written in `afterPhysics`, never in the scene's frame function. Every model is procedural.
49
50
 
50
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
51
+ <!-- shared: kit-commands -->
52
+ ## Commands
51
53
 
52
- `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
53
-
54
- ## Budget real time for the look
55
- Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
54
+ ```sh
55
+ pnpm dev # play in the browser
56
+ pnpm test # typecheck, lint, format, then every playtest
57
+ pnpm build --target desktop # also: web, android, ios
58
+ pnpm studio # open the game in Studio
59
+ npx threenative doctor # build, import, device or blank-frame failure
60
+ npx threenative doctor --fix # refresh agent files
61
+ ```
62
+ <!-- /shared -->
63
+
64
+ <!-- shared: kit-conventions -->
65
+ ## Conventions
66
+
67
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
68
+
69
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
70
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
71
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
72
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
73
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
74
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
75
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
76
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
77
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
78
+ - **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
79
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
80
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
81
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
82
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
83
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
84
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
85
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
86
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
87
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
88
+ - **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
89
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
90
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
91
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
92
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
93
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
94
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
95
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
96
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
97
+ - **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`.
98
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
99
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
100
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
101
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
102
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
103
+ <!-- /shared -->
104
+
105
+ <!-- shared: kit-stuck -->
106
+ ## When the framework blocks you, write plain Three.js
56
107
 
57
- For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
108
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
58
109
 
59
- ## Optional multiplayer transport
60
- For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
61
- Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
62
- `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
110
+ ## Stuck
63
111
 
64
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. The generated `quality.ts` uses those core defaults; game exposure policy stays in `src/render/exposure.ts`. `tonemapMode: "aces"` and `autoExposureEnabled: false` with fixed `exposure` are named overrides on the same preset.
112
+ `npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
113
+ <!-- /shared -->
@@ -7,6 +7,6 @@
7
7
  </head>
8
8
  <body>
9
9
  <div id="root"></div>
10
- <script type="module" src="/src/main.ts"></script>
10
+ <script type="module" src="/src/worker-page.ts"></script>
11
11
  </body>
12
12
  </html>
@@ -0,0 +1,12 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>__PROJECT_NAME__</title>
7
+ </head>
8
+ <body>
9
+ <div id="root"></div>
10
+ <script type="module" src="/src/main.ts"></script>
11
+ </body>
12
+ </html>
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.11",
23
- "@threenative/physics": "0.3.11",
24
- "@threenative/ui": "0.3.11",
22
+ "@threenative/core": "0.3.13",
23
+ "@threenative/physics": "0.3.13",
24
+ "@threenative/ui": "0.3.13",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "three": "0.187.0"
@@ -30,11 +30,11 @@
30
30
  "@tailwindcss/vite": "4.3.3",
31
31
  "@vitejs/plugin-react": "6.0.5",
32
32
  "@types/three": "0.187.0",
33
- "@threenative/assets": "0.3.12",
34
- "@threenative/playtest": "0.3.11",
33
+ "@threenative/assets": "0.3.14",
34
+ "@threenative/playtest": "0.3.13",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
- "create-threenative": "0.2.15",
37
+ "create-threenative": "0.2.18",
38
38
  "esbuild": "0.27.0",
39
39
  "playwright": "1.62.1",
40
40
  "tailwindcss": "4.3.3",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.11"
48
+ "@threenative/runtime-native": "0.3.13"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "platformer-gamepad-idle",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 20,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "stick resting at 0.1",
12
+ "gamepad": { "axes": [0.1, 0] },
13
+ "waitTicks": 180,
14
+ "release": true
15
+ }
16
+ ],
17
+ "assert": {
18
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
19
+ "movement": { "entity": "player", "maxDistance": 0.5 }
20
+ }
21
+ }
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "platformer-gamepad",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 20,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "stick right",
12
+ "gamepad": { "axes": [1, 0] },
13
+ "waitTicks": 180,
14
+ "release": true
15
+ },
16
+ {
17
+ "kind": "input",
18
+ "label": "south button",
19
+ "gamepad": { "buttons": [0] },
20
+ "waitTicks": 120,
21
+ "release": true
22
+ },
23
+ { "kind": "wait", "label": "settle", "waitFrames": 40, "release": true }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
27
+ "movement": { "entity": "player", "minAxisDelta": { "axis": "x", "min": 3 } },
28
+ "resources": [{ "changed": true, "gte": 1, "id": "state", "path": "jumps" }]
29
+ }
30
+ }
@@ -55,7 +55,7 @@ export type FoxState = "dash" | "fall" | "jump" | "run" | "idle";
55
55
  export class Fox {
56
56
  /** The body object. Its origin is the fox's waist, because that is what a capsule is centred on. */
57
57
  readonly mesh: Group;
58
- readonly body: CharacterBody3D;
58
+ #body: CharacterBody3D | undefined;
59
59
  readonly rig: IFox;
60
60
  readonly tags = ["player"];
61
61
  coyoteJumps = 0;
@@ -85,7 +85,15 @@ export class Fox {
85
85
  this.mesh.position.copy(spawn);
86
86
  this.#groundY = spawn.y - FOOT_OFFSET;
87
87
  ctx.add(this.mesh);
88
- this.body = new CharacterBody3D({
88
+ }
89
+
90
+ /**
91
+ * Builds the body in `Play.enter()`: Rapier initializes while the scene loads, so `ctx.physics`
92
+ * exists only from `enter()` on (TN_PHYSICS_NOT_READY). The body starts where `load()` or a
93
+ * scenario's `setup.place` left the mesh.
94
+ */
95
+ attach(ctx: GameCtx): void {
96
+ this.#body ??= new CharacterBody3D({
89
97
  autostep: { maxHeight: 0.4, minWidth: 0.2 },
90
98
  collisionMask: 0xffff,
91
99
  entity: "player",
@@ -99,6 +107,12 @@ export class Fox {
99
107
  });
100
108
  }
101
109
 
110
+ /** The capsule body, from `attach()` on. */
111
+ get body(): CharacterBody3D {
112
+ if (this.#body === undefined) throw new Error("Fox.body is built by attach() in Play.enter().");
113
+ return this.#body;
114
+ }
115
+
102
116
  /** The height of the last surface the fox stood on, at its feet. */
103
117
  get groundY(): number {
104
118
  return this.#groundY;
@@ -189,19 +203,20 @@ export class Fox {
189
203
  coyoteJumps: this.coyoteJumps,
190
204
  dashes: this.dashes,
191
205
  facing: this.#facing,
192
- grounded: this.body.grounded,
206
+ grounded: this.#body?.grounded ?? false,
193
207
  groundY: this.#groundY,
194
208
  jumps: this.jumps,
195
209
  position: this.mesh.position.toArray(),
196
- speed: Math.hypot(this.body.velocity.x, this.body.velocity.z),
210
+ speed:
211
+ this.#body === undefined ? 0 : Math.hypot(this.#body.velocity.x, this.#body.velocity.z),
197
212
  standingSwing: this.standingSwing,
198
213
  state: this.state,
199
- velocity: this.body.velocity.toArray(),
214
+ velocity: this.#body?.velocity.toArray() ?? [0, 0, 0],
200
215
  };
201
216
  }
202
217
 
203
218
  dispose(): void {
204
- this.body.dispose();
219
+ this.#body?.dispose();
205
220
  this.mesh.removeFromParent();
206
221
  }
207
222