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,43 @@
1
+ // Generated for you. Weak ownership and full provenance guard successful source estimates.
2
+ import type { Scene, Texture } from "three";
3
+ import type { IEnvironmentSample } from "./environmentSampling.js";
4
+ import { environmentSnapshotCurrent } from "./environmentSnapshot.js";
5
+ const samples = new WeakMap<object, WeakMap<Texture, IEnvironmentSample>>();
6
+ export function cachedEnvironmentSample(
7
+ renderer: object,
8
+ scene: Scene,
9
+ ): IEnvironmentSample | undefined {
10
+ if (scene.environment === null) return undefined;
11
+ const sample = samples.get(renderer)?.get(scene.environment);
12
+ return sample !== undefined && environmentSnapshotCurrent(scene, sample)
13
+ ? copySample(sample)
14
+ : undefined;
15
+ }
16
+ export function cacheEnvironmentSample(
17
+ renderer: object,
18
+ scene: Scene,
19
+ sample: IEnvironmentSample,
20
+ ): void {
21
+ if (
22
+ sample.source === null ||
23
+ sample.measurement.status !== "measured" ||
24
+ !environmentSnapshotCurrent(scene, sample)
25
+ )
26
+ return;
27
+ let byTexture = samples.get(renderer);
28
+ if (byTexture === undefined) {
29
+ byTexture = new WeakMap();
30
+ samples.set(renderer, byTexture);
31
+ }
32
+ byTexture.set(sample.source, copySample(sample));
33
+ }
34
+
35
+ function copySample(sample: IEnvironmentSample): IEnvironmentSample {
36
+ return {
37
+ ...sample,
38
+ measurement: {
39
+ ...sample.measurement,
40
+ meanRGB: sample.measurement.meanRGB === null ? null : [...sample.measurement.meanRGB],
41
+ },
42
+ };
43
+ }
@@ -0,0 +1,193 @@
1
+ // Generated for you. A bounded source-radiance estimate, never a material/BRDF measurement.
2
+ import {
3
+ FloatType,
4
+ LinearSRGBColorSpace,
5
+ NoToneMapping,
6
+ RGBAFormat,
7
+ RenderTarget,
8
+ type Scene,
9
+ type ToneMapping,
10
+ } from "three";
11
+ import { texture, uv } from "three/tsl";
12
+ import { MeshBasicNodeMaterial, QuadMesh, type WebGPURenderer } from "three/webgpu";
13
+ import { type IEnvironmentMeasurement, measureEnvironment } from "./environmentContribution.js";
14
+ import { sampledRadiance } from "./environmentRadiance.js";
15
+ import { cacheEnvironmentSample, cachedEnvironmentSample } from "./environmentSampleCache.js";
16
+ import {
17
+ type IEnvironmentSourceSnapshot,
18
+ captureEnvironmentSnapshot,
19
+ environmentSnapshotCurrent,
20
+ samplingSourceSupported,
21
+ } from "./environmentSnapshot.js";
22
+ import {
23
+ type IMaterialLightingEnvironment,
24
+ isWebGLFallbackRenderer,
25
+ materialLightingEnabled,
26
+ } from "./quality.js";
27
+ export interface IEnvironmentSample extends IEnvironmentSourceSnapshot {
28
+ readonly measurement: IEnvironmentMeasurement;
29
+ }
30
+ /** Editable bound on asynchronous readback, independent of the engine startup deadline. */
31
+ const ENVIRONMENT_READBACK_TIMEOUT_MS = 1000;
32
+ const WIDTH = 64;
33
+ const HEIGHT = 32;
34
+ /** Call from the scene's awaited load(), after its actual environment is bound. */
35
+ export async function sampleEnvironment(
36
+ renderer: unknown,
37
+ scene: Scene,
38
+ environment: IMaterialLightingEnvironment,
39
+ ): Promise<IEnvironmentSample> {
40
+ const snapshot = captureEnvironmentSnapshot(scene);
41
+ const { source, intensity } = snapshot;
42
+ const result = (measurement: IEnvironmentMeasurement): IEnvironmentSample => ({
43
+ ...snapshot,
44
+ measurement,
45
+ });
46
+ const unknown = (reason: string): IEnvironmentSample =>
47
+ result({ status: "unknown", meanRadiance: null, meanRGB: null, reason });
48
+ if (!materialLightingEnabled("high", environment) || isWebGLFallbackRenderer(renderer))
49
+ return unknown("Environment GPU sampling is unqualified on this platform/renderer.");
50
+ if (source === null) return result(measureEnvironment(scene, WIDTH * HEIGHT));
51
+ if (!samplingSourceSupported(source))
52
+ return unknown("Environment mapping/color-space is not qualified for the bounded GPU sample.");
53
+ if (!Number.isFinite(intensity) || intensity < 0)
54
+ return unknown("Environment intensity must be finite and nonnegative.");
55
+ if (!samplingRendererSupported(renderer))
56
+ return unknown("Raw Three.js renderer lacks the qualified sampling/readback methods.");
57
+ const raw = renderer as WebGPURenderer;
58
+ const cached = cachedEnvironmentSample(raw, scene);
59
+ if (cached !== undefined) return cached;
60
+ let state: {
61
+ target: ReturnType<WebGPURenderer["getRenderTarget"]>;
62
+ face: number;
63
+ mip: number;
64
+ toneMapping: ToneMapping;
65
+ colorSpace: string;
66
+ autoClear: boolean;
67
+ };
68
+ try {
69
+ state = {
70
+ target: raw.getRenderTarget(),
71
+ face: raw.getActiveCubeFace(),
72
+ mip: raw.getActiveMipmapLevel(),
73
+ toneMapping: raw.toneMapping,
74
+ colorSpace: raw.outputColorSpace,
75
+ autoClear: raw.autoClear,
76
+ };
77
+ } catch {
78
+ return unknown("Raw renderer state could not be saved; GPU sample skipped.");
79
+ }
80
+ const target = new RenderTarget(WIDTH, HEIGHT, {
81
+ type: FloatType,
82
+ format: RGBAFormat,
83
+ depthBuffer: false,
84
+ stencilBuffer: false,
85
+ });
86
+ target.texture.colorSpace = LinearSRGBColorSpace;
87
+ const material = new MeshBasicNodeMaterial();
88
+ material.toneMapped = false;
89
+ material.colorNode = texture(source, uv()).rgb;
90
+ const quad = new QuadMesh(material);
91
+ let pendingReadback: Promise<unknown> | undefined;
92
+ let readbackSettled = false;
93
+ let cleaned = false;
94
+ function cleanup(): void {
95
+ if (cleaned) return;
96
+ cleaned = true;
97
+ try {
98
+ material.dispose();
99
+ } finally {
100
+ target.dispose();
101
+ }
102
+ // QuadMesh geometry is shared and borrowed.
103
+ }
104
+ try {
105
+ try {
106
+ raw.toneMapping = NoToneMapping;
107
+ raw.outputColorSpace = LinearSRGBColorSpace;
108
+ raw.autoClear = true;
109
+ raw.setRenderTarget(target, 0, 0);
110
+ quad.render(raw);
111
+ pendingReadback = Promise.resolve(
112
+ raw.readRenderTargetPixelsAsync(target, 0, 0, WIDTH, HEIGHT),
113
+ ).then(
114
+ (value) => {
115
+ readbackSettled = true;
116
+ return value;
117
+ },
118
+ (error) => {
119
+ readbackSettled = true;
120
+ throw error;
121
+ },
122
+ );
123
+ } finally {
124
+ // No async gap while the shared renderer points at our scratch target.
125
+ try {
126
+ raw.setRenderTarget(state.target, state.face, state.mip);
127
+ } finally {
128
+ raw.toneMapping = state.toneMapping;
129
+ raw.outputColorSpace = state.colorSpace;
130
+ raw.autoClear = state.autoClear;
131
+ }
132
+ }
133
+ const outcome = await waitForReadback(pendingReadback);
134
+ if (outcome.timedOut)
135
+ return unknown(
136
+ `Environment GPU readback exceeded ${ENVIRONMENT_READBACK_TIMEOUT_MS} ms budget; scratch resources retained until readback settles.`,
137
+ );
138
+ const samples = outcome.samples;
139
+ if (!environmentSnapshotCurrent(scene, snapshot))
140
+ return unknown(
141
+ "Environment source/content/interpretation changed while GPU readback was pending; sample refused.",
142
+ );
143
+ const sampled = result(sampledRadiance(samples, intensity));
144
+ cacheEnvironmentSample(raw, scene, sampled);
145
+ return sampled;
146
+ } catch (error) {
147
+ return unknown(`Environment GPU sample/readback unavailable: ${String(error)}`);
148
+ } finally {
149
+ finishSampleCleanup(pendingReadback, readbackSettled, cleanup);
150
+ }
151
+ }
152
+
153
+ async function waitForReadback(
154
+ readback: Promise<unknown>,
155
+ ): Promise<{ timedOut: true } | { timedOut: false; samples: unknown }> {
156
+ let timer: ReturnType<typeof setTimeout> | undefined;
157
+ try {
158
+ return await Promise.race([
159
+ readback.then((samples) => ({ timedOut: false as const, samples })),
160
+ new Promise<{ timedOut: true }>((resolve) => {
161
+ timer = setTimeout(() => resolve({ timedOut: true }), ENVIRONMENT_READBACK_TIMEOUT_MS);
162
+ }),
163
+ ]);
164
+ } finally {
165
+ if (timer !== undefined) clearTimeout(timer);
166
+ }
167
+ }
168
+
169
+ function samplingRendererSupported(renderer: unknown): renderer is WebGPURenderer {
170
+ return (
171
+ renderer !== null &&
172
+ typeof renderer === "object" &&
173
+ Reflect.get(renderer, "isWebGPURenderer") === true &&
174
+ [
175
+ "render",
176
+ "getRenderTarget",
177
+ "getActiveCubeFace",
178
+ "getActiveMipmapLevel",
179
+ "setRenderTarget",
180
+ "readRenderTargetPixelsAsync",
181
+ ].every((name) => typeof Reflect.get(renderer, name) === "function")
182
+ );
183
+ }
184
+
185
+ function finishSampleCleanup(
186
+ readback: Promise<unknown> | undefined,
187
+ settled: boolean,
188
+ cleanup: () => void,
189
+ ): void {
190
+ // Timeout permits startup, but GPU work may still reference the target/material.
191
+ if (readback !== undefined && !settled) void readback.then(cleanup, cleanup);
192
+ else cleanup();
193
+ }
@@ -0,0 +1,53 @@
1
+ // Generated for you. Borrowed environment provenance for stale-readback rejection.
2
+ import {
3
+ EquirectangularReflectionMapping,
4
+ LinearSRGBColorSpace,
5
+ NoColorSpace,
6
+ SRGBColorSpace,
7
+ type Scene,
8
+ type Texture,
9
+ } from "three";
10
+ /** Provenance stays outside the printable measurement; source/image references are borrowed. */
11
+ export interface IEnvironmentSourceSnapshot {
12
+ readonly source: Texture | null;
13
+ readonly intensity: number;
14
+ readonly textureVersion: number | null;
15
+ readonly sourceVersion: number | null;
16
+ readonly colorSpace: string | null;
17
+ readonly mapping: number | null;
18
+ readonly image: unknown;
19
+ }
20
+ export function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot {
21
+ const source = scene.environment;
22
+ return {
23
+ source,
24
+ intensity: scene.environmentIntensity,
25
+ textureVersion: source?.version ?? null,
26
+ sourceVersion: source?.source.version ?? null,
27
+ colorSpace: source?.colorSpace ?? null,
28
+ mapping: source?.mapping ?? null,
29
+ image: source?.image ?? null,
30
+ };
31
+ }
32
+ export function environmentSnapshotCurrent(
33
+ scene: Scene,
34
+ snapshot: IEnvironmentSourceSnapshot,
35
+ ): boolean {
36
+ const source = scene.environment;
37
+ return (
38
+ source === snapshot.source &&
39
+ scene.environmentIntensity === snapshot.intensity &&
40
+ (source?.version ?? null) === snapshot.textureVersion &&
41
+ (source?.source.version ?? null) === snapshot.sourceVersion &&
42
+ (source?.colorSpace ?? null) === snapshot.colorSpace &&
43
+ (source?.mapping ?? null) === snapshot.mapping &&
44
+ (source?.image ?? null) === snapshot.image
45
+ );
46
+ }
47
+
48
+ export function samplingSourceSupported(source: NonNullable<Scene["environment"]>): boolean {
49
+ return (
50
+ source.mapping === EquirectangularReflectionMapping &&
51
+ new Set<string>([NoColorSpace, LinearSRGBColorSpace, SRGBColorSpace]).has(source.colorSpace)
52
+ );
53
+ }
@@ -0,0 +1,111 @@
1
+ // Generated for you: these controls and this metric are the game's look. Edit freely.
2
+ import { dot, float, vec2, vec3 } from "three/tsl";
3
+ import type { Node } from "three/webgpu";
4
+
5
+ export interface IExposureSettings {
6
+ enabled: boolean;
7
+ /** Middle-grey target; increase to brighten the metered subject. */
8
+ key: number;
9
+ /** Exposure limits in stops. Expand only if the scene needs more range. */
10
+ minStops: number;
11
+ maxStops: number;
12
+ /**
13
+ * Percent of metered weight, dark to bright, ignored at each end of the histogram.
14
+ * Raise highPercent's gap (lower it) when a large bright backdrop still sets the exposure.
15
+ */
16
+ lowPercent: number;
17
+ highPercent: number;
18
+ /** Exponential response per second in log2 space. Up opens the eye; down squints. */
19
+ rateUp: number;
20
+ rateDown: number;
21
+ /** Stop error where cut acceleration begins / reaches its authored maximum. */
22
+ snapLo: number;
23
+ snapHi: number;
24
+ snapGain: number;
25
+ /** Seed for known cuts. reset() without a value adopts the next measured target. */
26
+ initialExposure: number;
27
+ settleStops: number;
28
+ /** Limit catch-up after a suspended frame, avoiding an unrequested cut. */
29
+ maxDelta: number;
30
+ /** Readback/marker cadence in seconds. Metering still runs on every drawn frame. */
31
+ reportInterval: number;
32
+ }
33
+
34
+ export const exposureSettings: Readonly<IExposureSettings> = {
35
+ enabled: false, // Opt in after qualifying this game's bright and dark captures.
36
+ key: 0.18,
37
+ minStops: -12,
38
+ maxStops: 12,
39
+ lowPercent: 10,
40
+ highPercent: 90,
41
+ rateUp: 2,
42
+ rateDown: 4,
43
+ snapLo: 3,
44
+ snapHi: 8,
45
+ snapGain: 1,
46
+ initialExposure: 1,
47
+ settleStops: 0.25,
48
+ maxDelta: 0.1,
49
+ reportInterval: 0.5,
50
+ };
51
+
52
+ /**
53
+ * Return weighted luminance and weight. The histogram's percent clip, not a clamp here, rejects
54
+ * small bright sources. The upper bound only keeps a half-float overflow from poisoning a block.
55
+ */
56
+ export function exposureMeter(colour: Node<"vec4">, uv: Node<"vec2">): Node<"vec2"> {
57
+ const luminance = dot(colour.rgb, vec3(0.2126, 0.7152, 0.0722)).clamp(0.0001, 65504);
58
+ // Larger bottom-of-frame preference favours ground over bright sky (WebGPU UV y is down).
59
+ const weight = float(1).add(uv.y);
60
+ return vec2(luminance.mul(weight), weight);
61
+ }
62
+
63
+ /** Receives the clipped histogram's linear mean luminance. Change it if the game encodes RMS. */
64
+ export function exposureLuminance(mean: Node<"float">): Node<"float"> {
65
+ return mean.max(0.0001);
66
+ }
67
+
68
+ export function validateExposureSettings(value: IExposureSettings): void {
69
+ for (const key of Object.keys(exposureSettings) as (keyof IExposureSettings)[]) {
70
+ if (key === "enabled") continue;
71
+ const number = value[key];
72
+ if (typeof number !== "number" || !Number.isFinite(Math.fround(number)))
73
+ throw new Error(`Invalid exposure ${key}: expected a finite float32 number.`);
74
+ }
75
+ if (
76
+ typeof value.enabled !== "boolean" ||
77
+ Math.fround(value.key) <= 0 ||
78
+ Math.fround(value.initialExposure) <= 0 ||
79
+ value.rateUp < 0 ||
80
+ value.rateDown < 0 ||
81
+ value.snapLo < 0 ||
82
+ value.snapHi <= value.snapLo ||
83
+ value.snapGain < 0 ||
84
+ value.snapGain > 1 ||
85
+ value.lowPercent < 0 ||
86
+ value.highPercent > 100 ||
87
+ value.lowPercent >= value.highPercent ||
88
+ value.minStops >= value.maxStops ||
89
+ value.minStops < -126 ||
90
+ value.maxStops > 126 ||
91
+ value.settleStops < 0 ||
92
+ value.maxDelta <= 0 ||
93
+ value.reportInterval <= 0
94
+ )
95
+ throw new Error("Invalid exposure settings: check limits, rates and thresholds.");
96
+ }
97
+
98
+ /** Resize only the meter. The separate history targets always remain 1x1. */
99
+ export function exposureReductionSizes(width: number, height: number): [number, number][] {
100
+ if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1)
101
+ throw new Error("Exposure drawing buffer dimensions must be positive integers.");
102
+ const sizes: [number, number][] = [];
103
+ let w = width;
104
+ let h = height;
105
+ do {
106
+ w = Math.ceil(w / 4);
107
+ h = Math.ceil(h / 4);
108
+ sizes.push([w, h]);
109
+ } while (w > 1 || h > 1);
110
+ return sizes;
111
+ }
@@ -0,0 +1,178 @@
1
+ // Generated for you: GPU reduction and adaptation; exposure.ts owns the game's look.
2
+ import { FloatType, NearestFilter, RenderTarget } from "three";
3
+ import {
4
+ Fn,
5
+ If,
6
+ Loop,
7
+ float,
8
+ int,
9
+ ivec2,
10
+ mix,
11
+ screenCoordinate,
12
+ smoothstep,
13
+ type texture,
14
+ textureLoad,
15
+ vec2,
16
+ vec4,
17
+ } from "three/tsl";
18
+ import type { Node } from "three/webgpu";
19
+ import type { IExposureSettings } from "./exposure.js";
20
+
21
+ export type ColourTexture = ReturnType<typeof texture>;
22
+ export type Meter = (colour: Node<"vec4">, uv: Node<"vec2">) => Node<"vec2">;
23
+ export type Decode = (mean: Node<"float">) => Node<"float">;
24
+
25
+ export function exposureTarget(): RenderTarget {
26
+ return new RenderTarget(1, 1, {
27
+ type: FloatType,
28
+ minFilter: NearestFilter,
29
+ magFilter: NearestFilter,
30
+ depthBuffer: false,
31
+ });
32
+ }
33
+
34
+ /** Sum/16 at each level keeps values bounded. Mask partial blocks; never replicate edge texels. */
35
+ export function reduceExposure(
36
+ input: ColourTexture,
37
+ size: Node<"vec2">,
38
+ meter?: Meter,
39
+ ): Node<"vec4"> {
40
+ return Fn(() => {
41
+ const sum = vec2(0).toVar();
42
+ const origin = screenCoordinate.xy.floor().mul(4);
43
+ for (let y = 0; y < 4; y++)
44
+ for (let x = 0; x < 4; x++) {
45
+ const pixel = origin.add(vec2(x, y));
46
+ If(pixel.x.lessThan(size.x).and(pixel.y.lessThan(size.y)), () => {
47
+ const colour = textureLoad(input, ivec2(pixel));
48
+ sum.addAssign(meter === undefined ? colour.rg : meter(colour, pixel.add(0.5).div(size)));
49
+ });
50
+ }
51
+ return vec4(sum.div(16), 0, 1);
52
+ })();
53
+ }
54
+
55
+ /** The histogram has 64 bins. Each bin spans (maxStops - minStops) / 64 stops of scene luminance. */
56
+ export const exposureBins = 64;
57
+ /** The gather splits the blocks over 64 tiles, so a bin is summed by 64 short loops, not one long. */
58
+ export const exposureTiles = 64;
59
+
60
+ /**
61
+ * Stage one of the histogram, drawn as a 64 (bins) x 64 (tiles) target. Texel (bin, tile) gathers
62
+ * its tile of the block means of `blocks` (the second reduction level, about 8 000 texels at
63
+ * 1080p, so about 130 per tile) that fall in its bin.
64
+ * r = summed weight, g = summed weight * log2 luminance, so a bin keeps its exact mean.
65
+ */
66
+ export function histogramTiles(
67
+ blocks: ColourTexture,
68
+ size: Node<"vec2">,
69
+ policy: Readonly<IExposureSettings>,
70
+ ): Node<"vec4"> {
71
+ // Range follows the authored stops: goal = log2(key) - log2(L), clamped to [min, max].
72
+ const low = Math.log2(policy.key) - policy.maxStops;
73
+ const span = policy.maxStops - policy.minStops;
74
+ return Fn(() => {
75
+ const bin = screenCoordinate.x.floor();
76
+ const weight = float(0).toVar();
77
+ const logSum = float(0).toVar();
78
+ const width = int(size.x);
79
+ const total = int(size.x.mul(size.y));
80
+ const perTile = total.add(exposureTiles - 1).div(exposureTiles);
81
+ const first = int(screenCoordinate.y.floor()).mul(perTile);
82
+ Loop({ start: 0, end: perTile }, ({ i: offset }) => {
83
+ const i = first.add(offset);
84
+ If(i.lessThan(total), () => {
85
+ const block = textureLoad(blocks, ivec2(i.mod(width), i.div(width)));
86
+ const log = block.r
87
+ .div(block.g.max(1e-20))
88
+ .max(1e-20)
89
+ .log2()
90
+ .clamp(low, low + span);
91
+ const index = log
92
+ .sub(low)
93
+ .mul(exposureBins / span)
94
+ .floor()
95
+ .min(exposureBins - 1);
96
+ If(block.g.greaterThan(0).and(index.equal(bin)), () => {
97
+ weight.addAssign(block.g);
98
+ logSum.addAssign(block.g.mul(log));
99
+ });
100
+ });
101
+ });
102
+ return vec4(weight, logSum, 0, 1);
103
+ })();
104
+ }
105
+
106
+ /** Stage two, drawn as a 64x1 target: one texel per bin, summing that bin over every tile. */
107
+ export function histogramExposure(tiles: ColourTexture): Node<"vec4"> {
108
+ return Fn(() => {
109
+ const bin = int(screenCoordinate.x.floor());
110
+ const sum = vec2(0).toVar();
111
+ Loop(exposureTiles, ({ i }) => {
112
+ sum.addAssign(textureLoad(tiles, ivec2(bin, i)).rg);
113
+ });
114
+ return vec4(sum, 0, 1);
115
+ })();
116
+ }
117
+
118
+ /**
119
+ * UE's average without outliers: drop the darkest lowPercent of the weight, stop at
120
+ * highPercent, take the weighted log2 mean of what is left. Returns (log2 mean, kept weight).
121
+ */
122
+ function clippedLog2Mean(
123
+ histogram: ColourTexture,
124
+ policy: Readonly<IExposureSettings>,
125
+ ): Node<"vec2"> {
126
+ const total = float(0).toVar();
127
+ Loop(exposureBins, ({ i }) => {
128
+ total.addAssign(textureLoad(histogram, ivec2(i, 0)).r);
129
+ });
130
+ const dropLow = total.mul(policy.lowPercent / 100).toVar();
131
+ const keepUpTo = total.mul(policy.highPercent / 100).toVar();
132
+ const kept = float(0).toVar();
133
+ const logSum = float(0).toVar();
134
+ Loop(exposureBins, ({ i }) => {
135
+ const bin = textureLoad(histogram, ivec2(i, 0));
136
+ const removed = bin.r.min(dropLow);
137
+ dropLow.subAssign(removed);
138
+ keepUpTo.subAssign(removed);
139
+ const keep = bin.r.sub(removed).min(keepUpTo);
140
+ keepUpTo.subAssign(keep);
141
+ kept.addAssign(keep);
142
+ logSum.addAssign(bin.g.mul(keep.div(bin.r.max(1e-20))));
143
+ });
144
+ return vec2(logSum.div(kept.max(1e-20)), kept);
145
+ }
146
+
147
+ export function adaptExposure(
148
+ histogram: ColourTexture,
149
+ previous: ColourTexture,
150
+ resetMode: Node<"float">,
151
+ seed: Node<"float">,
152
+ delta: Node<"float">,
153
+ policy: Readonly<IExposureSettings>,
154
+ decode: Decode,
155
+ ): Node<"vec4"> {
156
+ return Fn(() => {
157
+ const measure = clippedLog2Mean(histogram, policy);
158
+ const luminance = decode(measure.x.exp2());
159
+ const valid = measure.y
160
+ .greaterThan(0)
161
+ .and(luminance.greaterThan(0))
162
+ .and(luminance.lessThan(3.4e38));
163
+ const goal = float(Math.log2(policy.key))
164
+ .sub(luminance.max(1e-20).log2())
165
+ .clamp(policy.minStops, policy.maxStops);
166
+ const old = resetMode.equal(1).select(seed, textureLoad(previous, ivec2(0)).r);
167
+ const error = goal.sub(old);
168
+ const rate = error.greaterThan(0).select(float(policy.rateUp), float(policy.rateDown));
169
+ const normal = float(1).sub(delta.mul(rate).negate().exp());
170
+ const cut = smoothstep(policy.snapLo, policy.snapHi, error.abs()).mul(policy.snapGain);
171
+ const adapted = valid.select(
172
+ resetMode.equal(2).select(goal, mix(old, goal, mix(normal, float(1), cut))),
173
+ old,
174
+ );
175
+ const settled = goal.sub(adapted).abs().lessThanEqual(policy.settleStops).select(1, 0);
176
+ return vec4(adapted, valid.select(luminance, -1), goal, settled);
177
+ })();
178
+ }
@@ -0,0 +1,79 @@
1
+ // Generated for you: async GPU observations stay tied to their owner's live generation.
2
+ import type { RenderTarget } from "three";
3
+ import type { Renderer } from "three/webgpu";
4
+
5
+ export class ExposureReadback {
6
+ #pending = false;
7
+ #generation = 0;
8
+ #lastReport = Number.NEGATIVE_INFINITY;
9
+ #disposed = false;
10
+ #value: Record<string, unknown>;
11
+ constructor(
12
+ readonly constant: number,
13
+ readonly enabled: () => boolean,
14
+ ) {
15
+ this.#value = { measured: false, applied: enabled() };
16
+ }
17
+ invalidate(): void {
18
+ this.#generation++;
19
+ this.#value = { measured: false, applied: this.enabled() };
20
+ this.#lastReport = Number.NEGATIVE_INFINITY;
21
+ }
22
+ get(): Record<string, unknown> {
23
+ return { ...this.#value };
24
+ }
25
+ dispose(): void {
26
+ this.#disposed = true;
27
+ this.#generation++;
28
+ }
29
+ report(renderer: Renderer, result: RenderTarget, time: number, interval: number): void {
30
+ if (this.#pending || time - this.#lastReport < interval) return;
31
+ this.#pending = true;
32
+ this.#lastReport = time;
33
+ const generation = this.#generation;
34
+ const current = () => !this.#disposed && generation === this.#generation;
35
+ const enabled = this.enabled;
36
+ const constant = this.constant;
37
+ const publish = (observation: Record<string, unknown>) => {
38
+ this.#value = observation;
39
+ };
40
+ const finished = () => {
41
+ this.#pending = false;
42
+ };
43
+ void renderer
44
+ .readRenderTargetPixelsAsync(result, 0, 0, 1, 1)
45
+ .then((values) => {
46
+ if (!current()) return;
47
+ if (
48
+ !(values instanceof Float32Array) ||
49
+ values.length < 4 ||
50
+ !Array.from(values).every(Number.isFinite) ||
51
+ (values[1] ?? 0) <= 0
52
+ )
53
+ throw new Error("Exposure readback is invalid; measurement is unavailable.");
54
+ const observation = {
55
+ measured: true,
56
+ applied: enabled(),
57
+ luminance: values[1],
58
+ exposureStops: enabled() ? values[0] : Math.log2(constant),
59
+ targetStops: values[2],
60
+ settled: values[3] === 1,
61
+ };
62
+ publish(observation);
63
+ console.info(`TN_AUTO_EXPOSURE:${JSON.stringify(observation)}`);
64
+ })
65
+ .catch((error: unknown) => {
66
+ if (!current()) return;
67
+ const observation = {
68
+ measured: false,
69
+ applied: enabled(),
70
+ reason: String(error),
71
+ };
72
+ publish(observation);
73
+ console.error(`TN_AUTO_EXPOSURE:${JSON.stringify(observation)}`);
74
+ })
75
+ .finally(() => {
76
+ finished();
77
+ });
78
+ }
79
+ }