create-threenative 0.2.10 → 0.2.13

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
@@ -19,11 +19,22 @@
19
19
  // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
20
  // in `sky.ts`, not in this file.
21
21
  //
22
- // **This template runs neither SSGI nor SSR at any tier.** Its frame cost is the snow — a dense
23
- // deforming heightfield mesh and tens of thousands of flakes — not the post chain, and snow is
24
- // already the brightest thing on screen, so the chain is tonemapping alone at every tier and the
25
- // sun glints come from the snow material.
26
- import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
22
+ // **The preset is core's Unreal look plus this game's exposure policy**, with one named cost
23
+ // override reported as `TN_RENDER_CHAIN_COST_OVERRIDE`: no final gather, SSGI or SSR, no
24
+ // temporal AA or motion blur, no bloom and no local exposure. The frame is the snow — a dense deforming heightfield mesh and tens
25
+ // of thousands of flakes. The screen-probe gather took the performance scenario to 38.8 ms GPU
26
+ // p95 against its 16.7 ms budget, and the flakes are GPU-computed sprites with no velocity, so
27
+ // both temporal stages trail and smear them. Snow fills the frame with bright pixels, so bloom
28
+ // lays a veil over everything and lifts the explorer's darkest pixel from 18 to 49. Local exposure
29
+ // lifts the explorer's shadows the same way and flattens it against the snow.
30
+ import {
31
+ type IWorldEnvironmentOptions,
32
+ qualityPreset as coreQualityPreset,
33
+ qualityTiers,
34
+ } from "@threenative/core";
35
+ import { exposureSettings } from "./exposure.js";
36
+ export type { QualityTier } from "@threenative/core";
37
+ import type { QualityTier } from "@threenative/core";
27
38
 
28
39
  /**
29
40
  * The three names this game's look comes in.
@@ -33,131 +44,40 @@ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
33
44
  * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
34
45
  * what any of them mean.
35
46
  */
36
- export type QualityTier = "low" | "medium" | "high";
37
-
38
- const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
39
-
40
- /**
41
- * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
42
- * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
43
- */
44
- function isQualityTier(value: string): value is QualityTier {
45
- return (QUALITY_TIERS as readonly string[]).includes(value);
46
- }
47
-
48
- /**
49
- * Where each GPU family starts, from `ctx.renderer.gpuClass`.
50
- *
51
- * A start, not a ceiling: the measured frame-budget windows move the look from here, and an
52
- * explicit `tier` above still wins. A class absent from this table — `unknown`, an adapter no
53
- * family rule matched — falls back to the `mobile` flag, exactly as before families existed.
54
- * Edit the right-hand side to change what a family looks like; nothing outside this file reads it.
55
- */
56
- const START_TIER_BY_GPU_CLASS: Readonly<Record<string, QualityTier | undefined>> = {
57
- software: "low",
58
- "mobile-low": "low",
59
- "mobile-mid": "low",
60
- "mobile-high": "medium",
61
- integrated: "medium",
62
- discrete: "high",
63
- };
47
+ export const resolveQualityTier = qualityTiers.resolve;
64
48
 
65
49
  /**
66
- * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
67
- *
68
- * Fails closed. An unrecognised tier name throws with the value it was handed rather than
69
- * quietly rendering the default, because a silent fallback here looks exactly like a tier that
70
- * turned out to have no effect.
50
+ * The stages and strengths a tier turns on: the core preset, this game's exposure policy and the
51
+ * one named cost override from the header: no final gather, no temporal AA, no motion blur. The
52
+ * snowfield and its flakes are the frame; the gather alone took the performance scenario to
53
+ * 38.8 ms GPU p95, and the flakes have no velocity for the temporal stages. Remove an override
54
+ * and read `TN_FRAME_BUDGET` when the snow gets cheaper.
71
55
  */
72
- export function resolveQualityTier(
73
- request: {
74
- readonly gpuClass?: string;
75
- readonly mobile?: boolean;
76
- readonly software?: boolean;
77
- readonly tier?: string;
78
- } = {},
79
- ): QualityTier {
80
- const requested = request.tier;
81
- if (requested !== undefined) {
82
- if (!isQualityTier(requested)) {
83
- throw new Error(
84
- `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
85
- );
86
- }
87
- return requested;
88
- }
89
- // A named software adapter — SwiftShader, llvmpipe, a basic-render driver — is the machine this
90
- // game's desktop look cannot run on: a single `high` frame on one can outlast the device it is
91
- // drawing on, and no adaptation that reacts to frame times gets to run first. `software` is the
92
- // fact the renderer read from `adapter.info`, not a guess from a driver string, and an explicit
93
- // `tier` above still wins over it.
94
- if (request.software === true) return "low";
95
- const family =
96
- request.gpuClass === undefined ? undefined : START_TIER_BY_GPU_CLASS[request.gpuClass];
97
- if (family !== undefined) return family;
98
- return request.mobile === true ? "low" : "high";
99
- }
100
-
101
- /**
102
- * What a desktop gets: this template's shipped desktop look, unchanged.
103
- */
104
- const high: IWorldEnvironmentOptions = {
105
- // Strength, radius and threshold are a look decision already tuned to this scene's palette.
106
- // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
107
- // to be.
108
- // Off. Snow is the brightest thing on screen, and at the default 0.2 threshold every lit
109
- // pixel blooms and the glade sinks into a white haze. A 0.92 threshold kept only the glints on
110
- // the web but left the native desktop frame blank behind the HUD (Dawn/Vulkan, 2026-10-01), so
111
- // the glints live in the snow material's emissive term instead. Turn it back on here.
112
- bloomEnabled: false,
113
- // No SSGI runs here, so there is nothing for the denoiser to clean up. Off, explicitly.
114
- denoiseEnabled: false,
115
- autoExposureEnabled: false,
116
- exposure: 0.95,
117
- // Off at every tier — see the note at the top of this file.
118
- ssgiEnabled: false,
119
- // Off at every tier — see the note at the top of this file.
120
- ssrEnabled: false,
121
- tonemapMode: "aces",
122
- };
123
-
124
- /**
125
- * The rung in between. With no screen-space stage and no bloom at any tier, the post chain is the
126
- * same everywhere; the tier only reaches the measured chain as `renderChainTier`. What a phone
127
- * saves is decided in `src/scenes/Snow.ts` (fewer flakes), and the snow mesh resolution in
128
- * `src/terrain.ts` is where the frame actually goes.
129
- */
130
- const medium: IWorldEnvironmentOptions = { ...high, renderChainTier: "medium" };
131
-
132
- /**
133
- * What a phone gets: this template's shipped mobile look, unchanged.
134
- */
135
- const low: IWorldEnvironmentOptions = {
136
- // Strength, radius and threshold are a look decision already tuned to this scene's palette.
137
- // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
138
- // to be.
139
- // Off, as at the high tier.
140
- bloomEnabled: false,
141
- exposure: 0.95,
142
- // Off at every tier — see the note at the top of this file.
143
- ssgiEnabled: false,
144
- // Off at every tier — see the note at the top of this file.
145
- ssrEnabled: false,
146
- renderChainTier: "low",
147
- tonemapMode: "aces",
148
- };
149
-
150
- const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
151
-
152
- /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
153
56
  export function qualityPreset(tier: string): IWorldEnvironmentOptions {
154
- const preset = QUALITY_PRESETS[tier as QualityTier];
155
- if (preset === undefined) {
156
- throw new Error(
157
- `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
158
- );
159
- }
160
- return preset;
57
+ console.info(
58
+ `TN_RENDER_CHAIN_COST_OVERRIDE ${JSON.stringify({
59
+ reason:
60
+ "Snow: the snowfield is the frame; the core gather took the performance scenario past 16.7 ms GPU p95, temporal AA and motion blur trail the GPU-computed flakes that have no velocity, bloom veils the white glade and lifts the explorer's blacks, and local exposure lifts the explorer's shadows and flattens it against the snow",
61
+ finalGatherMethod: "none",
62
+ ssgiEnabled: false,
63
+ ssrEnabled: false,
64
+ temporalAA: false,
65
+ motionBlurEnabled: false,
66
+ bloomEnabled: false,
67
+ localExposureEnabled: false,
68
+ })}`,
69
+ );
70
+ return {
71
+ ...coreQualityPreset(tier),
72
+ exposurePolicy: exposureSettings,
73
+ finalGatherMethod: "none",
74
+ ssgiEnabled: false,
75
+ ssrEnabled: false,
76
+ temporalAA: false,
77
+ motionBlurEnabled: false,
78
+ bloomEnabled: false,
79
+ localExposureEnabled: false,
80
+ };
161
81
  }
162
82
 
163
83
  export interface IMaterialLightingEnvironment {
@@ -31,6 +31,8 @@ const URGENT_CELLS = 12_000;
31
31
  /** A wide window is spread over about this many frames, never fewer than eight rows a frame. */
32
32
  const SLICE_FRAMES = 15;
33
33
  const SLICE_ROWS = 8;
34
+ /** More separate windows than this waiting for one draw are merged into their bounding box. */
35
+ const MAX_URGENT_WINDOWS = 16;
34
36
 
35
37
  type Bounds = {
36
38
  readonly column: number;
@@ -52,7 +54,7 @@ export interface ISnowSource {
52
54
  refreshGeometry(geometry: BufferGeometry, bounds?: Bounds): void;
53
55
  toColliderHeights(): Float32Array;
54
56
  };
55
- takeDirtyRegion(): Bounds | undefined;
57
+ takeDirtyRegions(): readonly Bounds[];
56
58
  copyChannel(
57
59
  channel: "indent" | "compaction",
58
60
  bounds: Bounds,
@@ -175,10 +177,10 @@ export function createSnowSurface(snow: ISnowSource): ISnowSurface {
175
177
  state.needsUpdate = true;
176
178
  };
177
179
 
178
- let urgent: Bounds | undefined;
180
+ let urgent: Bounds[] = [];
179
181
  let background: Bounds | undefined;
180
182
  // `toGeometry` already drew the field as it stands; the field's own first full write is not news.
181
- snow.takeDirtyRegion();
183
+ snow.takeDirtyRegions();
182
184
  const redraw = (written: Bounds): void => {
183
185
  // A normal reads its neighbours, so one sample beyond the written window moves too.
184
186
  const column = Math.max(0, written.column - 1);
@@ -191,19 +193,34 @@ export function createSnowSurface(snow: ISnowSource): ISnowSurface {
191
193
  };
192
194
  field.refreshGeometry(geometry, bounds);
193
195
  writeState(bounds);
194
- // Upload only the rows that moved: a whole-field upload every frame is megabytes per frame.
195
- const first = bounds.row * field.columns;
196
- const count = bounds.rows * field.columns;
196
+ // Upload only the samples that moved: a whole-field upload every frame is megabytes per
197
+ // frame, and whole rows of a narrow window are most of that. One range per row keeps a
198
+ // footprint's upload to a footprint, however far across the field the window sits.
199
+ const wholeRows = bounds.columns === field.columns;
197
200
  for (const name of ["position", "normal", STATE]) {
198
201
  const attribute = geometry.getAttribute(name) as BufferAttribute;
199
- attribute.addUpdateRange(first * attribute.itemSize, count * attribute.itemSize);
202
+ if (wholeRows) {
203
+ attribute.addUpdateRange(
204
+ bounds.row * field.columns * attribute.itemSize,
205
+ bounds.rows * field.columns * attribute.itemSize,
206
+ );
207
+ continue;
208
+ }
209
+ for (let row = bounds.row; row < bounds.row + bounds.rows; row += 1)
210
+ attribute.addUpdateRange(
211
+ (row * field.columns + bounds.column) * attribute.itemSize,
212
+ bounds.columns * attribute.itemSize,
213
+ );
200
214
  }
201
215
  };
202
216
  const collect = (): void => {
203
- const written = snow.takeDirtyRegion();
204
- if (written === undefined) return;
205
- if (written.columns * written.rows <= URGENT_CELLS) urgent = union(urgent, written);
206
- else background = union(background, written);
217
+ // Windows a long way apart stay apart: one box around a ball and a crate is most of the field.
218
+ for (const written of snow.takeDirtyRegions()) {
219
+ if (written.columns * written.rows <= URGENT_CELLS) urgent.push(written);
220
+ else background = union(background, written);
221
+ }
222
+ // A frame that waits long for its draw falls back to one box rather than a list that grows.
223
+ if (urgent.length > MAX_URGENT_WINDOWS) urgent = [urgent.reduce(union)];
207
224
  };
208
225
 
209
226
  return {
@@ -215,8 +232,8 @@ export function createSnowSurface(snow: ISnowSource): ISnowSurface {
215
232
  },
216
233
  refresh() {
217
234
  collect();
218
- if (urgent !== undefined) redraw(urgent);
219
- urgent = undefined;
235
+ for (const window of urgent) redraw(window);
236
+ urgent = [];
220
237
  if (background === undefined) return;
221
238
  // Proportional to what is waiting, so a refill always finishes before the next one lands.
222
239
  const rows = Math.min(
@@ -231,9 +248,9 @@ export function createSnowSurface(snow: ISnowSource): ISnowSurface {
231
248
  },
232
249
  renderError() {
233
250
  collect();
234
- if (urgent !== undefined) redraw(urgent);
251
+ for (const window of urgent) redraw(window);
235
252
  if (background !== undefined) redraw(background);
236
- urgent = undefined;
253
+ urgent = [];
237
254
  background = undefined;
238
255
  const positions = geometry.getAttribute("position");
239
256
  const heights = field.toColliderHeights();
@@ -20,6 +20,7 @@ import { type Command, commands } from "../commands.js";
20
20
  import { Explorer, type IFootstep, STANCE } from "../entities/Explorer.js";
21
21
  import { BOOT_AREA, bootPrint } from "../render/bootPrint.js";
22
22
  import { OrbitFollow, setupCamera } from "../render/camera.js";
23
+ import { exposureBias } from "../render/exposure.js";
23
24
  import { setupLighting } from "../render/lighting.js";
24
25
  import { createLoadingScreen } from "../render/loading.js";
25
26
  import { createMaterialLighting } from "../render/materialLighting.js";
@@ -410,7 +411,6 @@ export class Snow extends Scene<GameState, IPhysicsContext> {
410
411
  let autoExplore = initial.autoExplore;
411
412
  let blizzard = initial.blizzard;
412
413
  const act = (command: Command): void => {
413
- const state = ctx.state.getState();
414
414
  if (command === "reset") {
415
415
  snow.reset();
416
416
  placeBody(ctx, snow, ball, { x: 2.2, z: -2 }, BALL_RADIUS + 0.02);
@@ -592,6 +592,7 @@ export class Snow extends Scene<GameState, IPhysicsContext> {
592
592
  );
593
593
  lights.update(explorer.position, weather.storm);
594
594
  stormSky(weather.storm);
595
+ this.#post?.exposure?.setExposureBias(exposureBias(weather.storm));
595
596
  surface.setStorm(weather.storm);
596
597
  audio.update(weather.wind, weather.storm);
597
598
 
@@ -14,6 +14,10 @@ args = ["./node_modules/@threenative/core/mcp/sculpt.mjs"]
14
14
  command = "node"
15
15
  args = ["./node_modules/@threenative/core/mcp/engine.mjs"]
16
16
 
17
- [mcp_servers.threenative-blender]
17
+ [mcp_servers.threenative-animation]
18
18
  command = "node"
19
- args = ["./node_modules/@threenative/core/mcp/blender.mjs"]
19
+ args = ["./node_modules/@threenative/core/mcp/animation.mjs"]
20
+
21
+ [mcp_servers.threenative-devtools]
22
+ command = "node"
23
+ args = ["./node_modules/@threenative/core/mcp/devtools.mjs"]
@@ -22,10 +22,16 @@
22
22
  "./node_modules/@threenative/core/mcp/engine.mjs"
23
23
  ]
24
24
  },
25
- "threenative-blender": {
25
+ "threenative-animation": {
26
26
  "command": "node",
27
27
  "args": [
28
- "./node_modules/@threenative/core/mcp/blender.mjs"
28
+ "./node_modules/@threenative/core/mcp/animation.mjs"
29
+ ]
30
+ },
31
+ "threenative-devtools": {
32
+ "command": "node",
33
+ "args": [
34
+ "./node_modules/@threenative/core/mcp/devtools.mjs"
29
35
  ]
30
36
  }
31
37
  }
@@ -22,10 +22,16 @@
22
22
  "./node_modules/@threenative/core/mcp/engine.mjs"
23
23
  ]
24
24
  },
25
- "threenative-blender": {
25
+ "threenative-animation": {
26
26
  "command": "node",
27
27
  "args": [
28
- "./node_modules/@threenative/core/mcp/blender.mjs"
28
+ "./node_modules/@threenative/core/mcp/animation.mjs"
29
+ ]
30
+ },
31
+ "threenative-devtools": {
32
+ "command": "node",
33
+ "args": [
34
+ "./node_modules/@threenative/core/mcp/devtools.mjs"
29
35
  ]
30
36
  }
31
37
  }
@@ -22,10 +22,16 @@
22
22
  "./node_modules/@threenative/core/mcp/engine.mjs"
23
23
  ]
24
24
  },
25
- "threenative-blender": {
25
+ "threenative-animation": {
26
26
  "command": "node",
27
27
  "args": [
28
- "./node_modules/@threenative/core/mcp/blender.mjs"
28
+ "./node_modules/@threenative/core/mcp/animation.mjs"
29
+ ]
30
+ },
31
+ "threenative-devtools": {
32
+ "command": "node",
33
+ "args": [
34
+ "./node_modules/@threenative/core/mcp/devtools.mjs"
29
35
  ]
30
36
  }
31
37
  }
@@ -25,11 +25,18 @@
25
25
  "./node_modules/@threenative/core/mcp/engine.mjs"
26
26
  ]
27
27
  },
28
- "threenative-blender": {
28
+ "threenative-animation": {
29
29
  "type": "stdio",
30
30
  "command": "node",
31
31
  "args": [
32
- "./node_modules/@threenative/core/mcp/blender.mjs"
32
+ "./node_modules/@threenative/core/mcp/animation.mjs"
33
+ ]
34
+ },
35
+ "threenative-devtools": {
36
+ "type": "stdio",
37
+ "command": "node",
38
+ "args": [
39
+ "./node_modules/@threenative/core/mcp/devtools.mjs"
33
40
  ]
34
41
  }
35
42
  }
@@ -25,11 +25,18 @@
25
25
  "./node_modules/@threenative/core/mcp/engine.mjs"
26
26
  ]
27
27
  },
28
- "threenative-blender": {
28
+ "threenative-animation": {
29
29
  "source": "custom",
30
30
  "command": "node",
31
31
  "args": [
32
- "./node_modules/@threenative/core/mcp/blender.mjs"
32
+ "./node_modules/@threenative/core/mcp/animation.mjs"
33
+ ]
34
+ },
35
+ "threenative-devtools": {
36
+ "source": "custom",
37
+ "command": "node",
38
+ "args": [
39
+ "./node_modules/@threenative/core/mcp/devtools.mjs"
33
40
  ]
34
41
  }
35
42
  }
@@ -2,13 +2,11 @@
2
2
  Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
3
3
  ## Ownership
4
4
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
5
- `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as a photographed sky and a rigged figure: `src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) the background, the environment light and the fog colour, `lighting.ts` adds the one sun it names in `SUN_DIRECTION`, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Swap the sky for any equirectangular image and re-aim `SUN_DIRECTION` at its sun; swap the rig and edit `CLIPS`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `src/render/sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
5
+ `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as Unreal's default sky and a rigged figure: `src/render/sky.ts` draws an atmosphere sky with clouds (`atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) that is the background, the environment light and the height-fog colour, `lighting.ts` adds the one sun at `SUN_DIRECTION`, tinted by the air it crosses, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Move `SUN_DIRECTION` and the sky, sun colour and fog follow; `SKY_OPTIONS` in `sky.ts` takes `sky: "photo"` (the `assets/sky.jpg` photograph, Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce); swap the rig and edit `CLIPS`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `src/render/sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
6
6
 
7
7
  ## Start every change
8
- 1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
9
- `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
10
- matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
11
- 2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
8
+ 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
9
+ 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints,
12
10
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
13
11
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
14
12
  use returned subpaths and `attachToBone` rather than rebuilding installed systems.
@@ -22,14 +20,14 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
22
20
  ## Workflow skills
23
21
 
24
22
  - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
25
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
23
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
26
24
  - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
27
25
  - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
28
26
  - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
29
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
27
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
30
28
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
31
29
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
32
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
30
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
33
31
 
34
32
  ## Commands and map
35
33
 
@@ -38,7 +36,7 @@ pnpm dev
38
36
  pnpm studio
39
37
  pnpm build
40
38
  pnpm build --target desktop
41
- pnpm test
39
+ pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
42
40
  node tools/look.mjs
43
41
  ```
44
42
 
@@ -47,7 +45,8 @@ a flag, which together produce `won` or `lost`; `R` and the React restart intent
47
45
  `initialState`. Keep the packaged `assets/native-proof.glb` load and its console marker for the
48
46
  desktop asset gate. `Play.ts` owns gameplay, `src/render/` owns the look, `src/ui/Hud.tsx`/`Menu.tsx`
49
47
  own UI, and `state.ts` publishes JSON-safe values. Keep `playtests/survives.playtest.json` as smoke
50
- proof and update outcome tests.
48
+ proof and update outcome tests. `index.html` runs `game.ts` in a web worker
49
+ (`src/worker.ts`, page side `src/worker-page.ts`), so a busy page cannot stall its frames; `main.html` is the named override that runs it on the page thread.
51
50
 
52
51
  On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src/render/touch-controls.ts` adds a left movement stick and right jump button; the scene passes its input to `Player`, with keyboard mapping as the desktop fallback.
53
52
  ## Portable authoring contracts
@@ -65,19 +64,22 @@ randomness is deterministic only when `defineGame({ seed })` is configured.
65
64
  When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each
66
65
  rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names
67
66
  tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which
68
- therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
67
+ therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
68
+
69
+ `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
69
70
 
70
71
  ## The arena is a test arena, and its look is a grid
71
72
  `src/render/arena.ts` owns the ground, the four walls, one pillar, and `platform()`, the single builder both ends of the course are cut from. A platform is a light metre-grid plate over a dark-grid body down to the ground: two meshes, so the player collides with exactly the triangles they can see, and the sides read as structure while the walking surface reads as floor. The ground has no collider — that is the pit under the gap, and why falling costs a life instead of landing on scenery. Move a platform and move its support surface in `Play.ts` and `Goal.ts` with it, or grounding will answer for a surface that is no longer there.
73
+ The sun's shadow camera covers the diagonal of `ARENA` down to `GROUND_Y`; changing those dimensions updates coverage automatically.
72
74
  `materials.ts` is the whole look: two greys and one saturated colour. Light grid where the player walks, dark grid on sides and structure, and the single `accent` hue reserved for the crate, the pickup and the flagpole — what you can touch. `worldGridUVs` makes one grid tile one metre on every face of every prop, so call it after a geometry is placed and before it is given to a mesh.
73
75
  ## Quality and proof
74
76
 
75
77
  WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` selects the boot tier (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`; `unknown` falls back to `isMobile()`), and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
76
78
  `setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit. A bounded participating medium is generated source you own: `src/render/volumetricFog.ts` and its three companions build depth-correct mist, and `STARTER_MIST` there owns this game's density, colour, bounds and its single `enabled` flag — off costs no target and no pixel. `Play` passes it the live `ctx.renderer.kind`, so the WebGL fallback allocates nothing, and it owns `scene.fog` while it lives, so aerial perspective and god rays must stay off: they render the same air. `setupPost`'s `fog` factory rebuilds it whenever the tier replaces the chain. It is lit by `ambient` until you pass `points` (unshadowed, finite-range `PointLight`s) or a `sun` whose shadow map already exists — nothing wires one for you.
77
- The shipped chain is ambient occlusion on `high` and `medium`, bloom, vignette, the tone curve and the shared SMAA. There are no authored paint stages: a real sun and a real sky carry the shading, and a Kuwahara smear or an ink outline over a photograph only cost frames. `quality.ts` owns tier and strength, and every `xxxEnabled: true` carries the measurement that justified it; `TN_RENDER_CHAIN` names each stage independently, and a missing stage observation is a failure.
79
+ The shipped chain comes from `qualityPreset(tier)` and `WorldEnvironment` in `@threenative/core`. Keep this game's sky, materials, grade and effect overrides in `src/render/`; `TN_RENDER_CHAIN` reports every applied or refused stage. The neutral grade and optional film grain remain game-owned in `grade.ts` and `public/grade.cube`. Every override has a name on the same quality preset, and a missing stage observation is a failure.
78
80
  `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
79
81
 
80
- `src/render/temporalAA.ts` is an experimental, opt-in TRAANode provider for scene input reconstruction. Shipped quality tiers do not enable it. Supply colour/depth/velocity from the same scene pass through a `traa` RenderChain stage, reset history on camera cuts, and dispose with the stage. The optional exact scene-pass argument enables a bounded raw4 current-footprint candidate for supported reduced rasters; it owns four-sample beauty and matching visibility replays and restores ordinary pass policy on unsupported inputs. Opaque RGB remains a pixel-frequency approximation; alpha-tested visibility uses sample interpolation. The ordinary path uses scene-pass MSAA disabled. `temporalResolve.ts` retains optional linear/Catmull–Rom and ordinary-blend comparisons, both depth-history vetoes, and mandatory RGB clipping. Original quality/recovery, GPU cost, automatic scaling and native gates remain unqualified.
82
+ `src/render/temporalAA.ts` is an experimental, opt-in TRAANode provider for scene input reconstruction. Shipped quality tiers use the engine's built-in `traa` stage instead, and `debug().temporal` reports whichever one runs. Supply colour/depth/velocity from the same scene pass through a `traa` RenderChain stage, reset history on camera cuts, and dispose with the stage. The optional exact scene-pass argument enables a bounded raw4 current-footprint candidate for supported reduced rasters; it owns four-sample beauty and matching visibility replays and restores ordinary pass policy on unsupported inputs. Opaque RGB remains a pixel-frequency approximation; alpha-tested visibility uses sample interpolation. The ordinary path uses scene-pass MSAA disabled. `temporalResolve.ts` retains optional linear/Catmull–Rom and ordinary-blend comparisons, both depth-history vetoes, and mandatory RGB clipping. Original quality/recovery, GPU cost, automatic scaling and native gates remain unqualified.
81
83
  ## One shadow for a big outdoor level
82
84
  When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. Movers sort themselves: a caster whose matrix changes draws through a per-level mover map and returns to the cached levels after `staticAfterFrames` quiet frames, each change redrawing only its own region. `trackCaster(object)` pins a mover for good, `pinStatic(object)` opts an object out; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
83
85
  ## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
@@ -88,4 +90,6 @@ For terrain generation or editing, read `node_modules/create-threenative/agent-d
88
90
  For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
89
91
 
90
92
  High-tier desktop browser WebGPU adds game-owned grazing backlight (`lighting.ts`: `rimGain: 0`) and measured-dark directional fill (`fillGain: 0` or black `fillColor`). `materialLighting.ts` preserves borrowed material maps and restores originals on lower quality/exit; mobile, software, WebGL and native retain originals. `TN_ENVIRONMENT_CONTRIBUTION` reports even with overrides zero; `environmentSampling.ts` estimates actual IBL once during load; unavailable/stale samples stay unknown and disable analytic fill. Native material terms remain unqualified.
91
- `src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds. One fog owner at a time: an enabled `STARTER_MIST` clears both `scene.fog` and `scene.fogNode`.
93
+ `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds. One fog owner at a time: an enabled `STARTER_MIST` clears both `scene.fog` and `scene.fogNode`.
94
+
95
+ Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`; this kit uses them. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset. The render log reports the override.