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
@@ -1,10 +1,32 @@
1
1
  // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
2
  // ThreeNative does not read this file.
3
3
  //
4
- // One sun. The sky image in `sky.ts` is the fill light — its environment reaches every face the
4
+ // One sun. The sky in `sky.ts` is the fill light — its environment reaches every face the
5
5
  // sun misses — so there is no hemisphere or ambient light stacked on top to flatten the frame.
6
6
  import { Color, DirectionalLight, PCFSoftShadowMap, type Scene, Vector3 } from "three";
7
- import { SUN_DIRECTION } from "./sky.js";
7
+ import {
8
+ SUN_ILLUMINANCE,
9
+ SUN_KELVIN,
10
+ sunLight,
11
+ sunLightTransmittance,
12
+ temperatureColour,
13
+ } from "./atmosphere.js";
14
+ import { SKY_OPTIONS, SUN_DIRECTION } from "./sky.js";
15
+
16
+ /** The sun as Unreal's default level has it: 6 lux at 6500 K, tinted by the air it crosses. */
17
+ function atmosphereSun(): DirectionalLight {
18
+ const tint = temperatureColour(SUN_KELVIN);
19
+ const through = sunLightTransmittance(Math.asin(Math.min(1, Math.max(-1, SUN_DIRECTION.y))));
20
+ const colour = new Color().setRGB(
21
+ tint[0] * through[0],
22
+ tint[1] * through[1],
23
+ tint[2] * through[2],
24
+ );
25
+ const key = new DirectionalLight(colour, SUN_ILLUMINANCE);
26
+ // `gpuSky.ts` re-tints it when the sun moves.
27
+ sunLight.current = key;
28
+ return key;
29
+ }
8
30
 
9
31
  type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
10
32
 
@@ -16,8 +38,8 @@ export function setupLighting(
16
38
  renderer.shadowMap.enabled = true;
17
39
  renderer.shadowMap.type = PCFSoftShadowMap;
18
40
 
19
- // Warm white, matched by eye to the photographed midday sun against its own sky.
20
- const key = new DirectionalLight(0xfff1e0, 4.5);
41
+ // The photo sky keeps the warm white matched by eye to its photographed midday sun.
42
+ const key = SKY_OPTIONS.sky === "photo" ? new DirectionalLight(0xfff1e0, 4.5) : atmosphereSun();
21
43
  key.position.copy(SUN_DIRECTION).multiplyScalar(30);
22
44
  key.castShadow = true;
23
45
  // One map fitted to the 36 m arena: 4096² is under a centimetre a texel, so every shadow has the
@@ -1,14 +1,6 @@
1
1
  // Generated for you. Scene-owned material assignments; no engine appearance hooks.
2
- import {
3
- type Camera,
4
- type DirectionalLight,
5
- Material,
6
- Mesh,
7
- MeshStandardMaterial,
8
- type Scene,
9
- type Texture,
10
- } from "three";
11
- import { type IBacklightControls, backlightMaterial } from "./backlightMaterial.js";
2
+ import type { Camera, DirectionalLight, Scene, Texture } from "three";
3
+ import type { IBacklightControls } from "./backlightMaterial.js";
12
4
  import {
13
5
  type IEnvironmentMeasurement,
14
6
  measureEnvironment,
@@ -1,8 +1,10 @@
1
+ import type { OutputRenderer } from "@threenative/core";
2
+ import { WorldEnvironment } from "@threenative/core";
1
3
  // Generated for you: ordinary Three.js; ThreeNative does not read this file.
2
4
  //
3
5
  // This file wires two things together and decides nothing itself. `quality.ts`, in this folder,
4
- // owns which stages run at which tier and records what each one measured. `WorldEnvironment`,
5
- // also in this folder, builds them and prints `TN_WORLD_ENVIRONMENT` naming every stage as
6
+ // owns which stages run at which tier and records what each one measured. `WorldEnvironment` from
7
+ // the core package builds them and prints `TN_WORLD_ENVIRONMENT` naming every stage as
6
8
  // applied or refused **with a reason**, so a stage that silently no-op'd is never mistaken for
7
9
  // one you turned off.
8
10
  //
@@ -12,8 +14,6 @@
12
14
  // `TN_QUALITY_TIER` names the tier that ran either way.
13
15
  import type { Camera, DirectionalLight, Scene } from "three";
14
16
  import { type QualityTier, qualityPreset, resolveQualityTier } from "./quality.js";
15
- import type { OutputRenderer } from "./worldEnvironment.js";
16
- import { WorldEnvironment } from "./worldEnvironment.js";
17
17
 
18
18
  export function setupPost(
19
19
  renderer: OutputRenderer,
@@ -24,7 +24,14 @@
24
24
  // frame. With the gather on, `playtests/play.playtest.json` measured **34.2 ms p95 against the
25
25
  // 33 ms ceiling**; without it the same scenario passes. Turn it on when you replace the
26
26
  // atmosphere with a flat sky, and read the p95 back out of `TN_FRAME_BUDGET`.
27
- import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
27
+ import {
28
+ type IWorldEnvironmentOptions,
29
+ qualityPreset as coreQualityPreset,
30
+ qualityTiers,
31
+ } from "@threenative/core";
32
+ import { exposureSettings } from "./exposure.js";
33
+ export type { QualityTier } from "@threenative/core";
34
+ import type { QualityTier } from "@threenative/core";
28
35
 
29
36
  /**
30
37
  * The three names this game's look comes in.
@@ -34,123 +41,10 @@ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
34
41
  * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
35
42
  * what any of them mean.
36
43
  */
37
- export type QualityTier = "low" | "medium" | "high";
44
+ export const resolveQualityTier = qualityTiers.resolve;
38
45
 
39
- const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
40
-
41
- /**
42
- * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
43
- * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
44
- */
45
- function isQualityTier(value: string): value is QualityTier {
46
- return (QUALITY_TIERS as readonly string[]).includes(value);
47
- }
48
-
49
- /**
50
- * Where each GPU family starts, from `ctx.renderer.gpuClass`.
51
- *
52
- * A start, not a ceiling: the measured frame-budget windows move the look from here, and an
53
- * explicit `tier` above still wins. A class absent from this table — `unknown`, an adapter no
54
- * family rule matched — falls back to the `mobile` flag, exactly as before families existed.
55
- * Edit the right-hand side to change what a family looks like; nothing outside this file reads it.
56
- */
57
- const START_TIER_BY_GPU_CLASS: Readonly<Record<string, QualityTier | undefined>> = {
58
- software: "low",
59
- "mobile-low": "low",
60
- "mobile-mid": "low",
61
- "mobile-high": "medium",
62
- integrated: "medium",
63
- discrete: "high",
64
- };
65
-
66
- /**
67
- * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
68
- *
69
- * Fails closed. An unrecognised tier name throws with the value it was handed rather than
70
- * quietly rendering the default, because a silent fallback here looks exactly like a tier that
71
- * turned out to have no effect.
72
- */
73
- export function resolveQualityTier(
74
- request: {
75
- readonly gpuClass?: string;
76
- readonly mobile?: boolean;
77
- readonly software?: boolean;
78
- readonly tier?: string;
79
- } = {},
80
- ): QualityTier {
81
- const requested = request.tier;
82
- if (requested !== undefined) {
83
- if (!isQualityTier(requested)) {
84
- throw new Error(
85
- `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
86
- );
87
- }
88
- return requested;
89
- }
90
- // A named software adapter — SwiftShader, llvmpipe, a basic-render driver — is the machine this
91
- // game's desktop look cannot run on: a single `high` frame on one can outlast the device it is
92
- // drawing on, and no adaptation that reacts to frame times gets to run first. `software` is the
93
- // fact the renderer read from `adapter.info`, not a guess from a driver string, and an explicit
94
- // `tier` above still wins over it.
95
- if (request.software === true) return "low";
96
- const family =
97
- request.gpuClass === undefined ? undefined : START_TIER_BY_GPU_CLASS[request.gpuClass];
98
- if (family !== undefined) return family;
99
- return request.mobile === true ? "low" : "high";
100
- }
101
-
102
- /**
103
- * The look every tier shares: a wide, faint glow on what is genuinely brighter than white — the sun
104
- * disk, the visor — rather than a haze over the frame (a threshold under 1 blooms lit grey walls and
105
- * flattens contrast), and a corner falloff. Antialiasing is on in every tier that installs a chain;
106
- * see `screenSpaceAA` in `worldEnvironment.ts`.
107
- *
108
- * No screen-space reflections and no sharpen here, on purpose. Every surface already reflects the
109
- * captured sky (`sky.ts`), and SSR on rough floors traced speckle into the grid; RCAS then rang the
110
- * smooth sky gradient into visible bands. Both are one line to turn back on for a glossy scene.
111
- */
112
- const shared: IWorldEnvironmentOptions = {
113
- // Bloom: ~4.6 ms in the reference ablation — the second most expensive stage there.
114
- bloomEnabled: true,
115
- bloomRadius: 0.6,
116
- bloomStrength: 0.22,
117
- bloomThreshold: 1,
118
- autoExposureEnabled: false,
119
- exposure: 0.62,
120
- tonemapMode: "aces",
121
- vignetteAmount: 0.22,
122
- };
123
-
124
- /**
125
- * What a desktop gets: contact occlusion on top — the dark line where a foot meets the floor and a
126
- * wall meets the ground, most of what separates "objects in a world" from "objects pasted on a
127
- * background". Gathered at full resolution and denoised: at half, the upsample left a grain around
128
- * every foot.
129
- */
130
- const high: IWorldEnvironmentOptions = {
131
- ...shared,
132
- // GTAO, full resolution plus denoise: unmeasured on its own here; read `TN_FRAME_BUDGET`.
133
- gtaoEnabled: true,
134
- gtaoRadius: 0.35,
135
- };
136
-
137
- /** The rung in between: the same occlusion at half the directions. Saving unmeasured. */
138
- const medium: IWorldEnvironmentOptions = { ...high, gtaoSamples: 8, renderChainTier: "medium" };
139
-
140
- /** What a phone gets: bloom, vignette and the tone curve, nothing screen-space. */
141
- const low: IWorldEnvironmentOptions = { ...shared, renderChainTier: "low" };
142
-
143
- const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
144
-
145
- /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
146
46
  export function qualityPreset(tier: string): IWorldEnvironmentOptions {
147
- const preset = QUALITY_PRESETS[tier as QualityTier];
148
- if (preset === undefined) {
149
- throw new Error(
150
- `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
151
- );
152
- }
153
- return preset;
47
+ return { ...coreQualityPreset(tier), exposurePolicy: exposureSettings };
154
48
  }
155
49
 
156
50
  export interface IMaterialLightingEnvironment {
@@ -1,5 +1,11 @@
1
1
  // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
2
  //
3
+ // The default sky is Unreal 5.8.3's default level: a Sky Atmosphere with its volumetric cloud layer, a
4
+ // sky light that captures it, a sun tinted by the air it crosses, and an exponential height fog that
5
+ // takes its colour from the sky (`atmosphere.ts`, `clouds.ts`, `gpuSky.ts`). Sun, sky and fog read one
6
+ // illuminance, so moving `SUN_DIRECTION` recolours all three together. `SKY_OPTIONS.sky = "photo"`
7
+ // keeps the photograph below; `clouds: false` keeps a clear sky.
8
+ //
3
9
  // The sky is a photograph: `assets/sky.jpg`, Poly Haven's "Kloofendal 48d Partly Cloudy (Pure Sky)"
4
10
  // by Greg Zaal and Jarod Guest, CC0 (https://polyhaven.com/a/kloofendal_48d_partly_cloudy_puresky).
5
11
  // The same image is the background, the environment light every surface reflects and is filled by,
@@ -13,6 +19,7 @@ import {
13
19
  type Texture,
14
20
  Vector3,
15
21
  } from "three";
22
+ import { createGpuSky } from "./gpuSky.js";
16
23
  import { HEIGHT_FOG, type HeightFogParams, heightFogDepth, heightFogNode } from "./heightFog.js";
17
24
  import { palette } from "./palette.js";
18
25
 
@@ -42,7 +49,7 @@ function distanceDensity(p: HeightFogParams = HEIGHT_FOG): number {
42
49
  return Math.sqrt(Math.max(0, old - height)) / distance;
43
50
  }
44
51
 
45
- export function setupSky(scene: Scene, sky: Texture): void {
52
+ function setupPhotoSky(scene: Scene, sky: Texture): void {
46
53
  sky.mapping = EquirectangularReflectionMapping;
47
54
  sky.colorSpace = SRGBColorSpace;
48
55
  scene.background = sky;
@@ -59,3 +66,68 @@ export function setupSky(scene: Scene, sky: Texture): void {
59
66
  scene.fog = distanceFog;
60
67
  scene.fogNode = heightFogNode(distanceFog, HEIGHT_FOG, SUN_DIRECTION);
61
68
  }
69
+
70
+ export const SKY_OPTIONS: { sky: "atmosphere" | "photo"; clouds: boolean; ground: boolean } = {
71
+ sky: "atmosphere",
72
+ clouds: true,
73
+ // The sunlit ground below the horizon stands in for Unreal's Lumen floor bounce: it lifts shadow
74
+ // sides and a mirror reflects it. Set false when the game adds its own global illumination.
75
+ ground: true,
76
+ };
77
+
78
+ /**
79
+ * Unreal's default level fog in metres: density and falloff are per 1000 cm (x0.1 per metre), and its
80
+ * line integral carries ln2 against the exact integral `heightFog.ts` evaluates. `fogHeight` sits
81
+ * 68.5 m below the floor, where the default level puts the fog actor. Inscattering is black and the
82
+ * start distance 0, as in Unreal: the colour comes from the sky.
83
+ */
84
+ const ATMOSPHERE_FOG = {
85
+ ...HEIGHT_FOG,
86
+ density: 0.00436 * Math.LN2,
87
+ heightFalloff: 0.02,
88
+ fogHeight: -68.5,
89
+ startDistance: 0,
90
+ };
91
+
92
+ /** White in the 8-bit environment is this much scene radiance (`createGpuSky`). */
93
+ const ENVIRONMENT_RANGE = 4;
94
+
95
+ /**
96
+ * `photo` is only read when `SKY_OPTIONS.sky` is "photo". `fogged` false leaves the sky unfogged;
97
+ * `clouds` false draws the clear atmosphere. A software adapter draws the 64 x 32 bake as the
98
+ * background, with no LUT or cloud passes.
99
+ */
100
+ export function setupSky(
101
+ scene: Scene,
102
+ photo?: Texture,
103
+ software = false,
104
+ fogged = true,
105
+ clouds = SKY_OPTIONS.clouds,
106
+ ): void {
107
+ if (SKY_OPTIONS.sky === "photo") {
108
+ if (photo === undefined) throw new Error('SKY_OPTIONS.sky "photo" needs assets/sky.jpg loaded');
109
+ setupPhotoSky(scene, photo);
110
+ return;
111
+ }
112
+ // Height fog only; FogExp2 holds the colour `heightFogNode` reads, at zero density. `createGpuSky`
113
+ // sets that colour from the sky and again whenever the sun moves.
114
+ const fog = new FogExp2(0xffffff, 0);
115
+ scene.fog = fog;
116
+ scene.fogNode = heightFogNode(fog, { ...ATMOSPHERE_FOG }, SUN_DIRECTION);
117
+ const { node, environment } = createGpuSky(
118
+ scene,
119
+ SUN_DIRECTION,
120
+ fogged,
121
+ clouds,
122
+ ATMOSPHERE_FOG,
123
+ SKY_OPTIONS.ground,
124
+ );
125
+ environment.mapping = EquirectangularReflectionMapping;
126
+ environment.colorSpace = SRGBColorSpace;
127
+ scene.background = environment;
128
+ scene.backgroundNode = software ? null : node.backgroundNode;
129
+ scene.backgroundIntensity = software ? ENVIRONMENT_RANGE : 1;
130
+ // Unreal's sky light: the same sky, so the fill on every shaded face is the sky's colour.
131
+ scene.environment = environment;
132
+ scene.environmentIntensity = ENVIRONMENT_RANGE;
133
+ }
@@ -21,6 +21,7 @@ import {
21
21
  type PerspectiveCamera,
22
22
  PlaneGeometry,
23
23
  type Texture,
24
+ type Vector3,
24
25
  } from "three";
25
26
  import { RoundedBoxGeometry } from "three/addons/geometries/RoundedBoxGeometry.js";
26
27
  import { type IPlayerModel, Player } from "../entities/Player.js";
@@ -37,7 +38,7 @@ import {
37
38
  } from "../render/materials.js";
38
39
  import { setupPost } from "../render/postprocessing.js";
39
40
  import { isWebGLFallbackRenderer, materialLightingEnabled } from "../render/quality.js";
40
- import { setupSky } from "../render/sky.js";
41
+ import { SKY_OPTIONS, setupSky } from "../render/sky.js";
41
42
  import { TouchControls } from "../render/touch-controls.js";
42
43
  import type { GameState } from "../state.js";
43
44
 
@@ -58,9 +59,10 @@ export class Play extends Scene<GameState, IPhysicsContext> {
58
59
  override async load(ctx: GameCtx): Promise<void> {
59
60
  [this.#model, this.#sky] = await Promise.all([
60
61
  ctx.assets.model<IPlayerModel>("mannequin.glb"),
61
- ctx.assets.texture("sky.jpg"),
62
+ // Only the photo-sky override reads the photograph; the atmosphere sky is computed.
63
+ SKY_OPTIONS.sky === "photo" ? ctx.assets.texture("sky.jpg") : undefined,
62
64
  ]);
63
- setupSky(ctx.scene, this.#sky);
65
+ setupSky(ctx.scene, this.#sky, ctx.renderer.softwareAdapter !== undefined);
64
66
  this.#environmentSample = await sampleEnvironment(ctx.renderer.raw, ctx.scene, {
65
67
  web: getPlatform().runtime === "web",
66
68
  rendererKind: ctx.renderer.kind,
@@ -71,10 +73,10 @@ export class Play extends Scene<GameState, IPhysicsContext> {
71
73
  }
72
74
 
73
75
  override enter(ctx: GameCtx): SceneFrame<GameState, IPhysicsContext> {
74
- if (this.#model === undefined || this.#sky === undefined)
75
- throw new Error("Play.enter ran before load() loaded mannequin.glb and sky.jpg.");
76
+ if (this.#model === undefined)
77
+ throw new Error("Play.enter ran before load() loaded mannequin.glb.");
76
78
  const showTouchControls = isMobile() && isTouchscreenAvailable();
77
- setupSky(ctx.scene, this.#sky);
79
+ setupSky(ctx.scene, this.#sky, ctx.renderer.softwareAdapter !== undefined);
78
80
  const lighting = setupLighting(
79
81
  ctx.scene,
80
82
  ctx.renderer.raw as Parameters<typeof setupLighting>[1],
@@ -188,7 +190,16 @@ export class Play extends Scene<GameState, IPhysicsContext> {
188
190
  buildStaticColliders(ctx, level);
189
191
  const player = new Player(ctx, this.#model);
190
192
  const camera = ctx.camera as PerspectiveCamera;
191
- afterPhysics(ctx, (dt) => followCamera(camera, player.mesh.position, dt));
193
+ const probe = (from: Vector3, to: Vector3) =>
194
+ ctx.physics.directSpaceState.intersectRay({ from, to })?.distance;
195
+ // Whether a wall stands between the player and the lens: what a playtest asserts. The ray
196
+ // starts inside the player's capsule, which the query ignores.
197
+ let hidden = false;
198
+ ctx.entities.add("camera", { debug: () => ({ hidden }) });
199
+ afterPhysics(ctx, (dt) => {
200
+ followCamera(camera, player.mesh.position, dt, probe);
201
+ hidden = probe(player.mesh.position, camera.position) !== undefined;
202
+ });
192
203
  ctx.entities.add("player", player);
193
204
  const pickup = new Area3D({
194
205
  physics: ctx.physics,
@@ -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
  }
@@ -8,8 +8,8 @@ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics b
8
8
 
9
9
  ## Start every change
10
10
 
11
- 1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant 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.
12
- 2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints, direct the user to review it, and wait for explicit approval plus an instruction to implement it.
11
+ 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
12
+ 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints, direct the user to review it, and wait for explicit approval plus an instruction to implement it.
13
13
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this route needs no navigation: it is authored geometry, so the fox collides with exactly the triangles it sees and desktop/native stays honest.
14
14
  4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
15
15
 
@@ -19,20 +19,20 @@ When an `@threenative/*` API is broken, missing, or does not do what you need, r
19
19
 
20
20
  ## Workflow skills
21
21
  - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
22
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
22
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
23
23
  - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
24
24
  - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
25
25
  - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
26
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
26
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
27
27
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
28
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind MeshStandardMaterial.flatShading yet. The pin keeps upstream Three.js on web and the legacy host on desktop. Android and iOS use the legacy host.
28
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
29
29
  ## Commands and map
30
30
 
31
31
  ```sh
32
32
  pnpm dev
33
33
  pnpm build
34
34
  pnpm build --target desktop
35
- pnpm test
35
+ pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
36
36
  pnpm typecheck
37
37
  ```
38
38
 
@@ -43,9 +43,11 @@ Leave `assets` absent: the cook selects target-decodable passes, with `models.sh
43
43
 
44
44
  Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. No model here is imported, so there is no authored scale to normalise and the collider is the body: the generated scale-and-snap conventions do not apply to this template. `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
45
45
 
46
- WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/sky.ts` builds the gradient background from `palette.ts`; a separate measured environment lights the scene, the background's lower hemisphere matches `skyFloor`, and `SUN_DIRECTION` aims `lighting.ts`'s authored sun. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. The native production collector's explicit `--hosted-software` profile selects the existing `low` preset only when no tier override is passed; `TN_QUALITY_TIER` reports `source=hosted-software`. That smoke tier is not physical performance evidence and does not change an ordinary desktop run. Unknown tiers throw. Keep state values human-readable; the bridge flushes about 100 ms and per-frame feel stays in scene-owned Three.js.
46
+ WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/sky.ts` builds the gradient background from `palette.ts`; a separate measured environment lights the scene, the background's lower hemisphere matches `skyFloor`, and `SUN_DIRECTION` aims `lighting.ts`'s authored sun. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. The native production collector's explicit `--hosted-software` profile selects the existing `low` preset only when no tier override is passed; `TN_QUALITY_TIER` reports `source=hosted-software`. That smoke tier is not physical performance evidence and does not change an ordinary desktop run. Unknown tiers throw. `high` draws 4x MSAA and `medium` and `low` SMAA; `temporalAA: true` is the named opt-in. Keep state values human-readable; the bridge flushes about 100 ms and per-frame feel stays in scene-owned Three.js.
47
47
 
48
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
48
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
49
+
50
+ `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
49
51
 
50
52
  ## Budget real time for the look
51
53
  Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
@@ -55,4 +57,6 @@ For terrain generation or editing, read `node_modules/create-threenative/agent-d
55
57
  ## Optional multiplayer transport
56
58
  For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
57
59
  Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
58
- `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.
60
+ `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
61
+
62
+ Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. The generated `quality.ts` uses those core defaults; game exposure policy stays in `src/render/exposure.ts`. `tonemapMode: "aces"` and `autoExposureEnabled: false` with fixed `exposure` are named overrides on the same preset.