create-threenative 0.2.3 → 0.2.5

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 (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -0,0 +1,170 @@
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or rewrite
2
+ // it freely — the tiers below are a starting point, not a framework look.
3
+ //
4
+ // This is the one place this game decides how expensive it looks. `postprocessing.ts` reads
5
+ // `qualityPreset(resolveQualityTier(...))` and nothing else, so "make it run on a phone" is one
6
+ // file to edit rather than a hunt through anonymous literals.
7
+ //
8
+ // **Where the numbers come from.** Every millisecond below is GPU time from the per-stage
9
+ // ablation recorded in the engine repository's `docs/verification/runtime-perf-state.md`: Chrome
10
+ // on an RTX 2080, 1600x900, static build, `gpuMs` read from three's `timestamp-query`. In that
11
+ // scene the whole five-stage chain costs **12.5 ms of a 14.7 ms GPU frame**, and the same frame
12
+ // with every stage off costs **2.2 ms**. The per-stage figures oversum — removing SSGI also
13
+ // removes the denoise passes the later stages sample — so read each as *what turning this one off
14
+ // gave back*, not as a share of a partition. A stage nobody has ablated on its own says
15
+ // `unmeasured` rather than guessing, and your scene is not that scene: read `TN_FRAME_BUDGET`
16
+ // back after you change a tier.
17
+ //
18
+ // One cost that is **not** a stage here and outweighs most of them: the prefiltered reflection
19
+ // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
+ // in `sky.ts`, not in this file.
21
+ //
22
+ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
23
+
24
+ /**
25
+ * The three names this game's look comes in.
26
+ *
27
+ * `low` is what a phone gets and `high` what a desktop gets — those two are this template's
28
+ * shipped looks, unchanged. `medium` is the rung in between for a machine that is neither: a
29
+ * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
30
+ * what any of them mean.
31
+ */
32
+ export type QualityTier = "low" | "medium" | "high";
33
+
34
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
35
+
36
+ /**
37
+ * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
38
+ * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
39
+ */
40
+ function isQualityTier(value: string): value is QualityTier {
41
+ return (QUALITY_TIERS as readonly string[]).includes(value);
42
+ }
43
+
44
+ /**
45
+ * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
46
+ *
47
+ * Fails closed. An unrecognised tier name throws with the value it was handed rather than
48
+ * quietly rendering the default, because a silent fallback here looks exactly like a tier that
49
+ * turned out to have no effect.
50
+ */
51
+ export function resolveQualityTier(
52
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
53
+ ): QualityTier {
54
+ const requested = request.tier;
55
+ if (requested !== undefined) {
56
+ if (!isQualityTier(requested)) {
57
+ throw new Error(
58
+ `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
59
+ );
60
+ }
61
+ return requested;
62
+ }
63
+ return request.mobile === true ? "low" : "high";
64
+ }
65
+
66
+ /**
67
+ * What a desktop gets: this template's shipped desktop look, unchanged.
68
+ *
69
+ * The whole chain measured 12.5 ms of a 14.7 ms GPU frame in the reference ablation, and SSGI
70
+ * with its denoiser is ~9.2 ms of that.
71
+ */
72
+ const high: IWorldEnvironmentOptions = {
73
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
74
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
75
+ // to be.
76
+ bloomEnabled: true,
77
+ bloomRadius: 0.5,
78
+ bloomStrength: 0.3,
79
+ bloomThreshold: 0.62,
80
+ exposure: 1.02,
81
+ // The two full-resolution denoise passes over the AO and GI terms: ~1.9 ms. Only worth running
82
+ // when SSGI is on — its noise is what they clean up.
83
+ denoiseEnabled: true,
84
+ // SSGI, the screen-space indirect-light gather: ~7.3 ms alone, ~9.2 ms with the two denoise
85
+ // passes it feeds. The largest stage in the chain by a factor of two, of a 14.7 ms frame.
86
+ // Dropping this pair is what `medium` is.
87
+ ssgiEnabled: true,
88
+ ssgiRadius: 16,
89
+ ssgiQuality: "medium",
90
+ // Half the frame in each axis, so a quarter of the pixels. Full-res SSGI cost 14.4 ms
91
+ // of a 39.7 ms frame on an RTX 2080; this is the same gather over a quarter of the work,
92
+ // and it measured *sharper* because the scaler spends what it hands back on resolution.
93
+ // `worldEnvironment.ts` explains why it takes a wrapper instead of a property.
94
+ ssgiResolutionScale: 0.5,
95
+ // Screen-space reflections: ~4.1 ms.
96
+ ssrEnabled: true,
97
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
98
+ // are on and do nothing" — the ray dies a metre from where it started.
99
+ ssrMaxDistance: 40,
100
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
101
+ // the rays and is very hard to see in the result.
102
+ ssrResolutionScale: 0.5,
103
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
104
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
105
+ // that runs one of them.
106
+ sharpenEnabled: true,
107
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
108
+ sharpenStrength: 0.3,
109
+ tonemapMode: "aces",
110
+ };
111
+
112
+ /**
113
+ * `high` minus the gather and its denoiser — the single change in this chain measured to give
114
+ * back most of the frame: **14.7 ms -> 5.5 ms of GPU** in the reference ablation. Reflections,
115
+ * bloom and the sharpener stay, so it is recognisably the same look.
116
+ */
117
+ const medium: IWorldEnvironmentOptions = {
118
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
119
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
120
+ // to be.
121
+ bloomEnabled: true,
122
+ bloomRadius: 0.5,
123
+ bloomStrength: 0.3,
124
+ bloomThreshold: 0.62,
125
+ exposure: 1.02,
126
+ // Screen-space reflections: ~4.1 ms.
127
+ ssrEnabled: true,
128
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
129
+ // are on and do nothing" — the ray dies a metre from where it started.
130
+ ssrMaxDistance: 40,
131
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
132
+ // the rays and is very hard to see in the result.
133
+ ssrResolutionScale: 0.5,
134
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
135
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
136
+ // that runs one of them.
137
+ sharpenEnabled: true,
138
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
139
+ sharpenStrength: 0.3,
140
+ tonemapMode: "aces",
141
+ };
142
+
143
+ /**
144
+ * What a phone gets: this template's shipped mobile look, unchanged. Bloom and the tone curve,
145
+ * nothing screen-space. The ablation's floor — every stage off — was 2.2 ms.
146
+ */
147
+ const low: IWorldEnvironmentOptions = {
148
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
149
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
150
+ // to be.
151
+ bloomEnabled: true,
152
+ bloomRadius: 0.5,
153
+ bloomStrength: 0.3,
154
+ bloomThreshold: 0.62,
155
+ exposure: 1.02,
156
+ tonemapMode: "aces",
157
+ };
158
+
159
+ const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
160
+
161
+ /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
162
+ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
163
+ const preset = QUALITY_PRESETS[tier as QualityTier];
164
+ if (preset === undefined) {
165
+ throw new Error(
166
+ `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
167
+ );
168
+ }
169
+ return preset;
170
+ }
@@ -143,6 +143,34 @@ export interface IWorldEnvironmentOptions {
143
143
  readonly gtaoSamples?: number;
144
144
  /** Fraction of display resolution the occlusion is traced at. */
145
145
  readonly gtaoResolutionScale?: number;
146
+ /**
147
+ * The fraction of the frame SSGI actually gathers at. Half by default.
148
+ *
149
+ * `GTAONode` and `SSRNode` both carry a `resolutionScale` of their own; **`SSGINode` does not**,
150
+ * and its `setSize` passes width and height straight into its render target with no factor. So
151
+ * screen-space GI — a low-frequency effect every production renderer gathers at half or quarter
152
+ * res — was the only stage in this chain running at full resolution, and it cost accordingly.
153
+ *
154
+ * Measured on a 46,190-instance forest at 1600x900 on an RTX 2080, with the resolution scaler
155
+ * left on auto so the engine's own verdict is part of the result:
156
+ *
157
+ * fps still/walk scale it settled on interior median dead shadow
158
+ * full res 38.0 / 47.2 0.44 704x396 0.0299 19.19%
159
+ * off 60.0 / 60.0 0.61 976x549 0.0987 4.54%
160
+ * half res 59.8 / 60.0 0.72 1152x648 0.0301 18.58%
161
+ *
162
+ * Half res is better than both: it holds the budget like switching SSGI off, keeps the look
163
+ * within noise of full res, and produces the *sharpest* frame of the three — because the budget
164
+ * it hands back is spent by the scaler on pixels rather than on a gather nobody can see at full
165
+ * rate. Full-res SSGI was not buying quality, it was trading it.
166
+ *
167
+ * Fixed without touching three: `setSize` is public and the pass drives the node through it with
168
+ * the full frame size, so the instance is wrapped to hand it a smaller one. The node's own maths
169
+ * reads the `_resolution` uniform that `setSize` writes, so it stays self-consistent, and the
170
+ * result is sampled by UV rather than by texel — which is what makes the upsample free and is
171
+ * exactly the mechanism `GTAONode` uses internally.
172
+ */
173
+ readonly ssgiResolutionScale?: number;
146
174
  /**
147
175
  * Contrast-adaptive sharpening (RCAS) over the finished frame.
148
176
  *
@@ -163,6 +191,30 @@ export interface IWorldEnvironmentOptions {
163
191
  readonly bloomRadius?: number;
164
192
  /** Luminance a pixel must exceed before it blooms at all. */
165
193
  readonly bloomThreshold?: number;
194
+ /**
195
+ * Which of this kit's authored stages to run.
196
+ *
197
+ * Separate from the graph below, and not for tidiness: the chain has to know whether anything
198
+ * was requested at all before the scene pass exists — with nothing requested it sets an
199
+ * exposure and returns, and no pass is ever built. So the request is a static decision the kit
200
+ * makes from its own config, and only the graph needs the pass.
201
+ */
202
+ readonly authoredStageNames?: readonly string[];
203
+ /**
204
+ * This kit's own stages, composed after the built-ins.
205
+ *
206
+ * A factory because an authored stage needs the two things only this file can produce: the
207
+ * scene pass's depth texture node, which does not exist until the pass is built, and the
208
+ * resolved tier. It returns the complete graph — including stages left dormant this frame — so
209
+ * that an anchor like `watercolor after kuwahara` keeps naming a stage that exists.
210
+ *
211
+ * Naming specific stages here instead — an `outlineEnabled`, a `kuwaharaRadius` — is what put
212
+ * one kit's look inside the plumbing every kit copies verbatim, which
213
+ * `shared-render-sources.spec.ts` exists to refuse.
214
+ */
215
+ readonly authoredStages?: (context: IWorldEnvironmentStageContext) => readonly ChainStage[];
216
+ /** Quality tier passed to the measured chain; the quality module owns this value. */
217
+ readonly renderChainTier?: ChainTier;
166
218
  readonly tonemapMode?: TonemapMode;
167
219
  /**
168
220
  * Scene-referred exposure: multiplied into the scene pass **before** the tone curve, so
@@ -198,12 +250,33 @@ export interface IWorldEnvironmentTarget {
198
250
  * compiler checks the composition instead of taking a cast's word for it.
199
251
  */
200
252
  type ChainNode = Node<"vec4">;
253
+ /**
254
+ * The scene pass's depth texture, as the pass itself types it.
255
+ *
256
+ * Named through `pass()` rather than written out because the addon's return type is the only
257
+ * honest spelling of it, and a hand-written alias here would drift the first time three changes it.
258
+ */
259
+ export type DepthTextureNode = ReturnType<ReturnType<typeof pass>["getTextureNode"]>;
260
+ type ChainTier = "high" | "medium" | "low" | "off";
201
261
  type ChainContext = {
202
- readonly tier: "high" | "medium" | "low" | "off";
262
+ readonly tier: ChainTier;
203
263
  };
204
- type ChainStage = {
205
- readonly name: "ambientOcclusion" | "ssgi" | "godRays" | "ssr" | "sharpen" | "bloom" | "vignette";
264
+ /**
265
+ * What a kit's `authoredStages` factory is handed. The depth node is the scene pass's, so a
266
+ * stage that reads depth gets the same texture the built-in stages read rather than its own.
267
+ */
268
+ export interface IWorldEnvironmentStageContext {
269
+ readonly depthNode: DepthTextureNode;
270
+ readonly tier: ChainTier;
271
+ }
272
+
273
+ export type ChainStage = {
274
+ readonly name: string;
275
+ readonly before?: string;
276
+ readonly after?: string;
206
277
  readonly available?: (context: ChainContext) => boolean | string;
278
+ readonly dispose?: () => void;
279
+ readonly minimumTier?: ChainTier;
207
280
  /** The chain plumbing is stage-agnostic, so it names the node it carries `unknown`. */
208
281
  readonly build: (input: unknown, context: ChainContext) => unknown;
209
282
  };
@@ -218,6 +291,7 @@ type ChainStage = {
218
291
  */
219
292
  function stage(definition: {
220
293
  readonly name: ChainStage["name"];
294
+ readonly dispose?: () => void;
221
295
  readonly available?: (context: ChainContext) => boolean | string;
222
296
  readonly build: (input: ChainNode, context: ChainContext) => ChainNode;
223
297
  }): ChainStage {
@@ -248,10 +322,12 @@ export type OutputRenderer = {
248
322
  setOutputNode?: (node: unknown) => void;
249
323
  createRenderChain?: (options: {
250
324
  input?: unknown;
325
+ worldPass?: unknown;
251
326
  request?: { stages?: readonly string[]; tier?: ChainContext["tier"] };
252
327
  stages?: readonly ChainStage[];
253
328
  }) => {
254
329
  applied: { dropped: readonly { name: string; reason: string }[]; stages: readonly string[] };
330
+ dispose(): void;
255
331
  };
256
332
  };
257
333
 
@@ -281,7 +357,17 @@ export class WorldEnvironment {
281
357
  `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${Object.keys(TONEMAP).join(", ")}.`,
282
358
  );
283
359
  }
360
+ const renderChainTier = options.renderChainTier ?? "high";
361
+ if (!isChainTier(renderChainTier)) {
362
+ throw new Error(
363
+ `Unknown render chain tier '${String(renderChainTier)}'. Use high, medium, low, or off.`,
364
+ );
365
+ }
284
366
  this.#options = {
367
+ // A kit with no stages of its own is the common case, so both default to empty rather
368
+ // than to a branch every call site has to remember.
369
+ authoredStageNames: options.authoredStageNames ?? [],
370
+ authoredStages: options.authoredStages ?? (() => []),
285
371
  ssgiEnabled: options.ssgiEnabled ?? false,
286
372
  ssgiQuality: quality,
287
373
  ssgiIntensity: options.ssgiIntensity ?? 1,
@@ -301,6 +387,7 @@ export class WorldEnvironment {
301
387
  gtaoScale: options.gtaoScale ?? 1,
302
388
  gtaoSamples: options.gtaoSamples ?? 16,
303
389
  gtaoResolutionScale: options.gtaoResolutionScale ?? 1,
390
+ ssgiResolutionScale: options.ssgiResolutionScale ?? 0.5,
304
391
  sharpenEnabled: options.sharpenEnabled ?? false,
305
392
  sharpenStrength: options.sharpenStrength ?? 0.2,
306
393
  vignetteAmount: options.vignetteAmount ?? 0,
@@ -308,6 +395,7 @@ export class WorldEnvironment {
308
395
  bloomStrength: options.bloomStrength ?? 0.7,
309
396
  bloomRadius: options.bloomRadius ?? 0.5,
310
397
  bloomThreshold: options.bloomThreshold ?? 0.2,
398
+ renderChainTier,
311
399
  tonemapMode,
312
400
  exposure: options.exposure ?? 1,
313
401
  };
@@ -325,12 +413,13 @@ export class WorldEnvironment {
325
413
  ): {
326
414
  dropped: readonly { name: string; reason: string }[];
327
415
  stages: readonly string[];
416
+ dispose?: () => void;
328
417
  } {
329
418
  const options = this.#options;
330
419
  const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
331
420
  raw.toneMapping = TONEMAP[options.tonemapMode];
332
421
 
333
- const requested = (
422
+ const requested: string[] = (
334
423
  ["ssgi", "ambientOcclusion", "godRays", "ssr", "sharpen", "bloom", "vignette"] as const
335
424
  ).filter(
336
425
  (name) =>
@@ -342,6 +431,7 @@ export class WorldEnvironment {
342
431
  (name === "bloom" && options.bloomEnabled) ||
343
432
  (name === "vignette" && options.vignetteAmount > 0),
344
433
  );
434
+ requested.push(...options.authoredStageNames);
345
435
 
346
436
  // With no stage running there is no node graph to install — the renderer's own
347
437
  // tone-mapping path renders the frame, and the exposure scalar is live there (measured:
@@ -364,10 +454,25 @@ export class WorldEnvironment {
364
454
  if (options.ssgiEnabled || options.ssrEnabled || options.gtaoEnabled) {
365
455
  scenePass.setMRT(mrt({ output, normal: normalView, metalness, roughness }));
366
456
  }
367
- const depth = scenePass.getTextureNode("depth");
368
- const normal = scenePass.getTextureNode("normal");
369
- const metal = scenePass.getTextureNode("metalness");
370
- const rough = scenePass.getTextureNode("roughness");
457
+ // Requested lazily, and this is not a micro-optimisation. **Asking a pass for `normal`,
458
+ // `metalness` or `roughness` is what creates the extra render target.** A tier that runs none
459
+ // of the stages needing them — the mobile look is bloom and the tone curve — must not ask, or
460
+ // the pass carries a colour target no fragment shader writes and WebGPU refuses the pipeline:
461
+ // *"Color target has no corresponding fragment stage output but writeMask … is not zero.
462
+ // While validating targets[1]"*. The frame then comes out **black** while the chain still
463
+ // reports every stage as applied, which is the worst shape a failure can take here.
464
+ const nodes = new Map<string, ReturnType<typeof scenePass.getTextureNode>>();
465
+ const textureNode = (name: string): ReturnType<typeof scenePass.getTextureNode> => {
466
+ const cached = nodes.get(name);
467
+ if (cached !== undefined) return cached;
468
+ const node = scenePass.getTextureNode(name);
469
+ nodes.set(name, node);
470
+ return node;
471
+ };
472
+ const depth = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("depth");
473
+ const normal = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("normal");
474
+ const metal = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("metalness");
475
+ const rough = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("roughness");
371
476
  // Every stage here is perspective-camera maths — view-space reconstruction from depth,
372
477
  // and a projection matrix inverse. The scene's camera is the one the pass rendered with.
373
478
  const view = camera as PerspectiveCamera;
@@ -375,17 +480,39 @@ export class WorldEnvironment {
375
480
  const base = target.baseColour?.(scenePass) ?? scenePass.getTextureNode("output");
376
481
  const exposed = convertToTexture(base).mul(options.exposure);
377
482
  const giDenoise = (node: ChainNode): ChainNode =>
378
- options.denoiseEnabled ? denoised(denoise(node, depth, normal, view)) : node;
483
+ options.denoiseEnabled ? denoised(denoise(node, depth(), normal(), view)) : node;
379
484
 
485
+ let releaseBloom = (): void => {};
380
486
  const stages: ChainStage[] = [
381
487
  stage({
382
488
  name: "ssgi",
383
489
  build: (input) => {
384
- const gi = ssgi(input, depth, normal, view);
490
+ const gi = ssgi(input, depth(), normal(), view);
385
491
  const tier = SSGI_QUALITY[options.ssgiQuality];
386
492
  gi.sliceCount.value = tier.sliceCount;
387
493
  gi.stepCount.value = tier.stepCount;
388
494
  gi.radius.value = options.ssgiRadius;
495
+ // Gather at a fraction of the frame. See `ssgiResolutionScale` above for why this is a
496
+ // wrapper rather than a property: the node has no scale of its own, and `setSize` is the
497
+ // public seam the pass drives it through. `setSize` is present on the node and absent
498
+ // from its type declarations, so the seam is named here rather than cast away at the call
499
+ // site — if a future three release declares it, or gives the node a `resolutionScale`,
500
+ // this narrows to nothing and the wrapper can go. Guarded at one texel so a zero or a
501
+ // negative cannot ask for an empty target: a 0x0 gather returns black and reads as SSGI
502
+ // simply not working.
503
+ const ssgiScale = options.ssgiResolutionScale;
504
+ const sizedGi = gi as unknown as {
505
+ setSize?: (width: number, height: number) => void;
506
+ };
507
+ const fullGiSize = sizedGi.setSize?.bind(gi);
508
+ if (ssgiScale > 0 && ssgiScale < 1 && fullGiSize !== undefined) {
509
+ sizedGi.setSize = (width: number, height: number): void => {
510
+ fullGiSize(
511
+ Math.max(1, Math.round(width * ssgiScale)),
512
+ Math.max(1, Math.round(height * ssgiScale)),
513
+ );
514
+ };
515
+ }
389
516
 
390
517
  // SSGI writes two targets: AO in a single-channel `RedFormat` texture, and the GI
391
518
  // term in an RGB one. Multiplying the beauty pass by the whole AO vec4 therefore
@@ -405,7 +532,7 @@ export class WorldEnvironment {
405
532
  stage({
406
533
  name: "ambientOcclusion",
407
534
  build: (input) => {
408
- const contact = ao(depth, normal, view);
535
+ const contact = ao(depth(), normal(), view);
409
536
  contact.radius.value = options.gtaoRadius;
410
537
  contact.scale.value = options.gtaoScale;
411
538
  contact.samples.value = options.gtaoSamples;
@@ -428,11 +555,19 @@ export class WorldEnvironment {
428
555
  if (light === undefined) return "godraysEnabled is true but no godraysLight was passed";
429
556
  if (light.castShadow !== true)
430
557
  return `light '${light.name || "sun"}' does not cast shadows`;
558
+ // `castShadow` is a request, not a result: three allocates the shadow map on the first
559
+ // render that needs it, and `GodraysNode` reads `shadow.map.depthTexture` while the
560
+ // graph is built. Without this check that read throws inside TSL, the chain build
561
+ // fails, and *every* stage is lost — the frame comes back ungraded with no SSGI, no
562
+ // SSR and no tonemap, which looks like a scene problem rather than a missing map.
563
+ // Refusing by name keeps the rest of the chain, which is this stage list's contract.
564
+ if (light.shadow?.map == null)
565
+ return `light '${light.name || "sun"}' has no shadow map yet: set renderer.shadowMap.enabled on the raw renderer (ctx.renderer.raw), and build the chain after the first frame has rendered`;
431
566
  return true;
432
567
  },
433
568
  build: (input) => {
434
569
  const light = target.godraysLight as DirectionalLight;
435
- const shafts = godrays(depth, view, light);
570
+ const shafts = godrays(depth(), view, light);
436
571
  shafts.density.value = options.godraysDensity;
437
572
  shafts.maxDensity.value = options.godraysMaxDensity;
438
573
  shafts.raymarchSteps.value = options.godraysSteps;
@@ -443,7 +578,7 @@ export class WorldEnvironment {
443
578
  // silhouettes the depth term owns. Denoise before the floor: the floor's
444
579
  // subtraction amplifies relative noise on near-floor values.
445
580
  let shaft: ChainNode = convertToTexture(shafts);
446
- if (options.denoiseEnabled) shaft = denoised(denoise(shaft, depth, normal, view));
581
+ if (options.denoiseEnabled) shaft = denoised(denoise(shaft, depth(), normal(), view));
447
582
  // Floor, then scale, then tint. The floor is what turns this from a whole-frame
448
583
  // brightener into a shaft renderer; the tint by the light's own colour is what
449
584
  // stops a warm sun throwing a white beam.
@@ -469,10 +604,10 @@ export class WorldEnvironment {
469
604
  // reflections onto a second copy builds two parallel graphs, and the frame comes
470
605
  // out as the bare background colour.
471
606
  const base = convertToTexture(input);
472
- const reflections = ssr(base, depth, normal as unknown as Parameters<typeof ssr>[2], {
607
+ const reflections = ssr(base, depth(), normal() as unknown as Parameters<typeof ssr>[2], {
473
608
  camera: view,
474
- metalnessNode: metal.r,
475
- roughnessNode: rough.g,
609
+ metalnessNode: metal().r,
610
+ roughnessNode: rough().g,
476
611
  reflectNonMetals: true,
477
612
  });
478
613
  reflections.maxDistance.value = options.ssrMaxDistance;
@@ -493,15 +628,33 @@ export class WorldEnvironment {
493
628
  }),
494
629
  stage({
495
630
  name: "bloom",
496
- build: (input) =>
497
- input.add(
498
- bloom(
499
- convertToTexture(input),
500
- options.bloomStrength,
501
- options.bloomRadius,
502
- options.bloomThreshold,
503
- ),
504
- ),
631
+ dispose: () => {
632
+ releaseBloom();
633
+ releaseBloom = () => {};
634
+ },
635
+ build: (input) => {
636
+ const texture = convertToTexture(input);
637
+ const effect = bloom(
638
+ texture,
639
+ options.bloomStrength,
640
+ options.bloomRadius,
641
+ options.bloomThreshold,
642
+ );
643
+ releaseBloom = () => {
644
+ effect.dispose();
645
+ // convertToTexture may return its input. Only the newly allocated RTT is ours.
646
+ const scratch = texture as unknown as {
647
+ isRTTNode?: boolean;
648
+ renderTarget: { dispose(): void };
649
+ _quadMesh: { material: { dispose(): void } };
650
+ };
651
+ if (texture !== input && scratch.isRTTNode === true) {
652
+ scratch.renderTarget.dispose();
653
+ scratch._quadMesh.material.dispose();
654
+ }
655
+ };
656
+ return input.add(effect);
657
+ },
505
658
  }),
506
659
  stage({
507
660
  name: "vignette",
@@ -517,6 +670,11 @@ export class WorldEnvironment {
517
670
  }),
518
671
  ];
519
672
 
673
+ // The kit's own stages, composed after the built-ins. The factory is called with the two
674
+ // things only this file can produce — the scene pass's depth texture and the resolved tier —
675
+ // and returns the complete authored graph plus the subset to run.
676
+ stages.push(...options.authoredStages({ depthNode: depth(), tier: options.renderChainTier }));
677
+
520
678
  // A composed base colour with every stage off still has to reach the frame. The chain
521
679
  // installs nothing for an empty stage list, so this is the one path that goes direct.
522
680
  if (requested.length === 0) {
@@ -534,11 +692,19 @@ export class WorldEnvironment {
534
692
  if (renderer.createRenderChain === undefined) throw new Error("RenderChain is unavailable.");
535
693
  const chain = renderer.createRenderChain({
536
694
  input: exposed,
537
- request: { stages: requested, tier: "high" },
695
+ request: { stages: requested, tier: options.renderChainTier },
538
696
  stages,
697
+ worldPass: scenePass,
539
698
  });
540
699
  this.#reportApplied(chain.applied.stages, chain.applied.dropped);
541
- return { dropped: chain.applied.dropped, stages: chain.applied.stages };
700
+ return {
701
+ dropped: chain.applied.dropped,
702
+ stages: chain.applied.stages,
703
+ dispose: () => {
704
+ chain.dispose();
705
+ scenePass.dispose();
706
+ },
707
+ };
542
708
  }
543
709
 
544
710
  /**
@@ -555,7 +721,7 @@ export class WorldEnvironment {
555
721
  dropped: readonly { name: string; reason: string }[],
556
722
  ): void {
557
723
  const options = this.#options;
558
- const off: Record<ChainStage["name"], string> = {
724
+ const off: Record<string, string> = {
559
725
  ambientOcclusion: "gtaoEnabled is false",
560
726
  bloom: "bloomEnabled is false",
561
727
  godRays: "godraysEnabled is false",
@@ -563,12 +729,17 @@ export class WorldEnvironment {
563
729
  ssgi: "ssgiEnabled is false",
564
730
  ssr: "ssrEnabled is false",
565
731
  vignette: "vignetteAmount is 0",
732
+ kuwahara: "kuwaharaEnabled is false",
733
+ outline: "outlineEnabled is false",
734
+ watercolor: "watercolorEnabled is false",
566
735
  };
567
- const stages = (Object.keys(off) as ChainStage["name"][]).sort().map((name) => {
568
- if (applied.includes(name)) return { applied: true, name };
569
- const refused = dropped.find((entry) => entry.name === name);
570
- return { applied: false, name, reason: refused?.reason ?? off[name] };
571
- });
736
+ const stages = Object.keys(off)
737
+ .sort()
738
+ .map((name) => {
739
+ if (applied.includes(name)) return { applied: true, name };
740
+ const refused = dropped.find((entry) => entry.name === name);
741
+ return { applied: false, name, reason: refused?.reason ?? off[name] };
742
+ });
572
743
  console.info(
573
744
  `TN_WORLD_ENVIRONMENT:${JSON.stringify({
574
745
  denoise: options.denoiseEnabled,
@@ -581,3 +752,7 @@ export class WorldEnvironment {
581
752
  );
582
753
  }
583
754
  }
755
+
756
+ function isChainTier(value: unknown): value is ChainTier {
757
+ return value === "high" || value === "medium" || value === "low" || value === "off";
758
+ }