create-threenative 0.2.10 → 0.2.12

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 (737) hide show
  1. package/agent-docs/references/assertion-reference.md +109 -3
  2. package/agent-docs/references/auto-exposure.md +28 -45
  3. package/agent-docs/references/build-profiles.md +1 -1
  4. package/agent-docs/references/capability-reference.md +527 -44
  5. package/agent-docs/references/debug-surface.md +64 -0
  6. package/agent-docs/references/finding-assets.md +11 -12
  7. package/agent-docs/references/performance-basics.md +19 -0
  8. package/agent-docs/references/trace-a-slow-frame.md +21 -0
  9. package/agent-docs/references/visual-baseline.md +23 -4
  10. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/prd-creator/SKILL.md +17 -6
  12. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +87 -23
  13. package/agent-files/.agents/skills/threenative-performance/SKILL.md +12 -11
  14. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  15. package/agent-files/scripts/reference.mjs +9 -4
  16. package/capabilities.json +739 -50
  17. package/dist/index.d.ts +40 -6
  18. package/dist/index.js +227 -34
  19. package/dist/quality.d.ts +12 -0
  20. package/dist/quality.js +166747 -0
  21. package/dist/threenative.js +60 -44
  22. package/dist/web-engine-gltf-loader.js +2 -0
  23. package/dist/web-engine-mesh-bvh-webgpu.js +1 -1
  24. package/dist/web-engine-mesh-bvh.js +7 -0
  25. package/dist/web-engine-post-effects.js +645 -19
  26. package/dist/web-engine-runtime.js +3528 -343
  27. package/package.json +19 -9
  28. package/template-assets/assets/bay-PROVENANCE.md +21 -0
  29. package/template-assets/assets/bay-ground.webp +0 -0
  30. package/template-assets/assets/bay-metal.webp +0 -0
  31. package/template-assets/assets/bay-pavement-normal.webp +0 -0
  32. package/template-assets/assets/bay-pavement.webp +0 -0
  33. package/template-assets/assets/bay-plaster-normal.webp +0 -0
  34. package/template-assets/assets/bay-plaster.webp +0 -0
  35. package/template-assets/assets/bay-wood-normal.webp +0 -0
  36. package/template-assets/assets/bay-wood.webp +0 -0
  37. package/template-assets/assets/tex-PROVENANCE.md +25 -0
  38. package/template-assets/assets/tex-bark-normal.webp +0 -0
  39. package/template-assets/assets/tex-bark.webp +0 -0
  40. package/template-assets/assets/tex-birch-bark.webp +0 -0
  41. package/template-assets/assets/tex-grass.webp +0 -0
  42. package/template-assets/assets/tex-planks-normal.webp +0 -0
  43. package/template-assets/assets/tex-planks.webp +0 -0
  44. package/template-assets/assets/tex-rock-normal.webp +0 -0
  45. package/template-assets/assets/tex-rock.webp +0 -0
  46. package/template-assets/assets/tex-roof-tiles-normal.webp +0 -0
  47. package/template-assets/assets/tex-roof-tiles.webp +0 -0
  48. package/template-assets/assets/tex-sand-normal.webp +0 -0
  49. package/template-assets/assets/tex-sand.webp +0 -0
  50. package/template-assets/assets/tex-stone-wall-normal.webp +0 -0
  51. package/template-assets/assets/tex-stone-wall.webp +0 -0
  52. package/template-assets/kitExposure.ts +20 -0
  53. package/template-assets/patches/three@0.185.1.patch +481 -272
  54. package/template-assets/quality/biome.json +7 -0
  55. package/template-assets/quality/eslint.config.js +3 -0
  56. package/template-assets/realistic-ocean/README.md +113 -0
  57. package/template-assets/realistic-ocean/install.mjs +56 -0
  58. package/template-assets/realistic-ocean/src/realisticOcean.ts +151 -0
  59. package/template-assets/realistic-ocean/src/realisticOceanLifetime.ts +29 -0
  60. package/template-assets/realistic-ocean/src/render/REALISTIC-OCEAN-LICENSE.txt +25 -0
  61. package/template-assets/realistic-ocean/src/render/realisticSea.ts +642 -0
  62. package/template-assets/realistic-ocean/src/render/realisticSeaMaps.ts +311 -0
  63. package/template-assets/realistic-ocean/src/render/realisticSpectrum.ts +289 -0
  64. package/templates/AGENTS.md +21 -0
  65. package/templates/CLAUDE.md +23 -0
  66. package/templates/action-rpg/.codex/config.toml +6 -2
  67. package/templates/action-rpg/.cursor/mcp.json +8 -2
  68. package/templates/action-rpg/.gemini/settings.json +8 -2
  69. package/templates/action-rpg/.mcp.json +8 -2
  70. package/templates/action-rpg/.vscode/mcp.json +9 -2
  71. package/templates/action-rpg/.zed/settings.json +9 -2
  72. package/templates/action-rpg/AGENTS.md +11 -11
  73. package/templates/action-rpg/CLAUDE.md +11 -11
  74. package/templates/action-rpg/opencode.json +10 -2
  75. package/templates/action-rpg/package.json +15 -10
  76. package/templates/action-rpg/playtests/combat.playtest.json +6 -0
  77. package/templates/action-rpg/playtests/inventory.playtest.json +22 -0
  78. package/templates/action-rpg/playtests/performance.playtest.json +1 -1
  79. package/templates/action-rpg/playtests/roll.playtest.json +112 -0
  80. package/templates/action-rpg/playtests/swing.playtest.json +55 -0
  81. package/templates/action-rpg/playtests/win.playtest.json +4 -4
  82. package/templates/action-rpg/src/entities/Fighter.ts +44 -4
  83. package/templates/action-rpg/src/entities/Player.ts +64 -12
  84. package/templates/action-rpg/src/render/atmosphere.ts +444 -0
  85. package/templates/action-rpg/src/render/backlightMaterial.ts +49 -18
  86. package/templates/action-rpg/src/render/clouds.ts +605 -0
  87. package/templates/action-rpg/src/render/dungeon.ts +8 -6
  88. package/templates/action-rpg/src/render/exposure.ts +11 -109
  89. package/templates/action-rpg/src/render/gpuSky.ts +752 -0
  90. package/templates/action-rpg/src/render/lighting.ts +27 -4
  91. package/templates/action-rpg/src/render/materialLighting.ts +2 -11
  92. package/templates/action-rpg/src/render/palette.ts +1 -0
  93. package/templates/action-rpg/src/render/postprocessing.ts +4 -4
  94. package/templates/action-rpg/src/render/props.ts +10 -8
  95. package/templates/action-rpg/src/render/quality.ts +56 -108
  96. package/templates/action-rpg/src/render/sky.ts +74 -1
  97. package/templates/action-rpg/src/scenes/Play.ts +16 -12
  98. package/templates/action-rpg/src/ui/CharacterPanel.tsx +7 -2
  99. package/templates/action-rpg/src/ui/Hud.tsx +5 -7
  100. package/templates/action-rpg/src/ui/InventoryPanel.tsx +14 -14
  101. package/templates/action-rpg/threenative.config.ts +3 -0
  102. package/templates/adventure/.codex/config.toml +23 -0
  103. package/templates/adventure/.cursor/mcp.json +38 -0
  104. package/templates/adventure/.gemini/settings.json +38 -0
  105. package/templates/adventure/.mcp.json +38 -0
  106. package/templates/adventure/.vscode/mcp.json +43 -0
  107. package/templates/adventure/.zed/settings.json +43 -0
  108. package/templates/adventure/AGENTS.md +60 -0
  109. package/templates/adventure/CLAUDE.md +62 -0
  110. package/templates/adventure/index.html +14 -0
  111. package/templates/adventure/kit.json +8 -0
  112. package/templates/adventure/native-playtests/survives.playtest.json +52 -0
  113. package/templates/adventure/opencode.json +49 -0
  114. package/templates/adventure/package.json +65 -0
  115. package/templates/adventure/playtests/boss.playtest.json +406 -0
  116. package/templates/adventure/playtests/combat.playtest.json +342 -0
  117. package/templates/adventure/playtests/controls.playtest.json +142 -0
  118. package/templates/adventure/playtests/explore.playtest.json +45 -0
  119. package/templates/adventure/playtests/flicker.playtest.json +206 -0
  120. package/templates/adventure/playtests/hearts.playtest.json +171 -0
  121. package/templates/adventure/playtests/lockon.playtest.json +256 -0
  122. package/templates/adventure/playtests/look.playtest.json +72 -0
  123. package/templates/adventure/playtests/move-hollow.playtest.json +106 -0
  124. package/templates/adventure/playtests/move.playtest.json +84 -0
  125. package/templates/adventure/playtests/performance.playtest.json +55 -0
  126. package/templates/adventure/playtests/puzzle.playtest.json +250 -0
  127. package/templates/adventure/playtests/stride.playtest.json +67 -0
  128. package/templates/adventure/playtests/survives.playtest.json +171 -0
  129. package/templates/adventure/playtests/thornback.playtest.json +267 -0
  130. package/templates/adventure/public/favicon.svg +4 -0
  131. package/templates/adventure/src/entities/Block.ts +114 -0
  132. package/templates/adventure/src/entities/Chest.ts +69 -0
  133. package/templates/adventure/src/entities/Door.ts +81 -0
  134. package/templates/adventure/src/entities/Dummy.ts +69 -0
  135. package/templates/adventure/src/entities/Flicker.ts +239 -0
  136. package/templates/adventure/src/entities/Hero.ts +561 -0
  137. package/templates/adventure/src/entities/LockOn.ts +180 -0
  138. package/templates/adventure/src/entities/Mossling.ts +249 -0
  139. package/templates/adventure/src/entities/Switch.ts +49 -0
  140. package/templates/adventure/src/entities/Thornback.ts +238 -0
  141. package/templates/adventure/src/entities/Warden.ts +196 -0
  142. package/templates/adventure/src/game.ts +65 -0
  143. package/templates/adventure/src/interact.ts +63 -0
  144. package/templates/adventure/src/level/Hollow.ts +240 -0
  145. package/templates/adventure/src/level/Vale.ts +383 -0
  146. package/templates/adventure/src/main.ts +18 -0
  147. package/templates/adventure/src/render/camera.ts +416 -0
  148. package/templates/adventure/src/render/creatures.ts +405 -0
  149. package/templates/adventure/src/render/effects.ts +333 -0
  150. package/templates/adventure/src/render/foliage.ts +1072 -0
  151. package/templates/adventure/src/render/hero.ts +1447 -0
  152. package/templates/adventure/src/render/kitExposure.ts +20 -0
  153. package/templates/adventure/src/render/lighting.ts +74 -0
  154. package/templates/adventure/src/render/loading.ts +332 -0
  155. package/templates/adventure/src/render/materials.ts +179 -0
  156. package/templates/adventure/src/render/palette.ts +137 -0
  157. package/templates/adventure/src/render/postprocessing.ts +70 -0
  158. package/templates/adventure/src/render/props.ts +383 -0
  159. package/templates/adventure/src/render/quality.ts +46 -0
  160. package/templates/adventure/src/render/sky.ts +271 -0
  161. package/templates/adventure/src/render/surface.ts +259 -0
  162. package/templates/adventure/src/render/touch-controls.ts +137 -0
  163. package/templates/adventure/src/scenes/Play.ts +959 -0
  164. package/templates/adventure/src/state.ts +113 -0
  165. package/templates/adventure/src/style.css +98 -0
  166. package/templates/adventure/src/ui/App.tsx +22 -0
  167. package/templates/adventure/src/ui/GameUi.tsx +20 -0
  168. package/templates/adventure/src/ui/Hud.tsx +70 -0
  169. package/templates/adventure/src/ui/Menu.tsx +15 -0
  170. package/templates/adventure/src/ui/main.tsx +14 -0
  171. package/templates/adventure/tailwind.config.ts +2 -0
  172. package/templates/adventure/threenative.config.ts +62 -0
  173. package/templates/adventure/tsconfig.json +17 -0
  174. package/templates/adventure/vite.config.ts +49 -0
  175. package/templates/collectathon/.codex/config.toml +23 -0
  176. package/templates/collectathon/.cursor/mcp.json +38 -0
  177. package/templates/collectathon/.gemini/settings.json +38 -0
  178. package/templates/collectathon/.mcp.json +38 -0
  179. package/templates/collectathon/.vscode/mcp.json +43 -0
  180. package/templates/collectathon/.zed/settings.json +43 -0
  181. package/templates/collectathon/AGENTS.md +58 -0
  182. package/templates/collectathon/CLAUDE.md +60 -0
  183. package/templates/collectathon/index.html +14 -0
  184. package/templates/collectathon/kit.json +8 -0
  185. package/templates/collectathon/native-playtests/survives.playtest.json +52 -0
  186. package/templates/collectathon/opencode.json +49 -0
  187. package/templates/collectathon/package.json +65 -0
  188. package/templates/collectathon/playtests/acrobatics.playtest.json +238 -0
  189. package/templates/collectathon/playtests/camera.playtest.json +80 -0
  190. package/templates/collectathon/playtests/clipped-probe.playtest.json +101 -0
  191. package/templates/collectathon/playtests/collect.playtest.json +196 -0
  192. package/templates/collectathon/playtests/combat.playtest.json +246 -0
  193. package/templates/collectathon/playtests/double-tap-air.playtest.json +198 -0
  194. package/templates/collectathon/playtests/double-tap.playtest.json +136 -0
  195. package/templates/collectathon/playtests/effects.playtest.json +124 -0
  196. package/templates/collectathon/playtests/enemies.playtest.json +295 -0
  197. package/templates/collectathon/playtests/explore.playtest.json +45 -0
  198. package/templates/collectathon/playtests/hop-reach.playtest.json +117 -0
  199. package/templates/collectathon/playtests/jump-chain.playtest.json +274 -0
  200. package/templates/collectathon/playtests/ledge-angle.playtest.json +107 -0
  201. package/templates/collectathon/playtests/ledge-too-high.playtest.json +115 -0
  202. package/templates/collectathon/playtests/ledge.playtest.json +100 -0
  203. package/templates/collectathon/playtests/look.playtest.json +64 -0
  204. package/templates/collectathon/playtests/performance.playtest.json +55 -0
  205. package/templates/collectathon/playtests/stride.playtest.json +111 -0
  206. package/templates/collectathon/playtests/survives.playtest.json +123 -0
  207. package/templates/collectathon/playtests/telegraphs.playtest.json +132 -0
  208. package/templates/collectathon/playtests/thornback.playtest.json +157 -0
  209. package/templates/collectathon/playtests/wall-kick.playtest.json +206 -0
  210. package/templates/collectathon/playtests/win.playtest.json +166 -0
  211. package/templates/collectathon/public/favicon.svg +4 -0
  212. package/templates/collectathon/src/entities/Hero.ts +915 -0
  213. package/templates/collectathon/src/entities/Pickup.ts +63 -0
  214. package/templates/collectathon/src/entities/Walker.ts +248 -0
  215. package/templates/collectathon/src/game.ts +51 -0
  216. package/templates/collectathon/src/level/Course.ts +590 -0
  217. package/templates/collectathon/src/level/terrain.ts +144 -0
  218. package/templates/collectathon/src/main.ts +14 -0
  219. package/templates/collectathon/src/playtest-events.ts +15 -0
  220. package/templates/collectathon/src/render/camera.ts +163 -0
  221. package/templates/collectathon/src/render/castle.ts +408 -0
  222. package/templates/collectathon/src/render/effects.ts +284 -0
  223. package/templates/collectathon/src/render/foliage.ts +744 -0
  224. package/templates/collectathon/src/render/ground.ts +139 -0
  225. package/templates/collectathon/src/render/hero.ts +452 -0
  226. package/templates/collectathon/src/render/kitExposure.ts +20 -0
  227. package/templates/collectathon/src/render/lighting.ts +65 -0
  228. package/templates/collectathon/src/render/loading.ts +332 -0
  229. package/templates/collectathon/src/render/materials.ts +196 -0
  230. package/templates/collectathon/src/render/palette.ts +82 -0
  231. package/templates/collectathon/src/render/postprocessing.ts +79 -0
  232. package/templates/collectathon/src/render/props.ts +218 -0
  233. package/templates/collectathon/src/render/quality.ts +54 -0
  234. package/templates/collectathon/src/render/sky.ts +262 -0
  235. package/templates/collectathon/src/render/surface.ts +269 -0
  236. package/templates/collectathon/src/render/touch-controls.ts +179 -0
  237. package/templates/collectathon/src/render/touch-layout.ts +48 -0
  238. package/templates/collectathon/src/render/water.ts +191 -0
  239. package/templates/collectathon/src/scenes/Play.ts +481 -0
  240. package/templates/collectathon/src/state.ts +38 -0
  241. package/templates/collectathon/src/style.css +106 -0
  242. package/templates/collectathon/src/ui/App.tsx +22 -0
  243. package/templates/collectathon/src/ui/GameUi.tsx +20 -0
  244. package/templates/collectathon/src/ui/Hud.tsx +77 -0
  245. package/templates/collectathon/src/ui/Menu.tsx +13 -0
  246. package/templates/collectathon/src/ui/main.tsx +14 -0
  247. package/templates/collectathon/tailwind.config.ts +2 -0
  248. package/templates/collectathon/threenative.config.ts +62 -0
  249. package/templates/collectathon/tsconfig.json +17 -0
  250. package/templates/collectathon/vite.config.ts +49 -0
  251. package/templates/kart/.codex/config.toml +23 -0
  252. package/templates/kart/.cursor/mcp.json +38 -0
  253. package/templates/kart/.gemini/settings.json +38 -0
  254. package/templates/kart/.mcp.json +38 -0
  255. package/templates/kart/.vscode/mcp.json +43 -0
  256. package/templates/kart/.zed/settings.json +43 -0
  257. package/templates/kart/AGENTS.md +58 -0
  258. package/templates/kart/CLAUDE.md +60 -0
  259. package/templates/kart/index.html +14 -0
  260. package/templates/kart/kit.json +8 -0
  261. package/templates/kart/native-playtests/survives.playtest.json +65 -0
  262. package/templates/kart/opencode.json +49 -0
  263. package/templates/kart/package.json +64 -0
  264. package/templates/kart/playtests/drift.playtest.json +226 -0
  265. package/templates/kart/playtests/explore.playtest.json +45 -0
  266. package/templates/kart/playtests/hit-stays-above-road.playtest.json +92 -0
  267. package/templates/kart/playtests/item-key.playtest.json +108 -0
  268. package/templates/kart/playtests/items.playtest.json +143 -0
  269. package/templates/kart/playtests/lap-times.playtest.json +138 -0
  270. package/templates/kart/playtests/laps.playtest.json +149 -0
  271. package/templates/kart/playtests/performance.playtest.json +57 -0
  272. package/templates/kart/playtests/race.playtest.json +294 -0
  273. package/templates/kart/playtests/restart.playtest.json +87 -0
  274. package/templates/kart/playtests/rocket-start.playtest.json +56 -0
  275. package/templates/kart/playtests/smooth-drive.playtest.json +101 -0
  276. package/templates/kart/playtests/surfaces.playtest.json +113 -0
  277. package/templates/kart/playtests/survives.playtest.json +116 -0
  278. package/templates/kart/playtests/wall.playtest.json +118 -0
  279. package/templates/kart/public/favicon.svg +4 -0
  280. package/templates/kart/src/entities/Driver.ts +123 -0
  281. package/templates/kart/src/entities/Items.ts +194 -0
  282. package/templates/kart/src/entities/Kart.ts +517 -0
  283. package/templates/kart/src/game.ts +45 -0
  284. package/templates/kart/src/main.ts +14 -0
  285. package/templates/kart/src/playtest-events.ts +15 -0
  286. package/templates/kart/src/render/camera.ts +83 -0
  287. package/templates/kart/src/render/course.ts +579 -0
  288. package/templates/kart/src/render/effects.ts +266 -0
  289. package/templates/kart/src/render/items.ts +163 -0
  290. package/templates/kart/src/render/kart.ts +256 -0
  291. package/templates/kart/src/render/kitExposure.ts +20 -0
  292. package/templates/kart/src/render/lighting.ts +58 -0
  293. package/templates/kart/src/render/loading.ts +332 -0
  294. package/templates/kart/src/render/materials.ts +119 -0
  295. package/templates/kart/src/render/palette.ts +74 -0
  296. package/templates/kart/src/render/postprocessing.ts +79 -0
  297. package/templates/kart/src/render/quality.ts +54 -0
  298. package/templates/kart/src/render/skids.ts +86 -0
  299. package/templates/kart/src/render/sky.ts +105 -0
  300. package/templates/kart/src/render/touch-controls.ts +168 -0
  301. package/templates/kart/src/render/touch-layout.ts +48 -0
  302. package/templates/kart/src/scenes/Race.ts +850 -0
  303. package/templates/kart/src/state.ts +53 -0
  304. package/templates/kart/src/style.css +106 -0
  305. package/templates/kart/src/track/Course.ts +276 -0
  306. package/templates/kart/src/track/Race.ts +133 -0
  307. package/templates/kart/src/ui/App.tsx +21 -0
  308. package/templates/kart/src/ui/GameUi.tsx +20 -0
  309. package/templates/kart/src/ui/Hud.tsx +172 -0
  310. package/templates/kart/src/ui/Menu.tsx +13 -0
  311. package/templates/kart/src/ui/main.tsx +14 -0
  312. package/templates/kart/tailwind.config.ts +2 -0
  313. package/templates/kart/threenative.config.ts +62 -0
  314. package/templates/kart/tsconfig.json +17 -0
  315. package/templates/kart/vite.config.ts +49 -0
  316. package/templates/minimal/.codex/config.toml +6 -2
  317. package/templates/minimal/.cursor/mcp.json +8 -2
  318. package/templates/minimal/.gemini/settings.json +8 -2
  319. package/templates/minimal/.mcp.json +8 -2
  320. package/templates/minimal/.vscode/mcp.json +9 -2
  321. package/templates/minimal/.zed/settings.json +9 -2
  322. package/templates/minimal/AGENTS.md +11 -13
  323. package/templates/minimal/CLAUDE.md +11 -13
  324. package/templates/minimal/opencode.json +10 -2
  325. package/templates/minimal/package.json +14 -9
  326. package/templates/minimal/playtests/camera-wall.playtest.json +36 -0
  327. package/templates/minimal/playtests/jump.playtest.json +45 -0
  328. package/templates/minimal/playtests/play.playtest.json +1 -1
  329. package/templates/minimal/src/game.ts +2 -0
  330. package/templates/minimal/src/render/atmosphere.ts +444 -0
  331. package/templates/minimal/src/render/backlightMaterial.ts +49 -18
  332. package/templates/minimal/src/render/camera.ts +35 -4
  333. package/templates/minimal/src/render/clouds.ts +605 -0
  334. package/templates/minimal/src/render/exposure.ts +7 -111
  335. package/templates/minimal/src/render/gpuSky.ts +752 -0
  336. package/templates/minimal/src/render/lighting.ts +26 -4
  337. package/templates/minimal/src/render/materialLighting.ts +2 -10
  338. package/templates/minimal/src/render/postprocessing.ts +4 -4
  339. package/templates/minimal/src/render/quality.ts +10 -116
  340. package/templates/minimal/src/render/sky.ts +73 -1
  341. package/templates/minimal/src/scenes/Play.ts +18 -7
  342. package/templates/platformer/.codex/config.toml +6 -2
  343. package/templates/platformer/.cursor/mcp.json +8 -2
  344. package/templates/platformer/.gemini/settings.json +8 -2
  345. package/templates/platformer/.mcp.json +8 -2
  346. package/templates/platformer/.vscode/mcp.json +9 -2
  347. package/templates/platformer/.zed/settings.json +9 -2
  348. package/templates/platformer/AGENTS.md +13 -9
  349. package/templates/platformer/CLAUDE.md +13 -9
  350. package/templates/platformer/opencode.json +10 -2
  351. package/templates/platformer/package.json +15 -10
  352. package/templates/platformer/playtests/dash-jump.playtest.json +34 -0
  353. package/templates/platformer/playtests/finish.playtest.json +58 -0
  354. package/templates/platformer/playtests/idle.playtest.json +44 -0
  355. package/templates/platformer/playtests/performance.playtest.json +1 -1
  356. package/templates/platformer/src/entities/Fox.ts +19 -6
  357. package/templates/platformer/src/game.ts +1 -0
  358. package/templates/platformer/src/level/Stage.ts +4 -1
  359. package/templates/platformer/src/render/backlightMaterial.ts +49 -18
  360. package/templates/platformer/src/render/camera.ts +30 -1
  361. package/templates/platformer/src/render/exposure.ts +6 -111
  362. package/templates/platformer/src/render/fox.ts +5 -2
  363. package/templates/platformer/src/render/kitExposure.ts +20 -0
  364. package/templates/platformer/src/render/materialLighting.ts +2 -11
  365. package/templates/platformer/src/render/postprocessing.ts +4 -4
  366. package/templates/platformer/src/render/props.ts +1 -2
  367. package/templates/platformer/src/render/quality.ts +10 -118
  368. package/templates/platformer/src/scenes/Play.ts +31 -15
  369. package/templates/platformer/src/ui/Menu.tsx +1 -1
  370. package/templates/puzzle/.codex/config.toml +6 -2
  371. package/templates/puzzle/.cursor/mcp.json +8 -2
  372. package/templates/puzzle/.gemini/settings.json +8 -2
  373. package/templates/puzzle/.mcp.json +8 -2
  374. package/templates/puzzle/.vscode/mcp.json +9 -2
  375. package/templates/puzzle/.zed/settings.json +9 -2
  376. package/templates/puzzle/AGENTS.md +14 -17
  377. package/templates/puzzle/CLAUDE.md +14 -17
  378. package/templates/puzzle/opencode.json +10 -2
  379. package/templates/puzzle/package.json +15 -10
  380. package/templates/puzzle/playtests/performance.playtest.json +1 -1
  381. package/templates/puzzle/playtests/replay-keeps-progress.playtest.json +78 -0
  382. package/templates/puzzle/src/render/backlightMaterial.ts +49 -18
  383. package/templates/puzzle/src/render/exposure.ts +11 -109
  384. package/templates/puzzle/src/render/lighting.ts +3 -3
  385. package/templates/puzzle/src/render/materialLighting.ts +2 -11
  386. package/templates/puzzle/src/render/palette.ts +1 -1
  387. package/templates/puzzle/src/render/postprocessing.ts +4 -4
  388. package/templates/puzzle/src/render/quality.ts +44 -153
  389. package/templates/puzzle/src/render/vault.ts +18 -6
  390. package/templates/puzzle/src/scenes/Play.ts +6 -1
  391. package/templates/puzzle/src/ui/Hud.tsx +8 -43
  392. package/templates/racing/.codex/config.toml +6 -2
  393. package/templates/racing/.cursor/mcp.json +8 -2
  394. package/templates/racing/.gemini/settings.json +8 -2
  395. package/templates/racing/.mcp.json +8 -2
  396. package/templates/racing/.vscode/mcp.json +9 -2
  397. package/templates/racing/.zed/settings.json +9 -2
  398. package/templates/racing/AGENTS.md +10 -12
  399. package/templates/racing/CLAUDE.md +10 -12
  400. package/templates/racing/opencode.json +10 -2
  401. package/templates/racing/package.json +15 -10
  402. package/templates/racing/playtests/brake.playtest.json +54 -0
  403. package/templates/racing/playtests/outcome.playtest.json +19 -0
  404. package/templates/racing/playtests/performance.playtest.json +1 -1
  405. package/templates/racing/playtests/stopped-car-is-not-rescued.playtest.json +59 -0
  406. package/templates/racing/src/entities/RacingCar.ts +12 -3
  407. package/templates/racing/src/entities/Rival.ts +11 -2
  408. package/templates/racing/src/render/atmosphere.ts +444 -0
  409. package/templates/racing/src/render/backlightMaterial.ts +49 -18
  410. package/templates/racing/src/render/clouds.ts +605 -0
  411. package/templates/racing/src/render/exposure.ts +6 -111
  412. package/templates/racing/src/render/gpuSky.ts +752 -0
  413. package/templates/racing/src/render/kitExposure.ts +20 -0
  414. package/templates/racing/src/render/lighting.ts +26 -4
  415. package/templates/racing/src/render/materialLighting.ts +2 -11
  416. package/templates/racing/src/render/materials.ts +2 -1
  417. package/templates/racing/src/render/postprocessing.ts +4 -4
  418. package/templates/racing/src/render/quality.ts +27 -115
  419. package/templates/racing/src/render/sky.ts +72 -1
  420. package/templates/racing/src/scenes/Race.ts +9 -7
  421. package/templates/racing/src/track/TrackSector.ts +5 -2
  422. package/templates/racing/src/ui/Hud.tsx +12 -7
  423. package/templates/rain/.codex/config.toml +6 -2
  424. package/templates/rain/.cursor/mcp.json +8 -2
  425. package/templates/rain/.gemini/settings.json +8 -2
  426. package/templates/rain/.mcp.json +8 -2
  427. package/templates/rain/.vscode/mcp.json +9 -2
  428. package/templates/rain/.zed/settings.json +9 -2
  429. package/templates/rain/AGENTS.md +12 -12
  430. package/templates/rain/CLAUDE.md +12 -12
  431. package/templates/rain/opencode.json +10 -2
  432. package/templates/rain/package.json +14 -9
  433. package/templates/rain/playtests/performance.playtest.json +1 -1
  434. package/templates/rain/src/game.ts +1 -1
  435. package/templates/rain/src/render/bloom-shader.ts +1 -1
  436. package/templates/rain/src/render/clouds-shader.ts +2 -2
  437. package/templates/rain/src/render/clouds.ts +2 -1
  438. package/templates/rain/src/render/exposure.ts +11 -109
  439. package/templates/rain/src/render/post-shader.ts +7 -11
  440. package/templates/rain/src/render/postprocessing.ts +8 -24
  441. package/templates/rain/src/render/quality.ts +44 -98
  442. package/templates/rain/src/render/world-shader.ts +281 -97
  443. package/templates/rain/src/render/world.ts +82 -2
  444. package/templates/rain/src/style.css +1 -1
  445. package/templates/rain/src/ui/GameUi.tsx +6 -2
  446. package/templates/rain/src/ui/Hud.tsx +1 -1
  447. package/templates/rain/tools/generate-shaders.mjs +2 -2
  448. package/templates/rain/tools/tempest-post.frag +4 -6
  449. package/templates/rain/tools/tempest-world.frag +80 -12
  450. package/templates/rts/.codex/config.toml +6 -2
  451. package/templates/rts/.cursor/mcp.json +8 -2
  452. package/templates/rts/.gemini/settings.json +8 -2
  453. package/templates/rts/.mcp.json +8 -2
  454. package/templates/rts/.vscode/mcp.json +9 -2
  455. package/templates/rts/.zed/settings.json +9 -2
  456. package/templates/rts/AGENTS.md +15 -16
  457. package/templates/rts/CLAUDE.md +15 -16
  458. package/templates/rts/opencode.json +10 -2
  459. package/templates/rts/package.json +14 -9
  460. package/templates/rts/playtests/performance.playtest.json +1 -1
  461. package/templates/rts/playtests/rts-attack.playtest.json +5 -0
  462. package/templates/rts/playtests/rts-build.playtest.json +20 -1
  463. package/templates/rts/playtests/rts-orders.playtest.json +1 -1
  464. package/templates/rts/playtests/rts-pause.playtest.json +112 -0
  465. package/templates/rts/playtests/rts-train.playtest.json +1 -1
  466. package/templates/rts/playtests/rts-zoom.playtest.json +81 -0
  467. package/templates/rts/src/game.ts +29 -7
  468. package/templates/rts/src/render/army.ts +181 -49
  469. package/templates/rts/src/render/backlightMaterial.ts +49 -18
  470. package/templates/rts/src/render/environment.ts +276 -0
  471. package/templates/rts/src/render/exposure.ts +3 -65
  472. package/templates/rts/src/render/ground.ts +478 -0
  473. package/templates/rts/src/render/lighting.ts +62 -11
  474. package/templates/rts/src/render/materialLighting.ts +2 -11
  475. package/templates/rts/src/render/materials.ts +47 -118
  476. package/templates/rts/src/render/palette.ts +30 -13
  477. package/templates/rts/src/render/picking.ts +18 -0
  478. package/templates/rts/src/render/postprocessing.ts +4 -4
  479. package/templates/rts/src/render/quality.ts +64 -85
  480. package/templates/rts/src/render/resources.ts +21 -22
  481. package/templates/rts/src/render/sky.ts +9 -12
  482. package/templates/rts/src/render/terrain.ts +36 -11
  483. package/templates/rts/src/scenes/Play.ts +373 -38
  484. package/templates/rts/src/sim/ai.ts +0 -11
  485. package/templates/rts/src/state.ts +46 -0
  486. package/templates/rts/src/style.css +1543 -0
  487. package/templates/rts/src/ui/Commands.tsx +204 -107
  488. package/templates/rts/src/ui/GameUi.tsx +12 -5
  489. package/templates/rts/src/ui/Hud.tsx +611 -116
  490. package/templates/rts/src/ui/Minimap.tsx +103 -37
  491. package/templates/rts/src/ui/icons.tsx +116 -0
  492. package/templates/rts/src/ui/labels.ts +73 -0
  493. package/templates/rts/src/ui/minimapPoint.ts +30 -0
  494. package/templates/rts/threenative.config.ts +1 -1
  495. package/templates/runner/.codex/config.toml +6 -2
  496. package/templates/runner/.cursor/mcp.json +8 -2
  497. package/templates/runner/.gemini/settings.json +8 -2
  498. package/templates/runner/.mcp.json +8 -2
  499. package/templates/runner/.vscode/mcp.json +9 -2
  500. package/templates/runner/.zed/settings.json +9 -2
  501. package/templates/runner/AGENTS.md +12 -12
  502. package/templates/runner/CLAUDE.md +12 -12
  503. package/templates/runner/opencode.json +10 -2
  504. package/templates/runner/package.json +15 -10
  505. package/templates/runner/playtests/near-miss.playtest.json +48 -0
  506. package/templates/runner/playtests/performance.playtest.json +2 -2
  507. package/templates/runner/playtests/stride.playtest.json +27 -0
  508. package/templates/runner/playtests/survives.playtest.json +2 -2
  509. package/templates/runner/src/conventions.ts +3 -1
  510. package/templates/runner/src/entities/Runner.ts +11 -5
  511. package/templates/runner/src/render/atmosphere.ts +444 -0
  512. package/templates/runner/src/render/backlightMaterial.ts +49 -18
  513. package/templates/runner/src/render/clouds.ts +605 -0
  514. package/templates/runner/src/render/exposure.ts +6 -111
  515. package/templates/runner/src/render/gpuSky.ts +752 -0
  516. package/templates/runner/src/render/kitExposure.ts +20 -0
  517. package/templates/runner/src/render/lighting.ts +26 -4
  518. package/templates/runner/src/render/materialLighting.ts +2 -11
  519. package/templates/runner/src/render/postprocessing.ts +4 -4
  520. package/templates/runner/src/render/quality.ts +26 -114
  521. package/templates/runner/src/render/sky.ts +73 -1
  522. package/templates/runner/src/scenes/Run.ts +19 -15
  523. package/templates/runner/src/track.ts +12 -3
  524. package/templates/sailing/.codex/config.toml +6 -2
  525. package/templates/sailing/.cursor/mcp.json +8 -2
  526. package/templates/sailing/.gemini/settings.json +8 -2
  527. package/templates/sailing/.mcp.json +8 -2
  528. package/templates/sailing/.vscode/mcp.json +9 -2
  529. package/templates/sailing/.zed/settings.json +9 -2
  530. package/templates/sailing/AGENTS.md +10 -11
  531. package/templates/sailing/CLAUDE.md +10 -11
  532. package/templates/sailing/opencode.json +10 -2
  533. package/templates/sailing/package.json +15 -10
  534. package/templates/sailing/playtests/fail.playtest.json +46 -5
  535. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +7 -0
  536. package/templates/sailing/playtests/performance.playtest.json +1 -1
  537. package/templates/sailing/src/game.ts +1 -0
  538. package/templates/sailing/src/render/backlightMaterial.ts +49 -18
  539. package/templates/sailing/src/render/exposure.ts +6 -111
  540. package/templates/sailing/src/render/kitExposure.ts +20 -0
  541. package/templates/sailing/src/render/materialLighting.ts +2 -11
  542. package/templates/sailing/src/render/ocean.ts +0 -1
  543. package/templates/sailing/src/render/postprocessing.ts +4 -4
  544. package/templates/sailing/src/render/quality.ts +31 -138
  545. package/templates/sailing/src/scenes/Sailing.ts +12 -4
  546. package/templates/sailing/src/ui/Hud.tsx +6 -2
  547. package/templates/sailing/src/ui/Menu.tsx +1 -1
  548. package/templates/shooter/.codex/config.toml +6 -2
  549. package/templates/shooter/.cursor/mcp.json +8 -2
  550. package/templates/shooter/.gemini/settings.json +8 -2
  551. package/templates/shooter/.mcp.json +8 -2
  552. package/templates/shooter/.vscode/mcp.json +9 -2
  553. package/templates/shooter/.zed/settings.json +9 -2
  554. package/templates/shooter/AGENTS.md +13 -12
  555. package/templates/shooter/CLAUDE.md +13 -12
  556. package/templates/shooter/index.html +1 -1
  557. package/templates/shooter/main.html +13 -0
  558. package/templates/shooter/opencode.json +10 -2
  559. package/templates/shooter/package.json +15 -10
  560. package/templates/shooter/playtests/breakable-shatters.playtest.json +6 -0
  561. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +6 -0
  562. package/templates/shooter/playtests/hands-authored-rate.playtest.json +54 -0
  563. package/templates/shooter/playtests/movement-eases.playtest.json +53 -0
  564. package/templates/shooter/playtests/performance.playtest.json +3 -3
  565. package/templates/shooter/playtests/stairs-smooth-the-eye.playtest.json +56 -0
  566. package/templates/shooter/playtests/weapon-sharp-while-turning.playtest.json +206 -0
  567. package/templates/shooter/src/entities/Breakables.ts +34 -10
  568. package/templates/shooter/src/entities/Enemy.ts +176 -54
  569. package/templates/shooter/src/entities/FpsPlayer.ts +55 -16
  570. package/templates/shooter/src/entities/Rifle.ts +83 -9
  571. package/templates/shooter/src/entities/movement.ts +96 -0
  572. package/templates/shooter/src/render/atmosphere.ts +444 -0
  573. package/templates/shooter/src/render/backlightMaterial.ts +49 -18
  574. package/templates/shooter/src/render/camera.ts +3 -1
  575. package/templates/shooter/src/render/clouds.ts +605 -0
  576. package/templates/shooter/src/render/exposure.ts +10 -109
  577. package/templates/shooter/src/render/facade.ts +26 -68
  578. package/templates/shooter/src/render/gpuSky.ts +752 -0
  579. package/templates/shooter/src/render/lighting.ts +27 -4
  580. package/templates/shooter/src/render/materialAssignments.ts +9 -1
  581. package/templates/shooter/src/render/materialLighting.ts +2 -11
  582. package/templates/shooter/src/render/occlusion.ts +13 -4
  583. package/templates/shooter/src/render/palette.ts +1 -0
  584. package/templates/shooter/src/render/postprocessing.ts +4 -4
  585. package/templates/shooter/src/render/quality.ts +50 -108
  586. package/templates/shooter/src/render/scale.ts +0 -11
  587. package/templates/shooter/src/render/sky.ts +103 -2
  588. package/templates/shooter/src/render/surface.ts +140 -0
  589. package/templates/shooter/src/render/town.ts +3 -6
  590. package/templates/shooter/src/render/townMaterials.ts +95 -42
  591. package/templates/shooter/src/render/vehicles.ts +2 -0
  592. package/templates/shooter/src/scenes/Play.ts +83 -23
  593. package/templates/shooter/src/ui/Hud.tsx +268 -193
  594. package/templates/shooter/src/worker-page.ts +29 -0
  595. package/templates/shooter/src/worker.ts +5 -0
  596. package/templates/shooter/threenative.config.ts +3 -0
  597. package/templates/shooter/vite.config.ts +2 -0
  598. package/templates/snow/.codex/config.toml +6 -2
  599. package/templates/snow/.cursor/mcp.json +8 -2
  600. package/templates/snow/.gemini/settings.json +8 -2
  601. package/templates/snow/.mcp.json +8 -2
  602. package/templates/snow/.vscode/mcp.json +9 -2
  603. package/templates/snow/.zed/settings.json +9 -2
  604. package/templates/snow/AGENTS.md +12 -10
  605. package/templates/snow/CLAUDE.md +12 -10
  606. package/templates/snow/opencode.json +10 -2
  607. package/templates/snow/package.json +15 -10
  608. package/templates/snow/playtests/performance.playtest.json +1 -1
  609. package/templates/snow/src/render/backlightMaterial.ts +49 -18
  610. package/templates/snow/src/render/exposure.ts +17 -106
  611. package/templates/snow/src/render/materialLighting.ts +2 -11
  612. package/templates/snow/src/render/postprocessing.ts +11 -5
  613. package/templates/snow/src/render/quality.ts +46 -126
  614. package/templates/snow/src/render/snowSurface.ts +32 -15
  615. package/templates/snow/src/scenes/Snow.ts +2 -1
  616. package/templates/starter/.codex/config.toml +6 -2
  617. package/templates/starter/.cursor/mcp.json +8 -2
  618. package/templates/starter/.gemini/settings.json +8 -2
  619. package/templates/starter/.mcp.json +8 -2
  620. package/templates/starter/.vscode/mcp.json +9 -2
  621. package/templates/starter/.zed/settings.json +9 -2
  622. package/templates/starter/AGENTS.md +18 -14
  623. package/templates/starter/CLAUDE.md +18 -14
  624. package/templates/starter/index.html +1 -1
  625. package/templates/starter/main.html +12 -0
  626. package/templates/starter/native-playtests/react-hud.playtest.json +1 -0
  627. package/templates/starter/native-playtests/render-chain.playtest.json +34 -21
  628. package/templates/starter/opencode.json +10 -2
  629. package/templates/starter/package.json +15 -10
  630. package/templates/starter/playtests/play.playtest.json +22 -2
  631. package/templates/starter/playtests/production-readiness.playtest.json +14 -0
  632. package/templates/starter/src/entities/Crate.ts +19 -1
  633. package/templates/starter/src/render/arena.ts +2 -2
  634. package/templates/starter/src/render/atmosphere.ts +444 -0
  635. package/templates/starter/src/render/backlightMaterial.ts +49 -18
  636. package/templates/starter/src/render/camera.ts +28 -0
  637. package/templates/starter/src/render/clouds.ts +605 -0
  638. package/templates/starter/src/render/contactShadow.ts +50 -0
  639. package/templates/starter/src/render/exposure.ts +9 -111
  640. package/templates/starter/src/render/gpuSky.ts +752 -0
  641. package/templates/starter/src/render/grade.ts +1 -1
  642. package/templates/starter/src/render/lighting.ts +34 -6
  643. package/templates/starter/src/render/materialLighting.ts +2 -11
  644. package/templates/starter/src/render/postprocessing.ts +27 -14
  645. package/templates/starter/src/render/quality.ts +18 -147
  646. package/templates/starter/src/render/sky.ts +90 -40
  647. package/templates/starter/src/render/temporalAA.ts +1 -1
  648. package/templates/starter/src/render/temporalAAStage.ts +1 -1
  649. package/templates/starter/src/render/temporalCurrentFootprint.ts +0 -1
  650. package/templates/starter/src/render/temporalDetailStage.ts +106 -0
  651. package/templates/starter/src/render/temporalRejectionCounter.ts +2 -2
  652. package/templates/starter/src/render/volumetricFogCamera.ts +32 -0
  653. package/templates/starter/src/render/volumetricFogOptions.ts +7 -0
  654. package/templates/starter/src/render/volumetricFogTransport.ts +27 -19
  655. package/templates/starter/src/render/volumetricFogVolume.ts +31 -7
  656. package/templates/starter/src/scenes/Play.ts +11 -8
  657. package/templates/starter/src/ui/Hud.tsx +1 -1
  658. package/templates/starter/src/worker-page.ts +29 -0
  659. package/templates/starter/src/worker.ts +5 -0
  660. package/templates/starter/vite.config.ts +2 -0
  661. package/templates/tower-defense/.codex/config.toml +6 -2
  662. package/templates/tower-defense/.cursor/mcp.json +8 -2
  663. package/templates/tower-defense/.gemini/settings.json +8 -2
  664. package/templates/tower-defense/.mcp.json +8 -2
  665. package/templates/tower-defense/.vscode/mcp.json +9 -2
  666. package/templates/tower-defense/.zed/settings.json +9 -2
  667. package/templates/tower-defense/AGENTS.md +10 -12
  668. package/templates/tower-defense/CLAUDE.md +10 -12
  669. package/templates/tower-defense/opencode.json +10 -2
  670. package/templates/tower-defense/package.json +15 -10
  671. package/templates/tower-defense/playtests/chill-tint.playtest.json +387 -0
  672. package/templates/tower-defense/playtests/performance.playtest.json +1 -1
  673. package/templates/tower-defense/src/enemies/Enemy.ts +9 -0
  674. package/templates/tower-defense/src/render/backlightMaterial.ts +49 -18
  675. package/templates/tower-defense/src/render/exposure.ts +11 -109
  676. package/templates/tower-defense/src/render/lighting.ts +4 -2
  677. package/templates/tower-defense/src/render/materialLighting.ts +2 -11
  678. package/templates/tower-defense/src/render/postprocessing.ts +4 -4
  679. package/templates/tower-defense/src/render/quality.ts +10 -116
  680. package/templates/tower-defense/src/render/sky.ts +2 -2
  681. package/templates/tower-defense/src/scenes/Battle.ts +4 -0
  682. package/template-assets/autoExposure.ts +0 -225
  683. package/template-assets/exposureGraph.ts +0 -178
  684. package/template-assets/exposureReadback.ts +0 -79
  685. package/template-assets/worldEnvironment.ts +0 -1212
  686. package/templates/action-rpg/src/render/autoExposure.ts +0 -225
  687. package/templates/action-rpg/src/render/exposureGraph.ts +0 -178
  688. package/templates/action-rpg/src/render/exposureReadback.ts +0 -79
  689. package/templates/action-rpg/src/render/worldEnvironment.ts +0 -1212
  690. package/templates/minimal/src/render/autoExposure.ts +0 -225
  691. package/templates/minimal/src/render/exposureGraph.ts +0 -178
  692. package/templates/minimal/src/render/exposureReadback.ts +0 -79
  693. package/templates/minimal/src/render/worldEnvironment.ts +0 -1212
  694. package/templates/platformer/src/render/autoExposure.ts +0 -225
  695. package/templates/platformer/src/render/exposureGraph.ts +0 -178
  696. package/templates/platformer/src/render/exposureReadback.ts +0 -79
  697. package/templates/platformer/src/render/worldEnvironment.ts +0 -1212
  698. package/templates/puzzle/src/render/autoExposure.ts +0 -225
  699. package/templates/puzzle/src/render/exposureGraph.ts +0 -178
  700. package/templates/puzzle/src/render/exposureReadback.ts +0 -79
  701. package/templates/puzzle/src/render/worldEnvironment.ts +0 -1212
  702. package/templates/racing/src/render/autoExposure.ts +0 -225
  703. package/templates/racing/src/render/exposureGraph.ts +0 -178
  704. package/templates/racing/src/render/exposureReadback.ts +0 -79
  705. package/templates/racing/src/render/worldEnvironment.ts +0 -1212
  706. package/templates/rain/src/render/autoExposure.ts +0 -225
  707. package/templates/rain/src/render/exposureGraph.ts +0 -178
  708. package/templates/rain/src/render/exposureReadback.ts +0 -79
  709. package/templates/rain/src/render/worldEnvironment.ts +0 -1212
  710. package/templates/rts/src/render/autoExposure.ts +0 -225
  711. package/templates/rts/src/render/exposureGraph.ts +0 -178
  712. package/templates/rts/src/render/exposureReadback.ts +0 -79
  713. package/templates/rts/src/render/worldEnvironment.ts +0 -1212
  714. package/templates/runner/src/render/autoExposure.ts +0 -225
  715. package/templates/runner/src/render/exposureGraph.ts +0 -178
  716. package/templates/runner/src/render/exposureReadback.ts +0 -79
  717. package/templates/runner/src/render/worldEnvironment.ts +0 -1212
  718. package/templates/sailing/src/render/autoExposure.ts +0 -225
  719. package/templates/sailing/src/render/exposureGraph.ts +0 -178
  720. package/templates/sailing/src/render/exposureReadback.ts +0 -79
  721. package/templates/sailing/src/render/worldEnvironment.ts +0 -1212
  722. package/templates/shooter/src/render/autoExposure.ts +0 -225
  723. package/templates/shooter/src/render/exposureGraph.ts +0 -178
  724. package/templates/shooter/src/render/exposureReadback.ts +0 -79
  725. package/templates/shooter/src/render/worldEnvironment.ts +0 -1212
  726. package/templates/snow/src/render/autoExposure.ts +0 -225
  727. package/templates/snow/src/render/exposureGraph.ts +0 -178
  728. package/templates/snow/src/render/exposureReadback.ts +0 -79
  729. package/templates/snow/src/render/worldEnvironment.ts +0 -1212
  730. package/templates/starter/src/render/autoExposure.ts +0 -225
  731. package/templates/starter/src/render/exposureGraph.ts +0 -178
  732. package/templates/starter/src/render/exposureReadback.ts +0 -79
  733. package/templates/starter/src/render/worldEnvironment.ts +0 -1212
  734. package/templates/tower-defense/src/render/autoExposure.ts +0 -225
  735. package/templates/tower-defense/src/render/exposureGraph.ts +0 -178
  736. package/templates/tower-defense/src/render/exposureReadback.ts +0 -79
  737. package/templates/tower-defense/src/render/worldEnvironment.ts +0 -1212
@@ -5,6 +5,67 @@ day, each re-finding the shapes through TypeErrors. This page lists every global
5
5
  game exposes, what it returns, and how to read it from the browser console. All of them are
6
6
  read-only observation surfaces; none exists to drive gameplay.
7
7
 
8
+ ## One debug switch and one report window
9
+
10
+ Set `TN_DEBUG=1` in the host environment, add `?tnDebug=1` to the browser URL, or assign
11
+ `globalThis.__THREENATIVE_DEBUG__ = true` before the game boots. A console assignment after boot
12
+ does not install instrumentation retroactively. Worker boot must receive the flag before its game
13
+ module evaluates. The switch enables incumbent spans/counters and debug producers for bridge,
14
+ callbacks, scene/renderer/GPU, memory, loading, host and UI activity.
15
+
16
+ `TN_FRAME_BUDGET.counters.engine` contains numeric per-frame summaries by name (`samples`, `mean`,
17
+ percentiles and `max`). One `TN_DEBUG_REPORT` for that same window ranks observed costs with
18
+ `basis`, caller and a matching lever where available. Read the units before comparing:
19
+
20
+ | Basis | Meaning |
21
+ | --- | --- |
22
+ | Measured CPU milliseconds/share | Timed synchronous work divided by the observed frame interval. Parent phases and nested callbacks overlap; adding them double-counts work. |
23
+ | Getter-equivalent estimate | Crossing count times a measured getter calibration. This estimates boundary overhead; it does not time every invoke, set or write. |
24
+ | Counts and bytes | Work or traffic observed, with unavailable cost unless separately timed. A large total alone is no measured CPU share. |
25
+ | Asynchronous wall time | Time until a decode, GPU sample or completion arrives; it can overlap other work and is not synchronous CPU/GPU duration. |
26
+
27
+ Debug windows expose `durationMs` between completed report boundaries, including host gaps.
28
+ Count/byte observations include `perSecond` derived from that duration. The first window,
29
+ zero/unavailable duration, missing frame samples or a truncated summary ring leave the rate null.
30
+ Worker traffic reports shallow UTF-16/primitive byte estimates and explicit unmeasured nested
31
+ fields, rather than claiming structured-clone wire sizes. HUD serialized bytes are exact UTF-8.
32
+ Asset dispatch costs name each URL; asynchronous load/decode wall time stays out of CPU rankings.
33
+ `textureMainThreadDecodeFallbacks` identifies the image-element path, whose later decode CPU cost
34
+ is unavailable. Shared TRS writes include unchanged writes; pure math values stay outside the
35
+ scene-transform census. GPU created/freed bytes begin at diagnostic activation, without claiming
36
+ an inventory of earlier allocations.
37
+ Native V8 installs GC prologue/epilogue callbacks only after debug activation and reports
38
+ `gcPauses`/`gcPauseMs`; shutdown removes them. Browser/Wasm GC entries are optional platform
39
+ observations, so an unavailable GC observer leaves those counters absent.
40
+
41
+ GPU query results can arrive in a later frame. Join requested/resolved/delivered sample identity
42
+ before comparing cadence or attributing a duration to a world draw. Queue completion delivery
43
+ delay, host gaps and measured GPU execution are separate observations. An unsupported observer or
44
+ counter remains absent; treat it as unmeasured rather than a zero. Shared Wasm/native counter names
45
+ do not establish that desktop or Android has executed; those claims require their actual lanes.
46
+ The owned renderer's current CMake adapters reject Android/iOS; forwarding a debug flag to the
47
+ legacy host supplies no shared-renderer parity on those platforms.
48
+ `findings.share: null` means the finding has no corresponding measured cost; it is not zero cost.
49
+
50
+ `TN_HOT_CALL`, `TN_BRIDGE_WARNING` and `TN_SCENE_WARNING` are actionable performance warnings;
51
+ playtest fails them even when console-error checks are opted out. `TN_DEBUG_REPORT` is diagnostic
52
+ and does not itself fail a run. Bound its numeric source through `assert.engineCost`, using the
53
+ exact names from `TN_FRAME_BUDGET.counters.engine`; a missing or unmeasured bounded counter fails.
54
+
55
+ The engine-only smoke scenario reuses the native-smoke game without changing its gameplay:
56
+
57
+ ```sh
58
+ node packages/playtest/dist/runner/cli.js examples/native-smoke/playtests/debug-telemetry.playtest.json \
59
+ --url 'http://127.0.0.1:5173/?tnDebug=1' \
60
+ --server-command 'pnpm --filter threenative-native-smoke dev --host 127.0.0.1 --port 5173' \
61
+ --browser-recipe webgpu --headed
62
+ ```
63
+
64
+ It requires a debug-only callback counter in an actual budget window and bounds it by the loop's
65
+ five-step cap. This proves the observation path when run; it does not qualify every producer or
66
+ claim a device lane. Debug-off retains the existing census without installing debug observers,
67
+ timers or call stacks.
68
+
8
69
  ## `window.__THREENATIVE__` — entity snapshot (dev builds only)
9
70
 
10
71
  Installed by `defineGame` when the dev-server flag is on (`installDevTools`); absent in
@@ -54,6 +115,9 @@ On web this global does not exist — do not probe for it in portable code.
54
115
  `TN_OPACITY_TRANSPARENT`: scene-entry console warning; the engine turned `transparent` on for visible materials with `opacity < 1` so the authored opacity takes effect. Override on the material: `alphaHash: true`, or `opacity: 1` for an opaque surface.
55
116
  `TN_OPACITY_IGNORED`: printed by a direct `renderTrapAudit(scene)` call for a material that still ignores its opacity.
56
117
 
118
+ Markers print at the Verbose (`console.debug`) level in the browser console, so DevTools hides them
119
+ by default; harnesses still receive them. Open the page with `?tnLog=1` to print them normally.
120
+
57
121
  ## Runner-side markers
58
122
 
59
123
  Two further globals are set by tooling, not the game, and are named here so a stray
@@ -232,18 +232,17 @@ directory anyway and the build converts it:
232
232
  build fails and names the install command for your platform — it does not copy the unusable file
233
233
  through and report success. Ask the user before installing anything; it is roughly 350 MB.
234
234
 
235
- The `threenative-blender` MCP server answers the rest:
236
-
237
- - `blender_status` — can this machine convert at all? Never fails; with no Blender it returns
238
- `available: false` and the install command. Call it first.
239
- - `blender_inspect` — what is in this file? Mesh, triangle, vertex and bone counts, material
240
- names, clip names, image names. Use it before committing a download.
241
- - `blender_convert` — write a GLB somewhere other than the build's output. Zero meshes out is a
242
- failure, never an empty GLB.
243
- - `blender_recipes` — the shipped bpy recipes (`decimate`, `unwrap`, `bake_ao`, `retarget`) and
244
- their **full source text**. Read one and adapt it; do not write bpy cold.
245
- - `blender_run_python` — run a bpy script of your own. It is not a sandbox and does not claim to
246
- be; it gives you a resolved Blender and the same fail-closed handling, not extra privilege.
235
+ To see what a file contains before you commit it, ask Blender through the same converter the build
236
+ uses — `packages/blender-bridge/gpl/convert.py` reports mesh, triangle, vertex and bone counts,
237
+ material names, clip names and image names:
238
+
239
+ ```sh
240
+ blender --background --factory-startup --python packages/blender-bridge/gpl/convert.py -- \
241
+ '{"source": "assets/hero.fbx", "out": "/tmp/hero.glb"}'
242
+ ```
243
+
244
+ For bpy work of your own — decimating a scan, unwrapping, baking AO, retargeting — write the script
245
+ and run it with `blender --background --python`. Nothing here is a sandbox or claims to be.
247
246
 
248
247
  ## The narrower tools
249
248
 
@@ -30,6 +30,14 @@ revisit later is the engine's job, not yours.
30
30
  `matrixWorldAutoUpdate = false` is allowed and the engine will skip it, but its parents must stay
31
31
  still. For one node that never moves, `node.updateMatrix(); node.matrixAutoUpdate = false` is the
32
32
  cheaper pair: it skips the per-object compose and leaves the walk intact.
33
+ - **Web threads.** The dev and preview servers send `Cross-Origin-Opener-Policy: same-origin` and
34
+ `Cross-Origin-Embedder-Policy: require-corp`, and the build writes both into `dist/_headers`, so the
35
+ page is cross-origin isolated and loads the threaded engine: the world-matrix walk splits over up
36
+ to 8 workers. `TN_FRAME_BUDGET` reports `threads: "on (N)"`. The page always loads the threaded
37
+ engine and fails closed with `TN_WEB_THREADS_OFF` when it is not cross-origin isolated or the pool
38
+ starts no worker, so a host must send the two headers; `TN_WASM_THREADS_MISSING` names a missing
39
+ threaded build. A cross-origin asset without a `Cross-Origin-Resource-Policy` header needs
40
+ `credentialless` in place of `require-corp`. `?tnIsolation=0` serves a page without the headers.
33
41
  - **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
34
42
  and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
35
43
  batch bounds that span the map.
@@ -116,3 +124,14 @@ exactly when someone is measuring. `npx @threenative/playtest perf` turns a log
116
124
  report. When the percentile is
117
125
  bad but the cause is not obvious, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md` names the function before you
118
126
  change a line.
127
+
128
+ ## Static checks, and what they cannot tell you
129
+
130
+ `pnpm check` runs the strict typecheck, ESLint and a Biome format check, and `pnpm test` runs it
131
+ first. ESLint fails on a floating Promise and on an async callback given to a synchronous slot, and
132
+ it warns when a `new Vector3()`-style math constructor runs directly inside `Scene.update`,
133
+ `Scene.render` or a `ctx.beforeRender` callback. That warning is a prompt to measure, not a
134
+ finding: reuse an instance the scene owns only if `TN_FRAME_BUDGET` shows allocation pressure.
135
+ It does not follow helper calls, so a quiet result is not proof a frame allocates nothing. A
136
+ suppression needs a reason: `// eslint-disable-next-line <rule> -- <why>`. Lint does not prove a
137
+ frame rate, a resource leak or native portability; the playtest and the meters do.
@@ -66,6 +66,27 @@ Read it in this order, because each line rules out a whole class of fix:
66
66
 
67
67
  Only then open the raw trace file, and only if the summary points somewhere specific.
68
68
 
69
+ ## Go deeper with the `threenative-devtools` MCP server
70
+
71
+ Every project wires Chrome DevTools as the `threenative-devtools` MCP server. Use it after
72
+ `playtest trace`, when the summary points at one place and you need to look inside it. It launches
73
+ Chrome with the same WebGPU recipe as a playtest, in a temporary profile. Chrome starts only on the
74
+ first tool call.
75
+
76
+ 1. `navigate_page` to `http://127.0.0.1:<port>/?tnFrameSpans=1`, then hold the movement keys with
77
+ `press_key`, because a parked camera hides the cost of a moving one.
78
+ 2. `performance_start_trace`, play for at least 10 s, then `performance_stop_trace`.
79
+ 3. `performance_analyze_insight` on the insight the trace names.
80
+ 4. `list_console_messages` for `TN_FRAME_BUDGET`, `TN_FRAME_SPANS` and `TN_SCENE_WARNING`.
81
+
82
+ Use it for GPU timing, A/B deltas inside one page, the network and asset waterfall, heap snapshots
83
+ (`take_heapsnapshot`) and console output. **Do not quote its CPU times as absolute numbers.** Its
84
+ browser keeps async call stacks on, and the engine wraps every GPU callback in a promise. On one
85
+ game that read main render as 8.3 ms per frame against 1.3 ms in a clean browser, and a trace added
86
+ 3.9 ms per frame. An absolute CPU number comes from `playtest trace`. A ratio between two arms in
87
+ the same DevTools page is fine. The server sees only the browser: a native or Android frame goes
88
+ through `npx @threenative/playtest perf --target <platform>`.
89
+
69
90
  ## The trap that produces a confident wrong number
70
91
 
71
92
  **A frame rate measured on a virtual display is wrong, not missing.** Under a private Xvfb there
@@ -9,8 +9,8 @@ Three.js source in this project, yours to rewrite or delete.
9
9
  not raw `BoxGeometry`.** A sharp box reads as Minecraft; the same box with a 0.14 corner
10
10
  radius reads as a toy, and that is most of the difference between a scene that looks
11
11
  designed and one that looks like a test harness. For the seeded randomness that varies a
12
- run of meshes, the scene builds `createRandom(seed)` and passes it down — nothing in
13
- `src/render/` may import a framework package, which is what keeps this folder portable.
12
+ run of meshes, the scene builds `createRandom(seed)` and passes it down.
13
+ `src/render/` imports shared Unreal look plumbing from `@threenative/core`; its lighting and materials stay game-owned.
14
14
  - `lighting.ts` — key, sky/ground bounce, **rim**, ambient, with soft shadows and a
15
15
  `normalBias` tuned for rounded geometry. The rim is what stops silhouettes reading as
16
16
  flat cut-outs; do not delete it while "simplifying".
@@ -18,8 +18,7 @@ Three.js source in this project, yours to rewrite or delete.
18
18
  **lead** are the framing: the default aims ahead of the character rather than centring it,
19
19
  because a level that runs one way puts half the picture behind the player otherwise.
20
20
  - `postprocessing.ts` — the editable presets and `setupPost` delegation.
21
- - `worldEnvironment.ts` — the editable Godot-named render chain: tone mapping/exposure and
22
- optional TSL stages, with `createRenderChain` reporting applied or refused stages.
21
+ - `WorldEnvironment` from `@threenative/core` — the shared Unreal render chain, with filmic tone mapping and metered exposure. Override options in `quality.ts`; `TN_RENDER_CHAIN` reports applied or refused stages.
23
22
  - `materials.ts` — `floorMaterial`, `structureMaterial` and `propMaterial`, over a `DataTexture`
24
23
  metre grid and a grain normal map. **Two greys and one saturated colour is the whole rule:**
25
24
  light grid where the player walks, dark grid on sides and structure, and a single saturated
@@ -136,6 +135,26 @@ stage you turned on that is not in that line as `applied: true` did not run, and
136
135
  why. An unknown `ssgiQuality` or `tonemapMode` throws at construction rather than quietly
137
136
  becoming the default.
138
137
 
138
+ ## Unreal's film curve and colour grade
139
+
140
+ `tonemapMode: "filmic"` runs the curve and the defaults of a fresh Unreal Engine 5.8.3 project
141
+ (`render/tonemap.ts`, your source). `tonemapMode: "aces"` is the named override. The curve takes
142
+ `filmicCurve: { slope: 0.88, toe: 0.55, shoulder: 0.26, blackClip: 0, whiteClip: 0.04, ... }`, and
143
+ the grade takes Unreal's controls under `colorGrade`:
144
+
145
+ ```ts
146
+ colorGrade: {
147
+ whiteTemp: 5500, whiteTint: 0, // Kelvin; "colorTemperature" in temperatureMode warms instead
148
+ global: { saturation: [1, 1, 1, 1.1] }, // [red, green, blue, master], like Unreal's panel
149
+ shadows: { gain: [1, 1, 1.05, 1] }, // also midtones and highlights; limits shadowsMax, highlightsMin/Max
150
+ toneCurveAmount: 1, // 0 = graded colour with no curve
151
+ }
152
+ ```
153
+
154
+ A control left out keeps Unreal's default and adds no shader code. Both options throw under any
155
+ other `tonemapMode`. Unreal's colour LUT also clips each channel at 43.7 after exposure.
156
+ That clip is off by default because it moves hot-emitter pixels; `filmicCurve: { lutClip: LUT_CLIP }` turns it on.
157
+
139
158
  ## Shafts of light — the one recipe that is easy to get wrong
140
159
 
141
160
  You want the beam a cathedral window or a hole in a cave roof throws. **Do not build cone
@@ -26,7 +26,7 @@ problem, not instead of it: read the code the change touches and trace the real
26
26
  flow end to end, then climb. Two rungs work → take the higher one and move on.
27
27
 
28
28
  1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
29
- 2. **Already installed in the engine?** Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect hits with `engine_capability_detail`, and reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; never skip it because the task looks small, and never jump to hand-written code while it is unsearched.
29
+ 2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and inspect hits with `engine_capability_detail`; for an existing game, reuse its discovery and binding constraints through the steps 5-7 route in `threenative-capabilities`, without restarting whole-game discovery or planning. Reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; reuse its recorded result for an existing game rather than treating each edit as a new game. Keep installed systems instead of hand-writing replacements.
30
30
  3. **Already in this game?** Reuse a helper, type, or pattern that already lives in `src/`. Re-implementing what sits a few files over is the most common slop.
31
31
  4. **Stdlib or engine convention does it?** `loadAll`, `addInSlices`, `GroundSnap`, an input vector, a physics query — reach for those before writing your own loop.
32
32
  5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
@@ -1,13 +1,14 @@
1
1
  ---
2
2
  name: prd-creator
3
- description: Turn a ThreeNative game idea or change into an approved game plan and implementation tasks before authoring code. Use after threenative-capabilities has recorded a capability or no-match for every mechanic, and before any game source is written.
3
+ description: Plan new ThreeNative games only, after kit selection plus mechanics-reference and built-in capability discovery; hand approved plans to texture selection, execution and verification.
4
4
  ---
5
5
 
6
6
  # ThreeNative game PRD
7
7
 
8
- Use this after `threenative-capabilities` has recorded a capability or no-match for the full request
9
- and every concrete mechanic. The outcome is a small, distinctive, playable plan grounded in the
10
- engine surface and explicitly approved by the user, not a generic genre template.
8
+ Use this for new games only, at step 4 of `threenative-capabilities`, after kit selection and both
9
+ mechanics-reference and built-in capability discovery. Existing-game changes follow steps 5-7
10
+ using their existing context; do not invoke this skill to restart whole-game planning.
11
+ The outcome is a small, distinctive, playable plan grounded in both discovery passes.
11
12
 
12
13
  ## Plan
13
14
 
@@ -22,11 +23,21 @@ engine surface and explicitly approved by the user, not a generic genre template
22
23
  5. Record prerequisites: required tools/MCPs, service access, test users, and environment variable
23
24
  names. Use placeholders only; never read or write real secrets into planning artifacts.
24
25
 
26
+ Copy the three completed discovery sections into `.agent/prd/PRD.md`: **Kit**, **Mechanics**
27
+ and **References**. Each needs a value or explicit `none` with a reason; a blank or missing
28
+ section blocks approval. Required texture search/download is step 5, after plan approval;
29
+ record planned asset needs here without claiming assets have already been selected or downloaded.
30
+
25
31
  Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
26
32
  `.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
27
33
  bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
28
- The first task verifies prerequisites; later tasks include implementation, playtest proof, and
29
- visual inspection. Preserve the pre-planning capability decisions in the relevant task checks.
34
+ The first task verifies prerequisites and selects/downloads required textures from the mechanics
35
+ matches and supplied reference. Step 6 delegates to subagents focused on specific areas: every
36
+ bounded task names its area, file ownership and acceptance check. The coordinator reviews and
37
+ integrates all returned changes before step 7 mechanics playtests; do not use a catch-all worker.
38
+ Later tasks playtest mechanics with real actions and assertions, then require the reference-image
39
+ visual judge gate from `threenative-capabilities`. Preserve the pre-planning capability decisions
40
+ in the relevant task checks.
30
41
 
31
42
  ## Approval gate
32
43
 
@@ -1,27 +1,91 @@
1
1
  ---
2
2
  name: threenative-capabilities
3
- description: Discover and use the ThreeNative capability surface before writing a game system. Use before prd-creator drafts a plan, and before building or replacing any world, traversal, interaction, simulation, combat, camera, audio, UI, entity, movement, navigation, attachment, particle, terrain, or measurement system.
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.
4
4
  ---
5
5
 
6
- # ThreeNative capabilities
7
-
8
- This is a critical planning prerequisite. Use it before `prd-creator` drafts a plan, and before
9
- replacing any world, traversal, interaction, simulation, combat, camera, audio, UI, entity,
10
- movement, navigation, attachment, particle, terrain, or measurement system.
11
-
12
- 1. Infer the concrete mechanics from the request. Preserve its distinctive fantasy with the
13
- smallest characteristic loop; ask one short question only when two core loops remain equally
14
- plausible.
15
- 2. Search the full request with `engine_search_capabilities` using `scope: "request"`, then search
16
- every mechanic with `scope: "mechanic"`. Check each returned `matchedSituation`.
17
- 3. Record a capability or no-match for every mechanic before writing a replacement. Describe
18
- situations plainly, such as *"enemy walks around a wall"*.
19
- 4. Hand the recorded matches, inspected constraints, and no-matches to `prd-creator`; the PRD must
20
- plan against this actual engine surface.
21
-
22
- The manifest is the complete public surface; grep misses subpath exports such as
23
- `@threenative/physics/navigation`. If MCP is unavailable after `npx threenative doctor`, use
24
- `node_modules/create-threenative/agent-docs/references/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
25
- Returned constraints are binding: import navigation from its returned subpath, use `attachToBone`
26
- for held weapons (add a portable `Bone` named `RightHand` when needed), and never invent platform
27
- support. One game rewrote 446 installed lines and ran at 9 FPS; discovery prevents that.
6
+ # ThreeNative authoring route
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.
11
+ Preserve the request's distinctive fantasy and infer concrete mechanics, not just a genre label.
12
+
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.
18
+
19
+ ## New game
20
+
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.
23
+
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
+ `engine_reference_detail`. Search named games and the implied mechanics, inspect relevant
31
+ matches, and record pinned sources and feel rules. For Tier-2 matches, read the pinned repo
32
+ and use `engine_save_reference` for the nodes/cards actually walked; unavailable references
33
+ 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
46
+ `asset_download_file`; verify the returned licence and record downloaded paths/source/licence
47
+ in `CREDITS.md`. Follow `.agents/skills/threenative-assets/SKILL.md`; no unrelated downloads or
48
+ 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
50
+ bounded task, explicit file ownership, relevant context and an acceptance check; preserve other
51
+ writers and avoid a single catch-all worker. The coordinator reviews and integrates the areas
52
+ 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.
68
+
69
+ ## Existing game
70
+
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.
75
+
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.
85
+
86
+ Returned capability constraints are binding, including `@threenative/physics/navigation` subpaths
87
+ and platform support. Use `attachToBone` for held weapons (add a portable `Bone` named `RightHand`
88
+ when needed) rather than rebuilding installed systems. If MCP
89
+ is unavailable, run `npx threenative doctor`; for a new game's capability pass, use the installed
90
+ `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.
@@ -1,12 +1,11 @@
1
1
  ---
2
2
  name: threenative-performance
3
- description: Measure ThreeNative frame budgets and report platform evidence without guessing. Use when a frame budget, FPS floor, or platform performance claim is in question, when reading `TN_FRAME_BUDGET`, or when writing a bounded performance assertion.
3
+ description: Measure ThreeNative frame budgets and report platform evidence without guessing. Use when the game is slow, when a frame budget, FPS floor, or platform performance claim is in question, when reading `TN_FRAME_BUDGET`, or when writing a bounded performance assertion.
4
4
  ---
5
5
 
6
6
  # ThreeNative performance evidence
7
7
 
8
- Pool objects; load static GLBs through `ctx.assets.model()`; never claim Android/iOS from a
9
- desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
8
+ Pool objects; load static GLBs via `ctx.assets.model()`; Unexecuted platforms stay unverified. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
10
9
  `residual` and per-pass draws and triangles. `defineGame({ frameBudget: false })` silences
11
10
  output, never measurement.
12
11
 
@@ -15,16 +14,21 @@ output, never measurement.
15
14
  `TN_SCENE_WARNING` fires when the GPU used under a third of a frame whose render phase overran
16
15
  the display period: move draws and objects, not settings. `npx threenative doctor` and
17
16
  `DEV_MODE=true` repeat it; `TN_FRAME_SPANS=1` splits that phase.
18
- The largest static win is free — three skips per-object binding updates when nothing changed, so
19
- not writing a transform saved 7.35 ms on 1,561 objects where `markStatic(root)` saved 0.009 ms.
17
+ Largest static win: three skips binding updates when nothing changed; not writing a transform saved 7.35 ms on 1,561 objects, `markStatic(root)` 0.009 ms.
18
+ An uncaught per-frame walk or poll? Fix it, then `file-engine-bug`.
19
+
20
+ ## Slow or stuttering game
21
+
22
+ `npx @threenative/playtest trace --url <url> --text` names the hot function (`--cpu-prof <file>`
23
+ writes a `.cpuprofile`). Then use the `threenative-devtools` MCP: quote its GPU, heap and network, not its
24
+ inflated CPU times.
20
25
 
21
26
  ## Use the shipped defaults
22
27
 
23
28
  The engine prepares transforms, batches, culls, scales resolution and cooks assets;
24
29
  read `node_modules/create-threenative/agent-docs/references/performance-basics.md` before hand-rolling any.
25
- Unexecuted platforms stay unverified; never invent numbers.
26
- Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Bounded proof:
27
- `{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`,
30
+ Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Proof:
31
+ `{"performance":{"minFps":60,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`; frame time defaults to 16.7 ms p95 (looser needs `maxFrameMsReason`);
28
32
  defined in `node_modules/create-threenative/agent-docs/references/assertion-reference.md#performance`; pass bounds fail closed without a
29
33
  per-pass split.
30
34
 
@@ -53,6 +57,3 @@ per-pass split.
53
57
 
54
58
  Android: budget a ~500 MiB driver floor before textures; a dual-use equirectangular
55
59
  environment adds ~48 MiB: `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`.
56
-
57
- Name the hot function: `--cpu-prof <file>` (native, or a browser/desktop playtest) writes a
58
- DevTools `.cpuprofile`.
@@ -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. Already installed in the engine? Search `engine_search_capabilities` and inspect with `engine_capability_detail` — reuse the returned system. This rung IS the critical capability gate; a shipped node, convention, helper or subpath is the answer, never hand-write what it already does.",
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.",
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.",
@@ -373,8 +373,9 @@ function hasImageModality(architecture, key) {
373
373
  }
374
374
 
375
375
  function capabilitySupportsImages(value, needsInput) {
376
- if (!Array.isArray(value?.data)) return false;
377
- return value.data.some((endpoint) => {
376
+ // OpenRouter answers `/models/<id>/endpoints` with the model object; a list is accepted too.
377
+ const entries = Array.isArray(value?.data) ? value.data : value?.data ? [value.data] : [];
378
+ return entries.some((endpoint) => {
378
379
  const architecture = endpoint?.architecture;
379
380
  return (
380
381
  hasImageModality(architecture, "output_modalities") &&
@@ -387,7 +388,8 @@ function capabilityEndpoint(apiEndpoint, model) {
387
388
  if (process.env.NODE_ENV === "test" && process.env.TN_REFERENCE_CAPABILITIES_ENDPOINT)
388
389
  return process.env.TN_REFERENCE_CAPABILITIES_ENDPOINT;
389
390
  const endpoint = new URL(apiEndpoint);
390
- endpoint.pathname = `/api/v1/models/${encodeURIComponent(model)}/endpoints`;
391
+ // OpenRouter routes `<author>/<slug>` as two path segments; an encoded slash is a 404.
392
+ endpoint.pathname = `/api/v1/models/${model.split("/").map(encodeURIComponent).join("/")}/endpoints`;
391
393
  endpoint.search = "";
392
394
  return endpoint.toString();
393
395
  }
@@ -645,7 +647,10 @@ async function generate(options, recordFile, record, roots) {
645
647
  const safeError =
646
648
  error instanceof ProviderError
647
649
  ? error
648
- : new ProviderError("provider operation failed", { category: "provider" });
650
+ : // A check of the returned image (its type, its extension) names what failed; it holds no secret.
651
+ error instanceof InputError
652
+ ? new ProviderError(error.message, { category: "invalid-image" })
653
+ : new ProviderError("provider operation failed", { category: "provider" });
649
654
  const receipt = removeRequest(record, requestId, "pending");
650
655
  if (receipt !== undefined) {
651
656
  const destination =