create-threenative 0.2.10 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (737) hide show
  1. package/agent-docs/references/assertion-reference.md +109 -3
  2. package/agent-docs/references/auto-exposure.md +28 -45
  3. package/agent-docs/references/build-profiles.md +1 -1
  4. package/agent-docs/references/capability-reference.md +527 -44
  5. package/agent-docs/references/debug-surface.md +64 -0
  6. package/agent-docs/references/finding-assets.md +11 -12
  7. package/agent-docs/references/performance-basics.md +19 -0
  8. package/agent-docs/references/trace-a-slow-frame.md +21 -0
  9. package/agent-docs/references/visual-baseline.md +23 -4
  10. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/prd-creator/SKILL.md +17 -6
  12. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +87 -23
  13. package/agent-files/.agents/skills/threenative-performance/SKILL.md +12 -11
  14. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  15. package/agent-files/scripts/reference.mjs +9 -4
  16. package/capabilities.json +739 -50
  17. package/dist/index.d.ts +40 -6
  18. package/dist/index.js +227 -34
  19. package/dist/quality.d.ts +12 -0
  20. package/dist/quality.js +166747 -0
  21. package/dist/threenative.js +60 -44
  22. package/dist/web-engine-gltf-loader.js +2 -0
  23. package/dist/web-engine-mesh-bvh-webgpu.js +1 -1
  24. package/dist/web-engine-mesh-bvh.js +7 -0
  25. package/dist/web-engine-post-effects.js +645 -19
  26. package/dist/web-engine-runtime.js +3528 -343
  27. package/package.json +19 -9
  28. package/template-assets/assets/bay-PROVENANCE.md +21 -0
  29. package/template-assets/assets/bay-ground.webp +0 -0
  30. package/template-assets/assets/bay-metal.webp +0 -0
  31. package/template-assets/assets/bay-pavement-normal.webp +0 -0
  32. package/template-assets/assets/bay-pavement.webp +0 -0
  33. package/template-assets/assets/bay-plaster-normal.webp +0 -0
  34. package/template-assets/assets/bay-plaster.webp +0 -0
  35. package/template-assets/assets/bay-wood-normal.webp +0 -0
  36. package/template-assets/assets/bay-wood.webp +0 -0
  37. package/template-assets/assets/tex-PROVENANCE.md +25 -0
  38. package/template-assets/assets/tex-bark-normal.webp +0 -0
  39. package/template-assets/assets/tex-bark.webp +0 -0
  40. package/template-assets/assets/tex-birch-bark.webp +0 -0
  41. package/template-assets/assets/tex-grass.webp +0 -0
  42. package/template-assets/assets/tex-planks-normal.webp +0 -0
  43. package/template-assets/assets/tex-planks.webp +0 -0
  44. package/template-assets/assets/tex-rock-normal.webp +0 -0
  45. package/template-assets/assets/tex-rock.webp +0 -0
  46. package/template-assets/assets/tex-roof-tiles-normal.webp +0 -0
  47. package/template-assets/assets/tex-roof-tiles.webp +0 -0
  48. package/template-assets/assets/tex-sand-normal.webp +0 -0
  49. package/template-assets/assets/tex-sand.webp +0 -0
  50. package/template-assets/assets/tex-stone-wall-normal.webp +0 -0
  51. package/template-assets/assets/tex-stone-wall.webp +0 -0
  52. package/template-assets/kitExposure.ts +20 -0
  53. package/template-assets/patches/three@0.185.1.patch +481 -272
  54. package/template-assets/quality/biome.json +7 -0
  55. package/template-assets/quality/eslint.config.js +3 -0
  56. package/template-assets/realistic-ocean/README.md +113 -0
  57. package/template-assets/realistic-ocean/install.mjs +56 -0
  58. package/template-assets/realistic-ocean/src/realisticOcean.ts +151 -0
  59. package/template-assets/realistic-ocean/src/realisticOceanLifetime.ts +29 -0
  60. package/template-assets/realistic-ocean/src/render/REALISTIC-OCEAN-LICENSE.txt +25 -0
  61. package/template-assets/realistic-ocean/src/render/realisticSea.ts +642 -0
  62. package/template-assets/realistic-ocean/src/render/realisticSeaMaps.ts +311 -0
  63. package/template-assets/realistic-ocean/src/render/realisticSpectrum.ts +289 -0
  64. package/templates/AGENTS.md +21 -0
  65. package/templates/CLAUDE.md +23 -0
  66. package/templates/action-rpg/.codex/config.toml +6 -2
  67. package/templates/action-rpg/.cursor/mcp.json +8 -2
  68. package/templates/action-rpg/.gemini/settings.json +8 -2
  69. package/templates/action-rpg/.mcp.json +8 -2
  70. package/templates/action-rpg/.vscode/mcp.json +9 -2
  71. package/templates/action-rpg/.zed/settings.json +9 -2
  72. package/templates/action-rpg/AGENTS.md +11 -11
  73. package/templates/action-rpg/CLAUDE.md +11 -11
  74. package/templates/action-rpg/opencode.json +10 -2
  75. package/templates/action-rpg/package.json +15 -10
  76. package/templates/action-rpg/playtests/combat.playtest.json +6 -0
  77. package/templates/action-rpg/playtests/inventory.playtest.json +22 -0
  78. package/templates/action-rpg/playtests/performance.playtest.json +1 -1
  79. package/templates/action-rpg/playtests/roll.playtest.json +112 -0
  80. package/templates/action-rpg/playtests/swing.playtest.json +55 -0
  81. package/templates/action-rpg/playtests/win.playtest.json +4 -4
  82. package/templates/action-rpg/src/entities/Fighter.ts +44 -4
  83. package/templates/action-rpg/src/entities/Player.ts +64 -12
  84. package/templates/action-rpg/src/render/atmosphere.ts +444 -0
  85. package/templates/action-rpg/src/render/backlightMaterial.ts +49 -18
  86. package/templates/action-rpg/src/render/clouds.ts +605 -0
  87. package/templates/action-rpg/src/render/dungeon.ts +8 -6
  88. package/templates/action-rpg/src/render/exposure.ts +11 -109
  89. package/templates/action-rpg/src/render/gpuSky.ts +752 -0
  90. package/templates/action-rpg/src/render/lighting.ts +27 -4
  91. package/templates/action-rpg/src/render/materialLighting.ts +2 -11
  92. package/templates/action-rpg/src/render/palette.ts +1 -0
  93. package/templates/action-rpg/src/render/postprocessing.ts +4 -4
  94. package/templates/action-rpg/src/render/props.ts +10 -8
  95. package/templates/action-rpg/src/render/quality.ts +56 -108
  96. package/templates/action-rpg/src/render/sky.ts +74 -1
  97. package/templates/action-rpg/src/scenes/Play.ts +16 -12
  98. package/templates/action-rpg/src/ui/CharacterPanel.tsx +7 -2
  99. package/templates/action-rpg/src/ui/Hud.tsx +5 -7
  100. package/templates/action-rpg/src/ui/InventoryPanel.tsx +14 -14
  101. package/templates/action-rpg/threenative.config.ts +3 -0
  102. package/templates/adventure/.codex/config.toml +23 -0
  103. package/templates/adventure/.cursor/mcp.json +38 -0
  104. package/templates/adventure/.gemini/settings.json +38 -0
  105. package/templates/adventure/.mcp.json +38 -0
  106. package/templates/adventure/.vscode/mcp.json +43 -0
  107. package/templates/adventure/.zed/settings.json +43 -0
  108. package/templates/adventure/AGENTS.md +60 -0
  109. package/templates/adventure/CLAUDE.md +62 -0
  110. package/templates/adventure/index.html +14 -0
  111. package/templates/adventure/kit.json +8 -0
  112. package/templates/adventure/native-playtests/survives.playtest.json +52 -0
  113. package/templates/adventure/opencode.json +49 -0
  114. package/templates/adventure/package.json +65 -0
  115. package/templates/adventure/playtests/boss.playtest.json +406 -0
  116. package/templates/adventure/playtests/combat.playtest.json +342 -0
  117. package/templates/adventure/playtests/controls.playtest.json +142 -0
  118. package/templates/adventure/playtests/explore.playtest.json +45 -0
  119. package/templates/adventure/playtests/flicker.playtest.json +206 -0
  120. package/templates/adventure/playtests/hearts.playtest.json +171 -0
  121. package/templates/adventure/playtests/lockon.playtest.json +256 -0
  122. package/templates/adventure/playtests/look.playtest.json +72 -0
  123. package/templates/adventure/playtests/move-hollow.playtest.json +106 -0
  124. package/templates/adventure/playtests/move.playtest.json +84 -0
  125. package/templates/adventure/playtests/performance.playtest.json +55 -0
  126. package/templates/adventure/playtests/puzzle.playtest.json +250 -0
  127. package/templates/adventure/playtests/stride.playtest.json +67 -0
  128. package/templates/adventure/playtests/survives.playtest.json +171 -0
  129. package/templates/adventure/playtests/thornback.playtest.json +267 -0
  130. package/templates/adventure/public/favicon.svg +4 -0
  131. package/templates/adventure/src/entities/Block.ts +114 -0
  132. package/templates/adventure/src/entities/Chest.ts +69 -0
  133. package/templates/adventure/src/entities/Door.ts +81 -0
  134. package/templates/adventure/src/entities/Dummy.ts +69 -0
  135. package/templates/adventure/src/entities/Flicker.ts +239 -0
  136. package/templates/adventure/src/entities/Hero.ts +561 -0
  137. package/templates/adventure/src/entities/LockOn.ts +180 -0
  138. package/templates/adventure/src/entities/Mossling.ts +249 -0
  139. package/templates/adventure/src/entities/Switch.ts +49 -0
  140. package/templates/adventure/src/entities/Thornback.ts +238 -0
  141. package/templates/adventure/src/entities/Warden.ts +196 -0
  142. package/templates/adventure/src/game.ts +65 -0
  143. package/templates/adventure/src/interact.ts +63 -0
  144. package/templates/adventure/src/level/Hollow.ts +240 -0
  145. package/templates/adventure/src/level/Vale.ts +383 -0
  146. package/templates/adventure/src/main.ts +18 -0
  147. package/templates/adventure/src/render/camera.ts +416 -0
  148. package/templates/adventure/src/render/creatures.ts +405 -0
  149. package/templates/adventure/src/render/effects.ts +333 -0
  150. package/templates/adventure/src/render/foliage.ts +1072 -0
  151. package/templates/adventure/src/render/hero.ts +1447 -0
  152. package/templates/adventure/src/render/kitExposure.ts +20 -0
  153. package/templates/adventure/src/render/lighting.ts +74 -0
  154. package/templates/adventure/src/render/loading.ts +332 -0
  155. package/templates/adventure/src/render/materials.ts +179 -0
  156. package/templates/adventure/src/render/palette.ts +137 -0
  157. package/templates/adventure/src/render/postprocessing.ts +70 -0
  158. package/templates/adventure/src/render/props.ts +383 -0
  159. package/templates/adventure/src/render/quality.ts +46 -0
  160. package/templates/adventure/src/render/sky.ts +271 -0
  161. package/templates/adventure/src/render/surface.ts +259 -0
  162. package/templates/adventure/src/render/touch-controls.ts +137 -0
  163. package/templates/adventure/src/scenes/Play.ts +959 -0
  164. package/templates/adventure/src/state.ts +113 -0
  165. package/templates/adventure/src/style.css +98 -0
  166. package/templates/adventure/src/ui/App.tsx +22 -0
  167. package/templates/adventure/src/ui/GameUi.tsx +20 -0
  168. package/templates/adventure/src/ui/Hud.tsx +70 -0
  169. package/templates/adventure/src/ui/Menu.tsx +15 -0
  170. package/templates/adventure/src/ui/main.tsx +14 -0
  171. package/templates/adventure/tailwind.config.ts +2 -0
  172. package/templates/adventure/threenative.config.ts +62 -0
  173. package/templates/adventure/tsconfig.json +17 -0
  174. package/templates/adventure/vite.config.ts +49 -0
  175. package/templates/collectathon/.codex/config.toml +23 -0
  176. package/templates/collectathon/.cursor/mcp.json +38 -0
  177. package/templates/collectathon/.gemini/settings.json +38 -0
  178. package/templates/collectathon/.mcp.json +38 -0
  179. package/templates/collectathon/.vscode/mcp.json +43 -0
  180. package/templates/collectathon/.zed/settings.json +43 -0
  181. package/templates/collectathon/AGENTS.md +58 -0
  182. package/templates/collectathon/CLAUDE.md +60 -0
  183. package/templates/collectathon/index.html +14 -0
  184. package/templates/collectathon/kit.json +8 -0
  185. package/templates/collectathon/native-playtests/survives.playtest.json +52 -0
  186. package/templates/collectathon/opencode.json +49 -0
  187. package/templates/collectathon/package.json +65 -0
  188. package/templates/collectathon/playtests/acrobatics.playtest.json +238 -0
  189. package/templates/collectathon/playtests/camera.playtest.json +80 -0
  190. package/templates/collectathon/playtests/clipped-probe.playtest.json +101 -0
  191. package/templates/collectathon/playtests/collect.playtest.json +196 -0
  192. package/templates/collectathon/playtests/combat.playtest.json +246 -0
  193. package/templates/collectathon/playtests/double-tap-air.playtest.json +198 -0
  194. package/templates/collectathon/playtests/double-tap.playtest.json +136 -0
  195. package/templates/collectathon/playtests/effects.playtest.json +124 -0
  196. package/templates/collectathon/playtests/enemies.playtest.json +295 -0
  197. package/templates/collectathon/playtests/explore.playtest.json +45 -0
  198. package/templates/collectathon/playtests/hop-reach.playtest.json +117 -0
  199. package/templates/collectathon/playtests/jump-chain.playtest.json +274 -0
  200. package/templates/collectathon/playtests/ledge-angle.playtest.json +107 -0
  201. package/templates/collectathon/playtests/ledge-too-high.playtest.json +115 -0
  202. package/templates/collectathon/playtests/ledge.playtest.json +100 -0
  203. package/templates/collectathon/playtests/look.playtest.json +64 -0
  204. package/templates/collectathon/playtests/performance.playtest.json +55 -0
  205. package/templates/collectathon/playtests/stride.playtest.json +111 -0
  206. package/templates/collectathon/playtests/survives.playtest.json +123 -0
  207. package/templates/collectathon/playtests/telegraphs.playtest.json +132 -0
  208. package/templates/collectathon/playtests/thornback.playtest.json +157 -0
  209. package/templates/collectathon/playtests/wall-kick.playtest.json +206 -0
  210. package/templates/collectathon/playtests/win.playtest.json +166 -0
  211. package/templates/collectathon/public/favicon.svg +4 -0
  212. package/templates/collectathon/src/entities/Hero.ts +915 -0
  213. package/templates/collectathon/src/entities/Pickup.ts +63 -0
  214. package/templates/collectathon/src/entities/Walker.ts +248 -0
  215. package/templates/collectathon/src/game.ts +51 -0
  216. package/templates/collectathon/src/level/Course.ts +590 -0
  217. package/templates/collectathon/src/level/terrain.ts +144 -0
  218. package/templates/collectathon/src/main.ts +14 -0
  219. package/templates/collectathon/src/playtest-events.ts +15 -0
  220. package/templates/collectathon/src/render/camera.ts +163 -0
  221. package/templates/collectathon/src/render/castle.ts +408 -0
  222. package/templates/collectathon/src/render/effects.ts +284 -0
  223. package/templates/collectathon/src/render/foliage.ts +744 -0
  224. package/templates/collectathon/src/render/ground.ts +139 -0
  225. package/templates/collectathon/src/render/hero.ts +452 -0
  226. package/templates/collectathon/src/render/kitExposure.ts +20 -0
  227. package/templates/collectathon/src/render/lighting.ts +65 -0
  228. package/templates/collectathon/src/render/loading.ts +332 -0
  229. package/templates/collectathon/src/render/materials.ts +196 -0
  230. package/templates/collectathon/src/render/palette.ts +82 -0
  231. package/templates/collectathon/src/render/postprocessing.ts +79 -0
  232. package/templates/collectathon/src/render/props.ts +218 -0
  233. package/templates/collectathon/src/render/quality.ts +54 -0
  234. package/templates/collectathon/src/render/sky.ts +262 -0
  235. package/templates/collectathon/src/render/surface.ts +269 -0
  236. package/templates/collectathon/src/render/touch-controls.ts +179 -0
  237. package/templates/collectathon/src/render/touch-layout.ts +48 -0
  238. package/templates/collectathon/src/render/water.ts +191 -0
  239. package/templates/collectathon/src/scenes/Play.ts +481 -0
  240. package/templates/collectathon/src/state.ts +38 -0
  241. package/templates/collectathon/src/style.css +106 -0
  242. package/templates/collectathon/src/ui/App.tsx +22 -0
  243. package/templates/collectathon/src/ui/GameUi.tsx +20 -0
  244. package/templates/collectathon/src/ui/Hud.tsx +77 -0
  245. package/templates/collectathon/src/ui/Menu.tsx +13 -0
  246. package/templates/collectathon/src/ui/main.tsx +14 -0
  247. package/templates/collectathon/tailwind.config.ts +2 -0
  248. package/templates/collectathon/threenative.config.ts +62 -0
  249. package/templates/collectathon/tsconfig.json +17 -0
  250. package/templates/collectathon/vite.config.ts +49 -0
  251. package/templates/kart/.codex/config.toml +23 -0
  252. package/templates/kart/.cursor/mcp.json +38 -0
  253. package/templates/kart/.gemini/settings.json +38 -0
  254. package/templates/kart/.mcp.json +38 -0
  255. package/templates/kart/.vscode/mcp.json +43 -0
  256. package/templates/kart/.zed/settings.json +43 -0
  257. package/templates/kart/AGENTS.md +58 -0
  258. package/templates/kart/CLAUDE.md +60 -0
  259. package/templates/kart/index.html +14 -0
  260. package/templates/kart/kit.json +8 -0
  261. package/templates/kart/native-playtests/survives.playtest.json +65 -0
  262. package/templates/kart/opencode.json +49 -0
  263. package/templates/kart/package.json +64 -0
  264. package/templates/kart/playtests/drift.playtest.json +226 -0
  265. package/templates/kart/playtests/explore.playtest.json +45 -0
  266. package/templates/kart/playtests/hit-stays-above-road.playtest.json +92 -0
  267. package/templates/kart/playtests/item-key.playtest.json +108 -0
  268. package/templates/kart/playtests/items.playtest.json +143 -0
  269. package/templates/kart/playtests/lap-times.playtest.json +138 -0
  270. package/templates/kart/playtests/laps.playtest.json +149 -0
  271. package/templates/kart/playtests/performance.playtest.json +57 -0
  272. package/templates/kart/playtests/race.playtest.json +294 -0
  273. package/templates/kart/playtests/restart.playtest.json +87 -0
  274. package/templates/kart/playtests/rocket-start.playtest.json +56 -0
  275. package/templates/kart/playtests/smooth-drive.playtest.json +101 -0
  276. package/templates/kart/playtests/surfaces.playtest.json +113 -0
  277. package/templates/kart/playtests/survives.playtest.json +116 -0
  278. package/templates/kart/playtests/wall.playtest.json +118 -0
  279. package/templates/kart/public/favicon.svg +4 -0
  280. package/templates/kart/src/entities/Driver.ts +123 -0
  281. package/templates/kart/src/entities/Items.ts +194 -0
  282. package/templates/kart/src/entities/Kart.ts +517 -0
  283. package/templates/kart/src/game.ts +45 -0
  284. package/templates/kart/src/main.ts +14 -0
  285. package/templates/kart/src/playtest-events.ts +15 -0
  286. package/templates/kart/src/render/camera.ts +83 -0
  287. package/templates/kart/src/render/course.ts +579 -0
  288. package/templates/kart/src/render/effects.ts +266 -0
  289. package/templates/kart/src/render/items.ts +163 -0
  290. package/templates/kart/src/render/kart.ts +256 -0
  291. package/templates/kart/src/render/kitExposure.ts +20 -0
  292. package/templates/kart/src/render/lighting.ts +58 -0
  293. package/templates/kart/src/render/loading.ts +332 -0
  294. package/templates/kart/src/render/materials.ts +119 -0
  295. package/templates/kart/src/render/palette.ts +74 -0
  296. package/templates/kart/src/render/postprocessing.ts +79 -0
  297. package/templates/kart/src/render/quality.ts +54 -0
  298. package/templates/kart/src/render/skids.ts +86 -0
  299. package/templates/kart/src/render/sky.ts +105 -0
  300. package/templates/kart/src/render/touch-controls.ts +168 -0
  301. package/templates/kart/src/render/touch-layout.ts +48 -0
  302. package/templates/kart/src/scenes/Race.ts +850 -0
  303. package/templates/kart/src/state.ts +53 -0
  304. package/templates/kart/src/style.css +106 -0
  305. package/templates/kart/src/track/Course.ts +276 -0
  306. package/templates/kart/src/track/Race.ts +133 -0
  307. package/templates/kart/src/ui/App.tsx +21 -0
  308. package/templates/kart/src/ui/GameUi.tsx +20 -0
  309. package/templates/kart/src/ui/Hud.tsx +172 -0
  310. package/templates/kart/src/ui/Menu.tsx +13 -0
  311. package/templates/kart/src/ui/main.tsx +14 -0
  312. package/templates/kart/tailwind.config.ts +2 -0
  313. package/templates/kart/threenative.config.ts +62 -0
  314. package/templates/kart/tsconfig.json +17 -0
  315. package/templates/kart/vite.config.ts +49 -0
  316. package/templates/minimal/.codex/config.toml +6 -2
  317. package/templates/minimal/.cursor/mcp.json +8 -2
  318. package/templates/minimal/.gemini/settings.json +8 -2
  319. package/templates/minimal/.mcp.json +8 -2
  320. package/templates/minimal/.vscode/mcp.json +9 -2
  321. package/templates/minimal/.zed/settings.json +9 -2
  322. package/templates/minimal/AGENTS.md +11 -13
  323. package/templates/minimal/CLAUDE.md +11 -13
  324. package/templates/minimal/opencode.json +10 -2
  325. package/templates/minimal/package.json +14 -9
  326. package/templates/minimal/playtests/camera-wall.playtest.json +36 -0
  327. package/templates/minimal/playtests/jump.playtest.json +45 -0
  328. package/templates/minimal/playtests/play.playtest.json +1 -1
  329. package/templates/minimal/src/game.ts +2 -0
  330. package/templates/minimal/src/render/atmosphere.ts +444 -0
  331. package/templates/minimal/src/render/backlightMaterial.ts +49 -18
  332. package/templates/minimal/src/render/camera.ts +35 -4
  333. package/templates/minimal/src/render/clouds.ts +605 -0
  334. package/templates/minimal/src/render/exposure.ts +7 -111
  335. package/templates/minimal/src/render/gpuSky.ts +752 -0
  336. package/templates/minimal/src/render/lighting.ts +26 -4
  337. package/templates/minimal/src/render/materialLighting.ts +2 -10
  338. package/templates/minimal/src/render/postprocessing.ts +4 -4
  339. package/templates/minimal/src/render/quality.ts +10 -116
  340. package/templates/minimal/src/render/sky.ts +73 -1
  341. package/templates/minimal/src/scenes/Play.ts +18 -7
  342. package/templates/platformer/.codex/config.toml +6 -2
  343. package/templates/platformer/.cursor/mcp.json +8 -2
  344. package/templates/platformer/.gemini/settings.json +8 -2
  345. package/templates/platformer/.mcp.json +8 -2
  346. package/templates/platformer/.vscode/mcp.json +9 -2
  347. package/templates/platformer/.zed/settings.json +9 -2
  348. package/templates/platformer/AGENTS.md +13 -9
  349. package/templates/platformer/CLAUDE.md +13 -9
  350. package/templates/platformer/opencode.json +10 -2
  351. package/templates/platformer/package.json +15 -10
  352. package/templates/platformer/playtests/dash-jump.playtest.json +34 -0
  353. package/templates/platformer/playtests/finish.playtest.json +58 -0
  354. package/templates/platformer/playtests/idle.playtest.json +44 -0
  355. package/templates/platformer/playtests/performance.playtest.json +1 -1
  356. package/templates/platformer/src/entities/Fox.ts +19 -6
  357. package/templates/platformer/src/game.ts +1 -0
  358. package/templates/platformer/src/level/Stage.ts +4 -1
  359. package/templates/platformer/src/render/backlightMaterial.ts +49 -18
  360. package/templates/platformer/src/render/camera.ts +30 -1
  361. package/templates/platformer/src/render/exposure.ts +6 -111
  362. package/templates/platformer/src/render/fox.ts +5 -2
  363. package/templates/platformer/src/render/kitExposure.ts +20 -0
  364. package/templates/platformer/src/render/materialLighting.ts +2 -11
  365. package/templates/platformer/src/render/postprocessing.ts +4 -4
  366. package/templates/platformer/src/render/props.ts +1 -2
  367. package/templates/platformer/src/render/quality.ts +10 -118
  368. package/templates/platformer/src/scenes/Play.ts +31 -15
  369. package/templates/platformer/src/ui/Menu.tsx +1 -1
  370. package/templates/puzzle/.codex/config.toml +6 -2
  371. package/templates/puzzle/.cursor/mcp.json +8 -2
  372. package/templates/puzzle/.gemini/settings.json +8 -2
  373. package/templates/puzzle/.mcp.json +8 -2
  374. package/templates/puzzle/.vscode/mcp.json +9 -2
  375. package/templates/puzzle/.zed/settings.json +9 -2
  376. package/templates/puzzle/AGENTS.md +14 -17
  377. package/templates/puzzle/CLAUDE.md +14 -17
  378. package/templates/puzzle/opencode.json +10 -2
  379. package/templates/puzzle/package.json +15 -10
  380. package/templates/puzzle/playtests/performance.playtest.json +1 -1
  381. package/templates/puzzle/playtests/replay-keeps-progress.playtest.json +78 -0
  382. package/templates/puzzle/src/render/backlightMaterial.ts +49 -18
  383. package/templates/puzzle/src/render/exposure.ts +11 -109
  384. package/templates/puzzle/src/render/lighting.ts +3 -3
  385. package/templates/puzzle/src/render/materialLighting.ts +2 -11
  386. package/templates/puzzle/src/render/palette.ts +1 -1
  387. package/templates/puzzle/src/render/postprocessing.ts +4 -4
  388. package/templates/puzzle/src/render/quality.ts +44 -153
  389. package/templates/puzzle/src/render/vault.ts +18 -6
  390. package/templates/puzzle/src/scenes/Play.ts +6 -1
  391. package/templates/puzzle/src/ui/Hud.tsx +8 -43
  392. package/templates/racing/.codex/config.toml +6 -2
  393. package/templates/racing/.cursor/mcp.json +8 -2
  394. package/templates/racing/.gemini/settings.json +8 -2
  395. package/templates/racing/.mcp.json +8 -2
  396. package/templates/racing/.vscode/mcp.json +9 -2
  397. package/templates/racing/.zed/settings.json +9 -2
  398. package/templates/racing/AGENTS.md +10 -12
  399. package/templates/racing/CLAUDE.md +10 -12
  400. package/templates/racing/opencode.json +10 -2
  401. package/templates/racing/package.json +15 -10
  402. package/templates/racing/playtests/brake.playtest.json +54 -0
  403. package/templates/racing/playtests/outcome.playtest.json +19 -0
  404. package/templates/racing/playtests/performance.playtest.json +1 -1
  405. package/templates/racing/playtests/stopped-car-is-not-rescued.playtest.json +59 -0
  406. package/templates/racing/src/entities/RacingCar.ts +12 -3
  407. package/templates/racing/src/entities/Rival.ts +11 -2
  408. package/templates/racing/src/render/atmosphere.ts +444 -0
  409. package/templates/racing/src/render/backlightMaterial.ts +49 -18
  410. package/templates/racing/src/render/clouds.ts +605 -0
  411. package/templates/racing/src/render/exposure.ts +6 -111
  412. package/templates/racing/src/render/gpuSky.ts +752 -0
  413. package/templates/racing/src/render/kitExposure.ts +20 -0
  414. package/templates/racing/src/render/lighting.ts +26 -4
  415. package/templates/racing/src/render/materialLighting.ts +2 -11
  416. package/templates/racing/src/render/materials.ts +2 -1
  417. package/templates/racing/src/render/postprocessing.ts +4 -4
  418. package/templates/racing/src/render/quality.ts +27 -115
  419. package/templates/racing/src/render/sky.ts +72 -1
  420. package/templates/racing/src/scenes/Race.ts +9 -7
  421. package/templates/racing/src/track/TrackSector.ts +5 -2
  422. package/templates/racing/src/ui/Hud.tsx +12 -7
  423. package/templates/rain/.codex/config.toml +6 -2
  424. package/templates/rain/.cursor/mcp.json +8 -2
  425. package/templates/rain/.gemini/settings.json +8 -2
  426. package/templates/rain/.mcp.json +8 -2
  427. package/templates/rain/.vscode/mcp.json +9 -2
  428. package/templates/rain/.zed/settings.json +9 -2
  429. package/templates/rain/AGENTS.md +12 -12
  430. package/templates/rain/CLAUDE.md +12 -12
  431. package/templates/rain/opencode.json +10 -2
  432. package/templates/rain/package.json +14 -9
  433. package/templates/rain/playtests/performance.playtest.json +1 -1
  434. package/templates/rain/src/game.ts +1 -1
  435. package/templates/rain/src/render/bloom-shader.ts +1 -1
  436. package/templates/rain/src/render/clouds-shader.ts +2 -2
  437. package/templates/rain/src/render/clouds.ts +2 -1
  438. package/templates/rain/src/render/exposure.ts +11 -109
  439. package/templates/rain/src/render/post-shader.ts +7 -11
  440. package/templates/rain/src/render/postprocessing.ts +8 -24
  441. package/templates/rain/src/render/quality.ts +44 -98
  442. package/templates/rain/src/render/world-shader.ts +281 -97
  443. package/templates/rain/src/render/world.ts +82 -2
  444. package/templates/rain/src/style.css +1 -1
  445. package/templates/rain/src/ui/GameUi.tsx +6 -2
  446. package/templates/rain/src/ui/Hud.tsx +1 -1
  447. package/templates/rain/tools/generate-shaders.mjs +2 -2
  448. package/templates/rain/tools/tempest-post.frag +4 -6
  449. package/templates/rain/tools/tempest-world.frag +80 -12
  450. package/templates/rts/.codex/config.toml +6 -2
  451. package/templates/rts/.cursor/mcp.json +8 -2
  452. package/templates/rts/.gemini/settings.json +8 -2
  453. package/templates/rts/.mcp.json +8 -2
  454. package/templates/rts/.vscode/mcp.json +9 -2
  455. package/templates/rts/.zed/settings.json +9 -2
  456. package/templates/rts/AGENTS.md +15 -16
  457. package/templates/rts/CLAUDE.md +15 -16
  458. package/templates/rts/opencode.json +10 -2
  459. package/templates/rts/package.json +14 -9
  460. package/templates/rts/playtests/performance.playtest.json +1 -1
  461. package/templates/rts/playtests/rts-attack.playtest.json +5 -0
  462. package/templates/rts/playtests/rts-build.playtest.json +20 -1
  463. package/templates/rts/playtests/rts-orders.playtest.json +1 -1
  464. package/templates/rts/playtests/rts-pause.playtest.json +112 -0
  465. package/templates/rts/playtests/rts-train.playtest.json +1 -1
  466. package/templates/rts/playtests/rts-zoom.playtest.json +81 -0
  467. package/templates/rts/src/game.ts +29 -7
  468. package/templates/rts/src/render/army.ts +181 -49
  469. package/templates/rts/src/render/backlightMaterial.ts +49 -18
  470. package/templates/rts/src/render/environment.ts +276 -0
  471. package/templates/rts/src/render/exposure.ts +3 -65
  472. package/templates/rts/src/render/ground.ts +478 -0
  473. package/templates/rts/src/render/lighting.ts +62 -11
  474. package/templates/rts/src/render/materialLighting.ts +2 -11
  475. package/templates/rts/src/render/materials.ts +47 -118
  476. package/templates/rts/src/render/palette.ts +30 -13
  477. package/templates/rts/src/render/picking.ts +18 -0
  478. package/templates/rts/src/render/postprocessing.ts +4 -4
  479. package/templates/rts/src/render/quality.ts +64 -85
  480. package/templates/rts/src/render/resources.ts +21 -22
  481. package/templates/rts/src/render/sky.ts +9 -12
  482. package/templates/rts/src/render/terrain.ts +36 -11
  483. package/templates/rts/src/scenes/Play.ts +373 -38
  484. package/templates/rts/src/sim/ai.ts +0 -11
  485. package/templates/rts/src/state.ts +46 -0
  486. package/templates/rts/src/style.css +1543 -0
  487. package/templates/rts/src/ui/Commands.tsx +204 -107
  488. package/templates/rts/src/ui/GameUi.tsx +12 -5
  489. package/templates/rts/src/ui/Hud.tsx +611 -116
  490. package/templates/rts/src/ui/Minimap.tsx +103 -37
  491. package/templates/rts/src/ui/icons.tsx +116 -0
  492. package/templates/rts/src/ui/labels.ts +73 -0
  493. package/templates/rts/src/ui/minimapPoint.ts +30 -0
  494. package/templates/rts/threenative.config.ts +1 -1
  495. package/templates/runner/.codex/config.toml +6 -2
  496. package/templates/runner/.cursor/mcp.json +8 -2
  497. package/templates/runner/.gemini/settings.json +8 -2
  498. package/templates/runner/.mcp.json +8 -2
  499. package/templates/runner/.vscode/mcp.json +9 -2
  500. package/templates/runner/.zed/settings.json +9 -2
  501. package/templates/runner/AGENTS.md +12 -12
  502. package/templates/runner/CLAUDE.md +12 -12
  503. package/templates/runner/opencode.json +10 -2
  504. package/templates/runner/package.json +15 -10
  505. package/templates/runner/playtests/near-miss.playtest.json +48 -0
  506. package/templates/runner/playtests/performance.playtest.json +2 -2
  507. package/templates/runner/playtests/stride.playtest.json +27 -0
  508. package/templates/runner/playtests/survives.playtest.json +2 -2
  509. package/templates/runner/src/conventions.ts +3 -1
  510. package/templates/runner/src/entities/Runner.ts +11 -5
  511. package/templates/runner/src/render/atmosphere.ts +444 -0
  512. package/templates/runner/src/render/backlightMaterial.ts +49 -18
  513. package/templates/runner/src/render/clouds.ts +605 -0
  514. package/templates/runner/src/render/exposure.ts +6 -111
  515. package/templates/runner/src/render/gpuSky.ts +752 -0
  516. package/templates/runner/src/render/kitExposure.ts +20 -0
  517. package/templates/runner/src/render/lighting.ts +26 -4
  518. package/templates/runner/src/render/materialLighting.ts +2 -11
  519. package/templates/runner/src/render/postprocessing.ts +4 -4
  520. package/templates/runner/src/render/quality.ts +26 -114
  521. package/templates/runner/src/render/sky.ts +73 -1
  522. package/templates/runner/src/scenes/Run.ts +19 -15
  523. package/templates/runner/src/track.ts +12 -3
  524. package/templates/sailing/.codex/config.toml +6 -2
  525. package/templates/sailing/.cursor/mcp.json +8 -2
  526. package/templates/sailing/.gemini/settings.json +8 -2
  527. package/templates/sailing/.mcp.json +8 -2
  528. package/templates/sailing/.vscode/mcp.json +9 -2
  529. package/templates/sailing/.zed/settings.json +9 -2
  530. package/templates/sailing/AGENTS.md +10 -11
  531. package/templates/sailing/CLAUDE.md +10 -11
  532. package/templates/sailing/opencode.json +10 -2
  533. package/templates/sailing/package.json +15 -10
  534. package/templates/sailing/playtests/fail.playtest.json +46 -5
  535. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +7 -0
  536. package/templates/sailing/playtests/performance.playtest.json +1 -1
  537. package/templates/sailing/src/game.ts +1 -0
  538. package/templates/sailing/src/render/backlightMaterial.ts +49 -18
  539. package/templates/sailing/src/render/exposure.ts +6 -111
  540. package/templates/sailing/src/render/kitExposure.ts +20 -0
  541. package/templates/sailing/src/render/materialLighting.ts +2 -11
  542. package/templates/sailing/src/render/ocean.ts +0 -1
  543. package/templates/sailing/src/render/postprocessing.ts +4 -4
  544. package/templates/sailing/src/render/quality.ts +31 -138
  545. package/templates/sailing/src/scenes/Sailing.ts +12 -4
  546. package/templates/sailing/src/ui/Hud.tsx +6 -2
  547. package/templates/sailing/src/ui/Menu.tsx +1 -1
  548. package/templates/shooter/.codex/config.toml +6 -2
  549. package/templates/shooter/.cursor/mcp.json +8 -2
  550. package/templates/shooter/.gemini/settings.json +8 -2
  551. package/templates/shooter/.mcp.json +8 -2
  552. package/templates/shooter/.vscode/mcp.json +9 -2
  553. package/templates/shooter/.zed/settings.json +9 -2
  554. package/templates/shooter/AGENTS.md +13 -12
  555. package/templates/shooter/CLAUDE.md +13 -12
  556. package/templates/shooter/index.html +1 -1
  557. package/templates/shooter/main.html +13 -0
  558. package/templates/shooter/opencode.json +10 -2
  559. package/templates/shooter/package.json +15 -10
  560. package/templates/shooter/playtests/breakable-shatters.playtest.json +6 -0
  561. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +6 -0
  562. package/templates/shooter/playtests/hands-authored-rate.playtest.json +54 -0
  563. package/templates/shooter/playtests/movement-eases.playtest.json +53 -0
  564. package/templates/shooter/playtests/performance.playtest.json +3 -3
  565. package/templates/shooter/playtests/stairs-smooth-the-eye.playtest.json +56 -0
  566. package/templates/shooter/playtests/weapon-sharp-while-turning.playtest.json +206 -0
  567. package/templates/shooter/src/entities/Breakables.ts +34 -10
  568. package/templates/shooter/src/entities/Enemy.ts +176 -54
  569. package/templates/shooter/src/entities/FpsPlayer.ts +55 -16
  570. package/templates/shooter/src/entities/Rifle.ts +83 -9
  571. package/templates/shooter/src/entities/movement.ts +96 -0
  572. package/templates/shooter/src/render/atmosphere.ts +444 -0
  573. package/templates/shooter/src/render/backlightMaterial.ts +49 -18
  574. package/templates/shooter/src/render/camera.ts +3 -1
  575. package/templates/shooter/src/render/clouds.ts +605 -0
  576. package/templates/shooter/src/render/exposure.ts +10 -109
  577. package/templates/shooter/src/render/facade.ts +26 -68
  578. package/templates/shooter/src/render/gpuSky.ts +752 -0
  579. package/templates/shooter/src/render/lighting.ts +27 -4
  580. package/templates/shooter/src/render/materialAssignments.ts +9 -1
  581. package/templates/shooter/src/render/materialLighting.ts +2 -11
  582. package/templates/shooter/src/render/occlusion.ts +13 -4
  583. package/templates/shooter/src/render/palette.ts +1 -0
  584. package/templates/shooter/src/render/postprocessing.ts +4 -4
  585. package/templates/shooter/src/render/quality.ts +50 -108
  586. package/templates/shooter/src/render/scale.ts +0 -11
  587. package/templates/shooter/src/render/sky.ts +103 -2
  588. package/templates/shooter/src/render/surface.ts +140 -0
  589. package/templates/shooter/src/render/town.ts +3 -6
  590. package/templates/shooter/src/render/townMaterials.ts +95 -42
  591. package/templates/shooter/src/render/vehicles.ts +2 -0
  592. package/templates/shooter/src/scenes/Play.ts +83 -23
  593. package/templates/shooter/src/ui/Hud.tsx +268 -193
  594. package/templates/shooter/src/worker-page.ts +29 -0
  595. package/templates/shooter/src/worker.ts +5 -0
  596. package/templates/shooter/threenative.config.ts +3 -0
  597. package/templates/shooter/vite.config.ts +2 -0
  598. package/templates/snow/.codex/config.toml +6 -2
  599. package/templates/snow/.cursor/mcp.json +8 -2
  600. package/templates/snow/.gemini/settings.json +8 -2
  601. package/templates/snow/.mcp.json +8 -2
  602. package/templates/snow/.vscode/mcp.json +9 -2
  603. package/templates/snow/.zed/settings.json +9 -2
  604. package/templates/snow/AGENTS.md +12 -10
  605. package/templates/snow/CLAUDE.md +12 -10
  606. package/templates/snow/opencode.json +10 -2
  607. package/templates/snow/package.json +15 -10
  608. package/templates/snow/playtests/performance.playtest.json +1 -1
  609. package/templates/snow/src/render/backlightMaterial.ts +49 -18
  610. package/templates/snow/src/render/exposure.ts +17 -106
  611. package/templates/snow/src/render/materialLighting.ts +2 -11
  612. package/templates/snow/src/render/postprocessing.ts +11 -5
  613. package/templates/snow/src/render/quality.ts +46 -126
  614. package/templates/snow/src/render/snowSurface.ts +32 -15
  615. package/templates/snow/src/scenes/Snow.ts +2 -1
  616. package/templates/starter/.codex/config.toml +6 -2
  617. package/templates/starter/.cursor/mcp.json +8 -2
  618. package/templates/starter/.gemini/settings.json +8 -2
  619. package/templates/starter/.mcp.json +8 -2
  620. package/templates/starter/.vscode/mcp.json +9 -2
  621. package/templates/starter/.zed/settings.json +9 -2
  622. package/templates/starter/AGENTS.md +18 -14
  623. package/templates/starter/CLAUDE.md +18 -14
  624. package/templates/starter/index.html +1 -1
  625. package/templates/starter/main.html +12 -0
  626. package/templates/starter/native-playtests/react-hud.playtest.json +1 -0
  627. package/templates/starter/native-playtests/render-chain.playtest.json +34 -21
  628. package/templates/starter/opencode.json +10 -2
  629. package/templates/starter/package.json +15 -10
  630. package/templates/starter/playtests/play.playtest.json +22 -2
  631. package/templates/starter/playtests/production-readiness.playtest.json +14 -0
  632. package/templates/starter/src/entities/Crate.ts +19 -1
  633. package/templates/starter/src/render/arena.ts +2 -2
  634. package/templates/starter/src/render/atmosphere.ts +444 -0
  635. package/templates/starter/src/render/backlightMaterial.ts +49 -18
  636. package/templates/starter/src/render/camera.ts +28 -0
  637. package/templates/starter/src/render/clouds.ts +605 -0
  638. package/templates/starter/src/render/contactShadow.ts +50 -0
  639. package/templates/starter/src/render/exposure.ts +9 -111
  640. package/templates/starter/src/render/gpuSky.ts +752 -0
  641. package/templates/starter/src/render/grade.ts +1 -1
  642. package/templates/starter/src/render/lighting.ts +34 -6
  643. package/templates/starter/src/render/materialLighting.ts +2 -11
  644. package/templates/starter/src/render/postprocessing.ts +27 -14
  645. package/templates/starter/src/render/quality.ts +18 -147
  646. package/templates/starter/src/render/sky.ts +90 -40
  647. package/templates/starter/src/render/temporalAA.ts +1 -1
  648. package/templates/starter/src/render/temporalAAStage.ts +1 -1
  649. package/templates/starter/src/render/temporalCurrentFootprint.ts +0 -1
  650. package/templates/starter/src/render/temporalDetailStage.ts +106 -0
  651. package/templates/starter/src/render/temporalRejectionCounter.ts +2 -2
  652. package/templates/starter/src/render/volumetricFogCamera.ts +32 -0
  653. package/templates/starter/src/render/volumetricFogOptions.ts +7 -0
  654. package/templates/starter/src/render/volumetricFogTransport.ts +27 -19
  655. package/templates/starter/src/render/volumetricFogVolume.ts +31 -7
  656. package/templates/starter/src/scenes/Play.ts +11 -8
  657. package/templates/starter/src/ui/Hud.tsx +1 -1
  658. package/templates/starter/src/worker-page.ts +29 -0
  659. package/templates/starter/src/worker.ts +5 -0
  660. package/templates/starter/vite.config.ts +2 -0
  661. package/templates/tower-defense/.codex/config.toml +6 -2
  662. package/templates/tower-defense/.cursor/mcp.json +8 -2
  663. package/templates/tower-defense/.gemini/settings.json +8 -2
  664. package/templates/tower-defense/.mcp.json +8 -2
  665. package/templates/tower-defense/.vscode/mcp.json +9 -2
  666. package/templates/tower-defense/.zed/settings.json +9 -2
  667. package/templates/tower-defense/AGENTS.md +10 -12
  668. package/templates/tower-defense/CLAUDE.md +10 -12
  669. package/templates/tower-defense/opencode.json +10 -2
  670. package/templates/tower-defense/package.json +15 -10
  671. package/templates/tower-defense/playtests/chill-tint.playtest.json +387 -0
  672. package/templates/tower-defense/playtests/performance.playtest.json +1 -1
  673. package/templates/tower-defense/src/enemies/Enemy.ts +9 -0
  674. package/templates/tower-defense/src/render/backlightMaterial.ts +49 -18
  675. package/templates/tower-defense/src/render/exposure.ts +11 -109
  676. package/templates/tower-defense/src/render/lighting.ts +4 -2
  677. package/templates/tower-defense/src/render/materialLighting.ts +2 -11
  678. package/templates/tower-defense/src/render/postprocessing.ts +4 -4
  679. package/templates/tower-defense/src/render/quality.ts +10 -116
  680. package/templates/tower-defense/src/render/sky.ts +2 -2
  681. package/templates/tower-defense/src/scenes/Battle.ts +4 -0
  682. package/template-assets/autoExposure.ts +0 -225
  683. package/template-assets/exposureGraph.ts +0 -178
  684. package/template-assets/exposureReadback.ts +0 -79
  685. package/template-assets/worldEnvironment.ts +0 -1212
  686. package/templates/action-rpg/src/render/autoExposure.ts +0 -225
  687. package/templates/action-rpg/src/render/exposureGraph.ts +0 -178
  688. package/templates/action-rpg/src/render/exposureReadback.ts +0 -79
  689. package/templates/action-rpg/src/render/worldEnvironment.ts +0 -1212
  690. package/templates/minimal/src/render/autoExposure.ts +0 -225
  691. package/templates/minimal/src/render/exposureGraph.ts +0 -178
  692. package/templates/minimal/src/render/exposureReadback.ts +0 -79
  693. package/templates/minimal/src/render/worldEnvironment.ts +0 -1212
  694. package/templates/platformer/src/render/autoExposure.ts +0 -225
  695. package/templates/platformer/src/render/exposureGraph.ts +0 -178
  696. package/templates/platformer/src/render/exposureReadback.ts +0 -79
  697. package/templates/platformer/src/render/worldEnvironment.ts +0 -1212
  698. package/templates/puzzle/src/render/autoExposure.ts +0 -225
  699. package/templates/puzzle/src/render/exposureGraph.ts +0 -178
  700. package/templates/puzzle/src/render/exposureReadback.ts +0 -79
  701. package/templates/puzzle/src/render/worldEnvironment.ts +0 -1212
  702. package/templates/racing/src/render/autoExposure.ts +0 -225
  703. package/templates/racing/src/render/exposureGraph.ts +0 -178
  704. package/templates/racing/src/render/exposureReadback.ts +0 -79
  705. package/templates/racing/src/render/worldEnvironment.ts +0 -1212
  706. package/templates/rain/src/render/autoExposure.ts +0 -225
  707. package/templates/rain/src/render/exposureGraph.ts +0 -178
  708. package/templates/rain/src/render/exposureReadback.ts +0 -79
  709. package/templates/rain/src/render/worldEnvironment.ts +0 -1212
  710. package/templates/rts/src/render/autoExposure.ts +0 -225
  711. package/templates/rts/src/render/exposureGraph.ts +0 -178
  712. package/templates/rts/src/render/exposureReadback.ts +0 -79
  713. package/templates/rts/src/render/worldEnvironment.ts +0 -1212
  714. package/templates/runner/src/render/autoExposure.ts +0 -225
  715. package/templates/runner/src/render/exposureGraph.ts +0 -178
  716. package/templates/runner/src/render/exposureReadback.ts +0 -79
  717. package/templates/runner/src/render/worldEnvironment.ts +0 -1212
  718. package/templates/sailing/src/render/autoExposure.ts +0 -225
  719. package/templates/sailing/src/render/exposureGraph.ts +0 -178
  720. package/templates/sailing/src/render/exposureReadback.ts +0 -79
  721. package/templates/sailing/src/render/worldEnvironment.ts +0 -1212
  722. package/templates/shooter/src/render/autoExposure.ts +0 -225
  723. package/templates/shooter/src/render/exposureGraph.ts +0 -178
  724. package/templates/shooter/src/render/exposureReadback.ts +0 -79
  725. package/templates/shooter/src/render/worldEnvironment.ts +0 -1212
  726. package/templates/snow/src/render/autoExposure.ts +0 -225
  727. package/templates/snow/src/render/exposureGraph.ts +0 -178
  728. package/templates/snow/src/render/exposureReadback.ts +0 -79
  729. package/templates/snow/src/render/worldEnvironment.ts +0 -1212
  730. package/templates/starter/src/render/autoExposure.ts +0 -225
  731. package/templates/starter/src/render/exposureGraph.ts +0 -178
  732. package/templates/starter/src/render/exposureReadback.ts +0 -79
  733. package/templates/starter/src/render/worldEnvironment.ts +0 -1212
  734. package/templates/tower-defense/src/render/autoExposure.ts +0 -225
  735. package/templates/tower-defense/src/render/exposureGraph.ts +0 -178
  736. package/templates/tower-defense/src/render/exposureReadback.ts +0 -79
  737. package/templates/tower-defense/src/render/worldEnvironment.ts +0 -1212
@@ -1,1212 +0,0 @@
1
- // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or
2
- // rewrite it freely — every default in here is a starting point, not a framework look.
3
- //
4
- // `WorldEnvironment` is Godot's name for the node that says which lighting effects a scene
5
- // runs and how strong they are, and the property names below are Godot's `Environment`
6
- // properties where Godot has one (`ssr_enabled`, `glow_enabled`, `tonemap_mode`) and
7
- // Three.js's node names where it does not (`ssgi`, `gtao`). Nothing here is a new word.
8
- //
9
- // What it owns: building the stage factories and handing them to
10
- // `renderer.createRenderChain()`, which decides the order stages run in, whether each can
11
- // run on this target, and prints `TN_RENDER_CHAIN` naming every stage as applied or
12
- // refused **with a reason** — so a stage that silently no-op'd is never mistaken for one
13
- // you turned off. What it does not own: any colour, and any strength that is not a quality
14
- // tier. Those are arguments, supplied by `postprocessing.ts`, yours to change.
15
-
16
- import {
17
- ACESFilmicToneMapping,
18
- AgXToneMapping,
19
- type Camera,
20
- type DirectionalLight,
21
- MaterialBlending,
22
- NeutralToneMapping,
23
- type PerspectiveCamera,
24
- type RenderTarget,
25
- type Scene,
26
- type Texture,
27
- Vector2,
28
- } from "three";
29
- import { bloom } from "three/addons/tsl/display/BloomNode.js";
30
- import { denoise } from "three/addons/tsl/display/DenoiseNode.js";
31
- import { fxaa } from "three/addons/tsl/display/FXAANode.js";
32
- import { ao } from "three/addons/tsl/display/GTAONode.js";
33
- import { godrays } from "three/addons/tsl/display/GodraysNode.js";
34
- import { smaa } from "three/addons/tsl/display/SMAANode.js";
35
- import { ssgi } from "three/addons/tsl/display/SSGINode.js";
36
- import { ssr } from "three/addons/tsl/display/SSRNode.js";
37
- import { sharpen } from "three/addons/tsl/display/SharpenNode.js";
38
- import {
39
- clamp,
40
- color,
41
- convertToTexture,
42
- float,
43
- max,
44
- metalness,
45
- mrt,
46
- normalView,
47
- output,
48
- pass,
49
- roughness,
50
- smoothstep,
51
- uniform,
52
- uv,
53
- vec2,
54
- vec4,
55
- } from "three/tsl";
56
- import { BlendMode, type Node, type NodeBuilder, type TextureNode } from "three/webgpu";
57
- import { AutoExposureNode, applyExposure } from "./autoExposure.js";
58
- import { type IExposureSettings, exposureSettings } from "./exposure.js";
59
-
60
- /** Godot's `Viewport.screen_space_aa`: which post-process antialiasing smooths the frame's edges. */
61
- export type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
62
-
63
- /** Godot's `Environment.tonemap_mode`, with the modes Three.js actually ships. */
64
- export type TonemapMode = "aces" | "agx" | "neutral";
65
-
66
- /**
67
- * SSGI sample budget. The three tiers are the presets SSGINode's own documentation
68
- * recommends for the temporally-filtered case, not numbers invented here. An unknown
69
- * tier throws rather than quietly becoming the default.
70
- */
71
- export type SsgiQuality = "low" | "medium" | "high";
72
-
73
- const SSGI_QUALITY: Record<SsgiQuality, { sliceCount: number; stepCount: number }> = {
74
- low: { sliceCount: 1, stepCount: 12 },
75
- medium: { sliceCount: 2, stepCount: 8 },
76
- high: { sliceCount: 3, stepCount: 16 },
77
- };
78
-
79
- const TONEMAP: Record<TonemapMode, number> = {
80
- aces: ACESFilmicToneMapping,
81
- agx: AgXToneMapping,
82
- neutral: NeutralToneMapping,
83
- };
84
-
85
- export interface IWorldEnvironmentOptions {
86
- /** World-pass MSAA samples. Omit to inherit the renderer; 0 leaves post AA in charge. */
87
- readonly samples?: number;
88
- /** Screen-space indirect diffuse light. Godot calls this `ssil_enabled`. */
89
- readonly ssgiEnabled?: boolean;
90
- readonly ssgiQuality?: SsgiQuality;
91
- /** How much of the gathered indirect light reaches the frame. Godot's `ssil_intensity`. */
92
- readonly ssgiIntensity?: number;
93
- /** How far, in world units, indirect light is gathered from. Room scale, not contact scale. */
94
- readonly ssgiRadius?: number;
95
- /** Screen-space reflections. Godot's `ssr_enabled`. */
96
- readonly ssrEnabled?: boolean;
97
- /**
98
- * How far, in world units, a reflection ray is traced.
99
- *
100
- * `SSRNode` defaults this to **1**, which is one metre. On any scene larger than a
101
- * tabletop that reads as "screen-space reflections are on and do nothing" — the ray
102
- * terminates before it reaches the thing that should be standing in the floor.
103
- */
104
- readonly ssrMaxDistance?: number;
105
- /**
106
- * Fraction of the display resolution the reflection is traced at.
107
- *
108
- * A reflection in a rough surface carries almost no high-frequency detail, so tracing it
109
- * at half resolution costs a quarter of the rays and is very hard to see in the result.
110
- */
111
- readonly ssrResolutionScale?: number;
112
- /** Spatial denoise over the SSGI result. Off is noisier and cheaper. */
113
- readonly denoiseEnabled?: boolean;
114
- /** Raymarched shafts. Needs `godraysLight`, and that light must cast shadows. */
115
- readonly godraysEnabled?: boolean;
116
- /** How dense the participating medium is. Higher is foggier — and the whole frame brighter. */
117
- readonly godraysDensity?: number;
118
- /**
119
- * Haze below this value is discarded instead of added to the frame.
120
- *
121
- * Without it the pass is a uniform brightener rather than a shaft renderer: it returns a
122
- * non-zero value for nearly every pixel, and that "something" is tiny in linear space and
123
- * enormous after the tone curve, which lifts shadows hardest. Subtracting a floor keeps
124
- * the air inside a real beam and discards the ambient lift.
125
- */
126
- readonly godraysFloor?: number;
127
- /** Multiplier applied after the floor, so beams can be bright without the haze returning. */
128
- readonly godraysIntensity?: number;
129
- /**
130
- * Raymarch steps per pixel. `GodraysNode` defaults to 60.
131
- *
132
- * Every step is a shadow-map sample, so this multiplies directly into the cost of the
133
- * whole pass. The pass jitters its sample positions, so a lower count trades a hard shaft
134
- * edge for a slightly noisier one rather than for banding — which the denoiser then
135
- * largely absorbs.
136
- */
137
- readonly godraysSteps?: number;
138
- /**
139
- * Ceiling on shaft brightness.
140
- *
141
- * This is also the single strongest control over how bright the *whole* scene looks: the
142
- * pass adds its accumulated illumination to every pixel, not only to the pixels inside a
143
- * visible beam, so raising it raises the shadow floor of the entire frame.
144
- */
145
- readonly godraysMaxDensity?: number;
146
- /**
147
- * Ground-truth ambient occlusion, at contact scale. Godot's `ssao_enabled`.
148
- *
149
- * Deliberately a *second* occlusion term next to the one SSGI already produces. SSGI's AO
150
- * is gathered over `ssgiRadius` — metres — the right scale for "this hall is enclosed"
151
- * and the wrong one for "this foot is standing on this floor". This pass runs at a radius
152
- * of centimetres and multiplies on top.
153
- */
154
- readonly gtaoEnabled?: boolean;
155
- /** Occlusion gather radius in world units. Contact scale, not room scale. */
156
- readonly gtaoRadius?: number;
157
- /** Exponent on the occlusion term: higher is a darker, tighter contact. */
158
- readonly gtaoScale?: number;
159
- /** Directions sampled per pixel. Cost is linear in this. */
160
- readonly gtaoSamples?: number;
161
- /** Fraction of display resolution the occlusion is traced at. */
162
- readonly gtaoResolutionScale?: number;
163
- /**
164
- * The fraction of the frame SSGI actually gathers at. Half by default.
165
- *
166
- * `GTAONode` and `SSRNode` both carry a `resolutionScale` of their own; **`SSGINode` does not**,
167
- * and its `setSize` passes width and height straight into its render target with no factor. So
168
- * screen-space GI — a low-frequency effect every production renderer gathers at half or quarter
169
- * res — was the only stage in this chain running at full resolution, and it cost accordingly.
170
- *
171
- * Measured on a 46,190-instance forest at 1600x900 on an RTX 2080, with the resolution scaler
172
- * left on auto so the engine's own verdict is part of the result:
173
- *
174
- * fps still/walk scale it settled on interior median dead shadow
175
- * full res 38.0 / 47.2 0.44 704x396 0.0299 19.19%
176
- * off 60.0 / 60.0 0.61 976x549 0.0987 4.54%
177
- * half res 59.8 / 60.0 0.72 1152x648 0.0301 18.58%
178
- *
179
- * Half res is better than both: it holds the budget like switching SSGI off, keeps the look
180
- * within noise of full res, and produces the *sharpest* frame of the three — because the budget
181
- * it hands back is spent by the scaler on pixels rather than on a gather nobody can see at full
182
- * rate. Full-res SSGI was not buying quality, it was trading it.
183
- *
184
- * Fixed without touching three: `setSize` is public and the pass drives the node through it with
185
- * the full frame size, so the instance is wrapped to hand it a smaller one. The node's own maths
186
- * reads the `_resolution` uniform that `setSize` writes, so it stays self-consistent, and the
187
- * result is sampled by UV rather than by texel — which is what makes the upsample free and is
188
- * exactly the mechanism `GTAONode` uses internally.
189
- */
190
- readonly ssgiResolutionScale?: number;
191
- /**
192
- * Contrast-adaptive sharpening (RCAS) over the finished frame.
193
- *
194
- * Everything upstream of it blurs: the GI gather is denoised, the reflection is traced at
195
- * reduced resolution and roughness-blurred. Each is worth its softness on its own and the
196
- * sum is a frame with no micro-detail left. RCAS is contrast-adaptive, so it puts the
197
- * edges back without ringing the soft areas.
198
- */
199
- readonly sharpenEnabled?: boolean;
200
- /** RCAS sharpness. **0 is maximum sharpening and 2 is none** — it is a radius, not a gain. */
201
- readonly sharpenStrength?: number;
202
- /** Corner darkening, as a fraction removed at the extreme corner. Zero disables it. */
203
- readonly vignetteAmount?: number;
204
- /**
205
- * Post-process antialiasing, run last. Godot's `Viewport.screen_space_aa`. Default `"smaa"`.
206
- *
207
- * Not optional in practice: the chain renders `pass(scene, camera)` single-sampled, so the moment
208
- * any stage runs, the renderer's own multisampling no longer reaches the frame and every edge
209
- * stairsteps — the single loudest "this is a prototype" signal in a frame. It is requested only
210
- * when some other stage (or a `baseColour`) installs a chain; with nothing installed the renderer
211
- * draws straight to the canvas with its own MSAA and this would be paying twice.
212
- */
213
- readonly screenSpaceAA?: ScreenSpaceAA;
214
- /** Godot's `glow_enabled`. */
215
- readonly bloomEnabled?: boolean;
216
- readonly bloomStrength?: number;
217
- /** How far a bright pixel bleeds, as a fraction of the screen. */
218
- readonly bloomRadius?: number;
219
- /** Luminance a pixel must exceed before it blooms at all. */
220
- readonly bloomThreshold?: number;
221
- /**
222
- * Which of this kit's authored stages to run.
223
- *
224
- * Separate from the graph below, and not for tidiness: the chain has to know whether anything
225
- * was requested at all before the scene pass exists — with nothing requested it sets an
226
- * exposure and returns, and no pass is ever built. So the request is a static decision the kit
227
- * makes from its own config, and only the graph needs the pass.
228
- */
229
- readonly authoredStageNames?: readonly string[];
230
- /**
231
- * This kit's own stages, composed after the built-ins.
232
- *
233
- * A factory because an authored stage needs the two things only this file can produce: the
234
- * scene pass's depth texture node, which does not exist until the pass is built, and the
235
- * resolved tier. It returns the complete graph — including stages left dormant this frame — so
236
- * that an anchor like `watercolor after kuwahara` keeps naming a stage that exists.
237
- *
238
- * Naming specific stages here instead — an `outlineEnabled`, a `kuwaharaRadius` — is what put
239
- * one kit's look inside the plumbing every kit copies verbatim, which
240
- * `shared-render-sources.spec.ts` exists to refuse.
241
- */
242
- readonly authoredStages?: (context: IWorldEnvironmentStageContext) => readonly ChainStage[];
243
- /** Quality tier passed to the measured chain; the quality module owns this value. */
244
- readonly renderChainTier?: ChainTier;
245
- readonly tonemapMode?: TonemapMode;
246
- /**
247
- * Scene-referred exposure: multiplied into the scene pass **before** the tone curve, so
248
- * the GI gather, reflections and bloom threshold all see the exposed image and the bloom
249
- * threshold means the same thing at any exposure.
250
- *
251
- * `renderer.toneMappingExposure` is live too (measured on three@0.185.1 — see
252
- * `docs/verification/exposure-ab-2026-08-30.md`), and applies at the same point in the
253
- * graph, but only when no output node is installed. When every stage here is off, this
254
- * class falls back to that scalar; when any stage runs, this multiply is the shutter.
255
- */
256
- readonly exposure?: number;
257
- /** Cost opt-in. False retains the direct constant-exposure path. */
258
- readonly autoExposureEnabled?: boolean;
259
- /** Editable game policy; disabled application still measures when cost is opted in. */
260
- readonly exposurePolicy?: Readonly<IExposureSettings>;
261
- }
262
-
263
- export interface IWorldEnvironmentTarget {
264
- /** The directional light godrays are raymarched against. Required only by `godraysEnabled`. */
265
- readonly godraysLight?: DirectionalLight;
266
- /**
267
- * Composes the colour the chain starts from, given the scene pass it renders.
268
- *
269
- * The chain builds `pass(scene, camera)` itself, so a game that composes something onto the
270
- * beauty pass before any stage runs — aerial perspective, read against that pass's own view-Z,
271
- * is the one in these templates — has nowhere else to put it. The node returned here is the
272
- * game's; the chain only decides where it is spliced in, which is first, ahead of exposure and
273
- * every stage.
274
- */
275
- readonly baseColour?: (scenePass: ReturnType<typeof pass>) => Node<"vec4">;
276
- }
277
-
278
- /**
279
- * What travels down the chain: the composed colour, as TSL's proxied vec4 node — the thing
280
- * that carries `.mul`, `.add`, `.rgb` and `.r`. Every stage takes one and returns one, so the
281
- * compiler checks the composition instead of taking a cast's word for it.
282
- */
283
- type ChainNode = Node<"vec4">;
284
- type ResolutionSubrectView = {
285
- readonly viewFraction: Vector2;
286
- readonly halfTexel: Vector2;
287
- };
288
- /**
289
- * The scene pass's depth texture, as the pass itself types it.
290
- *
291
- * Named through `pass()` rather than written out because the addon's return type is the only
292
- * honest spelling of it, and a hand-written alias here would drift the first time three changes it.
293
- */
294
- export type DepthTextureNode = ReturnType<ReturnType<typeof pass>["getTextureNode"]>;
295
- type ChainTier = "high" | "medium" | "low" | "off";
296
- type ChainContext = {
297
- readonly tier: ChainTier;
298
- readonly resolutionSubrect?: ResolutionSubrectView;
299
- /**
300
- * The sampled velocity texture, present only when this chain request provisioned one.
301
- *
302
- * Distinct from the accessor TRAANode wants: the chain passes the texture here and installs the
303
- * accessor on the graph separately, so a stage that handed this node over as the accessor would
304
- * sample a texture that no fragment stage writes.
305
- */
306
- readonly velocityNode?: Node;
307
- };
308
- /**
309
- * What a kit's `authoredStages` factory is handed. The depth node is the scene pass's, so a
310
- * stage that reads depth gets the same texture the built-in stages read rather than its own.
311
- */
312
- export interface IWorldEnvironmentStageContext {
313
- readonly depthNode: DepthTextureNode;
314
- readonly tier: ChainTier;
315
- /** The camera the scene pass renders with, which is the one a temporal stage must jitter. */
316
- readonly camera: Camera;
317
- }
318
-
319
- export type ChainStage = {
320
- readonly name: string;
321
- readonly supportsResolutionSubrect?: boolean;
322
- readonly before?: string;
323
- readonly after?: string;
324
- /**
325
- * This stage reads display-referred colour — tone-mapped and sRGB-encoded — so the chain
326
- * installs the graph with the renderer's automatic output transform switched off and the stage
327
- * applies that transform itself (`renderOutput` from `three/tsl`).
328
- *
329
- * For effects authored against the picture rather than against light: a `.cube` table, an
330
- * sRGB-space edge filter. Such a stage runs last and may not declare an anchor, and the chain
331
- * only hands the renderer its transform back when the stage was actually refused.
332
- */
333
- readonly afterOutputTransform?: boolean;
334
- readonly available?: (context: ChainContext) => boolean | string;
335
- readonly dispose?: () => void;
336
- readonly minimumTier?: ChainTier;
337
- /**
338
- * A temporal stage's completed rejection measurement. Its shape is the engine's velocity
339
- * contract, restated here so this file keeps importing nothing, and it is asked once per frame
340
- * after rendering. A stage that has not built, or has nothing landed yet, answers `undefined` —
341
- * which the chain reports as absent rather than as zero.
342
- */
343
- readonly rejectionMeasurement?: () => { frame: number; rejectionFraction: number } | undefined;
344
- /** The chain plumbing is stage-agnostic, so it names the node it carries `unknown`. */
345
- readonly build: (input: unknown, context: ChainContext) => unknown;
346
- };
347
-
348
- /**
349
- * The one seam between the chain's `unknown` and this file's node algebra.
350
- *
351
- * What the chain hands a stage is the colour composed so far — the previous stage's return, or
352
- * the exposed scene pass for the first one — and that is always a `ChainNode`. Saying so once,
353
- * here, is what lets every stage below be written and *checked* as vec4-in, vec4-out instead of
354
- * asserting its way through each expression. The wrapper adds no node to the graph.
355
- */
356
- function stage(definition: {
357
- readonly name: ChainStage["name"];
358
- readonly supportsResolutionSubrect?: boolean;
359
- readonly dispose?: () => void;
360
- readonly available?: (context: ChainContext) => boolean | string;
361
- readonly build: (input: ChainNode, context: ChainContext) => ChainNode;
362
- }): ChainStage {
363
- return {
364
- ...definition,
365
- build: (input, context) => definition.build(input as ChainNode, context),
366
- };
367
- }
368
-
369
- /**
370
- * `three/addons` declares each TSL stage as its raw node class, and `DenoiseNode` is the only
371
- * one in this chain whose declaration omits the element API (`.mul`, `.rgb`, `.r`) that the
372
- * proxied node object it actually hands back at runtime carries — every other stage here is a
373
- * `ChainNode` on its own, checked by the compiler. This is an assertion and nothing else: no
374
- * conversion runs, no node is added to the graph, so it cannot move a pixel.
375
- */
376
- function denoised(node: ReturnType<typeof denoise>): ChainNode {
377
- return node as unknown as ChainNode;
378
- }
379
- type OutputInstallation = { isCurrent(): boolean; dispose(): void };
380
- type ResolutionSubrectTarget = {
381
- setSize(width: number, height: number, depth?: number): void;
382
- };
383
- type ResolutionSubrectController = {
384
- readonly active?: boolean;
385
- readonly view?: ResolutionSubrectView;
386
- retain(node: ResolutionSubrectTarget, targets: readonly RenderTarget[]): void;
387
- release(node: ResolutionSubrectTarget): void;
388
- textureView(texture: Texture): ResolutionSubrectView | undefined;
389
- dispose(): void;
390
- };
391
- type OutputSetter =
392
- | ((node: unknown, worldPass?: unknown) => void)
393
- | ((node: unknown, worldPass?: unknown) => OutputInstallation);
394
-
395
- type SampledTexture = TextureNode & {
396
- setupUV(builder: NodeBuilder, coordinates: Node<"vec2">): Node<"vec2">;
397
- };
398
-
399
- /** Cloned neighbourhood samplers retain the same per-texture viewport clamp. */
400
- function bindSubrectSampler(
401
- node: TextureNode,
402
- view: ResolutionSubrectController,
403
- bound: WeakSet<object>,
404
- ): void {
405
- if (bound.has(node)) return;
406
- bound.add(node);
407
- const sampled = node as SampledTexture;
408
- const full = new Vector2(1, 1);
409
- const zero = new Vector2();
410
- const fraction = uniform(full).onRenderUpdate(() =>
411
- view.active ? (view.textureView(node.value)?.viewFraction ?? full) : full,
412
- );
413
- const half = uniform(zero).onRenderUpdate(() =>
414
- view.active ? (view.textureView(node.value)?.halfTexel ?? zero) : zero,
415
- );
416
- const setup = sampled.setupUV;
417
- sampled.uvNode ??= uv();
418
- sampled.setupUV = function (builder, coordinates) {
419
- return setup.call(this, builder, coordinates.mul(fraction).clamp(half, fraction.sub(half)));
420
- };
421
- const clone = sampled.clone;
422
- sampled.clone = function () {
423
- const next = clone.call(this);
424
- bindSubrectSampler(next, view, bound);
425
- return next;
426
- };
427
- }
428
-
429
- function bindSubrectTexture(
430
- node: TextureNode,
431
- view: ResolutionSubrectController,
432
- bound: WeakSet<object>,
433
- ): void {
434
- if (Reflect.get(node, "isRTTNode") === true && !bound.has(node)) {
435
- const rtt = node as TextureNode & {
436
- width: number | null;
437
- setSize(w: number, h: number): void;
438
- renderTarget: RenderTarget;
439
- updateBefore(frame: unknown): void;
440
- };
441
- view.retain(rtt, [rtt.renderTarget]);
442
- const update = rtt.updateBefore;
443
- rtt.updateBefore = function (frame) {
444
- // Stock RTT bypasses setSize during auto-resize; the controller owns it while active.
445
- this.width = view.active ? 1 : null;
446
- update.call(this, frame);
447
- };
448
- }
449
- bindSubrectSampler(node, view, bound);
450
- }
451
-
452
- export type OutputRenderer = {
453
- kind: string;
454
- raw: unknown;
455
- createResolutionSubrect?: () => ResolutionSubrectController;
456
- /**
457
- * Installs a node graph directly. Only reached when a `baseColour` is composed and every
458
- * stage is off: the chain installs nothing for an empty stage list, and dropping the game's
459
- * own composition on the floor would be the silent no-op this class exists to prevent.
460
- */
461
- setOutputNode?: OutputSetter;
462
- /** Legacy node-only clear. The returned receipt distinguishes same-node reinstalls. */
463
- clearOutputNode?: (expectedNode?: unknown) => void;
464
- createRenderChain?: (options: {
465
- input?: unknown;
466
- worldPass?: unknown;
467
- request?: {
468
- stages?: readonly string[];
469
- tier?: ChainContext["tier"];
470
- /**
471
- * The scene pass that owns the shared velocity output, for a temporal stage to read. Its
472
- * shape is the engine's velocity contract, restated here so this file keeps importing
473
- * nothing: `pass(scene, camera)` returns exactly this.
474
- */
475
- velocity?: {
476
- pass?: ReturnType<typeof pass>;
477
- rejectionMeasurement?: () => { frame: number; rejectionFraction: number } | undefined;
478
- };
479
- };
480
- stages?: readonly ChainStage[];
481
- resolutionSubrect?: ResolutionSubrectController;
482
- }) => {
483
- applied: { dropped: readonly { name: string; reason: string }[]; stages: readonly string[] };
484
- dispose(): void;
485
- };
486
- };
487
-
488
- /**
489
- * Builds a Godot-named lighting chain and installs it through the renderer's render chain.
490
- *
491
- * Every stage a game turns on reports itself: the chain prints `TN_RENDER_CHAIN` naming
492
- * each requested stage as applied or refused with a reason that is never blank. A game with
493
- * GI switched off on a WebGL fallback looks exactly like a game that chose not to use it —
494
- * unless it reads that line.
495
- */
496
- export class WorldEnvironment {
497
- readonly #options: Required<Omit<IWorldEnvironmentOptions, "samples">> &
498
- Pick<IWorldEnvironmentOptions, "samples">;
499
-
500
- constructor(options: IWorldEnvironmentOptions = {}) {
501
- const quality = options.ssgiQuality ?? "medium";
502
- if (SSGI_QUALITY[quality] === undefined) {
503
- // Fail closed. A typo'd tier that silently became "medium" is a quality setting
504
- // nobody can trust afterwards.
505
- throw new Error(
506
- `Unknown ssgiQuality '${String(quality)}'. Use one of: ${Object.keys(SSGI_QUALITY).join(", ")}.`,
507
- );
508
- }
509
- const tonemapMode = options.tonemapMode ?? "aces";
510
- if (TONEMAP[tonemapMode] === undefined) {
511
- throw new Error(
512
- `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${Object.keys(TONEMAP).join(", ")}.`,
513
- );
514
- }
515
- const renderChainTier = options.renderChainTier ?? "high";
516
- if (!isChainTier(renderChainTier)) {
517
- throw new Error(
518
- `Unknown render chain tier '${String(renderChainTier)}'. Use high, medium, low, or off.`,
519
- );
520
- }
521
- this.#options = {
522
- samples: options.samples,
523
- // A kit with no stages of its own is the common case, so both default to empty rather
524
- // than to a branch every call site has to remember.
525
- authoredStageNames: options.authoredStageNames ?? [],
526
- authoredStages: options.authoredStages ?? (() => []),
527
- ssgiEnabled: options.ssgiEnabled ?? false,
528
- ssgiQuality: quality,
529
- ssgiIntensity: options.ssgiIntensity ?? 1,
530
- ssgiRadius: options.ssgiRadius ?? 12,
531
- ssrEnabled: options.ssrEnabled ?? false,
532
- ssrMaxDistance: options.ssrMaxDistance ?? 30,
533
- ssrResolutionScale: options.ssrResolutionScale ?? 0.5,
534
- denoiseEnabled: options.denoiseEnabled ?? true,
535
- godraysEnabled: options.godraysEnabled ?? false,
536
- godraysDensity: options.godraysDensity ?? 0.7,
537
- godraysFloor: options.godraysFloor ?? 0,
538
- godraysIntensity: options.godraysIntensity ?? 1,
539
- godraysSteps: options.godraysSteps ?? 60,
540
- godraysMaxDensity: options.godraysMaxDensity ?? 0.5,
541
- gtaoEnabled: options.gtaoEnabled ?? false,
542
- gtaoRadius: options.gtaoRadius ?? 0.25,
543
- gtaoScale: options.gtaoScale ?? 1,
544
- gtaoSamples: options.gtaoSamples ?? 16,
545
- gtaoResolutionScale: options.gtaoResolutionScale ?? 1,
546
- ssgiResolutionScale: options.ssgiResolutionScale ?? 0.5,
547
- sharpenEnabled: options.sharpenEnabled ?? false,
548
- sharpenStrength: options.sharpenStrength ?? 0.2,
549
- vignetteAmount: options.vignetteAmount ?? 0,
550
- screenSpaceAA: options.screenSpaceAA ?? "smaa",
551
- bloomEnabled: options.bloomEnabled ?? true,
552
- bloomStrength: options.bloomStrength ?? 0.7,
553
- bloomRadius: options.bloomRadius ?? 0.5,
554
- bloomThreshold: options.bloomThreshold ?? 0.2,
555
- renderChainTier,
556
- tonemapMode,
557
- exposure: options.exposure ?? 1,
558
- autoExposureEnabled: options.autoExposureEnabled ?? false,
559
- exposurePolicy: options.exposurePolicy ?? exposureSettings,
560
- };
561
- }
562
-
563
- /**
564
- * Installs the chain. Returns what actually ran — the same applied report the chain
565
- * printed — so a scene can assert on it instead of scraping the console.
566
- */
567
- apply(
568
- renderer: OutputRenderer,
569
- scene: Scene,
570
- camera: Camera,
571
- target: IWorldEnvironmentTarget = {},
572
- ): {
573
- dropped: readonly { name: string; reason: string }[];
574
- stages: readonly string[];
575
- dispose?: () => void;
576
- exposure?: AutoExposureNode;
577
- } {
578
- const options = this.#options;
579
- const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
580
- raw.toneMapping = TONEMAP[options.tonemapMode];
581
-
582
- const requested: string[] = (
583
- ["ssgi", "ambientOcclusion", "godRays", "ssr", "sharpen", "bloom", "vignette"] as const
584
- ).filter(
585
- (name) =>
586
- (name === "ssgi" && options.ssgiEnabled) ||
587
- (name === "ambientOcclusion" && options.gtaoEnabled) ||
588
- (name === "godRays" && options.godraysEnabled) ||
589
- (name === "ssr" && options.ssrEnabled) ||
590
- (name === "sharpen" && options.sharpenEnabled) ||
591
- (name === "bloom" && options.bloomEnabled) ||
592
- (name === "vignette" && options.vignetteAmount > 0),
593
- );
594
- requested.push(...options.authoredStageNames);
595
- if (
596
- options.screenSpaceAA !== "disabled" &&
597
- (requested.length > 0 || target.baseColour !== undefined)
598
- )
599
- requested.push("antialias");
600
-
601
- // With no stage running there is no node graph to install — the renderer's own
602
- // tone-mapping path renders the frame, and the exposure scalar is live there (measured:
603
- // `docs/verification/exposure-ab-2026-08-30.md`). With any stage running, exposure is
604
- // applied as a multiply on the scene pass instead: scene-referred, so every downstream
605
- // stage sees the exposed image and the bloom threshold means the same thing at any
606
- // exposure. Both land at the same point in the graph — before the tone curve.
607
- if (requested.length === 0 && target.baseColour === undefined && !options.autoExposureEnabled) {
608
- raw.toneMappingExposure = options.exposure;
609
- this.#reportApplied([], []);
610
- return { dropped: [], stages: [] };
611
- }
612
- if (options.autoExposureEnabled && renderer.kind !== "webgpu")
613
- throw new Error(`Automatic exposure requires WebGPU; renderer:${renderer.kind}`);
614
- if (requested.length === 0 && renderer.kind !== "webgpu") {
615
- const dropped = [{ name: "baseColour", reason: `renderer:${renderer.kind}` }];
616
- this.#reportApplied([], dropped);
617
- return { dropped, stages: [] };
618
- }
619
- const resolutionSubrectRefusal =
620
- target.baseColour !== undefined
621
- ? { name: "baseColour", reason: "custom base colour sampling is not supported" }
622
- : options.autoExposureEnabled
623
- ? { name: "autoExposure", reason: "automatic exposure sampling is not supported" }
624
- : undefined;
625
- if (resolutionSubrectRefusal !== undefined)
626
- console.info(
627
- `TN_RESOLUTION_SUBRECT ${JSON.stringify({ applied: [], refused: [resolutionSubrectRefusal] })}`,
628
- );
629
- raw.toneMappingExposure = 1;
630
-
631
- const scenePass = pass(scene, camera, { samples: options.samples });
632
- const resolutionSubrect =
633
- requested.length === 0 || resolutionSubrectRefusal !== undefined
634
- ? undefined
635
- : renderer.createResolutionSubrect?.();
636
- resolutionSubrect?.retain(scenePass, [scenePass.renderTarget]);
637
- const boundSamplers = new WeakSet<object>();
638
- const sample = (node: TextureNode): void => {
639
- if (resolutionSubrect) bindSubrectTexture(node, resolutionSubrect, boundSamplers);
640
- };
641
- // Normals come from the multi-render-target alongside the colour. SSGI can derive them
642
- // from depth alone, but the derived normal is flat across a triangle, which shows up as
643
- // faceted bounce on exactly the smooth surfaces GI is bought for. Metalness and
644
- // roughness ride along so SSR knows which pixels are supposed to reflect.
645
- if (options.ssgiEnabled || options.ssrEnabled || options.gtaoEnabled) {
646
- // The normal target uses the material blend mode. Its alpha is zero, so a transparent card
647
- // keeps the opaque normal beneath it. GTAO then does not darken a square behind the card.
648
- const sceneMrt = mrt({ output, normal: vec4(normalView, 0), metalness, roughness });
649
- sceneMrt.setBlendMode("normal", new BlendMode(MaterialBlending));
650
- scenePass.setMRT(sceneMrt);
651
- }
652
- // Requested lazily, and this is not a micro-optimisation. **Asking a pass for `normal`,
653
- // `metalness` or `roughness` is what creates the extra render target.** A tier that runs none
654
- // of the stages needing them — the mobile look is bloom and the tone curve — must not ask, or
655
- // the pass carries a colour target no fragment shader writes and WebGPU refuses the pipeline:
656
- // *"Color target has no corresponding fragment stage output but writeMask … is not zero.
657
- // While validating targets[1]"*. The frame then comes out **black** while the chain still
658
- // reports every stage as applied, which is the worst shape a failure can take here.
659
- const nodes = new Map<string, ReturnType<typeof scenePass.getTextureNode>>();
660
- const textureNode = (name: string): ReturnType<typeof scenePass.getTextureNode> => {
661
- const cached = nodes.get(name);
662
- if (cached !== undefined) return cached;
663
- const node = scenePass.getTextureNode(name);
664
- sample(node);
665
- nodes.set(name, node);
666
- return node;
667
- };
668
- const depth = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("depth");
669
- const normal = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("normal");
670
- const metal = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("metalness");
671
- const rough = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("roughness");
672
- // Every stage here is perspective-camera maths — view-space reconstruction from depth,
673
- // and a projection matrix inverse. The scene's camera is the one the pass rendered with.
674
- const view = camera as PerspectiveCamera;
675
-
676
- const base = target.baseColour?.(scenePass) ?? scenePass.getTextureNode("output");
677
- const colour = convertToTexture(base);
678
- sample(colour);
679
- const exposure = options.autoExposureEnabled
680
- ? new AutoExposureNode(colour, options.exposurePolicy, options.exposure)
681
- : undefined;
682
- const exposed =
683
- exposure === undefined
684
- ? colour.mul(options.exposure)
685
- : applyExposure(colour, exposure.exposureNode);
686
- let released = false;
687
- const releaseGraph = (): void => {
688
- if (released) return;
689
- released = true;
690
- exposure?.dispose();
691
- // Only a newly created RTT is ours. A PassNode converts to a borrowed PassTextureNode;
692
- // supplied TextureNodes/RTTs belong to the caller even when their resources are shared.
693
- if (colour !== base && Reflect.get(colour, "isRTTNode") === true) {
694
- const owned = colour as unknown as {
695
- renderTarget: { dispose(): void };
696
- _quadMesh: { material: { dispose(): void } };
697
- };
698
- owned.renderTarget.dispose();
699
- owned._quadMesh.material.dispose();
700
- }
701
- resolutionSubrect?.dispose();
702
- scenePass.dispose();
703
- };
704
- const subrectTexture = (input: ChainNode): ReturnType<typeof convertToTexture> => {
705
- const texture = convertToTexture(input);
706
- sample(texture);
707
- return texture;
708
- };
709
- const giDenoise = (node: ChainNode): ChainNode =>
710
- options.denoiseEnabled ? denoised(denoise(node, depth(), normal(), view)) : node;
711
-
712
- let releaseBloom = (): void => {};
713
- let releaseAo = (): void => {};
714
- let releaseAa = (): void => {};
715
- const stages: ChainStage[] = [
716
- stage({
717
- name: "ssgi",
718
- build: (input) => {
719
- const gi = ssgi(input, depth(), normal(), view);
720
- const tier = SSGI_QUALITY[options.ssgiQuality];
721
- gi.sliceCount.value = tier.sliceCount;
722
- gi.stepCount.value = tier.stepCount;
723
- gi.radius.value = options.ssgiRadius;
724
- // Gather at a fraction of the frame. See `ssgiResolutionScale` above for why this is a
725
- // wrapper rather than a property: the node has no scale of its own, and `setSize` is the
726
- // public seam the pass drives it through. `setSize` is present on the node and absent
727
- // from its type declarations, so the seam is named here rather than cast away at the call
728
- // site — if a future three release declares it, or gives the node a `resolutionScale`,
729
- // this narrows to nothing and the wrapper can go. Guarded at one texel so a zero or a
730
- // negative cannot ask for an empty target: a 0x0 gather returns black and reads as SSGI
731
- // simply not working.
732
- const ssgiScale = options.ssgiResolutionScale;
733
- const sizedGi = gi as unknown as {
734
- setSize?: (width: number, height: number) => void;
735
- };
736
- const fullGiSize = sizedGi.setSize?.bind(gi);
737
- if (ssgiScale > 0 && ssgiScale < 1 && fullGiSize !== undefined) {
738
- sizedGi.setSize = (width: number, height: number): void => {
739
- fullGiSize(
740
- Math.max(1, Math.round(width * ssgiScale)),
741
- Math.max(1, Math.round(height * ssgiScale)),
742
- );
743
- };
744
- }
745
-
746
- // SSGI writes two targets: AO in a single-channel `RedFormat` texture, and the GI
747
- // term in an RGB one. Multiplying the beauty pass by the whole AO vec4 therefore
748
- // zeroes green and blue and the entire scene renders monochrome red — take `.r`
749
- // for the scalar and `.rgb` for the colour.
750
- //
751
- // No albedo buffer here, so the beauty pass stands in for it: occlusion darkens
752
- // what is already lit, and the gathered indirect light is tinted by the surface it
753
- // lands on. That is the standard approximation, and it is why a red wall tints a
754
- // white floor at all. `ssgiIntensity` is the game's dial on that second term —
755
- // gathered light is unbounded, and a small white room at 1.0 blows out.
756
- const occlusion = giDenoise(gi.getAONode());
757
- const indirect = giDenoise(gi.getGINode());
758
- return input.mul(occlusion.r).add(input.mul(indirect.rgb).mul(options.ssgiIntensity));
759
- },
760
- }),
761
- stage({
762
- name: "ambientOcclusion",
763
- supportsResolutionSubrect: true,
764
- dispose: () => {
765
- releaseAo();
766
- releaseAo = () => {};
767
- },
768
- build: (input) => {
769
- const contact = ao(subrectTexture(depth()), subrectTexture(normal()), view);
770
- contact.radius.value = options.gtaoRadius;
771
- contact.scale.value = options.gtaoScale;
772
- contact.samples.value = options.gtaoSamples;
773
- contact.resolutionScale = options.gtaoResolutionScale;
774
- const retained = contact as unknown as {
775
- setSize(w: number, h: number): void;
776
- _aoRenderTarget: RenderTarget;
777
- };
778
- resolutionSubrect?.retain(retained, [retained._aoRenderTarget]);
779
- sample(contact.getTextureNode());
780
- releaseAo = () => {
781
- resolutionSubrect?.release(retained);
782
- contact.dispose();
783
- };
784
- // `RedFormat`, like SSGI's AO target: `.r` is the whole occlusion term, and
785
- // multiplying by the vec4 would zero green and blue and render the scene red.
786
- // Applied before SSGI by the chain's canonical order; composing it after the GI
787
- // combine instead darkens crevices the gather re-lit — that is a look choice, and
788
- // this file is where you make it.
789
- //
790
- // Denoised with the same depth-aware filter as the GI gather: GTAO's interleaved
791
- // sampling otherwise reads as a speckled halo around every contact — around feet on a
792
- // plain floor most of all — which is exactly the "not smooth" a player notices first.
793
- const filter = options.denoiseEnabled
794
- ? denoise(contact.getTextureNode(), depth(), normal(), view)
795
- : undefined;
796
- if (filter && resolutionSubrect) {
797
- const denoiser = filter as unknown as {
798
- textureNode: TextureNode;
799
- _resolution: { value: Vector2 };
800
- updateBefore(): void;
801
- };
802
- const update = denoiser.updateBefore;
803
- denoiser.updateBefore = function () {
804
- update.call(this);
805
- const fraction = resolutionSubrect.active
806
- ? resolutionSubrect.textureView(this.textureNode.value)?.viewFraction
807
- : undefined;
808
- if (fraction) this._resolution.value.multiply(fraction);
809
- };
810
- }
811
- const occlusion = filter ? denoised(filter) : contact;
812
- return input.mul(occlusion.r);
813
- },
814
- }),
815
- stage({
816
- name: "godRays",
817
- available: () => {
818
- // Godrays are raymarched against the light's shadow map: the shaft is the volume
819
- // the shadow map reports as lit. A light that casts no shadow yields a black pass,
820
- // which would read as "godrays are on and do nothing" — so refuse it by name.
821
- const light = target.godraysLight;
822
- if (light === undefined) return "godraysEnabled is true but no godraysLight was passed";
823
- if (light.castShadow !== true)
824
- return `light '${light.name || "sun"}' does not cast shadows`;
825
- // `castShadow` is a request, not a result: three allocates the shadow map on the first
826
- // render that needs it, and `GodraysNode` reads `shadow.map.depthTexture` while the
827
- // graph is built. Without this check that read throws inside TSL, the chain build
828
- // fails, and *every* stage is lost — the frame comes back ungraded with no SSGI, no
829
- // SSR and no tonemap, which looks like a scene problem rather than a missing map.
830
- // Refusing by name keeps the rest of the chain, which is this stage list's contract.
831
- if (light.shadow?.map == null)
832
- 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`;
833
- return true;
834
- },
835
- build: (input) => {
836
- const light = target.godraysLight as DirectionalLight;
837
- const shafts = godrays(depth(), view, light);
838
- shafts.density.value = options.godraysDensity;
839
- shafts.maxDensity.value = options.godraysMaxDensity;
840
- shafts.raymarchSteps.value = options.godraysSteps;
841
- // The pass jitters its samples with interleaved noise; at low step counts the
842
- // noise renders as a regular lattice over every hazy pixel. The bilateral
843
- // denoiser built for the GI gather smooths exactly that — high-frequency,
844
- // depth-coherent — and the shaft edges survive because they sit on geometry
845
- // silhouettes the depth term owns. Denoise before the floor: the floor's
846
- // subtraction amplifies relative noise on near-floor values.
847
- let shaft: ChainNode = convertToTexture(shafts);
848
- if (options.denoiseEnabled) shaft = denoised(denoise(shaft, depth(), normal(), view));
849
- // Floor, then scale, then tint. The floor is what turns this from a whole-frame
850
- // brightener into a shaft renderer; the tint by the light's own colour is what
851
- // stops a warm sun throwing a white beam.
852
- const cleaned = shaft.rgb.sub(options.godraysFloor).max(0).mul(options.godraysIntensity);
853
- return input.add(cleaned.mul(color(light.color)));
854
- },
855
- }),
856
- stage({
857
- name: "ssr",
858
- build: (input) => {
859
- // Three defaults that together make SSR silently do nothing on a real scene, all
860
- // fixed here and each worth stating:
861
- // maxDistance defaults to 1 world unit — a ray that dies after a metre
862
- // reflectNonMetals defaults to false, so a polished *stone* floor never reflects
863
- // roughnessNode null means every surface is treated as a perfect mirror
864
- // `normal`, not `normal.xyz`. SSR calls `.sample()` on this node, so it needs the
865
- // whole TextureNode; a swizzle produces a plain vec3 and the pass dies at shader
866
- // build. `@types/three` declares the parameter as `Node<"vec3">`, which is what
867
- // makes the swizzle look correct — the types are wrong here and the runtime is
868
- // right. Both `colorNode` and `normalNode` are `.sample()`d inside the pass, so
869
- // the composed input must be materialised ONCE and that texture reused on both
870
- // sides of the add: passing the unmaterialised node to the pass while adding the
871
- // reflections onto a second copy builds two parallel graphs, and the frame comes
872
- // out as the bare background colour.
873
- const base = convertToTexture(input);
874
- const reflections = ssr(base, depth(), normal() as unknown as Parameters<typeof ssr>[2], {
875
- camera: view,
876
- metalnessNode: metal().r,
877
- roughnessNode: rough().g,
878
- reflectNonMetals: true,
879
- });
880
- reflections.maxDistance.value = options.ssrMaxDistance;
881
- reflections.resolutionScale = options.ssrResolutionScale;
882
- return base.add(reflections);
883
- },
884
- }),
885
- stage({
886
- name: "sharpen",
887
- build: (input) => {
888
- // Last of the image stages but one, because RCAS is defined on the finished
889
- // picture: it looks at the contrast around a pixel and sharpens in proportion to
890
- // it, so running it before bloom would sharpen edges that bloom then spreads
891
- // back out. The third argument keeps the node from materialising its own render
892
- // target; the chain's graph is fused instead.
893
- return sharpen(convertToTexture(input), options.sharpenStrength, false);
894
- },
895
- }),
896
- stage({
897
- name: "bloom",
898
- supportsResolutionSubrect: true,
899
- dispose: () => {
900
- releaseBloom();
901
- releaseBloom = () => {};
902
- },
903
- build: (input) => {
904
- const texture = subrectTexture(input);
905
- const colour = input;
906
- const effect = bloom(
907
- texture,
908
- options.bloomStrength,
909
- options.bloomRadius,
910
- options.bloomThreshold,
911
- );
912
- if (resolutionSubrect) {
913
- const retained = effect as unknown as {
914
- setSize(w: number, h: number): void;
915
- setup(builder: NodeBuilder): unknown;
916
- getResolutionScale(): number;
917
- _separableBlurMaterials: { invSize: { value: Vector2 } }[];
918
- _renderTargetBright: RenderTarget;
919
- _renderTargetsHorizontal: RenderTarget[];
920
- _renderTargetsVertical: RenderTarget[];
921
- _textureOutput: TextureNode;
922
- _textureNodeBright: TextureNode;
923
- _textureNodeBlur0: TextureNode;
924
- _textureNodeBlur1: TextureNode;
925
- _textureNodeBlur2: TextureNode;
926
- _textureNodeBlur3: TextureNode;
927
- _textureNodeBlur4: TextureNode;
928
- _getSeparableBlurMaterial(
929
- builder: NodeBuilder,
930
- radius: number,
931
- ): { colorTexture: TextureNode };
932
- };
933
- // Stock bloom floors its last mip to zero on small views; clamp both target and texel size.
934
- retained.setSize = function (width, height) {
935
- let x = Math.max(1, Math.floor(width * this.getResolutionScale()));
936
- let y = Math.max(1, Math.floor(height * this.getResolutionScale()));
937
- this._renderTargetBright.setSize(x, y);
938
- for (const [index, horizontal] of this._renderTargetsHorizontal.entries()) {
939
- horizontal.setSize(x, y);
940
- this._renderTargetsVertical[index]?.setSize(x, y);
941
- this._separableBlurMaterials[index]?.invSize.value.set(1 / x, 1 / y);
942
- x = Math.max(1, Math.floor(x / 2));
943
- y = Math.max(1, Math.floor(y / 2));
944
- }
945
- };
946
- const setup = retained.setup;
947
- retained.setup = function (builder) {
948
- const result = setup.call(this, builder);
949
- resolutionSubrect.retain(retained, [
950
- retained._renderTargetBright,
951
- ...retained._renderTargetsHorizontal,
952
- ...retained._renderTargetsVertical,
953
- ]);
954
- return result;
955
- };
956
- for (const node of [
957
- retained._textureNodeBright,
958
- retained._textureNodeBlur0,
959
- retained._textureNodeBlur1,
960
- retained._textureNodeBlur2,
961
- retained._textureNodeBlur3,
962
- retained._textureNodeBlur4,
963
- retained._textureOutput,
964
- ])
965
- sample(node);
966
- const material = retained._getSeparableBlurMaterial;
967
- retained._getSeparableBlurMaterial = function (builder, radius) {
968
- const result = material.call(this, builder, radius);
969
- sample(result.colorTexture);
970
- return result;
971
- };
972
- }
973
- releaseBloom = () => {
974
- resolutionSubrect?.release(effect as unknown as ResolutionSubrectTarget);
975
- effect.dispose();
976
- // convertToTexture may return its input. Only the newly allocated RTT is ours.
977
- const scratch = texture as unknown as {
978
- isRTTNode?: boolean;
979
- renderTarget: { dispose(): void };
980
- _quadMesh: { material: { dispose(): void } };
981
- };
982
- if (texture !== input && scratch.isRTTNode === true) {
983
- resolutionSubrect?.release(texture as unknown as ResolutionSubrectTarget);
984
- scratch.renderTarget.dispose();
985
- scratch._quadMesh.material.dispose();
986
- }
987
- };
988
- return colour.add(effect);
989
- },
990
- }),
991
- stage({
992
- name: "vignette",
993
- supportsResolutionSubrect: true,
994
- build: (input) => {
995
- const colour = input;
996
- // Radius measured from the centre in screen-diagonal units, so the corner is 1
997
- // and the falloff does not change shape when the window does. It starts at 0.55 —
998
- // well outside the subject in a 16:9 frame — so the vignette is a corner, not a
999
- // spotlight.
1000
- const radius = uv().sub(vec2(0.5, 0.5)).mul(vec2(1.78, 1)).length().mul(1.04);
1001
- const fall = smoothstep(float(0.55), float(1.02), radius).mul(options.vignetteAmount);
1002
- return colour.mul(fall.oneMinus());
1003
- },
1004
- }),
1005
- {
1006
- // Last, after every built-in: antialiasing is defined on the finished picture, and any
1007
- // stage after it would put the stairsteps back.
1008
- name: "antialias",
1009
- after: "gradualBackground",
1010
- supportsResolutionSubrect: true,
1011
- dispose: () => {
1012
- releaseAa();
1013
- releaseAa = () => {};
1014
- },
1015
- build: (input) => {
1016
- const colour = input as ChainNode;
1017
- // SMAA and FXAA find edges by local contrast and expect display-range colour, but this is
1018
- // the linear HDR frame before the tone curve — a sun-lit edge at 20 against sky at 3
1019
- // would blend into a bright halo. The reversible Karis weighting squeezes it into [0, 1)
1020
- // for the filter and expands it back afterwards, so edges resolve without the halo.
1021
- const peak = max(colour.r, max(colour.g, colour.b));
1022
- const squeezed = colour.div(peak.add(1));
1023
- const texture = convertToTexture(squeezed);
1024
- sample(texture);
1025
- const effect = options.screenSpaceAA === "fxaa" ? fxaa(texture) : smaa(texture);
1026
- if (resolutionSubrect && options.screenSpaceAA !== "fxaa") {
1027
- const retained = effect as unknown as {
1028
- setSize(w: number, h: number): void;
1029
- _renderTargetEdges: RenderTarget;
1030
- _renderTargetWeights: RenderTarget;
1031
- _renderTargetBlend: RenderTarget;
1032
- _edgesTextureUniform: TextureNode;
1033
- _weightsTextureUniform: TextureNode;
1034
- _textureNode: TextureNode;
1035
- };
1036
- resolutionSubrect.retain(retained, [
1037
- retained._renderTargetEdges,
1038
- retained._renderTargetWeights,
1039
- retained._renderTargetBlend,
1040
- ]);
1041
- for (const node of [
1042
- retained._edgesTextureUniform,
1043
- retained._weightsTextureUniform,
1044
- retained._textureNode,
1045
- ])
1046
- sample(node);
1047
- } else if (resolutionSubrect) {
1048
- const filter = effect as unknown as {
1049
- updateBefore(): void;
1050
- _invSize: { value: Vector2 };
1051
- };
1052
- const update = filter.updateBefore;
1053
- filter.updateBefore = function () {
1054
- update.call(this);
1055
- const fraction = resolutionSubrect.active
1056
- ? resolutionSubrect.textureView(texture.value)?.viewFraction
1057
- : undefined;
1058
- if (fraction) this._invSize.value.divide(fraction);
1059
- };
1060
- }
1061
- releaseAa = () => {
1062
- resolutionSubrect?.release(effect as unknown as ResolutionSubrectTarget);
1063
- effect.dispose();
1064
- if (Reflect.get(texture, "isRTTNode") === true) {
1065
- resolutionSubrect?.release(texture as unknown as ResolutionSubrectTarget);
1066
- const owned = texture as unknown as {
1067
- renderTarget: RenderTarget;
1068
- _quadMesh: { material: { dispose(): void } };
1069
- };
1070
- owned.renderTarget.dispose();
1071
- owned._quadMesh.material.dispose();
1072
- }
1073
- };
1074
- const filtered = effect as unknown as ChainNode;
1075
- const back = max(filtered.r, max(filtered.g, filtered.b));
1076
- return filtered.div(float(1).sub(back).max(1e-4));
1077
- },
1078
- },
1079
- ];
1080
-
1081
- // The kit's own stages, composed after the built-ins. The factory is called with the two
1082
- // things only this file can produce — the scene pass's depth texture and the resolved tier —
1083
- // and returns the complete authored graph plus the subset to run.
1084
- stages.push(
1085
- ...options.authoredStages({
1086
- depthNode: depth(),
1087
- tier: options.renderChainTier,
1088
- camera,
1089
- }),
1090
- );
1091
-
1092
- // A composed base colour with every stage off still has to reach the frame. The chain
1093
- // installs nothing for an empty stage list, so this is the one path that goes direct.
1094
- if (requested.length === 0) {
1095
- if (renderer.setOutputNode === undefined || renderer.clearOutputNode === undefined) {
1096
- releaseGraph();
1097
- throw new Error("Output node installation and ownership-aware disposal are required.");
1098
- }
1099
- let installation: OutputInstallation | undefined;
1100
- try {
1101
- const returned = renderer.setOutputNode(exposed, scenePass);
1102
- installation =
1103
- returned &&
1104
- typeof returned.isCurrent === "function" &&
1105
- typeof returned.dispose === "function"
1106
- ? returned
1107
- : undefined;
1108
- } catch (error) {
1109
- releaseGraph();
1110
- throw error;
1111
- }
1112
- this.#reportApplied([], []);
1113
- return {
1114
- exposure,
1115
- dropped: [],
1116
- stages: [],
1117
- dispose: () => {
1118
- if (released) return;
1119
- if (installation) installation.dispose();
1120
- // Legacy adapters returning void retain node-only, not installation-level safety.
1121
- else renderer.clearOutputNode?.(exposed);
1122
- releaseGraph();
1123
- },
1124
- };
1125
- }
1126
-
1127
- if (renderer.createRenderChain === undefined) throw new Error("RenderChain is unavailable.");
1128
- // One stage owns the measurement, so the chain is asked for the one that published a callback
1129
- // rather than every stage in turn. A stage that dropped keeps answering `undefined`.
1130
- const rejectionMeasurement = stages.find(
1131
- (entry) => entry.rejectionMeasurement !== undefined,
1132
- )?.rejectionMeasurement;
1133
- const chain = renderer.createRenderChain({
1134
- input: exposed,
1135
- request: {
1136
- stages: requested,
1137
- tier: options.renderChainTier,
1138
- // Asked for on every chain and paid for only when a temporal stage is named: the chain
1139
- // provisions nothing while no requested stage needs velocity.
1140
- velocity: {
1141
- pass: scenePass,
1142
- ...(rejectionMeasurement === undefined ? {} : { rejectionMeasurement }),
1143
- },
1144
- },
1145
- stages,
1146
- resolutionSubrect,
1147
- worldPass: scenePass,
1148
- });
1149
- this.#reportApplied(chain.applied.stages, chain.applied.dropped);
1150
- return {
1151
- exposure,
1152
- dropped: chain.applied.dropped,
1153
- stages: chain.applied.stages,
1154
- dispose: () => {
1155
- if (released) return;
1156
- chain.dispose();
1157
- releaseGraph();
1158
- },
1159
- };
1160
- }
1161
-
1162
- /**
1163
- * Prints `TN_WORLD_ENVIRONMENT`: every stage this class can run, named as applied or refused
1164
- * **with a reason that is never blank**, plus the tone curve and exposure that framed them.
1165
- *
1166
- * The chain prints its own line for the stages it installed, and it prints nothing at all when
1167
- * nothing was requested — which is exactly the case where a reader most needs to know that GI
1168
- * is off because this file says so rather than because a node silently no-op'd. This line is
1169
- * emitted every run, including the run where every stage is off.
1170
- */
1171
- #reportApplied(
1172
- applied: readonly string[],
1173
- dropped: readonly { name: string; reason: string }[],
1174
- ): void {
1175
- const options = this.#options;
1176
- const off: Record<string, string> = {
1177
- ambientOcclusion: "gtaoEnabled is false",
1178
- antialias: 'screenSpaceAA is "disabled", or no other stage installed a chain',
1179
- bloom: "bloomEnabled is false",
1180
- godRays: "godraysEnabled is false",
1181
- sharpen: "sharpenEnabled is false",
1182
- ssgi: "ssgiEnabled is false",
1183
- ssr: "ssrEnabled is false",
1184
- vignette: "vignetteAmount is 0",
1185
- kuwahara: "kuwaharaEnabled is false",
1186
- outline: "outlineEnabled is false",
1187
- watercolor: "watercolorEnabled is false",
1188
- };
1189
- const stages = Object.keys(off)
1190
- .sort()
1191
- .map((name) => {
1192
- if (applied.includes(name)) return { applied: true, name };
1193
- const refused = dropped.find((entry) => entry.name === name);
1194
- return { applied: false, name, reason: refused?.reason ?? off[name] };
1195
- });
1196
- console.info(
1197
- `TN_WORLD_ENVIRONMENT:${JSON.stringify({
1198
- denoise: options.denoiseEnabled,
1199
- exposure: options.exposure,
1200
- marker: "TN_WORLD_ENVIRONMENT",
1201
- screenSpaceAA: options.screenSpaceAA,
1202
- ssgiQuality: options.ssgiQuality,
1203
- stages,
1204
- tonemapMode: options.tonemapMode,
1205
- })}`,
1206
- );
1207
- }
1208
- }
1209
-
1210
- function isChainTier(value: unknown): value is ChainTier {
1211
- return value === "high" || value === "medium" || value === "low" || value === "off";
1212
- }