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
@@ -0,0 +1,36 @@
1
+ // Generated for you: which renderers may run the material-lighting lane. No look lives here;
2
+ // `quality.ts` re-exports these, so existing imports keep working.
3
+ import type { QualityTier } from "./quality.js";
4
+
5
+ /** First admitted material lane: high desktop hardware WebGPU in the browser only. */
6
+ export interface IMaterialLightingEnvironment {
7
+ readonly web: boolean;
8
+ readonly rendererKind: string;
9
+ readonly mobile?: boolean;
10
+ readonly software?: boolean;
11
+ readonly webglFallback?: boolean;
12
+ }
13
+ export function materialLightingEnabled(
14
+ tier: QualityTier,
15
+ environment: IMaterialLightingEnvironment,
16
+ ): boolean {
17
+ return (
18
+ tier === "high" &&
19
+ environment.web &&
20
+ environment.rendererKind === "webgpu" &&
21
+ environment.mobile !== true &&
22
+ environment.software !== true &&
23
+ environment.webglFallback !== true
24
+ );
25
+ }
26
+
27
+ /** A WebGPURenderer wrapper may run an ordinary WebGL fallback backend. */
28
+ export function isWebGLFallbackRenderer(renderer: unknown): boolean {
29
+ if (renderer === null || typeof renderer !== "object") return false;
30
+ const backend = Reflect.get(renderer, "backend");
31
+ return (
32
+ backend !== null &&
33
+ typeof backend === "object" &&
34
+ Reflect.get(backend, "isWebGLBackend") === true
35
+ );
36
+ }
@@ -14,6 +14,7 @@ import {
14
14
  type Texture,
15
15
  Vector3,
16
16
  } from "three";
17
+ import { HEIGHT_FOG, type HeightFogParams, heightFogDepth, heightFogNode } from "./heightFog.js";
17
18
  import { palette } from "./palette.js";
18
19
 
19
20
  /**
@@ -26,6 +27,22 @@ const SKY_RANGE = 2.5;
26
27
  /** Unit vector toward the photographed sun: 47.9° up, measured from the source HDR. */
27
28
  export const SUN_DIRECTION = new Vector3(0.555, 0.742, 0.38).normalize();
28
29
 
30
+ /** The look this fog replaced: FogExp2 at 0.003, which read as 18% haze at 150 m from 2 m up. */
31
+ const EYE_LEVEL = { density: 0.003, distance: 150, cameraHeight: 2 };
32
+
33
+ /**
34
+ * The distance term's density that, with the height term, keeps the old eye-level haze: at
35
+ * `EYE_LEVEL.distance` along the horizon from `EYE_LEVEL.cameraHeight` the two together transmit what
36
+ * FogExp2 at `EYE_LEVEL.density` did. The distance term is lowered, never removed, so the ground
37
+ * still ends in fog at a kilometre.
38
+ */
39
+ function distanceDensity(p: HeightFogParams = HEIGHT_FOG): number {
40
+ const { distance, density, cameraHeight } = EYE_LEVEL;
41
+ const old = (density * distance) ** 2;
42
+ const height = heightFogDepth(p, cameraHeight, cameraHeight, distance) * Math.LN2;
43
+ return Math.sqrt(Math.max(0, old - height)) / distance;
44
+ }
45
+
29
46
  export function setupSky(scene: Scene, sky: Texture, software = false): void {
30
47
  sky.mapping = EquirectangularReflectionMapping;
31
48
  sky.colorSpace = SRGBColorSpace;
@@ -46,5 +63,10 @@ export function setupSky(scene: Scene, sky: Texture, software = false): void {
46
63
  // Almost nothing inside the arena (1.4% at 30 m), and the ground gone into the horizon by a
47
64
  // kilometre — so the floor meets the sky instead of ending at a line. The colour is the
48
65
  // photograph's own horizon, sampled from the same HDR, so the fade lands where the sky is.
49
- scene.fog = new FogExp2(palette.skyLow, 0.003);
66
+ // `scene.fog` stays the distance term for anything that reads it; `scene.fogNode` is what three
67
+ // applies, and it adds the height term. One owner at a time: `STARTER_MIST` clears both.
68
+ const params: HeightFogParams = { ...HEIGHT_FOG };
69
+ const distanceFog = new FogExp2(palette.skyLow, distanceDensity(params));
70
+ scene.fog = distanceFog;
71
+ scene.fogNode = heightFogNode(distanceFog, params, SUN_DIRECTION);
50
72
  }
@@ -0,0 +1,197 @@
1
+ // Generated user source: opt-in temporal AA using pinned Three.js TRAANode. Colour, depth and velocity
2
+ // share the scene pass raster, which may sit below the display raster; resolve and history hold the
3
+ // display raster, so presented pixels come from a display-sized resolve, not an upscaled copy.
4
+ import { Matrix4, type OrthographicCamera, type PerspectiveCamera, Vector2 } from "three";
5
+ import { traa } from "three/addons/tsl/display/TRAANode.js";
6
+ import { uniform } from "three/tsl";
7
+ import type { Node, PassNode, Renderer, TextureNode } from "three/webgpu";
8
+ import { type ITemporalAANode, createTemporalAAFrame } from "./temporalAAFrame.js";
9
+ import { type PipelineContext, createTemporalAAHooks } from "./temporalAAHooks.js";
10
+ import { disposeTemporalAAInput } from "./temporalAAInput.js";
11
+ import type { ITemporalAAReport, TemporalResetReason } from "./temporalAAStage.js";
12
+ import { createTemporalCurrentProducer } from "./temporalCurrentProducer.js";
13
+ import { ownsCurrentInput } from "./temporalCurrentSelection.js";
14
+ export type { ITemporalAAReport, TemporalResetReason } from "./temporalAAStage.js";
15
+ import { createTemporalAAResolve } from "./temporalAAResolve.js";
16
+ import type { TemporalResolveNode } from "./temporalResolveDepth.js";
17
+
18
+ /** Reuse TRAANode's jitter, depth rejection and variance clipping. In a RenderChain `traa` factory
19
+ * pass context.velocityNode and the scene pass's depth, keep the scene pass single-sampled, reset
20
+ * history on teleports, and dispose with the owning stage. */
21
+ export function createTemporalAA(
22
+ colour: Node,
23
+ depthInput: TextureNode,
24
+ velocityInput: TextureNode,
25
+ camera: PerspectiveCamera | OrthographicCamera,
26
+ currentPass?: PassNode,
27
+ ) {
28
+ const currentProducer = ownsCurrentInput(colour, depthInput, velocityInput, camera, currentPass)
29
+ ? createTemporalCurrentProducer(currentPass)
30
+ : undefined;
31
+ const depth = currentProducer?.depth ?? depthInput;
32
+ const velocity = currentProducer?.motion ?? velocityInput;
33
+ const node = traa(colour, depth, velocity, camera);
34
+ // Three 0.185.1 exposes no reset API, so its pinned seams are isolated here instead.
35
+ const historyValid = uniform(1);
36
+ // The reconstruction gathers around the exact jittered sample Three applied this frame.
37
+ const jitterOffset = uniform(new Vector2());
38
+ const internals = node as unknown as ITemporalAANode;
39
+ internals._historyValidUniform = historyValid;
40
+ internals._reconstructionJitterOffset = jitterOffset;
41
+ internals._currentJitterUV = uniform(new Vector2());
42
+ internals._previousJitterUV = uniform(new Vector2());
43
+ // One instance of the depth-rejection equations, shared by the resolve, the counter and every
44
+ // recompile, so a measured fraction cannot describe a different decision than the one drawn.
45
+ const resolve = createTemporalAAResolve(
46
+ node as TemporalResolveNode,
47
+ jitterOffset,
48
+ currentProducer,
49
+ );
50
+ const frames = createTemporalAAFrame(
51
+ internals,
52
+ camera,
53
+ depth,
54
+ historyValid,
55
+ resolve.equations,
56
+ currentProducer?.publishDepth,
57
+ );
58
+ const hooks = createTemporalAAHooks(frames.jitterInput);
59
+ let ownedViewOffset: { width: number; height: number } | null = null;
60
+ const projection = new Matrix4().copy(camera.projectionMatrix);
61
+ const setViewOffset = internals.setViewOffset.bind(node);
62
+ const clearViewOffset = internals.clearViewOffset.bind(node);
63
+ let pending: TemporalResetReason | null = "initial";
64
+ currentProducer?.onFailure(() => {
65
+ pending = "scene-reset";
66
+ });
67
+ let disposed = false;
68
+ let report: ITemporalAAReport = {
69
+ frame: 0,
70
+ historyValid: false,
71
+ resetReason: "initial",
72
+ inputWidth: 0,
73
+ inputHeight: 0,
74
+ outputWidth: 0,
75
+ outputHeight: 0,
76
+ };
77
+ currentProducer?.onModeChange((renderer) => {
78
+ pending = "resize";
79
+ resolve.invalidate(renderer);
80
+ });
81
+ internals.clearViewOffset = () => {
82
+ try {
83
+ clearViewOffset();
84
+ } finally {
85
+ ownedViewOffset = null;
86
+ }
87
+ };
88
+ internals.setViewOffset = (width: number, height: number) => {
89
+ if (ownedViewOffset?.width === width && ownedViewOffset?.height === height) return;
90
+ const aspect = (camera as PerspectiveCamera).aspect;
91
+ if (ownedViewOffset !== null) camera.clearViewOffset();
92
+ camera.updateProjectionMatrix();
93
+ if (!camera.projectionMatrix.equals(projection)) pending ??= "projection-change";
94
+ projection.copy(camera.projectionMatrix);
95
+ setViewOffset(width, height);
96
+ if ((camera as PerspectiveCamera).aspect !== aspect) {
97
+ (camera as PerspectiveCamera).aspect = aspect;
98
+ camera.updateProjectionMatrix();
99
+ }
100
+ ownedViewOffset = { width, height };
101
+ };
102
+ const setup = node.setup.bind(node);
103
+ node.setup = (builder) => {
104
+ // NodeBuilder schedules child passes only when setup declares them; upstream finds them too late.
105
+ const properties = (
106
+ builder as unknown as { getNodeProperties(node: Node): Record<string, Node> }
107
+ ).getNodeProperties(node);
108
+ properties.temporalColour = node.beautyNode;
109
+ properties.temporalDepth = depth;
110
+ properties.temporalVelocity = velocity;
111
+ const pipeline = (builder.context as { renderPipeline?: { context: PipelineContext } })
112
+ .renderPipeline;
113
+ // The originals are read before upstream's setup writes the node's own pair over them.
114
+ if (pipeline !== undefined) hooks.captureBeforeSetup(pipeline.context);
115
+ const output = setup(builder);
116
+ resolve.configure(builder.renderer);
117
+ // Upstream's resolve is what this replaces, so the reset kernel runs by default.
118
+ if (pipeline !== undefined) hooks.installAfterSetup(pipeline.context, builder.renderer);
119
+ // VelocityNode keeps whichever projection source that input pass first compiles: prime ours.
120
+ if (ownedViewOffset === null) {
121
+ camera.updateProjectionMatrix();
122
+ internals._originalProjectionMatrix.copy(camera.projectionMatrix);
123
+ }
124
+ if (internals._velocityNode === null)
125
+ throw new Error("Temporal AA requires a velocity accessor.");
126
+ internals._velocityNode.setProjectionMatrix(internals._originalProjectionMatrix);
127
+ return output;
128
+ };
129
+ node.updateBefore = (frame) => {
130
+ if (disposed) throw new Error("Temporal AA is disposed.");
131
+ try {
132
+ if (frame.renderer === null) throw new Error("Temporal AA requires a renderer.");
133
+ const source = frames.measure(frame.renderer);
134
+ if (source === undefined)
135
+ throw new Error("Temporal AA requires a materialized colour input.");
136
+ const { x: width, y: height } = frames.input;
137
+ for (const texture of [depth.value, velocity.value]) {
138
+ if (texture.width !== width || texture.height !== height)
139
+ throw new Error(
140
+ "Temporal AA colour, depth and velocity must share the same raster size.",
141
+ );
142
+ }
143
+ // Either raster moving invalidates history: UVs and depth no longer name the same samples.
144
+ if (
145
+ report.frame > 0 &&
146
+ (width !== report.inputWidth ||
147
+ height !== report.inputHeight ||
148
+ frames.display.x !== report.outputWidth ||
149
+ frames.display.y !== report.outputHeight)
150
+ )
151
+ pending = "resize";
152
+ const reason = pending;
153
+ frames.draw(frame.renderer, reason !== null, report.frame + 1);
154
+ if (reason !== null && width === frames.display.x && height === frames.display.y) {
155
+ frame.renderer.copyTextureToTexture(source.texture, internals._resolveRenderTarget.texture);
156
+ frame.renderer.copyTextureToTexture(source.texture, internals._historyRenderTarget.texture);
157
+ }
158
+ report = {
159
+ frame: report.frame + 1,
160
+ historyValid: reason === null,
161
+ resetReason: reason,
162
+ inputWidth: width,
163
+ inputHeight: height,
164
+ outputWidth: frames.display.x,
165
+ outputHeight: frames.display.y,
166
+ };
167
+ pending = null;
168
+ return undefined;
169
+ } catch (error) {
170
+ pending = "scene-reset";
171
+ throw error;
172
+ }
173
+ };
174
+ return {
175
+ node,
176
+ jitterOffset,
177
+ // Omitted rather than undefined, so a report carrying none stays JSON-safe for a bridge.
178
+ report: (): ITemporalAAReport => {
179
+ const measured = frames.rejection();
180
+ return { ...report, ...(measured === undefined ? {} : { rejection: measured }) };
181
+ },
182
+ rejectionMeasurement: frames.drainRejection,
183
+ settledRejection: frames.settledRejection,
184
+ resetHistory: (reason: TemporalResetReason = "scene-reset"): void => {
185
+ if (disposed) throw new Error("Temporal AA is disposed.");
186
+ pending = reason;
187
+ },
188
+ dispose: (): void => {
189
+ if (disposed) return;
190
+ disposed = true;
191
+ hooks.dispose();
192
+ currentProducer?.dispose();
193
+ frames.dispose();
194
+ disposeTemporalAAInput(internals, colour, ownedViewOffset !== null, () => node.dispose());
195
+ },
196
+ };
197
+ }
@@ -0,0 +1,179 @@
1
+ // Generated user source: the per-frame GPU work behind `createTemporalAA` — display-sized history and
2
+ // resolve targets, an input-sized depth history, the jitter lattice, and the measured rejection count.
3
+ // Upstream's `_quadMesh` is module private, so the quad is ours too.
4
+ import { type OrthographicCamera, type PerspectiveCamera, Vector2 } from "three";
5
+ import {
6
+ DepthTexture,
7
+ QuadMesh,
8
+ type RenderTarget,
9
+ type Renderer,
10
+ RendererUtils,
11
+ type TextureNode,
12
+ } from "three/webgpu";
13
+ import { createTemporalAAInput } from "./temporalAAInput.js";
14
+ import {
15
+ type ITemporalRejectionCounter,
16
+ type ITemporalRejectionMeasurement,
17
+ createTemporalRejectionCounter,
18
+ } from "./temporalRejectionCounter.js";
19
+
20
+ export type {
21
+ ITemporalAANode,
22
+ TemporalDepthRejection,
23
+ } from "./temporalResolveDepth.js";
24
+ import {
25
+ type ITemporalAANode,
26
+ type TemporalDepthRejection,
27
+ guardTemporalAASeams,
28
+ } from "./temporalResolveDepth.js";
29
+
30
+ /** Owns everything that survives between frames: the quad, the rasters, the depth history and the
31
+ * saved renderer state. */
32
+ export function createTemporalAAFrame(
33
+ internals: ITemporalAANode,
34
+ camera: PerspectiveCamera | OrthographicCamera,
35
+ depth: TextureNode,
36
+ historyValid: { value: number },
37
+ rejection: () => TemporalDepthRejection | undefined,
38
+ publishCurrentDepth?: (renderer: Renderer) => void,
39
+ ) {
40
+ const quadMesh = new QuadMesh();
41
+ quadMesh.name = "Temporal AA";
42
+ const display = new Vector2();
43
+ let previousDepth: DepthTexture | null = null;
44
+ let depthReady = false;
45
+ let disposed = false;
46
+ let frame = 0;
47
+ let counter: ITemporalRejectionCounter | undefined;
48
+ let counterEquations: TemporalDepthRejection | undefined;
49
+ let rendererState: Parameters<typeof RendererUtils.resetRendererState>[1] | undefined;
50
+
51
+ const { input, measureInput, jitterInput } = createTemporalAAInput(internals, () => disposed);
52
+
53
+ /** Publish and update history. Reset weights current only: reseeding cannot prevent motion
54
+ * from sampling the seed at shifted history UVs. */
55
+ function draw(renderer: Renderer, reset: boolean, currentFrame: number): void {
56
+ frame = currentFrame;
57
+ if (measure(renderer) === undefined)
58
+ throw new Error("Temporal AA requires a materialized colour input.");
59
+ guardTemporalAASeams(internals);
60
+ if (display.x < input.x || display.y < input.y)
61
+ throw new Error("Temporal AA cannot resolve to a display raster below its input raster.");
62
+ // Snapshot the input's actual camera before late first-compile synchronization installs jitter
63
+ // for a subsequent draw. The saved depth and its inverse projection must describe one raster.
64
+ if (internals._currentJitterUV !== undefined && internals._previousJitterUV !== undefined) {
65
+ internals._previousJitterUV.value.copy(internals._currentJitterUV.value);
66
+ const view = camera.view;
67
+ internals._currentJitterUV.value.set(
68
+ view?.enabled === true ? view.offsetX / input.x : 0,
69
+ view?.enabled === true ? view.offsetY / input.y : 0,
70
+ );
71
+ }
72
+ const reconstructionView = camera.view;
73
+ internals._reconstructionJitterOffset?.value.set(
74
+ reconstructionView?.enabled === true ? reconstructionView.offsetX : 0,
75
+ reconstructionView?.enabled === true ? reconstructionView.offsetY : 0,
76
+ );
77
+ // Store previous frame matrices before updating current ones.
78
+ internals._previousCameraWorldMatrix.value.copy(internals._cameraWorldMatrix.value);
79
+ internals._previousCameraProjectionMatrixInverse.value.copy(
80
+ internals._cameraProjectionMatrixInverse.value,
81
+ );
82
+ internals._cameraNearFar.value.set(camera.near, camera.far);
83
+ internals._cameraWorldMatrix.value.copy(camera.matrixWorld);
84
+ internals._cameraWorldMatrixInverse.value.copy(camera.matrixWorldInverse);
85
+ internals._cameraProjectionMatrixInverse.value.copy(camera.projectionMatrixInverse);
86
+ if (internals._needsPostProcessingSync === true) {
87
+ internals.setViewOffset(input.x, input.y);
88
+ internals._needsPostProcessingSync = false;
89
+ }
90
+ historyValid.value = reset ? 0 : 1;
91
+ // Depth history stays input sized, independently of display history. Seed on either-axis resize.
92
+ if (previousDepth?.image.width !== input.x || previousDepth?.image.height !== input.y) {
93
+ previousDepth?.dispose();
94
+ previousDepth = new DepthTexture(input.x, input.y, depth.value.type);
95
+ depthReady = false;
96
+ }
97
+ const seeded = depthReady === false;
98
+ const depthHistory = previousDepth;
99
+ let state: typeof rendererState;
100
+ try {
101
+ rendererState ??= RendererUtils.saveRendererState(renderer);
102
+ state = RendererUtils.resetRendererState(renderer, rendererState);
103
+ internals._previousDepthNode.value = depthHistory;
104
+ if (seeded) {
105
+ renderer.copyTextureToTexture(depth.value, depthHistory);
106
+ depthReady = true;
107
+ }
108
+ // Resolve and history hold the display raster whatever the input raster is.
109
+ const restarted =
110
+ internals._historyRenderTarget.width !== display.x ||
111
+ internals._historyRenderTarget.height !== display.y;
112
+ internals.setSize(display.x, display.y);
113
+ if (restarted) {
114
+ // A resize disposes the targets, so they need fresh GPU storage before the draw.
115
+ renderer.initRenderTarget(internals._historyRenderTarget);
116
+ renderer.initRenderTarget(internals._resolveRenderTarget);
117
+ }
118
+ if (
119
+ internals._historyRenderTarget.width !== display.x ||
120
+ internals._historyRenderTarget.height !== display.y
121
+ )
122
+ throw new Error("Temporal AA history and resolve must share the display raster.");
123
+ renderer.setRenderTarget(internals._resolveRenderTarget);
124
+ quadMesh.material = internals._resolveMaterial;
125
+ quadMesh.render(renderer);
126
+ // Between the resolve and the depth copy, so it reads the depth and matrices just drawn with.
127
+ const equations = rejection();
128
+ if (equations !== undefined) {
129
+ if (counterEquations !== equations) {
130
+ counter?.dispose();
131
+ counter = undefined;
132
+ counterEquations = equations;
133
+ }
134
+ counter ??= createTemporalRejectionCounter(equations);
135
+ counter.sample(renderer, frame, display.x, display.y);
136
+ }
137
+ publishCurrentDepth?.(renderer);
138
+ // History is the resolve this frame produced, at the same size, so the copy never crosses rasters.
139
+ if (seeded === false) renderer.copyTextureToTexture(depth.value, depthHistory);
140
+ renderer.copyTextureToTexture(
141
+ internals._resolveRenderTarget.texture,
142
+ internals._historyRenderTarget.texture,
143
+ );
144
+ } finally {
145
+ if (state !== undefined) RendererUtils.restoreRendererState(renderer, state);
146
+ }
147
+ }
148
+
149
+ /** Both rasters, from the real targets: the scene pass one, then the drawing buffer. */
150
+ function measure(renderer: Renderer): RenderTarget | undefined {
151
+ const target = measureInput();
152
+ if (target === undefined) return undefined;
153
+ renderer.getDrawingBufferSize(display);
154
+ return target;
155
+ }
156
+
157
+ return {
158
+ input,
159
+ display,
160
+ measure,
161
+ jitterInput,
162
+ draw,
163
+ // Forward the counter's measured report, drain and settle contracts.
164
+ rejection: (): ITemporalRejectionMeasurement | undefined => counter?.report(frame),
165
+ drainRejection: (): { frame: number; rejectionFraction: number } | undefined => {
166
+ const drained = counter?.drain();
167
+ return drained && { frame: drained.frame, rejectionFraction: drained.fraction };
168
+ },
169
+ settledRejection: (): Promise<void> => counter?.settled() ?? Promise.resolve(),
170
+ dispose: (): void => {
171
+ disposed = true;
172
+ counter?.dispose();
173
+ counter = undefined;
174
+ previousDepth?.dispose();
175
+ previousDepth = null;
176
+ depthReady = false;
177
+ },
178
+ };
179
+ }
@@ -0,0 +1,101 @@
1
+ // Generated user source: who owns the two pipeline callbacks a temporal AA compile borrows. Upstream
2
+ // TRAANode's setup writes its own pair bound to that node, so the originals are the slots as they
3
+ // stand before the first setup — a recompile must never capture them again as the originals.
4
+ import type { Matrix4 } from "three";
5
+ import type { NodeMaterial, RenderTarget, Renderer, TextureNode } from "three/webgpu";
6
+ import type { ITemporalResolvePinned } from "./temporalResolveDepth.js";
7
+
8
+ export interface ITemporalAANode extends ITemporalResolvePinned {
9
+ _resolveMaterial: NodeMaterial;
10
+ _needsPostProcessingSync: boolean;
11
+ _historyValidUniform: { value: number };
12
+ _originalProjectionMatrix: Matrix4;
13
+ _velocityNode: {
14
+ projectionMatrix: Matrix4 | null;
15
+ setProjectionMatrix(matrix: Matrix4 | null): void;
16
+ } | null;
17
+ beautyNode: TextureNode & {
18
+ isRTTNode?: boolean;
19
+ autoResize?: boolean;
20
+ getResolutionScale?: () => number;
21
+ renderTarget?: RenderTarget;
22
+ passNode?: { renderTarget: RenderTarget; getResolutionScale?: () => number };
23
+ };
24
+ setSize(width: number, height: number): void;
25
+ setViewOffset(width: number, height: number): void;
26
+ clearViewOffset(): void;
27
+ }
28
+
29
+ /** Fail closed rather than half-drive a pinned seam whose shape this version does not have: a
30
+ * missing uniform reads as `undefined` in a shader and comes back as a black frame. */
31
+ export function guardTemporalAASeams(node: ITemporalAANode): void {
32
+ if (
33
+ typeof node.setSize !== "function" ||
34
+ typeof node.setViewOffset !== "function" ||
35
+ typeof node.clearViewOffset !== "function" ||
36
+ node._resolveMaterial === undefined ||
37
+ node._previousDepthNode === undefined ||
38
+ node._cameraNearFar?.value === undefined ||
39
+ node._cameraWorldMatrix?.value === undefined ||
40
+ !Number.isFinite(node._resolveRenderTarget?.width) ||
41
+ !Number.isFinite(node._historyRenderTarget?.height)
42
+ )
43
+ throw new Error("Temporal AA requires the pinned TRAANode resolve seams of Three 0.185.1.");
44
+ }
45
+
46
+ export type PipelineContext = {
47
+ onBeforeRenderPipeline?: () => void;
48
+ onAfterRenderPipeline?: () => void;
49
+ };
50
+
51
+ export function createTemporalAAHooks(jitter: (renderer: Renderer) => void) {
52
+ let context: PipelineContext | undefined;
53
+ let previousBefore: (() => void) | undefined;
54
+ let previousAfter: (() => void) | undefined;
55
+ let ownedBefore: (() => void) | undefined;
56
+ let ownedAfter: (() => void) | undefined;
57
+
58
+ /**
59
+ * Each borrowed slot goes back to the original its own context held, and only while it is still
60
+ * this node's: a later owner keeps the slot, and upstream's pair belongs to the node.
61
+ */
62
+ function restore(): void {
63
+ if (context === undefined) return;
64
+ if (context.onBeforeRenderPipeline === ownedBefore)
65
+ context.onBeforeRenderPipeline = previousBefore;
66
+ if (context.onAfterRenderPipeline === ownedAfter) context.onAfterRenderPipeline = previousAfter;
67
+ }
68
+
69
+ return {
70
+ /**
71
+ * The originals, read once per context and before upstream's setup has written the node's own
72
+ * pair. A recompile into a fresh context object hands this one back, so the context three stops
73
+ * calling keeps nothing it borrowed.
74
+ */
75
+ captureBeforeSetup(next: PipelineContext): void {
76
+ if (context === next) return;
77
+ restore();
78
+ context = next;
79
+ previousBefore = next.onBeforeRenderPipeline;
80
+ previousAfter = next.onAfterRenderPipeline;
81
+ },
82
+ /**
83
+ * The node's own after-callback is ours to give back, since this compile is what installed it.
84
+ * The jitter callback keeps its identity across recompiles, so a second setup finds the slot
85
+ * already claimed instead of recording this provider's own callback as the previous owner.
86
+ */
87
+ installAfterSetup(next: PipelineContext, renderer: Renderer): void {
88
+ ownedBefore ??= () => jitter(renderer);
89
+ ownedAfter = next.onAfterRenderPipeline;
90
+ next.onBeforeRenderPipeline = ownedBefore;
91
+ },
92
+ dispose(): void {
93
+ restore();
94
+ context = undefined;
95
+ previousBefore = undefined;
96
+ previousAfter = undefined;
97
+ ownedBefore = undefined;
98
+ ownedAfter = undefined;
99
+ },
100
+ };
101
+ }
@@ -0,0 +1,56 @@
1
+ // The actual input raster and its pre-draw jitter; independent of display history storage.
2
+ import { Vector2 } from "three";
3
+ import type { Node, RenderTarget, Renderer } from "three/webgpu";
4
+ import type { ITemporalAANode } from "./temporalAAFrame.js";
5
+ export function createTemporalAAInput(internals: ITemporalAANode, isDisposed: () => boolean) {
6
+ const input = new Vector2();
7
+ /** The scene pass raster, from its real GPU target and never from a canvas label. */
8
+ function measureInput(): RenderTarget | undefined {
9
+ const target = internals.beautyNode.isRTTNode
10
+ ? internals.beautyNode.renderTarget
11
+ : internals.beautyNode.passNode?.renderTarget;
12
+ if (target === undefined) return undefined;
13
+ if (!Number.isFinite(target.width) || target.width < 1) return undefined;
14
+ if (!Number.isFinite(target.height) || target.height < 1) return undefined;
15
+ input.set(target.width, target.height);
16
+ return target;
17
+ }
18
+
19
+ /** Establish jitter before the pass sizes and draws its raster in updateBefore. Its raster is
20
+ * the drawing buffer scaled by the pass's own resolution scale, rather than the canvas alone. */
21
+ function jitterInput(renderer: Renderer): void {
22
+ if (isDisposed()) return;
23
+ const colour = internals.beautyNode;
24
+ // A fixed RTT owns its raster; an automatic RTT and a pass size themselves from the buffer.
25
+ if (colour.isRTTNode && colour.autoResize === false) {
26
+ if (measureInput() !== undefined) internals.setViewOffset(input.x, input.y);
27
+ return;
28
+ }
29
+ const scale = (colour.isRTTNode ? colour : colour.passNode)?.getResolutionScale?.() ?? 1;
30
+ renderer.getDrawingBufferSize(input);
31
+ if (scale !== 1) input.set(Math.floor(input.x * scale), Math.floor(input.y * scale));
32
+ internals.setViewOffset(input.x, input.y);
33
+ }
34
+
35
+ return { input, measureInput, jitterInput };
36
+ }
37
+
38
+ /** Release the upstream input conversion and restore only the projection this helper owns. */
39
+ export function disposeTemporalAAInput(
40
+ internals: ITemporalAANode,
41
+ colour: Node,
42
+ ownsView: boolean,
43
+ dispose: () => void,
44
+ ) {
45
+ if (internals._velocityNode?.projectionMatrix === internals._originalProjectionMatrix) {
46
+ if (ownsView) internals.clearViewOffset();
47
+ else internals._velocityNode.setProjectionMatrix(null);
48
+ }
49
+ dispose();
50
+ if (internals.beautyNode !== colour && internals.beautyNode.isRTTNode) {
51
+ internals.beautyNode.renderTarget?.dispose();
52
+ (
53
+ internals.beautyNode as unknown as { _quadMesh: { material: { dispose(): void } } }
54
+ )._quadMesh.material.dispose();
55
+ }
56
+ }
@@ -0,0 +1,65 @@
1
+ // One equation owner shared by resolve and rejection counter, including explicit raw-mode rebuilds.
2
+ import { Fn, int, texture } from "three/tsl";
3
+ import type { Node, Renderer } from "three/webgpu";
4
+ import type { ITemporalAANode } from "./temporalAAFrame.js";
5
+ import {
6
+ type TemporalCurrentFootprint,
7
+ createTemporalCurrentFootprint,
8
+ } from "./temporalCurrentFootprint.js";
9
+ import type { TemporalCurrentProducer } from "./temporalCurrentProducer.js";
10
+ import { createExperimentalTemporalResolve } from "./temporalResolve.js";
11
+ import {
12
+ type TemporalDepthRejection,
13
+ type TemporalResolveNode,
14
+ createTemporalDepthRejection,
15
+ } from "./temporalResolveDepth.js";
16
+
17
+ export function createTemporalAAResolve(
18
+ node: TemporalResolveNode,
19
+ jitterOffset: Node<"vec2">,
20
+ currentProducer?: TemporalCurrentProducer,
21
+ ) {
22
+ const internals = node as unknown as ITemporalAANode;
23
+ let rejection: TemporalDepthRejection | undefined;
24
+ let currentFootprint: TemporalCurrentFootprint | undefined;
25
+ function configure(renderer: Renderer): void {
26
+ if (rejection === undefined) {
27
+ const legacy = createTemporalDepthRejection(node, renderer);
28
+ const current = currentProducer?.active()
29
+ ? createTemporalCurrentFootprint(currentProducer.inputs, node, jitterOffset)
30
+ : undefined;
31
+ currentFootprint = current;
32
+ rejection =
33
+ current === undefined
34
+ ? legacy
35
+ : {
36
+ ...legacy,
37
+ historyValidity: Fn(([pixelUV]: [Node<"vec2">]) =>
38
+ current.historyValidity(
39
+ pixelUV,
40
+ texture(internals._historyRenderTarget.texture).size(int(0)) as Node<"uvec2">,
41
+ legacy.historyValidity(pixelUV),
42
+ ),
43
+ ),
44
+ };
45
+ }
46
+ internals._resolveMaterial.colorNode = createExperimentalTemporalResolve(
47
+ node,
48
+ renderer,
49
+ jitterOffset,
50
+ "linear",
51
+ "ordinary",
52
+ rejection,
53
+ currentFootprint,
54
+ );
55
+ internals._resolveMaterial.needsUpdate = true;
56
+ }
57
+ return {
58
+ equations: () => rejection,
59
+ configure,
60
+ invalidate: (renderer: Renderer) => {
61
+ rejection = undefined;
62
+ configure(renderer);
63
+ },
64
+ };
65
+ }