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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-threenative",
3
- "version": "0.2.8",
3
+ "version": "0.2.10",
4
4
  "license": "MIT",
5
5
  "description": "Scaffold a readable ThreeNative game project.",
6
6
  "keywords": [
@@ -66,7 +66,8 @@
66
66
  "ktx-parse": "^1.1.0",
67
67
  "ktx2-encoder": "0.6.0",
68
68
  "meshoptimizer": "1.1.1",
69
- "three": "0.185.1"
69
+ "three": "0.185.1",
70
+ "@jridgewell/trace-mapping": "0.3.31"
70
71
  },
71
72
  "devDependencies": {
72
73
  "@gltf-transform/core": "4.4.2",
@@ -75,15 +76,17 @@
75
76
  "esbuild": "0.27.0",
76
77
  "publint": "0.3.22",
77
78
  "tsup": "8.5.1",
78
- "typescript": "5.9.3",
79
+ "typescript": "npm:@typescript/typescript6@6.0.2",
79
80
  "vite": "8.2.0",
80
- "@threenative/assets": "0.3.5",
81
- "@threenative/core": "0.3.4",
82
- "threenative-blender-mcp": "0.1.4",
83
- "@threenative/physics": "0.3.4"
81
+ "@typescript/native": "npm:typescript@7.0.2",
82
+ "@typescript/typescript6": "6.0.2",
83
+ "threenative-blender-mcp": "0.1.6",
84
+ "@threenative/core": "0.3.6",
85
+ "@threenative/assets": "0.3.7",
86
+ "@threenative/physics": "0.3.6"
84
87
  },
85
88
  "peerDependencies": {
86
- "@threenative/assets": ">=0.3.5 <0.4.0"
89
+ "@threenative/assets": ">=0.3.7 <0.4.0"
87
90
  },
88
91
  "scripts": {
89
92
  "build": "tsup --config tsup.config.ts && publint",
@@ -0,0 +1,225 @@
1
+ // Generated for you: ordinary Three.js GPU metering; exposure.ts owns the game's look.
2
+ import { type RenderTarget, Texture, Vector2 } from "three";
3
+ import { float, ivec2, nodeObject, texture, textureLoad, uniform, vec4 } from "three/tsl";
4
+ import {
5
+ type Node,
6
+ type NodeBuilder,
7
+ type NodeFrame,
8
+ NodeMaterial,
9
+ NodeUpdateType,
10
+ QuadMesh,
11
+ type Renderer,
12
+ RendererUtils,
13
+ TempNode,
14
+ } from "three/webgpu";
15
+ import {
16
+ type IExposureSettings,
17
+ exposureLuminance,
18
+ exposureMeter,
19
+ exposureReductionSizes,
20
+ validateExposureSettings,
21
+ } from "./exposure.js";
22
+
23
+ import {
24
+ type ColourTexture,
25
+ type Decode,
26
+ type Meter,
27
+ adaptExposure,
28
+ exposureBins,
29
+ exposureTarget,
30
+ exposureTiles,
31
+ histogramExposure,
32
+ histogramTiles,
33
+ reduceExposure,
34
+ } from "./exposureGraph.js";
35
+ import { ExposureReadback } from "./exposureReadback.js";
36
+
37
+ /** Scene-referred exposure changes light, never coverage/compositing alpha. */
38
+ export function applyExposure(colour: Node<"vec4">, exposure: Node<"float">): Node<"vec4"> {
39
+ return vec4(colour.rgb.mul(exposure), colour.a);
40
+ }
41
+
42
+ /** Owns scratch targets only. Never draws the world or installs another output transform. */
43
+ export class AutoExposureNode extends TempNode<"float"> {
44
+ static get type(): string {
45
+ return "AutoExposureNode";
46
+ }
47
+ readonly input: ColourTexture;
48
+ readonly settings: Readonly<IExposureSettings>;
49
+ readonly #constant: number;
50
+ readonly #size = new Vector2();
51
+ readonly #sourceSize = uniform(new Vector2(1, 1));
52
+ readonly #reduceSize = uniform(new Vector2(1, 1));
53
+ readonly #blockSize = uniform(new Vector2(1, 1));
54
+ readonly #delta = uniform(0);
55
+ readonly #resetMode = uniform(1); // 0 = history, 1 = seed, 2 = next measured target
56
+ readonly #seed = uniform(0);
57
+ readonly #enabled = uniform(false);
58
+ readonly #quad = new QuadMesh();
59
+ readonly #meterMaterial = new NodeMaterial();
60
+ readonly #reduceMaterial = new NodeMaterial();
61
+ readonly #tilesMaterial = new NodeMaterial();
62
+ readonly #histogramMaterial = new NodeMaterial();
63
+ readonly #adaptMaterial = new NodeMaterial();
64
+ readonly #tilesTarget = exposureTarget();
65
+ readonly #histogramTarget = exposureTarget();
66
+ #readTarget = exposureTarget();
67
+ #writeTarget = exposureTarget();
68
+ #levels: RenderTarget[] = [];
69
+ readonly #reduced = texture(new Texture());
70
+ readonly #blocks = texture(new Texture());
71
+ readonly #previous = texture(this.#readTarget.texture);
72
+ readonly #result = texture(this.#writeTarget.texture);
73
+ #disposed = false;
74
+ readonly #observation: ExposureReadback;
75
+ // Three's runtime accepts undefined on first use, but its declaration requires a state.
76
+ #rendererState: Parameters<typeof RendererUtils.resetRendererState>[1] | undefined;
77
+
78
+ constructor(
79
+ input: ColourTexture,
80
+ settings: IExposureSettings,
81
+ constantExposure: number,
82
+ meter: Meter = (colour, uv) => exposureMeter(colour, uv),
83
+ decode: Decode = (mean) => exposureLuminance(mean),
84
+ ) {
85
+ super("float");
86
+ validateExposureSettings(settings);
87
+ if (!Number.isFinite(Math.fround(constantExposure)) || Math.fround(constantExposure) <= 0)
88
+ throw new Error("Exposure constant must be finite and positive.");
89
+ this.input = input;
90
+ this.settings = Object.freeze({ ...settings });
91
+ const policy = this.settings;
92
+ this.#constant = constantExposure;
93
+ this.#seed.value = Math.log2(settings.initialExposure);
94
+ this.#enabled.value = settings.enabled;
95
+ this.#observation = new ExposureReadback(constantExposure, () => this.#enabled.value);
96
+ this.updateBeforeType = NodeUpdateType.FRAME;
97
+ this.#meterMaterial.fragmentNode = reduceExposure(input, this.#sourceSize, meter);
98
+ this.#reduceMaterial.fragmentNode = reduceExposure(this.#reduced, this.#reduceSize);
99
+ this.#tilesTarget.setSize(exposureBins, exposureTiles);
100
+ this.#histogramTarget.setSize(exposureBins, 1);
101
+ this.#tilesMaterial.fragmentNode = histogramTiles(this.#blocks, this.#blockSize, policy);
102
+ this.#histogramMaterial.fragmentNode = histogramExposure(texture(this.#tilesTarget.texture));
103
+ this.#adaptMaterial.fragmentNode = adaptExposure(
104
+ texture(this.#histogramTarget.texture),
105
+ this.#previous,
106
+ this.#resetMode,
107
+ this.#seed,
108
+ this.#delta,
109
+ policy,
110
+ decode,
111
+ );
112
+ }
113
+
114
+ override setup(builder: NodeBuilder): Node<"float"> {
115
+ // Force the existing pass dependency even in disabled mode; off never means unmeasured.
116
+ super.setup(builder);
117
+ return this.#enabled.select(
118
+ textureLoad(this.#result, ivec2(0)).r.exp2(),
119
+ float(this.#constant),
120
+ );
121
+ }
122
+
123
+ get exposureNode(): Node<"float"> {
124
+ return nodeObject(this);
125
+ }
126
+
127
+ reset(exposure?: number): void {
128
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
129
+ if (
130
+ exposure !== undefined &&
131
+ (!Number.isFinite(Math.fround(exposure)) || Math.fround(exposure) <= 0)
132
+ )
133
+ throw new Error("Exposure reset must be finite and positive.");
134
+ this.#resetMode.value = exposure === undefined ? 2 : 1;
135
+ if (exposure !== undefined) this.#seed.value = Math.log2(exposure);
136
+ this.#observation.invalidate();
137
+ }
138
+
139
+ setEnabled(enabled: boolean): void {
140
+ if (typeof enabled !== "boolean") throw new Error("Exposure enabled must be boolean.");
141
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
142
+ this.#enabled.value = enabled;
143
+ this.#observation.invalidate();
144
+ }
145
+
146
+ getObservation(): Record<string, unknown> {
147
+ return this.#observation.get();
148
+ }
149
+
150
+ override updateBefore(frame: NodeFrame): undefined {
151
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
152
+ const renderer = frame.renderer;
153
+ if (renderer === null) throw new Error("Exposure requires a renderer.");
154
+ if (!Number.isFinite(frame.deltaTime) || frame.deltaTime < 0 || !Number.isFinite(frame.time))
155
+ throw new Error("Exposure frame time must be finite and nonnegative.");
156
+ renderer.getDrawingBufferSize(this.#size);
157
+ // Level 0 meters 4x4 pixels, level 1 averages 16x16. The histogram gathers level 1.
158
+ const sizes = exposureReductionSizes(this.#size.x, this.#size.y).slice(0, 2);
159
+ this.#sourceSize.value.copy(this.#size);
160
+ this.#delta.value = Math.min(frame.deltaTime, this.settings.maxDelta);
161
+ while (this.#levels.length > sizes.length) this.#levels.pop()?.dispose();
162
+ for (const [i, [width, height]] of sizes.entries()) {
163
+ const level = this.#levels[i] ?? exposureTarget();
164
+ this.#levels[i] = level;
165
+ level.setSize(width, height);
166
+ }
167
+ this.#rendererState ??= RendererUtils.saveRendererState(renderer);
168
+ this.#rendererState = RendererUtils.resetRendererState(renderer, this.#rendererState);
169
+ try {
170
+ for (const [i, level] of this.#levels.entries()) {
171
+ const previous = this.#levels[i - 1];
172
+ if (previous !== undefined) {
173
+ this.#reduced.value = previous.texture;
174
+ this.#reduceSize.value.set(previous.width, previous.height);
175
+ }
176
+ this.#quad.material = i === 0 ? this.#meterMaterial : this.#reduceMaterial;
177
+ renderer.setRenderTarget(level);
178
+ this.#quad.render(renderer);
179
+ }
180
+ const final = this.#levels.at(-1);
181
+ if (final === undefined) throw new Error("Exposure reduction is empty.");
182
+ this.#blocks.value = final.texture;
183
+ this.#blockSize.value.set(final.width, final.height);
184
+ this.#quad.material = this.#tilesMaterial;
185
+ renderer.setRenderTarget(this.#tilesTarget);
186
+ this.#quad.render(renderer);
187
+ this.#quad.material = this.#histogramMaterial;
188
+ renderer.setRenderTarget(this.#histogramTarget);
189
+ this.#quad.render(renderer);
190
+ const write = this.#writeTarget;
191
+ this.#previous.value = this.#readTarget.texture;
192
+ this.#quad.material = this.#adaptMaterial;
193
+ renderer.setRenderTarget(write);
194
+ this.#quad.render(renderer);
195
+ this.#result.value = write.texture;
196
+ this.#writeTarget = this.#readTarget;
197
+ this.#readTarget = write;
198
+ this.#resetMode.value = 0;
199
+ this.#observation.report(renderer, write, frame.time, this.settings.reportInterval);
200
+ } finally {
201
+ RendererUtils.restoreRendererState(renderer, this.#rendererState);
202
+ }
203
+ }
204
+
205
+ override dispose(): void {
206
+ if (this.#disposed) return;
207
+ this.#disposed = true;
208
+ this.#observation.dispose();
209
+ for (const level of [
210
+ ...this.#levels,
211
+ this.#tilesTarget,
212
+ this.#histogramTarget,
213
+ this.#readTarget,
214
+ this.#writeTarget,
215
+ ])
216
+ level.dispose();
217
+ this.#levels = [];
218
+ this.#meterMaterial.dispose();
219
+ this.#reduceMaterial.dispose();
220
+ this.#tilesMaterial.dispose();
221
+ this.#histogramMaterial.dispose();
222
+ this.#adaptMaterial.dispose();
223
+ super.dispose();
224
+ }
225
+ }
@@ -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
+ }
@@ -0,0 +1,22 @@
1
+ --- a/dist/index.mjs
2
+ +++ b/dist/index.mjs
3
+ @@ -12,7 +12,7 @@
4
+ Timers:`);let i=-1/0,l=new Map;for(let[o,{value:s}]of this.#t){let a=`${(Number(s)/1e6).toFixed(2)}ms`;l.set(o,a),i=Math.max(i,a.length)}for(let o of this.#t.keys()){let s=o.split("//").length;t.push(`${pe(`[${l.get(o).padStart(i," ")}]`)}${" ".repeat(s-1)}${s===1?" ":pe(" \u21B3 ")}${o.split("//").pop()} ${this.#r.get(o).value===1?"":pe(Nt(`\xD7 ${this.#r.get(o).value}`))}`.trimEnd())}r(`
5
+ ${t.join(`
6
+ `)}
7
+ -`),this.reset()}[Symbol.dispose](){this.shouldReport&&this.report()}};function pe(e){return`\x1B[2m${e}\x1B[22m`}function Nt(e){return`\x1B[34m${e}\x1B[39m`}import Xr from"@jridgewell/remapping";import{Features as ne,transform as en}from"lightningcss";import tn from"magic-string";function wu(e,{file:r="input.css",minify:t=!1,map:n}={}){function i(a,u){return en({filename:r,code:a,minify:t,sourceMap:typeof u<"u",inputSourceMap:u,drafts:{customMedia:!0},nonStandard:{deepSelectorCombinator:!0},include:ne.Nesting|ne.MediaQueries,exclude:ne.LogicalProperties|ne.DirSelector|ne.LightDark,targets:{safari:16<<16|1024,ios_saf:16<<16|1024,firefox:8388608,chrome:7274496},errorRecovery:!0})}let l=i(Buffer.from(e),n);if(n=l.map?.toString(),l.warnings=l.warnings.filter(a=>!(/'(deep|slotted|global)' is not recognized as a valid pseudo-/.test(a.message)||/Unknown at rule: @position-try/.test(a.message))),l.warnings.length>0){let a=e.split(`
8
+ +`),this.reset()}[Symbol.dispose](){this.shouldReport&&this.report()}};function pe(e){return`\x1B[2m${e}\x1B[22m`}function Nt(e){return`\x1B[34m${e}\x1B[39m`}import Xr from"@jridgewell/remapping";import{Features as ne,transform as en}from"lightningcss";import tn from"magic-string";function wu(e,{file:r="input.css",minify:t=!1,map:n}={}){function i(a,u){const result=en({filename:r,code:a,minify:t,sourceMap:typeof u<"u",drafts:{customMedia:!0},nonStandard:{deepSelectorCombinator:!0},include:ne.Nesting|ne.MediaQueries,exclude:ne.LogicalProperties|ne.DirSelector|ne.LightDark,targets:{safari:16<<16|1024,ios_saf:16<<16|1024,firefox:8388608,chrome:7274496},errorRecovery:!0});if(u!==void 0&&result.map)result.map=Buffer.from(Xr([JSON.parse(result.map.toString()),JSON.parse(u)],()=>null).toString());return result}let l=i(Buffer.from(e),n);if(n=l.map?.toString(),l.warnings=l.warnings.filter(a=>!(/'(deep|slotted|global)' is not recognized as a valid pseudo-/.test(a.message)||/Unknown at rule: @position-try/.test(a.message))),l.warnings.length>0){let a=e.split(`
9
+ `),u=[`Found ${l.warnings.length} ${l.warnings.length===1?"warning":"warnings"} while optimizing generated CSS:`];for(let[p,c]of l.warnings.entries()){u.push(""),l.warnings.length>1&&u.push(`Issue #${p+1}:`);let f=2,d=Math.max(0,c.loc.line-f-1),m=Math.min(a.length,c.loc.line+f),C=a.slice(d,m).map((k,I)=>d+I+1===c.loc.line?`${ie("\u2502")} ${k}`:ie(`\u2502 ${k}`));C.splice(c.loc.line-d,0,`${ie("\u2506")}${" ".repeat(c.loc.column-1)} ${rn(`${ie("^--")} ${c.message}`)}`,`${ie("\u2506")}`),u.push(...C)}u.push(""),console.warn(u.join(`
10
+ `))}l=i(l.code,n),n=l.map?.toString();let o=l.code.toString(),s=new tn(o);if(s.replaceAll("@media not (","@media not all and ("),n!==void 0&&s.hasChanged()){let a=s.generateMap({source:"original",hires:"boundary"}).toString();n=Xr([a,n],()=>null).toString()}return o=s.toString(),{code:o,map:n}}function ie(e){return`\x1B[2m${e}\x1B[22m`}function rn(e){return`\x1B[33m${e}\x1B[39m`}import{SourceMapGenerator as nn}from"source-map-js";function on(e){let r=new nn,t=1,n=new h(i=>({url:i?.url??`<unknown ${t++}>`,content:i?.content??"<none>"}));for(let i of e.mappings){let l=n.get(i.originalPosition?.source??null);r.addMapping({generated:i.generatedPosition,original:i.originalPosition,source:l.url,name:i.name}),r.setSourceContent(l.url,l.content)}return r.toString()}function Au(e){let r=typeof e=="string"?e:on(e);function t(n){return`/*# sourceMappingURL=${n} */
11
+ `}return{raw:r,get inline(){let n=Buffer.from(r,"utf-8").toString("base64");return t(`data:application/json;base64,${n}`)},comment:t}}if(!process.versions.bun)if(M.registerHooks)M.registerHooks({resolve:Ie});else{let e=M.createRequire(import.meta.url);M.register?.(ln(e.resolve("@tailwindcss/node/esm-cache-loader")))}export{lu as Features,Et as Instrumentation,au as Polyfills,pu as __unstable__loadDesignSystem,fu as compile,cu as compileAst,me as env,$t as loadModule,Ve as normalizePath,wu as optimize,Au as toSourceMap};
12
+ --- a/dist/index.js
13
+ +++ b/dist/index.js
14
+ @@ -12,7 +12,7 @@
15
+ Timers:`);let i=-1/0,l=new Map;for(let[o,{value:s}]of this.#t){let a=`${(Number(s)/1e6).toFixed(2)}ms`;l.set(o,a),i=Math.max(i,a.length)}for(let o of this.#t.keys()){let s=o.split("//").length;t.push(`${we(`[${l.get(o).padStart(i," ")}]`)}${" ".repeat(s-1)}${s===1?" ":we(" \u21B3 ")}${o.split("//").pop()} ${this.#r.get(o).value===1?"":we(It(`\xD7 ${this.#r.get(o).value}`))}`.trimEnd())}r(`
16
+ ${t.join(`
17
+ `)}
18
+ -`),this.reset()}[Symbol.dispose](){this.shouldReport&&this.report()}};function we(e){return`\x1B[2m${e}\x1B[22m`}function It(e){return`\x1B[34m${e}\x1B[39m`}var Ut=N(require("@jridgewell/remapping")),L=require("lightningcss"),Lt=N(require("magic-string"));function gn(e,{file:r="input.css",minify:t=!1,map:n}={}){function i(a,u){return(0,L.transform)({filename:r,code:a,minify:t,sourceMap:typeof u<"u",inputSourceMap:u,drafts:{customMedia:!0},nonStandard:{deepSelectorCombinator:!0},include:L.Features.Nesting|L.Features.MediaQueries,exclude:L.Features.LogicalProperties|L.Features.DirSelector|L.Features.LightDark,targets:{safari:16<<16|1024,ios_saf:16<<16|1024,firefox:8388608,chrome:7274496},errorRecovery:!0})}let l=i(Buffer.from(e),n);if(n=l.map?.toString(),l.warnings=l.warnings.filter(a=>!(/'(deep|slotted|global)' is not recognized as a valid pseudo-/.test(a.message)||/Unknown at rule: @position-try/.test(a.message))),l.warnings.length>0){let a=e.split(`
19
+ +`),this.reset()}[Symbol.dispose](){this.shouldReport&&this.report()}};function we(e){return`\x1B[2m${e}\x1B[22m`}function It(e){return`\x1B[34m${e}\x1B[39m`}var Ut=N(require("@jridgewell/remapping")),L=require("lightningcss"),Lt=N(require("magic-string"));function gn(e,{file:r="input.css",minify:t=!1,map:n}={}){function i(a,u){const result=(0,L.transform)({filename:r,code:a,minify:t,sourceMap:typeof u<"u",drafts:{customMedia:!0},nonStandard:{deepSelectorCombinator:!0},include:L.Features.Nesting|L.Features.MediaQueries,exclude:L.Features.LogicalProperties|L.Features.DirSelector|L.Features.LightDark,targets:{safari:16<<16|1024,ios_saf:16<<16|1024,firefox:8388608,chrome:7274496},errorRecovery:!0});if(u!==void 0&&result.map)result.map=Buffer.from((0,Ut.default)([JSON.parse(result.map.toString()),JSON.parse(u)],()=>null).toString());return result}let l=i(Buffer.from(e),n);if(n=l.map?.toString(),l.warnings=l.warnings.filter(a=>!(/'(deep|slotted|global)' is not recognized as a valid pseudo-/.test(a.message)||/Unknown at rule: @position-try/.test(a.message))),l.warnings.length>0){let a=e.split(`
20
+ `),u=[`Found ${l.warnings.length} ${l.warnings.length===1?"warning":"warnings"} while optimizing generated CSS:`];for(let[p,c]of l.warnings.entries()){u.push(""),l.warnings.length>1&&u.push(`Issue #${p+1}:`);let f=2,d=Math.max(0,c.loc.line-f-1),m=Math.min(a.length,c.loc.line+f),C=a.slice(d,m).map((k,z)=>d+z+1===c.loc.line?`${oe("\u2502")} ${k}`:oe(`\u2502 ${k}`));C.splice(c.loc.line-d,0,`${oe("\u2506")}${" ".repeat(c.loc.column-1)} ${hn(`${oe("^--")} ${c.message}`)}`,`${oe("\u2506")}`),u.push(...C)}u.push(""),console.warn(u.join(`
21
+ `))}l=i(l.code,n),n=l.map?.toString();let o=l.code.toString(),s=new Lt.default(o);if(s.replaceAll("@media not (","@media not all and ("),n!==void 0&&s.hasChanged()){let a=s.generateMap({source:"original",hires:"boundary"}).toString();n=(0,Ut.default)([a,n],()=>null).toString()}return o=s.toString(),{code:o,map:n}}function oe(e){return`\x1B[2m${e}\x1B[22m`}function hn(e){return`\x1B[33m${e}\x1B[39m`}var zt=require("source-map-js");function vn(e){let r=new zt.SourceMapGenerator,t=1,n=new h(i=>({url:i?.url??`<unknown ${t++}>`,content:i?.content??"<none>"}));for(let i of e.mappings){let l=n.get(i.originalPosition?.source??null);r.addMapping({generated:i.generatedPosition,original:i.originalPosition,source:l.url,name:i.name}),r.setSourceContent(l.url,l.content)}return r.toString()}function kn(e){let r=typeof e=="string"?e:vn(e);function t(n){return`/*# sourceMappingURL=${n} */
22
+ `}return{raw:r,get inline(){let n=Buffer.from(r,"utf-8").toString("base64");return t(`data:application/json;base64,${n}`)},comment:t}}process.versions.bun||(le.registerHooks?le.registerHooks({resolve:He}):le.register?.((0,Kt.pathToFileURL)(require.resolve("@tailwindcss/node/esm-cache-loader"))));0&&(module.exports={Features,Instrumentation,Polyfills,__unstable__loadDesignSystem,compile,compileAst,env,loadModule,normalizePath,optimize,toSourceMap});