create-threenative 0.2.8 → 0.2.9

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 +11 -9
  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 +9 -8
  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 +11 -9
  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 +11 -9
  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 +11 -9
  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 +21 -1
  166. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  167. package/templates/racing/src/scenes/Race.ts +91 -3
  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 +12 -9
  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 +10 -8
  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 +11 -9
  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 +11 -9
  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 +11 -9
  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 +11 -9
  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 +11 -9
  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 +1 -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 +84 -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 +11 -9
  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,89 @@
1
+ // Authenticate the ordinary raster/material/motion subset before borrowing raw sample sites.
2
+ import { Scene, Vector2 } from "three";
3
+ import { output } from "three/tsl";
4
+ import type { Node, PassNode, Renderer, TextureNode } from "three/webgpu";
5
+ import { currentVisibilityEligible } from "./temporalCurrentVisibility.js";
6
+ export interface IRawPass extends PassNode {
7
+ readonly options: { samples?: number };
8
+ getRawTextureNode(name?: string): TextureNode;
9
+ }
10
+ /** A composed colour, other camera or foreign depth/motion stays on the established provider. */
11
+ export function ownsCurrentInput(
12
+ colour: Node,
13
+ depth: TextureNode,
14
+ motion: TextureNode,
15
+ camera: PassNode["camera"],
16
+ source?: PassNode,
17
+ ): source is PassNode {
18
+ return (
19
+ source !== undefined &&
20
+ source.scene instanceof Scene &&
21
+ Reflect.get(source, "scope") === "color" &&
22
+ source.renderTarget.samples <= 1 &&
23
+ ((source as IRawPass).options.samples ?? 0) <= 1 &&
24
+ source.overrideMaterial === null &&
25
+ source.camera === camera &&
26
+ colour === source.getTextureNode() &&
27
+ depth === source.getTextureNode("depth") &&
28
+ motion === source.getTextureNode("velocity")
29
+ );
30
+ }
31
+ // Preserve the original fixture's constant-zero MRT control. Arbitrary graphs/uniform producers
32
+ // have no authenticated correspondence to the shared motion accessor and use the ordinary lane.
33
+ function knownMotion(node: Node | undefined, shared: Node): node is Node<"vec2"> {
34
+ if (node === shared) return true;
35
+ const constant =
36
+ node !== undefined &&
37
+ Reflect.get(node, "isVarNode") === true &&
38
+ Reflect.get(node, "intent") === true &&
39
+ (Reflect.get(node, "_beforeNodes") === null || Reflect.get(node, "_beforeNodes").length === 0)
40
+ ? Reflect.get(node, "node")
41
+ : node;
42
+ return (
43
+ constant !== undefined &&
44
+ Reflect.get(constant, "isConstNode") === true &&
45
+ Reflect.get(constant, "nodeType") === "vec2" &&
46
+ Reflect.get(constant, "value") instanceof Vector2 &&
47
+ Reflect.get(constant, "value").equals(new Vector2())
48
+ );
49
+ }
50
+
51
+ export function currentPassEligible(
52
+ beauty: PassNode,
53
+ renderer: Renderer,
54
+ buffer: Vector2,
55
+ width: number,
56
+ height: number,
57
+ sharedMotion: Node,
58
+ ) {
59
+ const sourceMotion = beauty.getMRT()?.get("velocity");
60
+ const sourceMRT = beauty.getMRT();
61
+ const ordinaryMRT =
62
+ sourceMRT?.get("output") === output &&
63
+ Object.keys(Reflect.get(sourceMRT, "outputNodes")).every(
64
+ (name) => name === "output" || name === "velocity",
65
+ ) &&
66
+ beauty.renderTarget.textures.length === 2;
67
+ const flow = (
68
+ renderer.contextNode as unknown as { getFlowContextData(): Record<string, unknown> }
69
+ ).getFlowContextData();
70
+ return (
71
+ ordinaryMRT &&
72
+ Object.keys(flow).length === 0 &&
73
+ !Reflect.get(renderer.getOutputRenderTarget() ?? {}, "isXRRenderTarget") &&
74
+ knownMotion(sourceMotion, sharedMotion) &&
75
+ Reflect.get(renderer.backend, "isWebGPUBackend") === true &&
76
+ !renderer.reversedDepthBuffer &&
77
+ !renderer.logarithmicDepthBuffer &&
78
+ renderer.getRenderObjectFunction() === null &&
79
+ Reflect.get(renderer, "_opaqueSort") === null &&
80
+ Reflect.get(beauty, "_viewport") === null &&
81
+ Reflect.get(beauty, "_scissor") === null &&
82
+ width > 2 &&
83
+ height > 2 &&
84
+ width <= buffer.x &&
85
+ height <= buffer.y &&
86
+ (width < buffer.x || height < buffer.y) &&
87
+ currentVisibilityEligible(beauty.scene as Scene)
88
+ );
89
+ }
@@ -0,0 +1,170 @@
1
+ // Generated appearance policy: replay original standard alpha/deformation/depth, without lighting.
2
+ // Private passes retain the original render-list order and use the existing scheduled motion node.
3
+ import {
4
+ Color,
5
+ Material,
6
+ Matrix4,
7
+ Mesh,
8
+ MeshBasicMaterial,
9
+ MeshStandardMaterial,
10
+ NoBlending,
11
+ NormalBlending,
12
+ Object3D,
13
+ type Scene,
14
+ } from "three";
15
+ import { float, vec3, vec4 } from "three/tsl";
16
+ import type { Node, NodeMaterial, Renderer } from "three/webgpu";
17
+
18
+ interface IMaterialLibrary {
19
+ fromMaterial(material: Material): NodeMaterial;
20
+ }
21
+
22
+ /** A clone of the actual renderer conversion keeps its vertex and alpha implementation. Replacing
23
+ * fragmentNode would bypass alpha discard. Replacing lighting/output after diffuse setup retains it,
24
+ * and the explicit output avoids NodeMaterial's nonnegative RGB clamp on signed motion. */
25
+ export function currentVisibilityMaterial(
26
+ renderer: Renderer,
27
+ source: Material,
28
+ motion: Node<"vec2">,
29
+ ): NodeMaterial {
30
+ const converted = (renderer.library as unknown as IMaterialLibrary).fromMaterial(source);
31
+ const material = converted.clone();
32
+ // Pinned NodeMaterial.copy skips inherited alphaTest's backing field. Material.copy restores
33
+ // all raster/alpha state; the converted clone already retained its material-specific maps.
34
+ Material.prototype.copy.call(material, source);
35
+ material.name = "Temporal current visibility";
36
+ material.setupAmbientOcclusion = () => float(1);
37
+ material.setupVariants = () => {};
38
+ material.setupLighting = () => vec3(0);
39
+ material.outputNode = vec4(motion, 0, 1);
40
+ material.fog = false;
41
+ return material;
42
+ }
43
+
44
+ /** Unknown/custom inputs use the ordinary provider. The shared VelocityTracker must already have
45
+ * scheduled the previous frame once; no pass here creates, advances or commits another tracker. */
46
+ export function currentVisibilityEligible(scene: Scene): boolean {
47
+ // Background sites have clear depth1/motion0, not an independent coverage alpha mask.
48
+ let eligible =
49
+ (scene.background === null || scene.background instanceof Color) &&
50
+ scene.overrideMaterial === null &&
51
+ !authoredNode(scene) &&
52
+ scene.onBeforeRender === Object3D.prototype.onBeforeRender &&
53
+ scene.onAfterRender === Object3D.prototype.onAfterRender;
54
+ scene.traverseVisible((object) => {
55
+ if (!eligible) return;
56
+ if (Reflect.get(object, "isBundleGroup")) {
57
+ eligible = false;
58
+ return;
59
+ }
60
+ if (
61
+ Reflect.get(object, "isClippingGroup") &&
62
+ Reflect.get(object, "enabled") &&
63
+ Reflect.get(object, "clippingPlanes")?.length
64
+ ) {
65
+ eligible = false;
66
+ return;
67
+ }
68
+ if (
69
+ object.onBeforeRender !== Object3D.prototype.onBeforeRender ||
70
+ object.onAfterRender !== Object3D.prototype.onAfterRender ||
71
+ object.onBeforeShadow !== Object3D.prototype.onBeforeShadow ||
72
+ object.onAfterShadow !== Object3D.prototype.onAfterShadow
73
+ ) {
74
+ eligible = false;
75
+ return;
76
+ }
77
+ if (
78
+ Reflect.get(object, "isLine") ||
79
+ Reflect.get(object, "isPoints") ||
80
+ Reflect.get(object, "isSprite")
81
+ ) {
82
+ eligible = false;
83
+ return;
84
+ }
85
+ if (authoredNode(object) || authoredNode(Reflect.get(object, "shadow"))) {
86
+ eligible = false;
87
+ return;
88
+ }
89
+ if (!(object instanceof Mesh)) return;
90
+ if (
91
+ Object.values(object.geometry.morphAttributes).some(
92
+ (attributes) => (attributes as readonly unknown[]).length > 0,
93
+ )
94
+ ) {
95
+ eligible = false;
96
+ return;
97
+ }
98
+ if (
99
+ !(
100
+ Reflect.get(object, Symbol.for("threenative.velocity.previousWorldMatrix")) instanceof
101
+ Matrix4
102
+ )
103
+ ) {
104
+ eligible = false;
105
+ return;
106
+ }
107
+ if (
108
+ Reflect.get(object, "isBatchedMesh") ||
109
+ (Reflect.get(object, "isInstancedMesh") &&
110
+ Reflect.get(object, Symbol.for("threenative.velocity.previousInstanceMatrices")) ===
111
+ undefined) ||
112
+ (Reflect.get(object, "isSkinnedMesh") &&
113
+ Reflect.get(object, Symbol.for("threenative.velocity.previousBoneMatrices")) === undefined)
114
+ ) {
115
+ eligible = false;
116
+ return;
117
+ }
118
+ for (const material of Array.isArray(object.material) ? object.material : [object.material]) {
119
+ const defines = Reflect.get(material, "defines") ?? {};
120
+ const ordinaryDefines = Object.keys(defines).every(
121
+ (name) =>
122
+ name === "STANDARD" &&
123
+ defines[name] === "" &&
124
+ Reflect.get(material, "isMeshStandardMaterial") === true,
125
+ );
126
+ if (
127
+ (material.constructor !== MeshStandardMaterial &&
128
+ material.constructor !== MeshBasicMaterial) ||
129
+ Object.keys(material).some(
130
+ (name) =>
131
+ (name.endsWith("Node") && Reflect.get(material, name) != null) ||
132
+ (name.startsWith("setup") && typeof Reflect.get(material, name) === "function"),
133
+ )
134
+ )
135
+ eligible = false;
136
+ if (
137
+ (Reflect.get(material, "isMeshStandardMaterial") !== true &&
138
+ Reflect.get(material, "isMeshBasicMaterial") !== true) ||
139
+ Reflect.get(material, "isNodeMaterial") ||
140
+ Reflect.get(material, "isMeshPhysicalMaterial") ||
141
+ Reflect.get(material, "displacementMap") ||
142
+ material.transparent ||
143
+ material.alphaHash ||
144
+ material.alphaToCoverage ||
145
+ !material.depthTest ||
146
+ !material.depthWrite ||
147
+ !material.colorWrite ||
148
+ material.stencilWrite ||
149
+ (material.blending !== NormalBlending && material.blending !== NoBlending) ||
150
+ material.onBeforeCompile !== Material.prototype.onBeforeCompile ||
151
+ material.onBeforeRender !== Material.prototype.onBeforeRender ||
152
+ material.customProgramCacheKey !== Material.prototype.customProgramCacheKey ||
153
+ material.clippingPlanes?.length ||
154
+ Reflect.get(material, "contextNode") ||
155
+ !ordinaryDefines
156
+ )
157
+ eligible = false;
158
+ }
159
+ });
160
+ return eligible;
161
+ }
162
+
163
+ function authoredNode(owner: unknown): boolean {
164
+ if (typeof owner !== "object" || owner === null) return false;
165
+ return Reflect.ownKeys(owner).some((field) => {
166
+ if (typeof field !== "string" || !field.endsWith("Node")) return false;
167
+ const value = Reflect.get(owner, field);
168
+ return value !== undefined && value !== null;
169
+ });
170
+ }
@@ -0,0 +1,34 @@
1
+ // Generated appearance source: matched input-sample coordinates and conservative depth support.
2
+ import { ivec2, max, vec2 } from "three/tsl";
3
+ import type { Node } from "three/webgpu";
4
+
5
+ /** Follow the same integer texel that textureLoad read into the previous jittered depth grid.
6
+ * Velocity excludes jitter; reconstructed colour history stays on its unjittered display grid. */
7
+ export function temporalDepthHistoryUV(
8
+ positionTexel: Node<"vec2">,
9
+ inputSize: Node<"vec2"> | Node<"uvec2">,
10
+ offsetUV: Node<"vec2">,
11
+ currentJitterUV: Node<"vec2">,
12
+ previousJitterUV: Node<"vec2">,
13
+ ) {
14
+ return vec2(ivec2(positionTexel))
15
+ .add(0.5)
16
+ .div(inputSize)
17
+ .add(currentJitterUV)
18
+ .sub(offsetUV)
19
+ .sub(previousJitterUV);
20
+ }
21
+
22
+ /** Both points have rejection authority. Matching a surviving neighbor cannot legalize removed
23
+ * colour at the centre; a clear centre cannot legalize an occluded selected surface either. */
24
+ export function temporalDepthHasDisocclusion(
25
+ currentDepth: Node<"float">,
26
+ previousCentreDepth: Node<"float">,
27
+ previousPointDepth: Node<"float">,
28
+ threshold: Node<"float"> | number,
29
+ ) {
30
+ return max(
31
+ currentDepth.sub(previousCentreDepth),
32
+ currentDepth.sub(previousPointDepth),
33
+ ).greaterThan(threshold);
34
+ }
@@ -0,0 +1,179 @@
1
+ // Generated user source: the measured temporal-history rejection counter. It calls the resolve's own
2
+ // history-validity node once per display pixel and adds each answer into two words, so the fraction
3
+ // a report states cannot drift from the decision the resolve drew with. One compute reset runs first,
4
+ // in its own single-thread dispatch, so no group can read a partial sum; the copy back is asynchronous
5
+ // and one at a time, so the frame never blocks on it.
6
+ import { type BufferAttribute, Vector2 } from "three";
7
+ import {
8
+ Fn,
9
+ If,
10
+ atomicAdd,
11
+ atomicStore,
12
+ float,
13
+ instanceIndex,
14
+ instancedArray,
15
+ uint,
16
+ uniform,
17
+ vec2,
18
+ } from "three/tsl";
19
+ import type { Node, Renderer } from "three/webgpu";
20
+ import type { TemporalDepthRejection } from "./temporalResolveDepth.js";
21
+
22
+ /**
23
+ * One completed measurement: the frame that counted, its rejected share, the display pixels the
24
+ * kernel actually visited, and how old the measurement now is.
25
+ */
26
+ export interface ITemporalRejectionMeasurement {
27
+ readonly frame: number;
28
+ readonly fraction: number;
29
+ /** The GPU's own visited count, so a fraction can be checked against the raster it came from. */
30
+ readonly visited: number;
31
+ readonly staleFrames: number;
32
+ }
33
+
34
+ export interface ITemporalRejectionCounter {
35
+ /** Dispatch reset and count for `frame`, then request one readback if none is in flight. */
36
+ sample(renderer: Renderer, frame: number, width: number, height: number): void;
37
+ /** The latest completed measurement, or `undefined` while none has landed. Never consumed. */
38
+ report(frame: number): ITemporalRejectionMeasurement | undefined;
39
+ /** The latest completed measurement, handed out once so a chain sees each measurement once. */
40
+ drain(): { frame: number; fraction: number } | undefined;
41
+ /** Resolves once no copy is in flight, and rejects with the reason the newest one is absent. */
42
+ settled(): Promise<void>;
43
+ dispose(): void;
44
+ }
45
+
46
+ export function createTemporalRejectionCounter(
47
+ rejection: TemporalDepthRejection,
48
+ ): ITemporalRejectionCounter {
49
+ // Word 0 counts rejected display pixels, word 1 counts the pixels visited. A word an atomic
50
+ // touches is only writable by another atomic, so the reset stores rather than assigns.
51
+ const counter = instancedArray(2, "uint").toAtomic();
52
+ const size = uniform(new Vector2(1, 1));
53
+ const reset = Fn(() => {
54
+ atomicStore(counter.element(0), uint(0));
55
+ atomicStore(counter.element(1), uint(0));
56
+ })().compute(1);
57
+ const count = Fn(() => {
58
+ const pixel = instanceIndex.toVar();
59
+ const column = float(pixel.mod(uint(size.x)));
60
+ const row = float(pixel.div(uint(size.x)));
61
+ const hasValidHistory = rejection
62
+ .historyValidity(vec2(column.add(0.5), row.add(0.5)).div(size))
63
+ .get("hasValidHistory") as Node<"float">;
64
+ If(hasValidHistory.oneMinus().greaterThan(0.5), () => {
65
+ atomicAdd(counter.element(0), uint(1));
66
+ });
67
+ atomicAdd(counter.element(1), uint(1));
68
+ })();
69
+ let dispatched: ReturnType<typeof count.compute> | undefined;
70
+ let pixels = 0;
71
+ let inFlight: Promise<void> | undefined;
72
+ let latest: { frame: number; fraction: number; visited: number } | undefined;
73
+ let unpublished = false;
74
+ let failure: string | undefined;
75
+ let disposed = false;
76
+ const owners = new Set<Renderer & { deleteAttribute(attribute: BufferAttribute): unknown }>();
77
+ function releaseStorage() {
78
+ for (const renderer of owners) renderer.deleteAttribute(counter.value);
79
+ owners.clear();
80
+ }
81
+
82
+ /** The newest measurement is withdrawn and the reason kept, so nothing stale stays claimable. */
83
+ function absent(reason: string): void {
84
+ latest = undefined;
85
+ unpublished = false;
86
+ failure = reason;
87
+ }
88
+
89
+ return {
90
+ sample(renderer: Renderer, frame: number, width: number, height: number): void {
91
+ if (disposed) return;
92
+ if (!Number.isInteger(frame) || !Number.isInteger(width) || !Number.isInteger(height))
93
+ throw new Error(
94
+ `Temporal AA rejection counting needs whole numbers, got frame ${frame} at ${width}x${height}.`,
95
+ );
96
+ if (width < 1 || height < 1) return;
97
+ if (typeof Reflect.get(renderer, "deleteAttribute") !== "function")
98
+ throw new Error("Temporal rejection counting requires owned attribute disposal.");
99
+ owners.add(renderer as Renderer & { deleteAttribute(attribute: BufferAttribute): unknown });
100
+ // The dispatch size is part of the compute node, so a new display raster builds a new one over
101
+ // the same counter rather than a new counter.
102
+ if (pixels !== width * height) {
103
+ dispatched?.dispose();
104
+ pixels = width * height;
105
+ size.value.set(width, height);
106
+ dispatched = count.compute(pixels);
107
+ }
108
+ renderer.compute(reset);
109
+ renderer.compute(dispatched as NonNullable<typeof dispatched>);
110
+ if (inFlight !== undefined) return;
111
+ const dispatchedFrame = frame;
112
+ const expected = pixels;
113
+ // A readback that never lands, or lands malformed, withdraws the measurement instead of
114
+ // publishing a zero. The reason rides the settled diagnostic, so nothing claims a count.
115
+ inFlight = Promise.resolve(renderer.getArrayBufferAsync(counter.value))
116
+ .then((bytes: ArrayBuffer) => {
117
+ if (disposed) return;
118
+ const words = new Uint32Array(bytes);
119
+ const rejected = words[0];
120
+ const visited = words[1];
121
+ if (rejected === undefined || visited === undefined) {
122
+ absent(`Temporal AA rejection readback carried ${words.length} of 2 words.`);
123
+ return;
124
+ }
125
+ if (visited !== expected) {
126
+ absent(
127
+ `Temporal AA rejection readback visited ${visited} of ${expected} display pixels.`,
128
+ );
129
+ return;
130
+ }
131
+ if (rejected > visited) {
132
+ absent(`Temporal AA rejection readback rejected ${rejected} of ${visited} pixels.`);
133
+ return;
134
+ }
135
+ const fraction = rejected / visited;
136
+ if (!Number.isFinite(fraction)) {
137
+ absent(`Temporal AA rejection readback reported ${fraction}.`);
138
+ return;
139
+ }
140
+ failure = undefined;
141
+ latest = { frame: dispatchedFrame, fraction, visited };
142
+ unpublished = true;
143
+ })
144
+ .catch((error: unknown) => {
145
+ if (disposed) return;
146
+ absent(`Temporal AA rejection readback failed: ${String(error)}`);
147
+ })
148
+ .finally(() => {
149
+ inFlight = undefined;
150
+ if (disposed) releaseStorage();
151
+ });
152
+ },
153
+ report(frame: number): ITemporalRejectionMeasurement | undefined {
154
+ if (latest === undefined) return undefined;
155
+ return { ...latest, staleFrames: frame - latest.frame };
156
+ },
157
+ drain(): { frame: number; fraction: number } | undefined {
158
+ if (latest === undefined || unpublished === false) return undefined;
159
+ unpublished = false;
160
+ return latest;
161
+ },
162
+ async settled(): Promise<void> {
163
+ await inFlight;
164
+ if (failure !== undefined) throw new Error(failure);
165
+ },
166
+ dispose(): void {
167
+ if (disposed) return;
168
+ disposed = true;
169
+ latest = undefined;
170
+ unpublished = false;
171
+ failure = undefined;
172
+ reset.dispose();
173
+ dispatched?.dispose();
174
+ dispatched = undefined;
175
+ pixels = 0;
176
+ if (inFlight === undefined) releaseStorage();
177
+ },
178
+ };
179
+ }
@@ -0,0 +1,139 @@
1
+ // Generated user source: the temporal resolve kernel. It allocates no target, applies no jitter and
2
+ // owns no loop. The default arm is what `temporalAA.ts` installs, so every published frame comes
3
+ // from this kernel; `temporalResolveMath.ts` and `temporalResolveDepth.ts` hold its equations.
4
+ // Derived resolve source: three/examples/jsm/tsl/display/TRAANode.js (pinned 0.185.1).
5
+ import type TRAANode from "three/addons/tsl/display/TRAANode.js";
6
+ import { Fn, add, float, int, luminance, max, mix, texture, uv } from "three/tsl";
7
+ import type { Node } from "three/webgpu";
8
+ import type { TemporalCurrentFootprint } from "./temporalCurrentFootprint.js";
9
+ import {
10
+ type TemporalDepthRejection,
11
+ type TemporalResolveNode,
12
+ createTemporalDepthRejection,
13
+ } from "./temporalResolveDepth.js";
14
+ import {
15
+ createTemporalResolveMath,
16
+ reconstructNeighbourhood,
17
+ sampleCatmullRom,
18
+ } from "./temporalResolveMath.js";
19
+
20
+ export { CATMULL_ROM_BASIS } from "./temporalResolveMath.js";
21
+
22
+ /** Returns the amount of subpixel (expressed within [0, 1]) in the velocity. */
23
+ const subpixelCorrection = Fn(([velocityUV, textureSize]: [Node<"vec2">, Node<"uvec2">]) => {
24
+ const velocityTexel = velocityUV.mul(textureSize);
25
+ const phase = velocityTexel.fract().abs();
26
+ const weight = max(phase, phase.oneMinus());
27
+ return weight.x.mul(weight.y).oneMinus().div(0.75);
28
+ }).setLayout({
29
+ name: "subpixelCorrection",
30
+ type: "float",
31
+ inputs: [
32
+ { name: "velocityUV", type: "vec2" },
33
+ { name: "textureSize", type: "ivec2" },
34
+ ],
35
+ });
36
+
37
+ /** Flicker reduction based on luminance weighing. */
38
+ const flickerReduction = Fn(
39
+ ([currentColor, historyColor, currentWeight]: [Node<"vec4">, Node<"vec4">, Node<"float">]) => {
40
+ const historyWeight = currentWeight.oneMinus();
41
+ const compressedCurrent = currentColor.mul(
42
+ float(1).div(max(currentColor.r, currentColor.g, currentColor.b).add(1)),
43
+ );
44
+ const compressedHistory = historyColor.mul(
45
+ float(1).div(max(historyColor.r, historyColor.g, historyColor.b).add(1)),
46
+ );
47
+ const luminanceCurrent = luminance(compressedCurrent.rgb);
48
+ const luminanceHistory = luminance(compressedHistory.rgb);
49
+ currentWeight.mulAssign(float(1).div(luminanceCurrent.add(1)));
50
+ historyWeight.mulAssign(float(1).div(luminanceHistory.add(1)));
51
+ return add(currentColor.mul(currentWeight), historyColor.mul(historyWeight))
52
+ .div(max(currentWeight.add(historyWeight), 0.00001))
53
+ .toVar();
54
+ },
55
+ );
56
+
57
+ /**
58
+ * Build the resolve node. Reuse the installed node's depth/history uniforms and lifetime; replace
59
+ * only its resolve.
60
+ *
61
+ * `interpolation` and `blend` are the comparison arms: linear against Catmull–Rom history sampling,
62
+ * and luminance reweighting against an ordinary blend at the same weight. The default comparison keeps
63
+ * upstream's luminance weighting; the provider selects ordinary linear-coverage blending.
64
+ */
65
+ export function createExperimentalTemporalResolve(
66
+ source: TRAANode,
67
+ renderer: { reversedDepthBuffer: boolean; logarithmicDepthBuffer: boolean },
68
+ jitterOffset: Node<"vec2">,
69
+ interpolation: "linear" | "catmull-rom",
70
+ blend: "luminance" | "ordinary" = "luminance",
71
+ rejection: TemporalDepthRejection = createTemporalDepthRejection(
72
+ source as TemporalResolveNode,
73
+ renderer,
74
+ ),
75
+ current?: TemporalCurrentFootprint,
76
+ ) {
77
+ const node = source as TemporalResolveNode;
78
+ const { historyValidity } = rejection;
79
+ const { clipAABB } = createTemporalResolveMath(node);
80
+ const historyNode = texture(node._historyRenderTarget.texture);
81
+
82
+ const resolve = Fn(() => {
83
+ const uvNode = uv();
84
+ // Two rasters: colour, depth and velocity share the input one, resolve and history are display
85
+ // sized. Every gather below reads the input lattice; the history sample stays a normalized UV,
86
+ // and the motion weight and subpixel correction count display pixels.
87
+ const inputSize = node.beautyNode.size(int(0)) as Node<"uvec2">;
88
+ const displaySize = historyNode.size(int(0)) as Node<"uvec2">;
89
+ const validity = historyValidity(uvNode);
90
+ const hasValidHistory = validity.get("hasValidHistory") as Node<"float">;
91
+ const historyUV = validity.get("historyUV") as Node<"vec2">;
92
+ const offsetUV = validity.get("offsetUV") as Node<"vec2">;
93
+ // Reconstruction: gather the current frame's 3×3 input neighbourhood around the jittered sample
94
+ // the scene pass drew, and read its moments for the variance clip from the same taps. At a 1:1
95
+ // raster the plain current sample is exact; retain it instead of adding Gaussian blur.
96
+ const reconstruction =
97
+ current?.reconstruct(uvNode, displaySize) ??
98
+ reconstructNeighbourhood(node.beautyNode, uvNode, inputSize, jitterOffset, displaySize);
99
+ const upsampled = inputSize.x.lessThan(displaySize.x).or(inputSize.y.lessThan(displaySize.y));
100
+ const currentColor = upsampled.select(
101
+ reconstruction.get("color") as Node<"vec4">,
102
+ node.beautyNode.sample(uvNode),
103
+ ) as Node<"vec4">;
104
+ const mean = reconstruction.get("mean") as Node<"vec4">;
105
+ const historyColor =
106
+ interpolation === "linear"
107
+ ? historyNode.sample(historyUV)
108
+ : sampleCatmullRom(historyNode, historyUV).max(0);
109
+ const motionFactor = uvNode
110
+ .sub(historyUV)
111
+ .mul(displaySize)
112
+ .length()
113
+ .div(node.maxVelocityLength)
114
+ .saturate();
115
+ const currentWeight = float(0.05).toVar(); // A minimum weight
116
+ if (node.useSubpixelCorrection) {
117
+ // Increase the minimum weight towards the current frame when the velocity is more subpixel.
118
+ currentWeight.addAssign(subpixelCorrection(offsetUV, displaySize).mul(0.25));
119
+ }
120
+ currentWeight.assign(hasValidHistory.select(currentWeight.add(motionFactor).saturate(), 1));
121
+ // Reasonable gamma range is [0.75, 2]
122
+ const varianceGamma = mix(0.5, 1, motionFactor.oneMinus().pow2());
123
+ const variance = (reconstruction.get("variance") as Node<"vec4">).mul(varianceGamma);
124
+ const minColor = mean.sub(variance);
125
+ const maxColor = mean.add(variance);
126
+ const clippedHistoryColor = clipAABB(
127
+ mean.clamp(minColor, maxColor),
128
+ historyColor,
129
+ minColor,
130
+ maxColor,
131
+ );
132
+ // Every accepted history colour still passes the raw current-tap variance box.
133
+ // Diagnostic only: ordinary blending isolates luminance reweighting at the same weight.
134
+ return blend === "ordinary"
135
+ ? mix(clippedHistoryColor, currentColor, currentWeight)
136
+ : flickerReduction(currentColor, clippedHistoryColor, currentWeight);
137
+ });
138
+ return resolve();
139
+ }