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,91 +1,116 @@
1
1
  ---
2
2
  name: threenative-capabilities
3
- description: Route ThreeNative authoring: new games follow prompt, kit, mechanics discovery, plan, textures, execution, mechanics playtest and reference-image judge; existing games use steps 5-7 only.
3
+ description: Route ThreeNative authoring: the kit AGENTS.md "Authoring flow" in detail. A new game follows kit, mechanics, built-ins, plan, assets, build, prove and report; a change to an existing game searches built-ins for each change and references for each gameplay mechanic.
4
4
  ---
5
5
 
6
6
  # ThreeNative authoring route
7
7
 
8
- This is the critical planning prerequisite for a new game and the routing entry for an existing
9
- game. Classify the user's intent using the current project and plan: starter code alone does not
10
- make a new-game request an existing-game change. Ask if intent is ambiguous.
8
+ This is the critical planning prerequisite for a new game and the routing entry for a change to an
9
+ existing game. The kit `AGENTS.md` "Authoring flow" lists the same eight steps with the exact calls;
10
+ this skill holds the detail. Classify the user's intent using the current project and plan: starter
11
+ code alone does not make a new-game request an existing-game change. Ask if intent is ambiguous.
11
12
  Preserve the request's distinctive fantasy and infer concrete mechanics, not just a genre label.
12
13
 
13
- **Tools.** Every server named below is in this game's `.mcp.json`, and a host loads it only for a
14
- session started in this folder. A session started elsewhere (one that ran `create-threenative`)
15
- has none of them in its tool list: run `node node_modules/@threenative/core/mcp/call.mjs <server>
16
- <tool> '<json>'` from this folder, and `call.mjs <server>` lists that server's tools. A tool that
17
- is missing from your list never skips its step.
14
+ **Tools.** Every server named below is in this game's `.mcp.json`. A session started in this folder
15
+ has them, and they can show as deferred: load them with `ToolSearch` `select:` plus the exact names,
16
+ 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`.
17
+ A session started elsewhere (one that ran `create-threenative`) has none of them in its tool list:
18
+ run `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'` from this folder,
19
+ and `call.mjs <server>` lists that server's tools. A tool that is missing from your list never
20
+ skips its step.
18
21
 
19
22
  ## New game
20
23
 
21
- Follow steps 1-8 in order; finish both discovery passes before planning. Record actual results,
22
- including explicit `none` with a reason; a blank discovery result blocks plan approval.
24
+ Follow steps 1-8 in order; finish steps 2 and 3 before planning. Record actual results, including
25
+ explicit `none` with a reason; a blank result blocks plan approval. A session with no user
26
+ (`claude -p`, a script) records the plan and its assumptions, then continues; an interactive session
27
+ waits for approval. A hook blocks the first new file under `src/` until step 3 ran for the current
28
+ prompt (`TN_DISCOVERY_GATE=off` opts out).
23
29
 
24
- 1. **Prompt** — read the user's complete request and any supplied reference image.
25
- 2. **Starter kit** — inspect installed `create-threenative` template `kit.json` fields and exact
26
- `--genre` routing. Choose a matching kit; if no kit matches, use `minimal` (`--template minimal`).
27
- Record the kit and why it fits. Keep the chosen kit's source as the starting point.
28
- 3. **Mechanics discovery** — threenative-reverse-engineer is the mechanics-reference role:
29
- the current `threenative-engine` MCP serves it through `engine_search_references` and
30
+ 1. **Kit** — read the user's complete request and any supplied reference image. Call
31
+ `engine_search_capabilities` with `scope: "request"` for the complete request: it returns the
32
+ matching starter kit first, with its `npx create-threenative <dir> --template <name>` command.
33
+ Inspect the installed `create-threenative` template `kit.json` fields and exact `--genre`
34
+ routing. Choose a matching kit; if no kit matches, use `minimal` (`--template minimal`). Record
35
+ the kit and why it fits. Keep the chosen kit's source as the starting point.
36
+ 2. **Mechanics** — threenative-reverse-engineer is the mechanics-reference role: the
37
+ `threenative-engine` MCP serves it through `engine_search_references` and
30
38
  `engine_reference_detail`. Search named games and the implied mechanics, inspect relevant
31
39
  matches, and record pinned sources and feel rules. For Tier-2 matches, read the pinned repo
32
40
  and use `engine_save_reference` for the nodes/cards actually walked; unavailable references
33
41
  remain `none: references unavailable`, not fabricated matches.
34
- PLUS engine_capabilities built-in discovery, served by that same MCP: call
35
- `engine_search_capabilities` with `scope: "request"` for the complete mechanically explicit
36
- request, then `scope: "mechanic"` per mechanic; inspect hits with `engine_capability_detail`.
37
- Record installed capabilities and binding constraints. A `verdict: "none"` means game-owned
38
- behavior in `src/`; do not rephrase until something matches. These role names add no servers.
39
- 4. **Core-mechanics plan** — hand **Kit**, **Mechanics** and **References** to `prd-creator`.
40
- Plan the core loop from both discovery passes, with controls, camera, state, acceptance checks,
41
- target platforms and appearance/asset needs. Get explicit approval and an instruction to
42
- implement before downloads or game-source edits. Required texture selection follows the plan.
43
- 5. **Required textures** — use threenative-asset-mcp (configured as `threenative-assets`). From
44
- the mechanics matches and reference image, if provided, identify only the textures needed by
45
- the plan. Call `asset_search_sources`, the returned source's search/list-files tools, then
42
+ A card states the numbers, never the arc. When the plan turns on how a mechanic looks moving
43
+ (jump arc, parry window, camera lag, hit reaction), watch a reference instead of inventing the
44
+ motion: `engine_watch_reference {query: "<game> <mechanic>", duration, frames}` returns a
45
+ `sheet.jpg` holding every frame in order; read it, then aim with `pick`, `from` and `at` when the
46
+ first sheet is a menu instead of gameplay. It needs `yt-dlp` and `ffmpeg`. Without the tool, fetch
47
+ `https://raw.githubusercontent.com/ThreeNativeHQ/threenative-reverse-engineer-mcp/main/scripts/watch.mjs`
48
+ and run it with `--duration 20 --frames 6`. Record the sheet path and the frame times with the
49
+ references. Frames are study material, not game assets: commit none of them, and cite a
50
+ mechanic from pinned `file:line`, never from a video. No network or no tools: record
51
+ `none: gameplay frames unavailable`.
52
+ 3. **Built-ins** — engine_capabilities built-in discovery, served by the same MCP: call
53
+ `engine_search_capabilities` with `scope: "mechanic"` per mechanic, system or symptom, and read
54
+ every row — it carries the import path, signature, example, constraints, overrides and
55
+ deprecations, so call `engine_capability_detail` only for a symbol the search did not return.
56
+ Record installed capabilities and binding constraints. A
57
+ `verdict: "none"` means game-owned behavior in `src/`; do not rephrase until something matches.
58
+ These role names add no servers.
59
+ 4. **Plan** — hand **Kit**, **Mechanics** and **References** to `prd-creator`. Plan the core loop
60
+ from both discovery passes, with controls, camera, state, acceptance checks, target platforms
61
+ and appearance/asset needs. With a user, get explicit approval and an instruction to implement
62
+ before downloads or game-source edits. Required texture selection follows the plan.
63
+ 5. **Assets** — use threenative-asset-mcp (configured as `threenative-assets`).
64
+ From the mechanics matches and reference image, if provided, identify only the textures needed by the plan. Call
65
+ `asset_search_sources`, the returned source's search/list-files tools, then
46
66
  `asset_download_file`; verify the returned licence and record downloaded paths/source/licence
47
67
  in `CREDITS.md`. Follow `.agents/skills/threenative-assets/SKILL.md`; no unrelated downloads or
48
68
  invented tool results. If no textures are required, record `none` and why. Reuse existing files.
49
- 6. **Execute** — execute plan, delegate to subagents focused on specific areas. Give each a
69
+ 6. **Build** — execute the plan, delegate to subagents focused on specific areas. Give each a
50
70
  bounded task, explicit file ownership, relevant context and an acceptance check; preserve other
51
71
  writers and avoid a single catch-all worker. The coordinator reviews and integrates the areas
52
72
  before step 7, resolving interfaces and failures rather than trusting worker reports. Use the
53
- chosen kit, discovered capabilities and downloaded textures. Keep appearance in game-owned `src/render/`; use stock
54
- `WorldEnvironment` defaults or explicitly report named overrides. Borrow mechanics only:
55
- no code, level layouts, character names or art; cite pinned `file:line` sources.
56
- 7. **Mechanics playtest** — follow `.agents/skills/threenative-playtest/SKILL.md`. Execute a
57
- fail-closed scenario for each core mechanic with observable state, real input actions and
58
- assertions. An empty assertion set or missing observation fails; a screenshot is not mechanics
59
- proof. Repair failures and rerun the affected scenario. Report only platforms actually run.
60
- 8. **Reference-image visual judge** — after mechanics pass, use
61
- `.agents/skills/threenative-visuals/SKILL.md` and the installed
62
- `node_modules/create-threenative/agent-docs/references/dream-loop.md`: compare a fresh, nonblank
63
- gameplay capture against the supplied reference image with a fresh read-only judge. If no
64
- image was supplied, ask for a supplied target or an explicitly authorized image-tool route,
65
- as that existing contract requires; do not invent a target or choose a provider/model.
66
- A missing target, capture or judgment is unverified, not a pass. Require `PASS`;
67
- `REQUEST_CHANGES` and `NOT_OBSERVED` block completion. Fix and rejudge against the same target.
73
+ chosen kit, discovered capabilities and downloaded textures. Keep appearance in game-owned
74
+ `src/render/`; use stock `WorldEnvironment` defaults or explicitly report named overrides.
75
+ Borrow mechanics only: no code, level layouts, character names or art; cite pinned `file:line`
76
+ sources.
77
+ 7. **Prove** — follow `.agents/skills/threenative-playtest/SKILL.md`. Execute a fail-closed
78
+ scenario for each core mechanic with observable state, real input actions and assertions. An
79
+ empty assertion set or missing observation fails; a screenshot is not mechanics proof. Repair
80
+ failures and rerun the affected scenario. Report only platforms actually run. After mechanics
81
+ pass, use `.agents/skills/threenative-visuals/SKILL.md` and the installed
82
+ `node_modules/create-threenative/agent-docs/references/dream-loop.md` for the
83
+ **Reference-image visual judge**: compare a fresh, nonblank gameplay capture against the supplied
84
+ reference image with a fresh read-only judge. If no image was supplied, ask for a supplied
85
+ target or an explicitly authorized image-tool route, as that existing contract requires; do not
86
+ invent a target or choose a provider/model. A missing target, capture or judgment is unverified,
87
+ not a pass. Require `PASS`; `REQUEST_CHANGES` and `NOT_OBSERVED` block completion. Fix and
88
+ rejudge against the same target.
89
+ 8. **Report** — give the user the `pnpm dev` URL, play from the spawn, and quote `TN_FRAME_BUDGET`,
90
+ `TN_SCENE_WARNING` and `TN_RENDER_PROJECTION`. Name every step you skipped and why.
68
91
 
69
92
  ## Existing game
70
93
 
71
- Use steps 5-7 only, with the existing game, plan, mechanics matches and reference context.
72
- Do not repeat kit selection, mechanics discovery or whole-game planning; do not invoke
73
- `prd-creator` just to restart the game plan. Do not add step 8 to this route. If another binding
74
- project gate conflicts, ask the user rather than silently waiving or appending it.
94
+ A change to an existing game skips step 1 and whole-game planning; do not invoke `prd-creator` just
95
+ to restart the game plan. For each change, search before you write:
75
96
 
76
- 5. **Required textures** — apply new-game step 5 to the requested change using existing context;
77
- reuse current assets and download only missing required textures. Ask a targeted question if
78
- essential context is missing instead of restarting discovery.
79
- 6. **Execute** — delegate to subagents focused on specific areas with bounded tasks and file ownership,
80
- using the existing game and plan. The coordinator reviews and integrates their changes before step 7;
81
- preserve established mechanics, assets, appearance choices and binding capability constraints.
82
- Apply the same step-6 ownership and acceptance checks above; do not restart planning or use a catch-all worker.
83
- 7. **Mechanics playtest** — execute step 7 for affected mechanics and their related regressions.
84
- Keep real captures where needed to observe the change; do not substitute them for assertions.
97
+ - Step 3 for every change: `engine_search_capabilities` with `scope: "mechanic"`, then read every
98
+ row — `engine_capability_detail` only for a symbol the search did not return — so installed
99
+ systems are reused.
100
+ - Step 2 for each gameplay mechanic the change adds or alters: `engine_search_references`, then
101
+ `engine_reference_detail`; use `engine_watch_reference` when the motion is the question.
102
+ - Steps 5-8 for the change, using the existing game, plan and context: apply step 5 to the
103
+ requested change (reuse current assets and download only missing required textures), step 6
104
+ with the same ownership and acceptance checks (a coordinator, no catch-all worker), step 7 for
105
+ affected mechanics and their related regressions (keep real captures where needed to observe the
106
+ change), and step 8 for the change.
107
+
108
+ Ask a targeted question if essential context is missing instead of restarting discovery. If another
109
+ binding project gate conflicts, ask the user rather than silently waiving or appending it.
85
110
 
86
111
  Returned capability constraints are binding, including `@threenative/physics/navigation` subpaths
87
112
  and platform support. Use `attachToBone` for held weapons (add a portable `Bone` named `RightHand`
88
113
  when needed) rather than rebuilding installed systems. If MCP
89
114
  is unavailable, run `npx threenative doctor`; for a new game's capability pass, use the installed
90
115
  `node_modules/create-threenative/agent-docs/references/capability-reference.md` and report missing
91
- services honestly. Existing games keep their existing context and requested 5-7 route.
116
+ services honestly.
@@ -0,0 +1,125 @@
1
+ #!/usr/bin/env node
2
+ // Discovery gate (PRD-827). Each user prompt records its time; the first new file under `src/`
3
+ // after it is blocked until `.threenative/engine-mcp.log` holds an `engine_search_capabilities`
4
+ // line newer than that prompt. The engine server writes the log for MCP and `call.mjs` calls
5
+ // alike, so one script serves Claude Code and Codex. Edits to existing files pass.
6
+ // `TN_DISCOVERY_GATE=off` opts out and says so once per session.
7
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
8
+ import path from "node:path";
9
+
10
+ const SEARCH =
11
+ 'mcp__threenative-engine__engine_search_capabilities {"situation": "<the mechanic or change>", "scope": "mechanic"}';
12
+ const BRIDGE =
13
+ 'node node_modules/@threenative/core/mcp/call.mjs threenative-engine engine_search_capabilities \'{"situation":"<the mechanic or change>"}\'';
14
+
15
+ function readJson(file, fallback) {
16
+ try {
17
+ return JSON.parse(readFileSync(file, "utf8"));
18
+ } catch {
19
+ return fallback;
20
+ }
21
+ }
22
+
23
+ /** Every path the tool call creates: `file_path`/`path` (Write, Edit) or `*** Add File:` lines
24
+ * in any string of the input (Codex `apply_patch`). */
25
+ function targets(input) {
26
+ const found = [];
27
+ const visit = (value) => {
28
+ if (typeof value === "string")
29
+ for (const match of value.matchAll(/^\*\*\* Add File: (.+)$/gmu)) found.push(match[1].trim());
30
+ else if (Array.isArray(value)) value.forEach(visit);
31
+ else if (value && typeof value === "object") Object.values(value).forEach(visit);
32
+ };
33
+ if (input && typeof input === "object") {
34
+ for (const key of ["file_path", "path"])
35
+ if (typeof input[key] === "string") found.push(input[key]);
36
+ }
37
+ visit(input);
38
+ return found;
39
+ }
40
+
41
+ function newSourceFiles(root, input) {
42
+ return targets(input)
43
+ .map((file) => path.resolve(root, file))
44
+ .filter((absolute) => !existsSync(absolute))
45
+ .map((absolute) => path.relative(root, absolute).split(path.sep).join("/"))
46
+ .filter((relative) => relative.startsWith("src/"));
47
+ }
48
+
49
+ function respond(output) {
50
+ process.stdout.write(`${JSON.stringify(output)}\n`);
51
+ }
52
+
53
+ function deny(reason) {
54
+ respond({
55
+ hookSpecificOutput: {
56
+ hookEventName: "PreToolUse",
57
+ permissionDecision: "deny",
58
+ permissionDecisionReason: reason,
59
+ },
60
+ });
61
+ }
62
+
63
+ function searchedSince(log, since) {
64
+ return log.split("\n").some((line) => {
65
+ if (!line.includes("engine_search_capabilities")) return false;
66
+ try {
67
+ const entry = JSON.parse(line);
68
+ return entry.tool === "engine_search_capabilities" && Date.parse(entry.time) > since;
69
+ } catch {
70
+ return false;
71
+ }
72
+ });
73
+ }
74
+
75
+ let input;
76
+ try {
77
+ input = JSON.parse(readFileSync(0, "utf8") || "{}");
78
+ } catch {
79
+ process.exit(0);
80
+ }
81
+ const root = process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd();
82
+ const stateFile = path.join(root, ".threenative", "discovery-gate.json");
83
+ const state = readJson(stateFile, {});
84
+ const save = (next) => {
85
+ mkdirSync(path.dirname(stateFile), { recursive: true });
86
+ writeFileSync(stateFile, `${JSON.stringify(next)}\n`);
87
+ };
88
+
89
+ if (input.hook_event_name === "UserPromptSubmit") {
90
+ save({ ...state, prompt: new Date().toISOString() });
91
+ process.exit(0);
92
+ }
93
+ if (input.hook_event_name !== "PreToolUse") process.exit(0);
94
+ const created = newSourceFiles(root, input.tool_input);
95
+ if (created.length === 0) process.exit(0);
96
+
97
+ if (process.env.TN_DISCOVERY_GATE === "off") {
98
+ if (state.optOutSession !== input.session_id) {
99
+ save({ ...state, optOutSession: input.session_id });
100
+ respond({
101
+ hookSpecificOutput: {
102
+ hookEventName: "PreToolUse",
103
+ additionalContext:
104
+ "TN_DISCOVERY_GATE=off: the discovery gate is off for this session, so new src/ files are written without an engine capability search. Report this opt-out to the user.",
105
+ },
106
+ });
107
+ }
108
+ process.exit(0);
109
+ }
110
+
111
+ const logFile = path.join(root, ".threenative", "engine-mcp.log");
112
+ let log;
113
+ try {
114
+ log = readFileSync(logFile, "utf8");
115
+ } catch (error) {
116
+ deny(
117
+ `Discovery gate: cannot read ${path.relative(root, logFile)} (${error.code ?? error.message}), so the engine was not searched in this project. Before you create ${created.join(", ")}, run ${SEARCH} and read every row; engine_capability_detail is only for a symbol the search did not return. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
118
+ );
119
+ process.exit(0);
120
+ }
121
+ const since = Date.parse(state.prompt ?? "") || 0;
122
+ if (!searchedSince(log, since))
123
+ deny(
124
+ `Discovery gate: no engine_search_capabilities call since the last user prompt. Before you create ${created.join(", ")}, run ${SEARCH} and read every row — engine_capability_detail is only for a symbol the search did not return — and use what it returns. Outside this folder: ${BRIDGE}. Opt out with TN_DISCOVERY_GATE=off.`,
125
+ );
@@ -13,7 +13,7 @@ const RULESET = [
13
13
  "",
14
14
  "Before writing code, stop at the first rung that holds (read the code the change touches first):",
15
15
  "1. Does this need to exist? No -> skip it (YAGNI).",
16
- "2. Follow `threenative-capabilities`: New games: steps 1-8 (discovery before `prd-creator`). Existing games: steps 5-7 only, reusing existing context without whole-game replanning. Step 6 delegates bounded areas with file ownership to subagents; the coordinator integrates before step 7. References borrow mechanics only: no code, level layouts, character names or art.",
16
+ "2. Follow the Authoring flow in `AGENTS.md` (`threenative-capabilities` skill): search capabilities and references before the first new `src/` file. References borrow mechanics only: no code, level layouts, character names or art.",
17
17
  "3. Already in this game? Reuse what is in `src/`.",
18
18
  "4. Stdlib or engine convention (loadAll, addInSlices, GroundSnap, an input vector, a physics query)? Use it.",
19
19
  "5. Already-installed dependency? Use it; add none for a few lines.",
@@ -1,4 +1,12 @@
1
1
  {
2
+ "enabledMcpjsonServers": [
3
+ "threenative-assets",
4
+ "threenative-sculpt",
5
+ "threenative-engine",
6
+ "threenative-terrain",
7
+ "threenative-animation",
8
+ "threenative-devtools"
9
+ ],
2
10
  "hooks": {
3
11
  "SessionStart": [
4
12
  {
@@ -19,6 +27,23 @@
19
27
  "type": "command",
20
28
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
21
29
  "timeout": 5
30
+ },
31
+ {
32
+ "type": "command",
33
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/discovery-gate.mjs\"",
34
+ "timeout": 5
35
+ }
36
+ ]
37
+ }
38
+ ],
39
+ "PreToolUse": [
40
+ {
41
+ "matcher": "Write|Edit|MultiEdit",
42
+ "hooks": [
43
+ {
44
+ "type": "command",
45
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/discovery-gate.mjs\"",
46
+ "timeout": 5
22
47
  }
23
48
  ]
24
49
  }
@@ -1,5 +1,5 @@
1
1
  {
2
- "description": "Project-scoped ponytail activation; review and trust it with /hooks.",
2
+ "description": "Project-scoped ponytail activation and the discovery gate; review and trust them with /hooks.",
3
3
  "hooks": {
4
4
  "SessionStart": [
5
5
  {
@@ -21,6 +21,23 @@
21
21
  "type": "command",
22
22
  "command": "node .claude/hooks/ponytail-context.mjs",
23
23
  "timeout": 5
24
+ },
25
+ {
26
+ "type": "command",
27
+ "command": "node .claude/hooks/discovery-gate.mjs",
28
+ "timeout": 5
29
+ }
30
+ ]
31
+ }
32
+ ],
33
+ "PreToolUse": [
34
+ {
35
+ "matcher": "apply_patch",
36
+ "hooks": [
37
+ {
38
+ "type": "command",
39
+ "command": "node .claude/hooks/discovery-gate.mjs",
40
+ "timeout": 5
24
41
  }
25
42
  ]
26
43
  }
package/dist/index.d.ts CHANGED
@@ -1,6 +1,41 @@
1
1
  #!/usr/bin/env node
2
2
  import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, IThreeNativeConfig, ThreeNativeUiRenderer, IThreeNativeAudioConfig, IThreeNativeLodConfig, IThreeNativeTexturesConfig } from '@threenative/core';
3
3
 
4
+ interface IEngineCatalogOptions {
5
+ /** "error" (the default) fails the edit and the build; "warn" reports, and the page throws at first use. */
6
+ readonly mode?: "error" | "warn";
7
+ }
8
+ interface ITransformContext {
9
+ error(failure: {
10
+ readonly message: string;
11
+ readonly id: string;
12
+ readonly loc?: {
13
+ readonly file: string;
14
+ readonly line: number;
15
+ readonly column: number;
16
+ };
17
+ }): never;
18
+ warn(message: string): void;
19
+ }
20
+ interface IEngineCatalogVitePlugin {
21
+ readonly name: string;
22
+ readonly enforce: "pre";
23
+ config(): {
24
+ worker: {
25
+ plugins: () => object[];
26
+ };
27
+ };
28
+ configResolved(config: {
29
+ readonly root: string;
30
+ }): Promise<void>;
31
+ transform(this: ITransformContext, code: string, id: string): Promise<null>;
32
+ }
33
+ /**
34
+ * Fails a game file's `import { X } from "three"` when the Wasm engine refuses `X` (PRD-830). Off,
35
+ * and reported once, under `engine: "threejs"` and for the native host's bundle.
36
+ */
37
+ declare function createEngineCatalogPlugin(options?: IEngineCatalogOptions): IEngineCatalogVitePlugin;
38
+
4
39
  interface IEngineFreshnessVitePlugin {
5
40
  readonly name: string;
6
41
  config(config: {
@@ -51,6 +86,7 @@ interface IResolvedThreeNativeConfig {
51
86
  readonly orientation: ThreeNativeOrientation;
52
87
  readonly fullscreen: boolean;
53
88
  readonly keepScreenOn: boolean;
89
+ readonly priority: "game" | "normal";
54
90
  readonly maxFps: number;
55
91
  };
56
92
  readonly window: {
@@ -214,8 +250,11 @@ interface IWebBrandVitePlugin {
214
250
  load(id: string): Promise<string | null>;
215
251
  configResolved(config: {
216
252
  readonly root: string;
253
+ readonly command?: "build" | "serve";
217
254
  }): Promise<void>;
218
- transformIndexHtml(html: string): string;
255
+ transformIndexHtml(html: string, context?: {
256
+ readonly bundle?: Readonly<Record<string, IBundleFile>>;
257
+ }): string;
219
258
  configureServer(server: IMiddlewareServer): void;
220
259
  configurePreviewServer(server: IMiddlewareServer): void;
221
260
  generateBundle(this: {
@@ -237,15 +276,30 @@ interface IMiddlewareServer {
237
276
  use(handler: Middleware): void;
238
277
  };
239
278
  }
279
+ interface IBundleFile {
280
+ readonly fileName: string;
281
+ readonly type: string;
282
+ readonly moduleIds?: readonly string[];
283
+ }
240
284
  declare function renderWebManifest(root: string, config: IResolvedThreeNativeConfig): string;
241
285
  declare function createWebBrandPlugin(): IWebBrandVitePlugin;
242
286
 
243
287
  /**
244
- * The asset decoders the web engine ships: its glTF loader decodes neither KTX2 nor Meshopt (addons/gltf-loader-web.ts), so a
245
- * native-engine game's models are cooked without it, which is also the cooker's default. `engine: "threejs"` names both.
246
- * `threenative build` and each template's dev-server asset watch both read it, so the two cook the same bytes.
288
+ * The asset decoders the web build ships, per format.
289
+ *
290
+ * Meshopt geometry decodes on both engines: on `engine: "threenative"` the engine's own glTF loader
291
+ * decompresses EXT/KHR_meshopt_compression with meshoptimizer, which `pnpm wasm:build` provisions
292
+ * and without which the `tn-native-engine-web` target refuses to link (PRD-861).
293
+ *
294
+ * KTX2 decodes on both engines too: the owned engine transcodes KHR_texture_basisu to BC7 or ETC2
295
+ * and uploads the blocks, or RGBA8 on a device with neither (PRD-867), and three's KTX2Loader runs
296
+ * on it. The web cook keeps an authored WebP a KTX2 cannot undercut, so Midway's KTX2 cook is
297
+ * 98,236,952 B against 125,132,608 B with WebP model textures.
298
+ *
299
+ * `threenative build` and each template's dev-server asset watch both read it, so the two cook the
300
+ * same bytes.
247
301
  */
248
- declare function webRuntimeDecoders(config: {
302
+ declare function webRuntimeDecoders(_config: {
249
303
  readonly engine?: "threejs" | "threenative";
250
304
  }): {
251
305
  readonly ktx2: boolean;
@@ -307,8 +361,19 @@ declare function stampLoadingSource(canonical: string, template: string): string
307
361
  * render-chain plumbing is not: it is the same 600 lines in every kit, and keeping seven copies by
308
362
  * hand let one fall a revision behind without anything failing. A file belongs here only when a
309
363
  * kit editing it would be a mistake rather than a choice.
364
+ *
365
+ * `__tests__/shared-render-drift.spec.ts` fails on any render source that ships byte-identical in
366
+ * two or more kits and is missing here, so a new copy cannot land unrestamped. The environment
367
+ * measure-and-sample mechanism and the backlight used to be seven of these copies; they live in
368
+ * `@threenative/core/render/environment` now (PRD-833).
310
369
  */
311
370
  declare const SHARED_RENDER_SOURCES: readonly string[];
371
+ /**
372
+ * The shared sources `createProject` also writes into a kit that does not ship them. A kit owns its
373
+ * look, so presence is per kit: `starter` ships the temporal detail stage and the collectathon kits
374
+ * do not, and all four still get the same plumbing.
375
+ */
376
+ declare const ADDED_RENDER_SOURCES: readonly string[];
312
377
  declare function canonicalRenderSourcePath(relativePath: string, root?: string): string;
313
378
  /** Re-copies every shared render source into each kit that ships it. */
314
379
  declare function restampSharedRenderCopies(root?: string): Promise<readonly string[]>;
@@ -339,10 +404,36 @@ declare function projectMcpServers(target: string): string[];
339
404
  */
340
405
  declare function referenceDigest(target: string, genre: string, run?: (args: string[]) => string): string;
341
406
  declare function cliHelp(): string;
407
+ interface IAuthoringLayerStatus {
408
+ /** The create-threenative version running this check, which is the one the game installed. */
409
+ readonly installed: string;
410
+ readonly kit?: string;
411
+ /** Why the layer cannot be checked; set instead of `stale`'s meaning. */
412
+ readonly problem?: string;
413
+ /** Layer paths whose bytes differ from the installed package, and dropped files still present. */
414
+ readonly stale: readonly string[];
415
+ readonly stamped?: string;
416
+ }
417
+ interface IAuthoringLayerFix {
418
+ readonly deleted: readonly string[];
419
+ readonly kept: readonly string[];
420
+ readonly written: readonly string[];
421
+ }
422
+ /** How far the game's authoring layer is from what the installed create-threenative renders. */
423
+ declare function authoringLayerStatus(game: string, root?: string): Promise<IAuthoringLayerStatus>;
424
+ /**
425
+ * `threenative doctor --fix` (PRD-829): re-renders the authoring layer from the installed package with
426
+ * the scaffold's writers. A file whose bytes still match the stamp is overwritten, an edited one is
427
+ * kept unless `force`, and a file the package dropped is deleted only when unedited. Without a stamp,
428
+ * every differing file counts as edited.
429
+ */
430
+ declare function fixAuthoringLayer(game: string, options: {
431
+ readonly force: boolean;
432
+ }, root?: string): Promise<IAuthoringLayerFix>;
342
433
  declare function createProject(options: IScaffoldOptions, cwd?: string, root?: string): Promise<IScaffoldResult>;
343
434
  /** The inverse of `scripts/workspace-packages.ts`'s `workspacePackageSourceFlag`; exported so
344
435
  * the pair is gated rather than trusted. */
345
436
  declare function packageNameFromFlag(flag: string): string | undefined;
346
437
  declare function parseArgs(argv: readonly string[]): IScaffoldOptions;
347
438
 
348
- export { type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, projectMcpServers, referenceDigest, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, scaffoldNextSteps, stampLoadingSource, templateForGenre, templateRoot, webRuntimeDecoders };
439
+ export { ADDED_RENDER_SOURCES, type IAuthoringLayerFix, type IAuthoringLayerStatus, type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, authoringLayerStatus, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineCatalogPlugin, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, fixAuthoringLayer, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, projectMcpServers, referenceDigest, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, scaffoldNextSteps, stampLoadingSource, templateForGenre, templateRoot, webRuntimeDecoders };