create-threenative 0.2.8 → 0.2.10

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 (431) hide show
  1. package/agent-docs/references/assertion-reference.md +87 -35
  2. package/agent-docs/references/auto-exposure.md +57 -0
  3. package/agent-docs/references/capability-reference.md +1097 -23
  4. package/agent-docs/references/debug-surface.md +6 -0
  5. package/agent-docs/references/finding-assets.md +46 -10
  6. package/agent-docs/references/performance-basics.md +5 -4
  7. package/agent-docs/references/terrain-authoring.md +140 -0
  8. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  9. package/capabilities.json +1210 -27
  10. package/dist/index.d.ts +28 -3
  11. package/dist/index.js +396 -166
  12. package/dist/threenative.js +986 -235
  13. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  14. package/dist/web-engine-decal-geometry.js +184 -0
  15. package/dist/web-engine-gltf-loader.js +196 -0
  16. package/dist/web-engine-hdr-loader.js +190 -0
  17. package/dist/web-engine-lut-cube-loader.js +122 -0
  18. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  19. package/dist/web-engine-mesh-bvh.js +32 -0
  20. package/dist/web-engine-post-effects.js +168 -0
  21. package/dist/web-engine-runtime.js +42506 -0
  22. package/package.json +11 -8
  23. package/template-assets/autoExposure.ts +225 -0
  24. package/template-assets/exposure.ts +111 -0
  25. package/template-assets/exposureGraph.ts +178 -0
  26. package/template-assets/exposureReadback.ts +79 -0
  27. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  28. package/template-assets/patches/three@0.185.1.patch +6594 -700
  29. package/template-assets/patches/vite@8.2.0.patch +422 -0
  30. package/template-assets/worldEnvironment.ts +433 -30
  31. package/templates/action-rpg/AGENTS.md +11 -10
  32. package/templates/action-rpg/CLAUDE.md +11 -10
  33. package/templates/action-rpg/package.json +13 -10
  34. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  35. package/templates/action-rpg/src/progress.ts +0 -4
  36. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  37. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  38. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  39. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  40. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  41. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  42. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  43. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  44. package/templates/action-rpg/src/render/exposure.ts +111 -0
  45. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  46. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  47. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  48. package/templates/action-rpg/src/render/lighting.ts +26 -1
  49. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  50. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  51. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  52. package/templates/action-rpg/src/render/quality.ts +61 -2
  53. package/templates/action-rpg/src/render/sky.ts +21 -1
  54. package/templates/action-rpg/src/render/vfx.ts +133 -58
  55. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  56. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  57. package/templates/action-rpg/threenative.config.ts +3 -0
  58. package/templates/action-rpg/vite.config.ts +10 -2
  59. package/templates/minimal/AGENTS.md +9 -10
  60. package/templates/minimal/CLAUDE.md +9 -10
  61. package/templates/minimal/package.json +11 -9
  62. package/templates/minimal/playtests/play.playtest.json +7 -1
  63. package/templates/minimal/playtests/sky.playtest.json +10 -1
  64. package/templates/minimal/src/render/autoExposure.ts +225 -0
  65. package/templates/minimal/src/render/backlightControls.ts +66 -0
  66. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  67. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  68. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  69. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  70. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  71. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  72. package/templates/minimal/src/render/exposure.ts +111 -0
  73. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  74. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  75. package/templates/minimal/src/render/heightFog.ts +118 -0
  76. package/templates/minimal/src/render/lighting.ts +25 -1
  77. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  78. package/templates/minimal/src/render/materialLighting.ts +146 -0
  79. package/templates/minimal/src/render/postprocessing.ts +16 -2
  80. package/templates/minimal/src/render/quality.ts +60 -2
  81. package/templates/minimal/src/render/sky.ts +21 -1
  82. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  83. package/templates/minimal/src/scenes/Play.ts +50 -1
  84. package/templates/minimal/vite.config.ts +10 -2
  85. package/templates/platformer/AGENTS.md +7 -5
  86. package/templates/platformer/CLAUDE.md +7 -5
  87. package/templates/platformer/package.json +13 -10
  88. package/templates/platformer/playtests/performance.playtest.json +7 -1
  89. package/templates/platformer/src/render/autoExposure.ts +225 -0
  90. package/templates/platformer/src/render/backlightControls.ts +66 -0
  91. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  92. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  93. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  94. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  95. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  96. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  97. package/templates/platformer/src/render/exposure.ts +111 -0
  98. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  99. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  100. package/templates/platformer/src/render/heightFog.ts +118 -0
  101. package/templates/platformer/src/render/lighting.ts +26 -1
  102. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  103. package/templates/platformer/src/render/materialLighting.ts +155 -0
  104. package/templates/platformer/src/render/materials.ts +7 -2
  105. package/templates/platformer/src/render/palette.ts +3 -3
  106. package/templates/platformer/src/render/postprocessing.ts +17 -2
  107. package/templates/platformer/src/render/quality.ts +61 -2
  108. package/templates/platformer/src/render/sky.ts +72 -23
  109. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  110. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  111. package/templates/platformer/src/scenes/Play.ts +70 -6
  112. package/templates/platformer/vite.config.ts +10 -2
  113. package/templates/puzzle/AGENTS.md +10 -9
  114. package/templates/puzzle/CLAUDE.md +10 -9
  115. package/templates/puzzle/package.json +13 -10
  116. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  117. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  118. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  119. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  120. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  121. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  122. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  123. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  124. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  125. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  126. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  127. package/templates/puzzle/src/render/exposure.ts +111 -0
  128. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  129. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  130. package/templates/puzzle/src/render/heightFog.ts +118 -0
  131. package/templates/puzzle/src/render/lighting.ts +33 -1
  132. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  133. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  134. package/templates/puzzle/src/render/materials.ts +1 -1
  135. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  136. package/templates/puzzle/src/render/quality.ts +62 -1
  137. package/templates/puzzle/src/render/sky.ts +20 -1
  138. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  139. package/templates/puzzle/src/scenes/Play.ts +51 -2
  140. package/templates/puzzle/vite.config.ts +10 -2
  141. package/templates/racing/AGENTS.md +8 -7
  142. package/templates/racing/CLAUDE.md +8 -7
  143. package/templates/racing/package.json +13 -10
  144. package/templates/racing/playtests/performance.playtest.json +7 -1
  145. package/templates/racing/playtests/survives.playtest.json +6 -0
  146. package/templates/racing/src/render/autoExposure.ts +225 -0
  147. package/templates/racing/src/render/backlightControls.ts +66 -0
  148. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  149. package/templates/racing/src/render/environmentContribution.ts +188 -0
  150. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  151. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  152. package/templates/racing/src/render/environmentSampling.ts +193 -0
  153. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  154. package/templates/racing/src/render/exposure.ts +111 -0
  155. package/templates/racing/src/render/exposureGraph.ts +178 -0
  156. package/templates/racing/src/render/exposureReadback.ts +79 -0
  157. package/templates/racing/src/render/heightFog.ts +118 -0
  158. package/templates/racing/src/render/lighting.ts +29 -1
  159. package/templates/racing/src/render/materialAssignments.ts +160 -0
  160. package/templates/racing/src/render/materialLighting.ts +155 -0
  161. package/templates/racing/src/render/palette.ts +1 -10
  162. package/templates/racing/src/render/postprocessing.ts +17 -2
  163. package/templates/racing/src/render/quality.ts +61 -2
  164. package/templates/racing/src/render/shapes.ts +0 -25
  165. package/templates/racing/src/render/sky.ts +25 -5
  166. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  167. package/templates/racing/src/scenes/Race.ts +110 -13
  168. package/templates/racing/src/track/circuit.ts +0 -9
  169. package/templates/racing/vite.config.ts +10 -2
  170. package/templates/rain/AGENTS.md +8 -9
  171. package/templates/rain/CLAUDE.md +8 -9
  172. package/templates/rain/native-playtests/boot.playtest.json +11 -1
  173. package/templates/rain/package.json +14 -10
  174. package/templates/rain/playtests/automation.playtest.json +1 -1
  175. package/templates/rain/playtests/performance.playtest.json +11 -1
  176. package/templates/rain/playtests/tiers.playtest.json +15 -0
  177. package/templates/rain/playtests/weather.playtest.json +1 -1
  178. package/templates/rain/src/game.ts +1 -34
  179. package/templates/rain/src/render/autoExposure.ts +225 -0
  180. package/templates/rain/src/render/exposure.ts +111 -0
  181. package/templates/rain/src/render/exposureGraph.ts +178 -0
  182. package/templates/rain/src/render/exposureReadback.ts +79 -0
  183. package/templates/rain/src/render/postprocessing.ts +3 -0
  184. package/templates/rain/src/render/quality.ts +27 -1
  185. package/templates/rain/src/render/worldEnvironment.ts +433 -30
  186. package/templates/rain/src/scenes/Boot.ts +14 -0
  187. package/templates/rain/src/state.ts +5 -1
  188. package/templates/rain/src/ui/GameUi.tsx +6 -6
  189. package/templates/rain/tools/generate-shaders.mjs +1 -1
  190. package/templates/rain/vite.config.ts +10 -2
  191. package/templates/rts/AGENTS.md +10 -11
  192. package/templates/rts/CLAUDE.md +10 -11
  193. package/templates/rts/package.json +12 -9
  194. package/templates/rts/playtests/performance.playtest.json +7 -1
  195. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  196. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  197. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  198. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  199. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  200. package/templates/rts/src/render/army.ts +10 -2
  201. package/templates/rts/src/render/autoExposure.ts +225 -0
  202. package/templates/rts/src/render/backlightControls.ts +66 -0
  203. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  204. package/templates/rts/src/render/environmentContribution.ts +188 -0
  205. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  206. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  207. package/templates/rts/src/render/environmentSampling.ts +193 -0
  208. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  209. package/templates/rts/src/render/exposure.ts +111 -0
  210. package/templates/rts/src/render/exposureGraph.ts +178 -0
  211. package/templates/rts/src/render/exposureReadback.ts +79 -0
  212. package/templates/rts/src/render/heightFog.ts +118 -0
  213. package/templates/rts/src/render/lighting.ts +26 -1
  214. package/templates/rts/src/render/materialAssignments.ts +160 -0
  215. package/templates/rts/src/render/materialLighting.ts +155 -0
  216. package/templates/rts/src/render/postprocessing.ts +8 -2
  217. package/templates/rts/src/render/quality.ts +61 -2
  218. package/templates/rts/src/render/sky.ts +21 -1
  219. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  220. package/templates/rts/src/scenes/Play.ts +54 -3
  221. package/templates/rts/src/sim/ai.ts +0 -1
  222. package/templates/rts/src/sim/terrain.ts +0 -4
  223. package/templates/rts/vite.config.ts +10 -2
  224. package/templates/runner/AGENTS.md +10 -8
  225. package/templates/runner/CLAUDE.md +10 -8
  226. package/templates/runner/package.json +13 -10
  227. package/templates/runner/playtests/performance.playtest.json +10 -1
  228. package/templates/runner/src/physics.ts +0 -1
  229. package/templates/runner/src/render/autoExposure.ts +225 -0
  230. package/templates/runner/src/render/backlightControls.ts +66 -0
  231. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  232. package/templates/runner/src/render/environmentContribution.ts +188 -0
  233. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  234. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  235. package/templates/runner/src/render/environmentSampling.ts +193 -0
  236. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  237. package/templates/runner/src/render/exposure.ts +111 -0
  238. package/templates/runner/src/render/exposureGraph.ts +178 -0
  239. package/templates/runner/src/render/exposureReadback.ts +79 -0
  240. package/templates/runner/src/render/heightFog.ts +118 -0
  241. package/templates/runner/src/render/lighting.ts +26 -1
  242. package/templates/runner/src/render/materialAssignments.ts +160 -0
  243. package/templates/runner/src/render/materialLighting.ts +155 -0
  244. package/templates/runner/src/render/postprocessing.ts +17 -2
  245. package/templates/runner/src/render/quality.ts +61 -2
  246. package/templates/runner/src/render/sky.ts +21 -1
  247. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  248. package/templates/runner/src/scenes/Run.ts +67 -2
  249. package/templates/runner/threenative.config.ts +3 -0
  250. package/templates/runner/vite.config.ts +10 -2
  251. package/templates/sailing/AGENTS.md +14 -13
  252. package/templates/sailing/CLAUDE.md +14 -13
  253. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  254. package/templates/sailing/package.json +13 -10
  255. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  256. package/templates/sailing/src/entities/Ship.ts +38 -18
  257. package/templates/sailing/src/render/autoExposure.ts +225 -0
  258. package/templates/sailing/src/render/backlightControls.ts +66 -0
  259. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  260. package/templates/sailing/src/render/camera.ts +12 -4
  261. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  262. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  263. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  264. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  265. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  266. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  267. package/templates/sailing/src/render/exposure.ts +111 -0
  268. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  269. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  270. package/templates/sailing/src/render/heightFog.ts +118 -0
  271. package/templates/sailing/src/render/lighting.ts +26 -1
  272. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  273. package/templates/sailing/src/render/materialLighting.ts +155 -0
  274. package/templates/sailing/src/render/ocean.ts +71 -53
  275. package/templates/sailing/src/render/postprocessing.ts +16 -2
  276. package/templates/sailing/src/render/props.ts +0 -45
  277. package/templates/sailing/src/render/quality.ts +61 -1
  278. package/templates/sailing/src/render/sky.ts +21 -1
  279. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  280. package/templates/sailing/src/scenes/Boot.ts +12 -1
  281. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  282. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  283. package/templates/sailing/threenative.config.ts +3 -0
  284. package/templates/sailing/vite.config.ts +10 -2
  285. package/templates/shooter/AGENTS.md +8 -6
  286. package/templates/shooter/CLAUDE.md +8 -6
  287. package/templates/shooter/package.json +13 -10
  288. package/templates/shooter/playtests/performance.playtest.json +7 -1
  289. package/templates/shooter/src/entities/Enemy.ts +0 -15
  290. package/templates/shooter/src/entities/Rifle.ts +38 -1
  291. package/templates/shooter/src/render/autoExposure.ts +225 -0
  292. package/templates/shooter/src/render/backlightControls.ts +66 -0
  293. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  294. package/templates/shooter/src/render/camera.ts +1 -12
  295. package/templates/shooter/src/render/decals.ts +299 -5
  296. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  297. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  298. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  299. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  300. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  301. package/templates/shooter/src/render/exposure.ts +111 -0
  302. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  303. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  304. package/templates/shooter/src/render/gunfx.ts +0 -1
  305. package/templates/shooter/src/render/heightFog.ts +118 -0
  306. package/templates/shooter/src/render/lighting.ts +26 -1
  307. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  308. package/templates/shooter/src/render/materialLighting.ts +155 -0
  309. package/templates/shooter/src/render/postprocessing.ts +17 -2
  310. package/templates/shooter/src/render/quality.ts +61 -2
  311. package/templates/shooter/src/render/scale.ts +2 -93
  312. package/templates/shooter/src/render/sky.ts +21 -1
  313. package/templates/shooter/src/render/vehicles.ts +0 -17
  314. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  315. package/templates/shooter/src/scenes/Play.ts +64 -2
  316. package/templates/shooter/vite.config.ts +10 -2
  317. package/templates/snow/AGENTS.md +8 -6
  318. package/templates/snow/CLAUDE.md +8 -6
  319. package/templates/snow/package.json +13 -10
  320. package/templates/snow/src/render/autoExposure.ts +225 -0
  321. package/templates/snow/src/render/backlightControls.ts +66 -0
  322. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  323. package/templates/snow/src/render/environmentContribution.ts +188 -0
  324. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  325. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/snow/src/render/environmentSampling.ts +193 -0
  327. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  328. package/templates/snow/src/render/exposure.ts +111 -0
  329. package/templates/snow/src/render/exposureGraph.ts +178 -0
  330. package/templates/snow/src/render/exposureReadback.ts +79 -0
  331. package/templates/snow/src/render/heightFog.ts +118 -0
  332. package/templates/snow/src/render/lighting.ts +33 -1
  333. package/templates/snow/src/render/materialAssignments.ts +160 -0
  334. package/templates/snow/src/render/materialLighting.ts +155 -0
  335. package/templates/snow/src/render/postprocessing.ts +16 -2
  336. package/templates/snow/src/render/quality.ts +59 -1
  337. package/templates/snow/src/render/sky.ts +21 -2
  338. package/templates/snow/src/render/worldEnvironment.ts +433 -30
  339. package/templates/snow/src/scenes/Snow.ts +29 -1
  340. package/templates/snow/threenative.config.ts +3 -0
  341. package/templates/snow/vite.config.ts +10 -2
  342. package/templates/starter/AGENTS.md +11 -16
  343. package/templates/starter/CLAUDE.md +11 -16
  344. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  345. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  346. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  347. package/templates/starter/package.json +13 -10
  348. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  349. package/templates/starter/playtests/movement.playtest.json +192 -0
  350. package/templates/starter/playtests/play.playtest.json +18 -2
  351. package/templates/starter/playtests/production-readiness.playtest.json +43 -1
  352. package/templates/starter/public/grade.cube +735 -0
  353. package/templates/starter/src/entities/Crate.ts +4 -0
  354. package/templates/starter/src/entities/Player.ts +79 -18
  355. package/templates/starter/src/game.ts +1 -0
  356. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  357. package/templates/starter/src/render/autoExposure.ts +225 -0
  358. package/templates/starter/src/render/backlightControls.ts +66 -0
  359. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  360. package/templates/starter/src/render/environmentContribution.ts +188 -0
  361. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  362. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  363. package/templates/starter/src/render/environmentSampling.ts +193 -0
  364. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  365. package/templates/starter/src/render/exposure.ts +111 -0
  366. package/templates/starter/src/render/exposureGraph.ts +178 -0
  367. package/templates/starter/src/render/exposureReadback.ts +79 -0
  368. package/templates/starter/src/render/grade.ts +157 -0
  369. package/templates/starter/src/render/heightFog.ts +118 -0
  370. package/templates/starter/src/render/lighting.ts +26 -1
  371. package/templates/starter/src/render/materialAssignments.ts +160 -0
  372. package/templates/starter/src/render/materialLighting.ts +155 -0
  373. package/templates/starter/src/render/postprocessing.ts +90 -4
  374. package/templates/starter/src/render/quality.ts +80 -8
  375. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  376. package/templates/starter/src/render/rendererGate.ts +36 -0
  377. package/templates/starter/src/render/sky.ts +23 -1
  378. package/templates/starter/src/render/temporalAA.ts +197 -0
  379. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  380. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  381. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  382. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  383. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  384. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  385. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  386. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  387. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  388. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  389. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  390. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  391. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  392. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  393. package/templates/starter/src/render/temporalResolve.ts +139 -0
  394. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  395. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  396. package/templates/starter/src/render/volumetricFog.ts +124 -0
  397. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  398. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  399. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  400. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  401. package/templates/starter/src/scenes/Play.ts +110 -1
  402. package/templates/starter/src/state.ts +1 -0
  403. package/templates/starter/src/ui/Hud.tsx +1 -1
  404. package/templates/starter/src/ui/Menu.tsx +1 -1
  405. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  406. package/templates/starter/vite.config.ts +10 -2
  407. package/templates/tower-defense/AGENTS.md +10 -9
  408. package/templates/tower-defense/CLAUDE.md +10 -9
  409. package/templates/tower-defense/package.json +13 -10
  410. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  411. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  412. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  413. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  414. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  415. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  416. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  417. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  418. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  419. package/templates/tower-defense/src/render/exposure.ts +111 -0
  420. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  421. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  422. package/templates/tower-defense/src/render/lighting.ts +33 -1
  423. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  424. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  425. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  426. package/templates/tower-defense/src/render/quality.ts +61 -2
  427. package/templates/tower-defense/src/render/shapes.ts +0 -3
  428. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  429. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  430. package/templates/tower-defense/vite.config.ts +10 -2
  431. package/templates/minimal/src/scenes/Boot.ts +0 -5
@@ -18,9 +18,13 @@ import {
18
18
  AgXToneMapping,
19
19
  type Camera,
20
20
  type DirectionalLight,
21
+ MaterialBlending,
21
22
  NeutralToneMapping,
22
23
  type PerspectiveCamera,
24
+ type RenderTarget,
23
25
  type Scene,
26
+ type Texture,
27
+ Vector2,
24
28
  } from "three";
25
29
  import { bloom } from "three/addons/tsl/display/BloomNode.js";
26
30
  import { denoise } from "three/addons/tsl/display/DenoiseNode.js";
@@ -32,6 +36,7 @@ import { ssgi } from "three/addons/tsl/display/SSGINode.js";
32
36
  import { ssr } from "three/addons/tsl/display/SSRNode.js";
33
37
  import { sharpen } from "three/addons/tsl/display/SharpenNode.js";
34
38
  import {
39
+ clamp,
35
40
  color,
36
41
  convertToTexture,
37
42
  float,
@@ -42,11 +47,15 @@ import {
42
47
  output,
43
48
  pass,
44
49
  roughness,
45
- screenUV,
46
50
  smoothstep,
51
+ uniform,
52
+ uv,
47
53
  vec2,
54
+ vec4,
48
55
  } from "three/tsl";
49
- import type { Node } from "three/webgpu";
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";
50
59
 
51
60
  /** Godot's `Viewport.screen_space_aa`: which post-process antialiasing smooths the frame's edges. */
52
61
  export type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
@@ -74,6 +83,8 @@ const TONEMAP: Record<TonemapMode, number> = {
74
83
  };
75
84
 
76
85
  export interface IWorldEnvironmentOptions {
86
+ /** World-pass MSAA samples. Omit to inherit the renderer; 0 leaves post AA in charge. */
87
+ readonly samples?: number;
77
88
  /** Screen-space indirect diffuse light. Godot calls this `ssil_enabled`. */
78
89
  readonly ssgiEnabled?: boolean;
79
90
  readonly ssgiQuality?: SsgiQuality;
@@ -243,6 +254,10 @@ export interface IWorldEnvironmentOptions {
243
254
  * class falls back to that scalar; when any stage runs, this multiply is the shutter.
244
255
  */
245
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>;
246
261
  }
247
262
 
248
263
  export interface IWorldEnvironmentTarget {
@@ -266,6 +281,10 @@ export interface IWorldEnvironmentTarget {
266
281
  * compiler checks the composition instead of taking a cast's word for it.
267
282
  */
268
283
  type ChainNode = Node<"vec4">;
284
+ type ResolutionSubrectView = {
285
+ readonly viewFraction: Vector2;
286
+ readonly halfTexel: Vector2;
287
+ };
269
288
  /**
270
289
  * The scene pass's depth texture, as the pass itself types it.
271
290
  *
@@ -276,6 +295,15 @@ export type DepthTextureNode = ReturnType<ReturnType<typeof pass>["getTextureNod
276
295
  type ChainTier = "high" | "medium" | "low" | "off";
277
296
  type ChainContext = {
278
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;
279
307
  };
280
308
  /**
281
309
  * What a kit's `authoredStages` factory is handed. The depth node is the scene pass's, so a
@@ -284,15 +312,35 @@ type ChainContext = {
284
312
  export interface IWorldEnvironmentStageContext {
285
313
  readonly depthNode: DepthTextureNode;
286
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;
287
317
  }
288
318
 
289
319
  export type ChainStage = {
290
320
  readonly name: string;
321
+ readonly supportsResolutionSubrect?: boolean;
291
322
  readonly before?: string;
292
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;
293
334
  readonly available?: (context: ChainContext) => boolean | string;
294
335
  readonly dispose?: () => void;
295
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;
296
344
  /** The chain plumbing is stage-agnostic, so it names the node it carries `unknown`. */
297
345
  readonly build: (input: unknown, context: ChainContext) => unknown;
298
346
  };
@@ -307,6 +355,7 @@ export type ChainStage = {
307
355
  */
308
356
  function stage(definition: {
309
357
  readonly name: ChainStage["name"];
358
+ readonly supportsResolutionSubrect?: boolean;
310
359
  readonly dispose?: () => void;
311
360
  readonly available?: (context: ChainContext) => boolean | string;
312
361
  readonly build: (input: ChainNode, context: ChainContext) => ChainNode;
@@ -327,20 +376,109 @@ function stage(definition: {
327
376
  function denoised(node: ReturnType<typeof denoise>): ChainNode {
328
377
  return node as unknown as ChainNode;
329
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
+
330
452
  export type OutputRenderer = {
331
453
  kind: string;
332
454
  raw: unknown;
455
+ createResolutionSubrect?: () => ResolutionSubrectController;
333
456
  /**
334
457
  * Installs a node graph directly. Only reached when a `baseColour` is composed and every
335
458
  * stage is off: the chain installs nothing for an empty stage list, and dropping the game's
336
459
  * own composition on the floor would be the silent no-op this class exists to prevent.
337
460
  */
338
- setOutputNode?: (node: unknown) => void;
461
+ setOutputNode?: OutputSetter;
462
+ /** Legacy node-only clear. The returned receipt distinguishes same-node reinstalls. */
463
+ clearOutputNode?: (expectedNode?: unknown) => void;
339
464
  createRenderChain?: (options: {
340
465
  input?: unknown;
341
466
  worldPass?: unknown;
342
- request?: { stages?: readonly string[]; tier?: ChainContext["tier"] };
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
+ };
343
480
  stages?: readonly ChainStage[];
481
+ resolutionSubrect?: ResolutionSubrectController;
344
482
  }) => {
345
483
  applied: { dropped: readonly { name: string; reason: string }[]; stages: readonly string[] };
346
484
  dispose(): void;
@@ -356,7 +494,8 @@ export type OutputRenderer = {
356
494
  * unless it reads that line.
357
495
  */
358
496
  export class WorldEnvironment {
359
- readonly #options: Required<IWorldEnvironmentOptions>;
497
+ readonly #options: Required<Omit<IWorldEnvironmentOptions, "samples">> &
498
+ Pick<IWorldEnvironmentOptions, "samples">;
360
499
 
361
500
  constructor(options: IWorldEnvironmentOptions = {}) {
362
501
  const quality = options.ssgiQuality ?? "medium";
@@ -380,6 +519,7 @@ export class WorldEnvironment {
380
519
  );
381
520
  }
382
521
  this.#options = {
522
+ samples: options.samples,
383
523
  // A kit with no stages of its own is the common case, so both default to empty rather
384
524
  // than to a branch every call site has to remember.
385
525
  authoredStageNames: options.authoredStageNames ?? [],
@@ -415,6 +555,8 @@ export class WorldEnvironment {
415
555
  renderChainTier,
416
556
  tonemapMode,
417
557
  exposure: options.exposure ?? 1,
558
+ autoExposureEnabled: options.autoExposureEnabled ?? false,
559
+ exposurePolicy: options.exposurePolicy ?? exposureSettings,
418
560
  };
419
561
  }
420
562
 
@@ -431,6 +573,7 @@ export class WorldEnvironment {
431
573
  dropped: readonly { name: string; reason: string }[];
432
574
  stages: readonly string[];
433
575
  dispose?: () => void;
576
+ exposure?: AutoExposureNode;
434
577
  } {
435
578
  const options = this.#options;
436
579
  const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
@@ -461,20 +604,50 @@ export class WorldEnvironment {
461
604
  // applied as a multiply on the scene pass instead: scene-referred, so every downstream
462
605
  // stage sees the exposed image and the bloom threshold means the same thing at any
463
606
  // exposure. Both land at the same point in the graph — before the tone curve.
464
- if (requested.length === 0 && target.baseColour === undefined) {
607
+ if (requested.length === 0 && target.baseColour === undefined && !options.autoExposureEnabled) {
465
608
  raw.toneMappingExposure = options.exposure;
466
609
  this.#reportApplied([], []);
467
610
  return { dropped: [], stages: [] };
468
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
+ );
469
629
  raw.toneMappingExposure = 1;
470
630
 
471
- const scenePass = pass(scene, camera);
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
+ };
472
641
  // Normals come from the multi-render-target alongside the colour. SSGI can derive them
473
642
  // from depth alone, but the derived normal is flat across a triangle, which shows up as
474
643
  // faceted bounce on exactly the smooth surfaces GI is bought for. Metalness and
475
644
  // roughness ride along so SSR knows which pixels are supposed to reflect.
476
645
  if (options.ssgiEnabled || options.ssrEnabled || options.gtaoEnabled) {
477
- scenePass.setMRT(mrt({ output, normal: normalView, metalness, roughness }));
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);
478
651
  }
479
652
  // Requested lazily, and this is not a micro-optimisation. **Asking a pass for `normal`,
480
653
  // `metalness` or `roughness` is what creates the extra render target.** A tier that runs none
@@ -488,6 +661,7 @@ export class WorldEnvironment {
488
661
  const cached = nodes.get(name);
489
662
  if (cached !== undefined) return cached;
490
663
  const node = scenePass.getTextureNode(name);
664
+ sample(node);
491
665
  nodes.set(name, node);
492
666
  return node;
493
667
  };
@@ -500,11 +674,44 @@ export class WorldEnvironment {
500
674
  const view = camera as PerspectiveCamera;
501
675
 
502
676
  const base = target.baseColour?.(scenePass) ?? scenePass.getTextureNode("output");
503
- const exposed = convertToTexture(base).mul(options.exposure);
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
+ };
504
709
  const giDenoise = (node: ChainNode): ChainNode =>
505
710
  options.denoiseEnabled ? denoised(denoise(node, depth(), normal(), view)) : node;
506
711
 
507
712
  let releaseBloom = (): void => {};
713
+ let releaseAo = (): void => {};
714
+ let releaseAa = (): void => {};
508
715
  const stages: ChainStage[] = [
509
716
  stage({
510
717
  name: "ssgi",
@@ -553,12 +760,27 @@ export class WorldEnvironment {
553
760
  }),
554
761
  stage({
555
762
  name: "ambientOcclusion",
763
+ supportsResolutionSubrect: true,
764
+ dispose: () => {
765
+ releaseAo();
766
+ releaseAo = () => {};
767
+ },
556
768
  build: (input) => {
557
- const contact = ao(depth(), normal(), view);
769
+ const contact = ao(subrectTexture(depth()), subrectTexture(normal()), view);
558
770
  contact.radius.value = options.gtaoRadius;
559
771
  contact.scale.value = options.gtaoScale;
560
772
  contact.samples.value = options.gtaoSamples;
561
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
+ };
562
784
  // `RedFormat`, like SSGI's AO target: `.r` is the whole occlusion term, and
563
785
  // multiplying by the vec4 would zero green and blue and render the scene red.
564
786
  // Applied before SSGI by the chain's canonical order; composing it after the GI
@@ -568,9 +790,25 @@ export class WorldEnvironment {
568
790
  // Denoised with the same depth-aware filter as the GI gather: GTAO's interleaved
569
791
  // sampling otherwise reads as a speckled halo around every contact — around feet on a
570
792
  // plain floor most of all — which is exactly the "not smooth" a player notices first.
571
- const occlusion = options.denoiseEnabled
572
- ? denoised(denoise(contact.getTextureNode(), depth(), normal(), view))
573
- : contact;
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;
574
812
  return input.mul(occlusion.r);
575
813
  },
576
814
  }),
@@ -657,19 +895,83 @@ export class WorldEnvironment {
657
895
  }),
658
896
  stage({
659
897
  name: "bloom",
898
+ supportsResolutionSubrect: true,
660
899
  dispose: () => {
661
900
  releaseBloom();
662
901
  releaseBloom = () => {};
663
902
  },
664
903
  build: (input) => {
665
- const texture = convertToTexture(input);
904
+ const texture = subrectTexture(input);
905
+ const colour = input;
666
906
  const effect = bloom(
667
907
  texture,
668
908
  options.bloomStrength,
669
909
  options.bloomRadius,
670
910
  options.bloomThreshold,
671
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
+ }
672
973
  releaseBloom = () => {
974
+ resolutionSubrect?.release(effect as unknown as ResolutionSubrectTarget);
673
975
  effect.dispose();
674
976
  // convertToTexture may return its input. Only the newly allocated RTT is ours.
675
977
  const scratch = texture as unknown as {
@@ -678,23 +980,26 @@ export class WorldEnvironment {
678
980
  _quadMesh: { material: { dispose(): void } };
679
981
  };
680
982
  if (texture !== input && scratch.isRTTNode === true) {
983
+ resolutionSubrect?.release(texture as unknown as ResolutionSubrectTarget);
681
984
  scratch.renderTarget.dispose();
682
985
  scratch._quadMesh.material.dispose();
683
986
  }
684
987
  };
685
- return input.add(effect);
988
+ return colour.add(effect);
686
989
  },
687
990
  }),
688
991
  stage({
689
992
  name: "vignette",
993
+ supportsResolutionSubrect: true,
690
994
  build: (input) => {
995
+ const colour = input;
691
996
  // Radius measured from the centre in screen-diagonal units, so the corner is 1
692
997
  // and the falloff does not change shape when the window does. It starts at 0.55 —
693
998
  // well outside the subject in a 16:9 frame — so the vignette is a corner, not a
694
999
  // spotlight.
695
- const radius = screenUV.sub(vec2(0.5, 0.5)).mul(vec2(1.78, 1)).length().mul(1.04);
1000
+ const radius = uv().sub(vec2(0.5, 0.5)).mul(vec2(1.78, 1)).length().mul(1.04);
696
1001
  const fall = smoothstep(float(0.55), float(1.02), radius).mul(options.vignetteAmount);
697
- return input.mul(fall.oneMinus());
1002
+ return colour.mul(fall.oneMinus());
698
1003
  },
699
1004
  }),
700
1005
  {
@@ -702,6 +1007,11 @@ export class WorldEnvironment {
702
1007
  // stage after it would put the stairsteps back.
703
1008
  name: "antialias",
704
1009
  after: "gradualBackground",
1010
+ supportsResolutionSubrect: true,
1011
+ dispose: () => {
1012
+ releaseAa();
1013
+ releaseAa = () => {};
1014
+ },
705
1015
  build: (input) => {
706
1016
  const colour = input as ChainNode;
707
1017
  // SMAA and FXAA find edges by local contrast and expect display-range colour, but this is
@@ -710,9 +1020,58 @@ export class WorldEnvironment {
710
1020
  // for the filter and expands it back afterwards, so edges resolve without the halo.
711
1021
  const peak = max(colour.r, max(colour.g, colour.b));
712
1022
  const squeezed = colour.div(peak.add(1));
713
- const filtered = (options.screenSpaceAA === "fxaa"
714
- ? fxaa(squeezed)
715
- : smaa(squeezed)) as unknown as ChainNode;
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;
716
1075
  const back = max(filtered.r, max(filtered.g, filtered.b));
717
1076
  return filtered.div(float(1).sub(back).max(1e-4));
718
1077
  },
@@ -722,36 +1081,80 @@ export class WorldEnvironment {
722
1081
  // The kit's own stages, composed after the built-ins. The factory is called with the two
723
1082
  // things only this file can produce — the scene pass's depth texture and the resolved tier —
724
1083
  // and returns the complete authored graph plus the subset to run.
725
- stages.push(...options.authoredStages({ depthNode: depth(), tier: options.renderChainTier }));
1084
+ stages.push(
1085
+ ...options.authoredStages({
1086
+ depthNode: depth(),
1087
+ tier: options.renderChainTier,
1088
+ camera,
1089
+ }),
1090
+ );
726
1091
 
727
1092
  // A composed base colour with every stage off still has to reach the frame. The chain
728
1093
  // installs nothing for an empty stage list, so this is the one path that goes direct.
729
1094
  if (requested.length === 0) {
730
- if (renderer.kind !== "webgpu") {
731
- this.#reportApplied([], [{ name: "baseColour", reason: `renderer:${renderer.kind}` }]);
732
- return { dropped: [], stages: [] };
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;
733
1111
  }
734
- if (renderer.setOutputNode === undefined)
735
- throw new Error("setOutputNode is unavailable, so the composed base colour cannot run.");
736
- renderer.setOutputNode(exposed);
737
1112
  this.#reportApplied([], []);
738
- return { dropped: [], stages: [] };
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
+ };
739
1125
  }
740
1126
 
741
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;
742
1133
  const chain = renderer.createRenderChain({
743
1134
  input: exposed,
744
- request: { stages: requested, tier: options.renderChainTier },
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
+ },
745
1145
  stages,
1146
+ resolutionSubrect,
746
1147
  worldPass: scenePass,
747
1148
  });
748
1149
  this.#reportApplied(chain.applied.stages, chain.applied.dropped);
749
1150
  return {
1151
+ exposure,
750
1152
  dropped: chain.applied.dropped,
751
1153
  stages: chain.applied.stages,
752
1154
  dispose: () => {
1155
+ if (released) return;
753
1156
  chain.dispose();
754
- scenePass.dispose();
1157
+ releaseGraph();
755
1158
  },
756
1159
  };
757
1160
  }