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,193 @@
1
+ // Generated user source: the temporal kernel's depth rejection. Split out of `temporalResolve.ts`
2
+ // so each file stays readable; the equations are unchanged.
3
+ // Derived resolve source: three/examples/jsm/tsl/display/TRAANode.js (pinned 0.185.1).
4
+ /*
5
+ The MIT License
6
+
7
+ Copyright © 2010-2026 three.js authors
8
+
9
+ Permission is hereby granted, free of charge, to any person obtaining a copy
10
+ of this software and associated documentation files (the "Software"), to deal
11
+ in the Software without restriction, including without limitation the rights
12
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
+ copies of the Software, and to permit persons to whom the Software is
14
+ furnished to do so, subject to the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be included in
17
+ all copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25
+ THE SOFTWARE.
26
+ */
27
+ import type { Matrix4, OrthographicCamera, Vector2 } from "three";
28
+ import type TRAANode from "three/addons/tsl/display/TRAANode.js";
29
+ import {
30
+ Fn,
31
+ If,
32
+ float,
33
+ getViewPosition,
34
+ int,
35
+ ivec2,
36
+ logarithmicDepthToViewZ,
37
+ struct,
38
+ texture,
39
+ vec2,
40
+ vec4,
41
+ viewZToOrthographicDepth,
42
+ viewZToPerspectiveDepth,
43
+ } from "three/tsl";
44
+ import type { Node, RenderTarget, TextureNode } from "three/webgpu";
45
+ export type { ITemporalAANode } from "./temporalAAHooks.js";
46
+ export { guardTemporalAASeams } from "./temporalAAHooks.js";
47
+ import { temporalDepthHasDisocclusion, temporalDepthHistoryUV } from "./temporalDepthSamples.js";
48
+
49
+ /** A TSL uniform node: the shader reads it as a node, this reconstruction writes its value. */
50
+ export interface ITemporalUniform<T> {
51
+ value: T;
52
+ }
53
+
54
+ /**
55
+ * The pinned TRAANode seams this reconstruction reads.
56
+ *
57
+ * Declared here, beside its first reader, so `temporalAA.ts` and `temporalAAFrame.ts` name the
58
+ * same shape — and so a three.js version that drops one of them fails the seam guard in
59
+ * `temporalAA.ts` rather than reading `undefined` on a GPU.
60
+ */
61
+ export interface ITemporalResolvePinned {
62
+ _historyRenderTarget: RenderTarget;
63
+ _resolveRenderTarget: RenderTarget;
64
+ _previousDepthNode: TextureNode;
65
+ _cameraNearFar: Node<"vec2"> & ITemporalUniform<Vector2>;
66
+ _cameraWorldMatrix: Node<"mat4"> & ITemporalUniform<Matrix4>;
67
+ _cameraWorldMatrixInverse: Node<"mat4"> & ITemporalUniform<Matrix4>;
68
+ _cameraProjectionMatrixInverse: Node<"mat4"> & ITemporalUniform<Matrix4>;
69
+ _previousCameraWorldMatrix: Node<"mat4"> & ITemporalUniform<Matrix4>;
70
+ _previousCameraProjectionMatrixInverse: Node<"mat4"> & ITemporalUniform<Matrix4>;
71
+ /** Installed by `createTemporalAA`. 0 on a reset frame, which then weights current colour only. */
72
+ _historyValidUniform?: ITemporalUniform<number>;
73
+ /** Input-pixel jitter for current-frame reconstruction, captured beside the depth matrices. */
74
+ _reconstructionJitterOffset?: Node<"vec2"> & ITemporalUniform<Vector2>;
75
+ /** Actual input jitter, in input-raster UVs, captured beside the matching depth matrices. */
76
+ _currentJitterUV?: Node<"vec2"> & ITemporalUniform<Vector2>;
77
+ _previousJitterUV?: Node<"vec2"> & ITemporalUniform<Vector2>;
78
+ }
79
+
80
+ export type TemporalResolveNode = TRAANode & ITemporalResolvePinned;
81
+
82
+ /** The 3×3 neighbourhood depth test that decides whether last frame's colour is still legal. */
83
+ export function createTemporalDepthRejection(
84
+ node: TemporalResolveNode,
85
+ renderer: { reversedDepthBuffer: boolean; logarithmicDepthBuffer: boolean },
86
+ ) {
87
+ const toPerspectiveDepth = (depth: Node<"float">) => {
88
+ const { x: near, y: far } = node._cameraNearFar;
89
+ return viewZToPerspectiveDepth(logarithmicDepthToViewZ(depth, near, far), near, far);
90
+ };
91
+ const currentDepthStruct = struct({
92
+ closestDepth: "float",
93
+ closestPositionTexel: "vec2",
94
+ });
95
+ // Samples 3×3 neighborhood pixels and returns the closest depth and its texel.
96
+ const currentDepth = Fn(([positionTexel]: [Node<"vec2">]) => {
97
+ const inputSize = vec2(node.depthNode.size(int(0)) as Node<"uvec2">);
98
+ const closestDepth = float(2).toVar();
99
+ const closestPositionTexel = vec2(0).toVar();
100
+ for (let x = -1; x <= 1; ++x)
101
+ for (let y = -1; y <= 1; ++y) {
102
+ const neighbor = vec2(ivec2(positionTexel.add(vec2(x, y))))
103
+ .clamp(vec2(0), inputSize.sub(1))
104
+ .toVar();
105
+ let depth = node.depthNode.load(neighbor).r;
106
+ if (renderer.reversedDepthBuffer) depth = depth.oneMinus();
107
+ if (renderer.logarithmicDepthBuffer) depth = toPerspectiveDepth(depth);
108
+ depth = depth.toVar();
109
+ If(depth.lessThan(closestDepth), () => {
110
+ closestDepth.assign(depth);
111
+ closestPositionTexel.assign(neighbor);
112
+ });
113
+ }
114
+ return currentDepthStruct(closestDepth, closestPositionTexel);
115
+ });
116
+ // Samples a previous depth and reprojects it using the current camera matrices. The mip is named
117
+ // because the rejection counter reads this from a compute dispatch, where WGSL has no implicit
118
+ // derivatives to sample with; the depth history carries one mip, so the resolved value is the one
119
+ // the resolve fragment reads.
120
+ const previousDepth = (historyUV: Node<"vec2">) => {
121
+ let depth = texture(node._previousDepthNode, historyUV).level(int(0)).r;
122
+ if (renderer.logarithmicDepthBuffer) depth = toPerspectiveDepth(depth);
123
+ const positionView = getViewPosition(
124
+ historyUV,
125
+ depth,
126
+ node._previousCameraProjectionMatrixInverse,
127
+ );
128
+ const positionWorld = node._previousCameraWorldMatrix.mul(vec4(positionView, 1)).xyz;
129
+ const viewZ = node._cameraWorldMatrixInverse.mul(vec4(positionWorld, 1)).z;
130
+ const { x: near, y: far } = node._cameraNearFar;
131
+ return (node.camera as OrthographicCamera).isOrthographicCamera
132
+ ? viewZToOrthographicDepth(viewZ, near, far)
133
+ : viewZToPerspectiveDepth(viewZ, near, far);
134
+ };
135
+ const historyValidityStruct = struct({
136
+ hasValidHistory: "float",
137
+ historyUV: "vec2",
138
+ offsetUV: "vec2",
139
+ });
140
+ // Absent on a standalone node, which then keeps upstream's own history reuse unchanged.
141
+ const historyValid = (node._historyValidUniform ?? float(1)) as Node<"float">;
142
+ /**
143
+ * The one history-validity decision, parameterised by the pixel's own UV: `historyValid ∧ validUV
144
+ * ∧ ¬disocclusion`. The resolve weights its blend with this, and the rejection counter calls the
145
+ * same node once per display pixel, so a reported fraction cannot diverge from the decision that
146
+ * was drawn.
147
+ *
148
+ * Upstream also ORs in a depth-edge bypass (`farthestDepth − closestDepth > edgeDepthDiff`).
149
+ * PRD-455 holds the paired policy ablation: with that term off the measured reveal residue falls
150
+ * while edge error, instability and excursion each move by under 0.0001, which supports the term
151
+ * as the residue's cause.
152
+ */
153
+ const historyValidity = Fn(([pixelUV]: [Node<"vec2">]) => {
154
+ const inputSize = node.beautyNode.size(int(0)) as Node<"uvec2">;
155
+ const sampled = currentDepth(pixelUV.mul(inputSize));
156
+ const closestDepth = sampled.get("closestDepth") as Node<"float">;
157
+ const closestPositionTexel = sampled.get("closestPositionTexel") as Node<"vec2">;
158
+ const offsetUV = node.velocityNode.load(closestPositionTexel).xy.mul(vec2(0.5, -0.5));
159
+ const historyUV = pixelUV.sub(offsetUV);
160
+ const sampledPreviousDepth = previousDepth(historyUV);
161
+ let isValidUV = historyUV.greaterThanEqual(0).all().and(historyUV.lessThanEqual(1).all());
162
+ let isDisocclusion = closestDepth.sub(sampledPreviousDepth).greaterThan(node.depthThreshold);
163
+ if (node._currentJitterUV !== undefined && node._previousJitterUV !== undefined) {
164
+ // The conservative centre test remains intact. Also validate the actual closest texel whose
165
+ // velocity we used: previous depth is input sized and jittered, colour history is neither.
166
+ const depthHistoryUV = temporalDepthHistoryUV(
167
+ closestPositionTexel,
168
+ inputSize,
169
+ offsetUV,
170
+ node._currentJitterUV,
171
+ node._previousJitterUV,
172
+ );
173
+ const pointInBounds = depthHistoryUV
174
+ .greaterThanEqual(0)
175
+ .all()
176
+ .and(depthHistoryUV.lessThan(1).all());
177
+ isValidUV = isValidUV.and(pointInBounds);
178
+ isDisocclusion = temporalDepthHasDisocclusion(
179
+ closestDepth,
180
+ sampledPreviousDepth,
181
+ previousDepth(depthHistoryUV),
182
+ node.depthThreshold,
183
+ );
184
+ }
185
+ // A reset frame has no legal cross-size colour seed, so it weights only the current frame.
186
+ const hasValidHistory = historyValid.greaterThan(0.5).and(isValidUV.and(isDisocclusion.not()));
187
+ return historyValidityStruct(hasValidHistory, historyUV, offsetUV);
188
+ });
189
+ return { currentDepth, previousDepth, historyValidity };
190
+ }
191
+
192
+ /** The depth-rejection equations one shared instance of, so no two callers can disagree. */
193
+ export type TemporalDepthRejection = ReturnType<typeof createTemporalDepthRejection>;
@@ -0,0 +1,196 @@
1
+ // Generated user source: history sampling and neighbourhood clipping for the temporal kernel.
2
+ // Split out of `temporalResolve.ts` so each file stays readable; the equations are unchanged.
3
+ // Derived resolve source: three/examples/jsm/tsl/display/TRAANode.js (pinned 0.185.1).
4
+ /*
5
+ The MIT License
6
+
7
+ Copyright © 2010-2026 three.js authors
8
+
9
+ Permission is hereby granted, free of charge, to any person obtaining a copy
10
+ of this software and associated documentation files (the "Software"), to deal
11
+ in the Software without restriction, including without limitation the rights
12
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
+ copies of the Software, and to permit persons to whom the Software is
14
+ furnished to do so, subject to the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be included in
17
+ all copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25
+ THE SOFTWARE.
26
+ */
27
+ import { Fn, float, int, ivec2, max, struct, vec2, vec4 } from "three/tsl";
28
+ import type { Node, TextureNode } from "three/webgpu";
29
+ import type { TemporalResolveNode } from "./temporalResolveDepth.js";
30
+
31
+ // Polynomial coefficients, ascending power, for samples at -1, 0, 1 and 2.
32
+ export const CATMULL_ROM_BASIS = [
33
+ [0, -0.5, 1, -0.5],
34
+ [1, 0, -2.5, 1.5],
35
+ [0, 0.5, 2, -1.5],
36
+ [0, 0, -0.5, 0.5],
37
+ ] as const;
38
+
39
+ /** Nine bilinear taps reproduce the separable sixteen-tap Catmull–Rom kernel. */
40
+ export function sampleCatmullRom(source: TextureNode, coordinate: Node<"vec2">) {
41
+ return Fn(() => {
42
+ const size = vec2(source.size(int(0)) as Node<"uvec2">);
43
+ const position = coordinate.mul(size).sub(0.5);
44
+ const centre = position.floor().add(0.5);
45
+ const phase = position.fract();
46
+ const polynomial = (row: readonly [number, number, number, number]) =>
47
+ phase.mul(row[3]).add(row[2]).mul(phase).add(row[1]).mul(phase).add(row[0]);
48
+ const w0 = polynomial(CATMULL_ROM_BASIS[0]);
49
+ const w1 = polynomial(CATMULL_ROM_BASIS[1]);
50
+ const w2 = polynomial(CATMULL_ROM_BASIS[2]);
51
+ const w3 = polynomial(CATMULL_ROM_BASIS[3]);
52
+ const middle = w1.add(w2);
53
+ const p0 = centre.sub(1).div(size);
54
+ const p12 = centre.add(w2.div(middle)).div(size);
55
+ const p3 = centre.add(2).div(size);
56
+ const result = vec4(0).toVar();
57
+ const xs = [
58
+ [p0.x, w0.x],
59
+ [p12.x, middle.x],
60
+ [p3.x, w3.x],
61
+ ] as const;
62
+ const ys = [
63
+ [p0.y, w0.y],
64
+ [p12.y, middle.y],
65
+ [p3.y, w3.y],
66
+ ] as const;
67
+ for (const [x, wx] of xs)
68
+ for (const [y, wy] of ys) result.addAssign(source.sample(vec2(x, y)).mul(wx).mul(wy));
69
+ return result;
70
+ })();
71
+ }
72
+
73
+ const reconstructionStruct = struct({
74
+ color: "vec4",
75
+ mean: "vec4",
76
+ variance: "vec4",
77
+ });
78
+
79
+ /** Gaussian reconstruction on reduced axes at the samples' jittered centres. Native axes retain
80
+ * their owned point; all nine raw taps still supply the unchanged clipping moments. Omitting
81
+ * displaySize retains the original two-axis filter for existing helper calls. */
82
+ export function reconstructNeighbourhood(
83
+ source: TextureNode,
84
+ uvNode: Node<"vec2">,
85
+ inputSize: Node<"uvec2">,
86
+ jitterOffset: Node<"vec2">,
87
+ displaySize?: Node<"uvec2">,
88
+ ) {
89
+ const inputSizeF = vec2(inputSize);
90
+ const pIn = uvNode.mul(inputSizeF);
91
+ const closestTap = ivec2(pIn.sub(vec2(0.5).add(jitterOffset)).round());
92
+ const offsets = [-1, 0, 1].flatMap((y) => [-1, 0, 1].map((x) => [x, y] as const));
93
+ const nativeAxes = displaySize === undefined ? undefined : inputSizeF.equal(vec2(displaySize));
94
+ const sumColor = vec4(0).toVar();
95
+ const sumWeight = float(0).toVar();
96
+ const moment1 = vec4(0).toVar();
97
+ const moment2 = vec4(0).toVar();
98
+ for (const [x, y] of offsets) {
99
+ const tap = closestTap.add(ivec2(x, y));
100
+ const tapCenter = vec2(tap).add(vec2(0.5).add(jitterOffset));
101
+ const delta = pIn.sub(tapCenter);
102
+ const weight = delta
103
+ .dot(delta)
104
+ .mul(-2.29)
105
+ .exp()
106
+ .mul(x === 0 ? 1 : (nativeAxes?.x.select(0, 1) ?? 1))
107
+ .mul(y === 0 ? 1 : (nativeAxes?.y.select(0, 1) ?? 1));
108
+ // Use max() to prevent NaN values from propagating.
109
+ // Match the colour sampler's clamp-to-edge support.
110
+ const boundedTap = ivec2(vec2(tap).clamp(vec2(0), vec2(inputSize).sub(1)));
111
+ const sample = source.load(boundedTap).max(0);
112
+ sumColor.addAssign(sample.mul(weight));
113
+ sumWeight.addAssign(weight);
114
+ moment1.addAssign(sample);
115
+ moment2.addAssign(sample.pow2());
116
+ }
117
+ const N = float(offsets.length);
118
+ const mean = moment1.div(N);
119
+ const variance = moment2.div(N).sub(mean.pow2()).max(0).sqrt();
120
+ return reconstructionStruct(sumColor.div(sumWeight.max(1e-6)), mean, variance);
121
+ }
122
+
123
+ /**
124
+ * Variance clipping over the current frame's neighbourhood.
125
+ *
126
+ * The neighbourhood offsets are in input texels, which is what `positionTexel` already carries, so
127
+ * this reads the same pixels at full resolution and at a lower input raster.
128
+ */
129
+ export function createTemporalResolveMath(node: TemporalResolveNode) {
130
+ // Optimized version of AABB clipping.
131
+ // Reference: https://github.com/playdeadgames/temporal
132
+ const clipAABB = Fn(
133
+ ([currentColor, historyColor, minColor, maxColor]: [
134
+ Node<"vec4">,
135
+ Node<"vec4">,
136
+ Node<"vec4">,
137
+ Node<"vec4">,
138
+ ]) => {
139
+ const pClip = maxColor.rgb.add(minColor.rgb).mul(0.5);
140
+ const eClip = maxColor.rgb.sub(minColor.rgb).mul(0.5).add(1e-7);
141
+ const vClip = historyColor.sub(vec4(pClip, currentColor.a));
142
+ const vUnit = vClip.xyz.div(eClip);
143
+ const absUnit = vUnit.abs();
144
+ const maxUnit = max(absUnit.x, absUnit.y, absUnit.z);
145
+ return maxUnit
146
+ .greaterThan(1)
147
+ .select(vec4(pClip, currentColor.a).add(vClip.div(maxUnit)), historyColor);
148
+ },
149
+ ).setLayout({
150
+ name: "clipAABB",
151
+ type: "vec4",
152
+ inputs: [
153
+ { name: "currentColor", type: "vec4" },
154
+ { name: "historyColor", type: "vec4" },
155
+ { name: "minColor", type: "vec4" },
156
+ { name: "maxColor", type: "vec4" },
157
+ ],
158
+ });
159
+ // Performs variance clipping.
160
+ // See: https://developer.download.nvidia.com/gameworks/events/GDC2016/msalvi_temporal_supersampling.pdf
161
+ return {
162
+ clipAABB,
163
+ varianceClipping: Fn(
164
+ ([positionTexel, historyColor, gamma]: [Node<"vec2">, Node<"vec4">, Node<"float">]) => {
165
+ const offsets = [
166
+ [-1, -1],
167
+ [-1, 1],
168
+ [1, -1],
169
+ [1, 1],
170
+ [1, 0],
171
+ [0, -1],
172
+ [0, 1],
173
+ [-1, 0],
174
+ ];
175
+ // Moments describe nine equally weighted input texels. The displayed current colour may
176
+ // be filtered between them, so using it as the centre would change this population with
177
+ // display-pixel phase and clip valid history below the input neighbourhood's bound.
178
+ const centre = node.beautyNode.load(positionTexel).max(0);
179
+ const moment1 = centre.toVar();
180
+ const moment2 = centre.pow2().toVar();
181
+ for (const [x, y] of offsets) {
182
+ // Use max() to prevent NaN values from propagating.
183
+ const neighbor = node.beautyNode.offset(ivec2(x, y)).load(positionTexel).max(0);
184
+ moment1.addAssign(neighbor);
185
+ moment2.addAssign(neighbor.pow2());
186
+ }
187
+ const N = float(offsets.length + 1);
188
+ const mean = moment1.div(N);
189
+ const variance = moment2.div(N).sub(mean.pow2()).max(0).sqrt().mul(gamma);
190
+ const minColor = mean.sub(variance);
191
+ const maxColor = mean.add(variance);
192
+ return clipAABB(mean.clamp(minColor, maxColor), historyColor, minColor, maxColor);
193
+ },
194
+ ),
195
+ };
196
+ }
@@ -0,0 +1,124 @@
1
+ // Generated for you: opt-in Three.js, with no default tier or picture change.
2
+ // Compose this medium before exposure/bloom/output. It takes the scene's own fog over while it
3
+ // lives and restores it on disposal; aerial haze and god rays must stay off, and a separate
4
+ // clear-air sky remains valid. Density/phase/colour belong to this game — see `STARTER_MIST`
5
+ // below for the starter's own, which is the object to edit when the mist should be on.
6
+ // Pinned Three 0.185.1 VolumeNodeMaterial skips directional lights and couples extinction to
7
+ // illumination. This bounded integrator reuses GodraysNode's depth/shadow coordinates instead.
8
+ // `volumetricFogOptions.ts` is the contract it accepts, `volumetricFogVolume.ts` the graph it
9
+ // builds and owns, and `volumetricFogTransport.ts` the per-step integration inside it.
10
+ import { Box3, Color, type PerspectiveCamera, type Scene, Vector3 } from "three";
11
+ import type { Node, NodeMaterial, RenderTarget } from "three/webgpu";
12
+ import type { IFogVolume, IVolumetricFogOptions } from "./volumetricFogOptions.js";
13
+ import { validateFogOptions } from "./volumetricFogOptions.js";
14
+ import type { ScenePass } from "./volumetricFogTransport.js";
15
+ import { type IFogVolumeGraph, composeFogVolume } from "./volumetricFogVolume.js";
16
+
17
+ export type { IFogVolume, IVolumetricFogOptions };
18
+
19
+ /** The owned medium a composed graph exposes: one controller, one graph, one owned target. */
20
+ export type FogMedium = Exclude<ReturnType<typeof createVolumetricFog>, undefined>;
21
+
22
+ /**
23
+ * This game's mist — the one flag, density, colour, bounds and step count, all in this folder
24
+ * because they are look decisions. `Play.ts` passes this object and the live renderer's `kind` to
25
+ * `createVolumetricFog`; the backend is deliberately not in here, so no scene can claim a backend
26
+ * the renderer does not have.
27
+ *
28
+ * `enabled: false` costs nothing: the medium returns before this module allocates a target, a
29
+ * material or a graph, so the shipped picture and the off baseline are exactly what they were
30
+ * without it. Set it true and the mist is bounded by `volumes`, thins with height and is lit by
31
+ * `ambient` alone.
32
+ *
33
+ * There is no automatic sun. Pass `sun: key` from `lighting.ts` once `key.shadow.map` exists — the
34
+ * graph is built before the first render, so the first medium has no shadow map to sample and none
35
+ * is invented; a tier change rebuilds it and picks one up. Up to four unshadowed finite-range
36
+ * `PointLight`s need no preparation at all.
37
+ */
38
+ export const STARTER_MIST: Omit<IVolumetricFogOptions, "renderer"> = {
39
+ enabled: false,
40
+ steps: 32,
41
+ resolutionScale: 0.5,
42
+ // A slab over the arena floor: thickest at the boards, thinning with height.
43
+ volumes: [
44
+ {
45
+ bounds: new Box3(new Vector3(-9, 0, -6), new Vector3(9, 3, 6)),
46
+ density: 0.06,
47
+ baseHeight: 0,
48
+ heightFalloff: 0.5,
49
+ },
50
+ ],
51
+ albedo: new Color("#cfd8e3"),
52
+ ambient: new Color("#0b1016"),
53
+ anisotropy: 0.3,
54
+ environment: { aerialPerspective: false, godRays: false },
55
+ };
56
+
57
+ /**
58
+ * Off, unsupported and zero-density return before allocating any graph/target/material.
59
+ *
60
+ * While a medium lives it owns the scene's fog: `sky.ts` renders the same air through
61
+ * `scene.fog` and `scene.fogNode`, so two of them would double it. Disposal puts the authored fog back, unless
62
+ * the game authored a new one while the medium lived — that later fog is then the live one.
63
+ */
64
+ export function createVolumetricFog(
65
+ scene: Scene,
66
+ camera: PerspectiveCamera,
67
+ supplied: IVolumetricFogOptions,
68
+ ) {
69
+ if (!supplied.enabled || supplied.renderer !== "webgpu") return undefined;
70
+ const options = { ...supplied };
71
+ validateFogOptions(camera, options);
72
+ const volumes = options.volumes.filter((volume) => volume.density > 0);
73
+ if (volumes.length === 0) return undefined;
74
+ const authoredFog = scene.fog;
75
+ const authoredFogNode = scene.fogNode;
76
+ scene.fog = null;
77
+ scene.fogNode = null;
78
+ let graph: IFogVolumeGraph | undefined;
79
+ let disposed = false;
80
+ return {
81
+ get target(): RenderTarget | undefined {
82
+ return graph?.target;
83
+ },
84
+ get material(): NodeMaterial | undefined {
85
+ return graph?.material;
86
+ },
87
+ get transport(): Node<"vec4"> | undefined {
88
+ return graph?.transport;
89
+ },
90
+ diagnostics: () => ({
91
+ steps: options.steps,
92
+ resolutionScale: options.resolutionScale,
93
+ volumes: volumes.length,
94
+ localLights: (options.points ?? []).length,
95
+ history: false,
96
+ renderTargets: graph === undefined ? 0 : 1,
97
+ pixels: graph === undefined ? 0 : graph.target.width * graph.target.height,
98
+ }),
99
+ compose(scenePass: ScenePass): Node<"vec4"> {
100
+ if (disposed) throw new Error("volumetricFog: disposed controller.");
101
+ if (graph !== undefined) throw new Error("volumetricFog: compose once per owned graph.");
102
+ if (scenePass.camera !== camera)
103
+ throw new Error("volumetricFog: scene depth must come from this camera.");
104
+ if (
105
+ Reflect.get(scenePass.scene, "fog") != null ||
106
+ Reflect.get(scenePass.scene, "fogNode") != null
107
+ )
108
+ throw new Error("volumetricFog: scene fog duplicates the same medium.");
109
+ graph = composeFogVolume(camera, options, volumes, scenePass);
110
+ return graph.compose;
111
+ },
112
+ dispose(): void {
113
+ if (disposed) return;
114
+ disposed = true;
115
+ graph?.target.dispose();
116
+ graph?.material.dispose();
117
+ graph = undefined;
118
+ if (scene.fog == null && scene.fogNode == null) {
119
+ scene.fog = authoredFog;
120
+ scene.fogNode = authoredFogNode;
121
+ }
122
+ },
123
+ };
124
+ }
@@ -0,0 +1,96 @@
1
+ // The contract this medium accepts. Everything here is checked before a graph, a target or a
2
+ // material exists, so a rejected request costs nothing and names itself in the error.
3
+ import type { Box3, Color, DirectionalLight, PerspectiveCamera, PointLight } from "three";
4
+
5
+ export interface IFogVolume {
6
+ bounds: Box3;
7
+ /** Extinction per metre at/below baseHeight, independent of light intensity. */
8
+ density: number;
9
+ baseHeight: number;
10
+ heightFalloff: number;
11
+ }
12
+ export interface IVolumetricFogOptions {
13
+ enabled: boolean;
14
+ /** The live renderer's backend, `renderer.kind`. Anything but `webgpu` allocates nothing. */
15
+ renderer: string;
16
+ /** Explicit unqualified budget, 8–128. No automatic tier admission before measurements. */
17
+ steps: number;
18
+ resolutionScale: number;
19
+ volumes: IFogVolume[];
20
+ albedo: Color;
21
+ ambient: Color;
22
+ anisotropy: number;
23
+ /**
24
+ * A shadow-casting `DirectionalLight` whose `shadow.map` is already initialized — there is no
25
+ * other shadow source this graph can read, and none is created for it.
26
+ */
27
+ sun?: DirectionalLight;
28
+ /** At most four unshadowed finite-range PointLights; spot/cube shadows are excluded. */
29
+ points?: PointLight[];
30
+ logarithmicDepth?: boolean;
31
+ reversedDepth?: boolean;
32
+ /**
33
+ * What else is already drawing the same air. Both false is the only qualified answer: the
34
+ * medium takes `scene.fog` over while it lives and puts it back on disposal, so only aerial
35
+ * perspective and god rays have to stay off — either would add its contribution a second time.
36
+ */
37
+ environment: { aerialPerspective: boolean; godRays: boolean };
38
+ }
39
+ function finite(name: string, value: number, low: number, high = Number.POSITIVE_INFINITY): void {
40
+ if (!Number.isFinite(value) || value < low || value > high)
41
+ throw new Error(`volumetricFog: ${name} must be finite in [${low}, ${high}].`);
42
+ }
43
+ function validateVolumes(volumes: IFogVolume[]): void {
44
+ if (volumes.length > 8) throw new Error("volumetricFog: at most eight bounds.");
45
+ for (const volume of volumes) {
46
+ finite("density", volume.density, 0);
47
+ finite("heightFalloff", volume.heightFalloff, 0);
48
+ finite("baseHeight", volume.baseHeight, Number.NEGATIVE_INFINITY);
49
+ const { min: low, max: high } = volume.bounds;
50
+ if (
51
+ ![...low, ...high].every(Number.isFinite) ||
52
+ low.x >= high.x ||
53
+ low.y >= high.y ||
54
+ low.z >= high.z
55
+ )
56
+ throw new Error("volumetricFog: bounds need finite positive extent.");
57
+ }
58
+ }
59
+ export function validateFogOptions(
60
+ camera: PerspectiveCamera,
61
+ options: IVolumetricFogOptions,
62
+ ): void {
63
+ if (!camera.isPerspectiveCamera) throw new Error("volumetricFog: perspective camera required.");
64
+ if (options.logarithmicDepth || options.reversedDepth)
65
+ throw new Error("volumetricFog: only ordinary perspective depth is qualified for this graph.");
66
+ finite("steps", options.steps, 8, 128);
67
+ if (!Number.isInteger(options.steps)) throw new Error("volumetricFog: steps must be integer.");
68
+ if (options.resolutionScale !== 1 && options.resolutionScale !== 0.5)
69
+ throw new Error("volumetricFog: resolutionScale must be 1 or 0.5.");
70
+ finite("anisotropy", options.anisotropy, -0.9, 0.9);
71
+ validateVolumes(options.volumes);
72
+ for (const channel of options.albedo.toArray()) finite("albedo", channel, 0, 1);
73
+ for (const channel of options.ambient.toArray()) finite("ambient", channel, 0);
74
+ if (options.environment.aerialPerspective || options.environment.godRays)
75
+ throw new Error(
76
+ "volumetricFog: aerial perspective and god rays must be off — this graph renders the same medium.",
77
+ );
78
+ const sun = options.sun;
79
+ if (
80
+ sun !== undefined &&
81
+ (!sun.castShadow || sun.shadow.map?.depthTexture == null || sun.shadow.shadowNode != null)
82
+ )
83
+ throw new Error("volumetricFog: sun needs an initialized ordinary directional shadow map.");
84
+ const points = options.points ?? [];
85
+ if (points.length > 4) throw new Error("volumetricFog: at most four local lights.");
86
+ for (const point of points) {
87
+ if (
88
+ !point.isPointLight ||
89
+ point.castShadow ||
90
+ !Number.isFinite(point.distance) ||
91
+ point.distance <= 0
92
+ )
93
+ throw new Error("volumetricFog: local lights must be unshadowed finite-range PointLights.");
94
+ finite("point decay", point.decay, 0, 4);
95
+ }
96
+ }