create-threenative 0.2.8 → 0.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (431) hide show
  1. package/agent-docs/references/assertion-reference.md +87 -35
  2. package/agent-docs/references/auto-exposure.md +57 -0
  3. package/agent-docs/references/capability-reference.md +1097 -23
  4. package/agent-docs/references/debug-surface.md +6 -0
  5. package/agent-docs/references/finding-assets.md +46 -10
  6. package/agent-docs/references/performance-basics.md +5 -4
  7. package/agent-docs/references/terrain-authoring.md +140 -0
  8. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  9. package/capabilities.json +1210 -27
  10. package/dist/index.d.ts +28 -3
  11. package/dist/index.js +396 -166
  12. package/dist/threenative.js +986 -235
  13. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  14. package/dist/web-engine-decal-geometry.js +184 -0
  15. package/dist/web-engine-gltf-loader.js +196 -0
  16. package/dist/web-engine-hdr-loader.js +190 -0
  17. package/dist/web-engine-lut-cube-loader.js +122 -0
  18. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  19. package/dist/web-engine-mesh-bvh.js +32 -0
  20. package/dist/web-engine-post-effects.js +168 -0
  21. package/dist/web-engine-runtime.js +42506 -0
  22. package/package.json +11 -8
  23. package/template-assets/autoExposure.ts +225 -0
  24. package/template-assets/exposure.ts +111 -0
  25. package/template-assets/exposureGraph.ts +178 -0
  26. package/template-assets/exposureReadback.ts +79 -0
  27. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  28. package/template-assets/patches/three@0.185.1.patch +6594 -700
  29. package/template-assets/patches/vite@8.2.0.patch +422 -0
  30. package/template-assets/worldEnvironment.ts +433 -30
  31. package/templates/action-rpg/AGENTS.md +11 -10
  32. package/templates/action-rpg/CLAUDE.md +11 -10
  33. package/templates/action-rpg/package.json +13 -10
  34. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  35. package/templates/action-rpg/src/progress.ts +0 -4
  36. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  37. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  38. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  39. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  40. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  41. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  42. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  43. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  44. package/templates/action-rpg/src/render/exposure.ts +111 -0
  45. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  46. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  47. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  48. package/templates/action-rpg/src/render/lighting.ts +26 -1
  49. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  50. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  51. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  52. package/templates/action-rpg/src/render/quality.ts +61 -2
  53. package/templates/action-rpg/src/render/sky.ts +21 -1
  54. package/templates/action-rpg/src/render/vfx.ts +133 -58
  55. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  56. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  57. package/templates/action-rpg/threenative.config.ts +3 -0
  58. package/templates/action-rpg/vite.config.ts +10 -2
  59. package/templates/minimal/AGENTS.md +9 -10
  60. package/templates/minimal/CLAUDE.md +9 -10
  61. package/templates/minimal/package.json +11 -9
  62. package/templates/minimal/playtests/play.playtest.json +7 -1
  63. package/templates/minimal/playtests/sky.playtest.json +10 -1
  64. package/templates/minimal/src/render/autoExposure.ts +225 -0
  65. package/templates/minimal/src/render/backlightControls.ts +66 -0
  66. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  67. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  68. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  69. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  70. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  71. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  72. package/templates/minimal/src/render/exposure.ts +111 -0
  73. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  74. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  75. package/templates/minimal/src/render/heightFog.ts +118 -0
  76. package/templates/minimal/src/render/lighting.ts +25 -1
  77. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  78. package/templates/minimal/src/render/materialLighting.ts +146 -0
  79. package/templates/minimal/src/render/postprocessing.ts +16 -2
  80. package/templates/minimal/src/render/quality.ts +60 -2
  81. package/templates/minimal/src/render/sky.ts +21 -1
  82. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  83. package/templates/minimal/src/scenes/Play.ts +50 -1
  84. package/templates/minimal/vite.config.ts +10 -2
  85. package/templates/platformer/AGENTS.md +7 -5
  86. package/templates/platformer/CLAUDE.md +7 -5
  87. package/templates/platformer/package.json +13 -10
  88. package/templates/platformer/playtests/performance.playtest.json +7 -1
  89. package/templates/platformer/src/render/autoExposure.ts +225 -0
  90. package/templates/platformer/src/render/backlightControls.ts +66 -0
  91. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  92. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  93. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  94. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  95. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  96. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  97. package/templates/platformer/src/render/exposure.ts +111 -0
  98. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  99. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  100. package/templates/platformer/src/render/heightFog.ts +118 -0
  101. package/templates/platformer/src/render/lighting.ts +26 -1
  102. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  103. package/templates/platformer/src/render/materialLighting.ts +155 -0
  104. package/templates/platformer/src/render/materials.ts +7 -2
  105. package/templates/platformer/src/render/palette.ts +3 -3
  106. package/templates/platformer/src/render/postprocessing.ts +17 -2
  107. package/templates/platformer/src/render/quality.ts +61 -2
  108. package/templates/platformer/src/render/sky.ts +72 -23
  109. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  110. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  111. package/templates/platformer/src/scenes/Play.ts +70 -6
  112. package/templates/platformer/vite.config.ts +10 -2
  113. package/templates/puzzle/AGENTS.md +10 -9
  114. package/templates/puzzle/CLAUDE.md +10 -9
  115. package/templates/puzzle/package.json +13 -10
  116. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  117. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  118. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  119. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  120. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  121. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  122. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  123. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  124. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  125. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  126. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  127. package/templates/puzzle/src/render/exposure.ts +111 -0
  128. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  129. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  130. package/templates/puzzle/src/render/heightFog.ts +118 -0
  131. package/templates/puzzle/src/render/lighting.ts +33 -1
  132. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  133. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  134. package/templates/puzzle/src/render/materials.ts +1 -1
  135. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  136. package/templates/puzzle/src/render/quality.ts +62 -1
  137. package/templates/puzzle/src/render/sky.ts +20 -1
  138. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  139. package/templates/puzzle/src/scenes/Play.ts +51 -2
  140. package/templates/puzzle/vite.config.ts +10 -2
  141. package/templates/racing/AGENTS.md +8 -7
  142. package/templates/racing/CLAUDE.md +8 -7
  143. package/templates/racing/package.json +13 -10
  144. package/templates/racing/playtests/performance.playtest.json +7 -1
  145. package/templates/racing/playtests/survives.playtest.json +6 -0
  146. package/templates/racing/src/render/autoExposure.ts +225 -0
  147. package/templates/racing/src/render/backlightControls.ts +66 -0
  148. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  149. package/templates/racing/src/render/environmentContribution.ts +188 -0
  150. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  151. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  152. package/templates/racing/src/render/environmentSampling.ts +193 -0
  153. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  154. package/templates/racing/src/render/exposure.ts +111 -0
  155. package/templates/racing/src/render/exposureGraph.ts +178 -0
  156. package/templates/racing/src/render/exposureReadback.ts +79 -0
  157. package/templates/racing/src/render/heightFog.ts +118 -0
  158. package/templates/racing/src/render/lighting.ts +29 -1
  159. package/templates/racing/src/render/materialAssignments.ts +160 -0
  160. package/templates/racing/src/render/materialLighting.ts +155 -0
  161. package/templates/racing/src/render/palette.ts +1 -10
  162. package/templates/racing/src/render/postprocessing.ts +17 -2
  163. package/templates/racing/src/render/quality.ts +61 -2
  164. package/templates/racing/src/render/shapes.ts +0 -25
  165. package/templates/racing/src/render/sky.ts +25 -5
  166. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  167. package/templates/racing/src/scenes/Race.ts +110 -13
  168. package/templates/racing/src/track/circuit.ts +0 -9
  169. package/templates/racing/vite.config.ts +10 -2
  170. package/templates/rain/AGENTS.md +8 -9
  171. package/templates/rain/CLAUDE.md +8 -9
  172. package/templates/rain/native-playtests/boot.playtest.json +11 -1
  173. package/templates/rain/package.json +14 -10
  174. package/templates/rain/playtests/automation.playtest.json +1 -1
  175. package/templates/rain/playtests/performance.playtest.json +11 -1
  176. package/templates/rain/playtests/tiers.playtest.json +15 -0
  177. package/templates/rain/playtests/weather.playtest.json +1 -1
  178. package/templates/rain/src/game.ts +1 -34
  179. package/templates/rain/src/render/autoExposure.ts +225 -0
  180. package/templates/rain/src/render/exposure.ts +111 -0
  181. package/templates/rain/src/render/exposureGraph.ts +178 -0
  182. package/templates/rain/src/render/exposureReadback.ts +79 -0
  183. package/templates/rain/src/render/postprocessing.ts +3 -0
  184. package/templates/rain/src/render/quality.ts +27 -1
  185. package/templates/rain/src/render/worldEnvironment.ts +433 -30
  186. package/templates/rain/src/scenes/Boot.ts +14 -0
  187. package/templates/rain/src/state.ts +5 -1
  188. package/templates/rain/src/ui/GameUi.tsx +6 -6
  189. package/templates/rain/tools/generate-shaders.mjs +1 -1
  190. package/templates/rain/vite.config.ts +10 -2
  191. package/templates/rts/AGENTS.md +10 -11
  192. package/templates/rts/CLAUDE.md +10 -11
  193. package/templates/rts/package.json +12 -9
  194. package/templates/rts/playtests/performance.playtest.json +7 -1
  195. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  196. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  197. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  198. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  199. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  200. package/templates/rts/src/render/army.ts +10 -2
  201. package/templates/rts/src/render/autoExposure.ts +225 -0
  202. package/templates/rts/src/render/backlightControls.ts +66 -0
  203. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  204. package/templates/rts/src/render/environmentContribution.ts +188 -0
  205. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  206. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  207. package/templates/rts/src/render/environmentSampling.ts +193 -0
  208. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  209. package/templates/rts/src/render/exposure.ts +111 -0
  210. package/templates/rts/src/render/exposureGraph.ts +178 -0
  211. package/templates/rts/src/render/exposureReadback.ts +79 -0
  212. package/templates/rts/src/render/heightFog.ts +118 -0
  213. package/templates/rts/src/render/lighting.ts +26 -1
  214. package/templates/rts/src/render/materialAssignments.ts +160 -0
  215. package/templates/rts/src/render/materialLighting.ts +155 -0
  216. package/templates/rts/src/render/postprocessing.ts +8 -2
  217. package/templates/rts/src/render/quality.ts +61 -2
  218. package/templates/rts/src/render/sky.ts +21 -1
  219. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  220. package/templates/rts/src/scenes/Play.ts +54 -3
  221. package/templates/rts/src/sim/ai.ts +0 -1
  222. package/templates/rts/src/sim/terrain.ts +0 -4
  223. package/templates/rts/vite.config.ts +10 -2
  224. package/templates/runner/AGENTS.md +10 -8
  225. package/templates/runner/CLAUDE.md +10 -8
  226. package/templates/runner/package.json +13 -10
  227. package/templates/runner/playtests/performance.playtest.json +10 -1
  228. package/templates/runner/src/physics.ts +0 -1
  229. package/templates/runner/src/render/autoExposure.ts +225 -0
  230. package/templates/runner/src/render/backlightControls.ts +66 -0
  231. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  232. package/templates/runner/src/render/environmentContribution.ts +188 -0
  233. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  234. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  235. package/templates/runner/src/render/environmentSampling.ts +193 -0
  236. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  237. package/templates/runner/src/render/exposure.ts +111 -0
  238. package/templates/runner/src/render/exposureGraph.ts +178 -0
  239. package/templates/runner/src/render/exposureReadback.ts +79 -0
  240. package/templates/runner/src/render/heightFog.ts +118 -0
  241. package/templates/runner/src/render/lighting.ts +26 -1
  242. package/templates/runner/src/render/materialAssignments.ts +160 -0
  243. package/templates/runner/src/render/materialLighting.ts +155 -0
  244. package/templates/runner/src/render/postprocessing.ts +17 -2
  245. package/templates/runner/src/render/quality.ts +61 -2
  246. package/templates/runner/src/render/sky.ts +21 -1
  247. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  248. package/templates/runner/src/scenes/Run.ts +67 -2
  249. package/templates/runner/threenative.config.ts +3 -0
  250. package/templates/runner/vite.config.ts +10 -2
  251. package/templates/sailing/AGENTS.md +14 -13
  252. package/templates/sailing/CLAUDE.md +14 -13
  253. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  254. package/templates/sailing/package.json +13 -10
  255. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  256. package/templates/sailing/src/entities/Ship.ts +38 -18
  257. package/templates/sailing/src/render/autoExposure.ts +225 -0
  258. package/templates/sailing/src/render/backlightControls.ts +66 -0
  259. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  260. package/templates/sailing/src/render/camera.ts +12 -4
  261. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  262. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  263. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  264. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  265. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  266. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  267. package/templates/sailing/src/render/exposure.ts +111 -0
  268. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  269. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  270. package/templates/sailing/src/render/heightFog.ts +118 -0
  271. package/templates/sailing/src/render/lighting.ts +26 -1
  272. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  273. package/templates/sailing/src/render/materialLighting.ts +155 -0
  274. package/templates/sailing/src/render/ocean.ts +71 -53
  275. package/templates/sailing/src/render/postprocessing.ts +16 -2
  276. package/templates/sailing/src/render/props.ts +0 -45
  277. package/templates/sailing/src/render/quality.ts +61 -1
  278. package/templates/sailing/src/render/sky.ts +21 -1
  279. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  280. package/templates/sailing/src/scenes/Boot.ts +12 -1
  281. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  282. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  283. package/templates/sailing/threenative.config.ts +3 -0
  284. package/templates/sailing/vite.config.ts +10 -2
  285. package/templates/shooter/AGENTS.md +8 -6
  286. package/templates/shooter/CLAUDE.md +8 -6
  287. package/templates/shooter/package.json +13 -10
  288. package/templates/shooter/playtests/performance.playtest.json +7 -1
  289. package/templates/shooter/src/entities/Enemy.ts +0 -15
  290. package/templates/shooter/src/entities/Rifle.ts +38 -1
  291. package/templates/shooter/src/render/autoExposure.ts +225 -0
  292. package/templates/shooter/src/render/backlightControls.ts +66 -0
  293. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  294. package/templates/shooter/src/render/camera.ts +1 -12
  295. package/templates/shooter/src/render/decals.ts +299 -5
  296. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  297. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  298. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  299. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  300. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  301. package/templates/shooter/src/render/exposure.ts +111 -0
  302. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  303. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  304. package/templates/shooter/src/render/gunfx.ts +0 -1
  305. package/templates/shooter/src/render/heightFog.ts +118 -0
  306. package/templates/shooter/src/render/lighting.ts +26 -1
  307. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  308. package/templates/shooter/src/render/materialLighting.ts +155 -0
  309. package/templates/shooter/src/render/postprocessing.ts +17 -2
  310. package/templates/shooter/src/render/quality.ts +61 -2
  311. package/templates/shooter/src/render/scale.ts +2 -93
  312. package/templates/shooter/src/render/sky.ts +21 -1
  313. package/templates/shooter/src/render/vehicles.ts +0 -17
  314. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  315. package/templates/shooter/src/scenes/Play.ts +64 -2
  316. package/templates/shooter/vite.config.ts +10 -2
  317. package/templates/snow/AGENTS.md +8 -6
  318. package/templates/snow/CLAUDE.md +8 -6
  319. package/templates/snow/package.json +13 -10
  320. package/templates/snow/src/render/autoExposure.ts +225 -0
  321. package/templates/snow/src/render/backlightControls.ts +66 -0
  322. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  323. package/templates/snow/src/render/environmentContribution.ts +188 -0
  324. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  325. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/snow/src/render/environmentSampling.ts +193 -0
  327. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  328. package/templates/snow/src/render/exposure.ts +111 -0
  329. package/templates/snow/src/render/exposureGraph.ts +178 -0
  330. package/templates/snow/src/render/exposureReadback.ts +79 -0
  331. package/templates/snow/src/render/heightFog.ts +118 -0
  332. package/templates/snow/src/render/lighting.ts +33 -1
  333. package/templates/snow/src/render/materialAssignments.ts +160 -0
  334. package/templates/snow/src/render/materialLighting.ts +155 -0
  335. package/templates/snow/src/render/postprocessing.ts +16 -2
  336. package/templates/snow/src/render/quality.ts +59 -1
  337. package/templates/snow/src/render/sky.ts +21 -2
  338. package/templates/snow/src/render/worldEnvironment.ts +433 -30
  339. package/templates/snow/src/scenes/Snow.ts +29 -1
  340. package/templates/snow/threenative.config.ts +3 -0
  341. package/templates/snow/vite.config.ts +10 -2
  342. package/templates/starter/AGENTS.md +11 -16
  343. package/templates/starter/CLAUDE.md +11 -16
  344. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  345. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  346. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  347. package/templates/starter/package.json +13 -10
  348. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  349. package/templates/starter/playtests/movement.playtest.json +192 -0
  350. package/templates/starter/playtests/play.playtest.json +18 -2
  351. package/templates/starter/playtests/production-readiness.playtest.json +43 -1
  352. package/templates/starter/public/grade.cube +735 -0
  353. package/templates/starter/src/entities/Crate.ts +4 -0
  354. package/templates/starter/src/entities/Player.ts +79 -18
  355. package/templates/starter/src/game.ts +1 -0
  356. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  357. package/templates/starter/src/render/autoExposure.ts +225 -0
  358. package/templates/starter/src/render/backlightControls.ts +66 -0
  359. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  360. package/templates/starter/src/render/environmentContribution.ts +188 -0
  361. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  362. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  363. package/templates/starter/src/render/environmentSampling.ts +193 -0
  364. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  365. package/templates/starter/src/render/exposure.ts +111 -0
  366. package/templates/starter/src/render/exposureGraph.ts +178 -0
  367. package/templates/starter/src/render/exposureReadback.ts +79 -0
  368. package/templates/starter/src/render/grade.ts +157 -0
  369. package/templates/starter/src/render/heightFog.ts +118 -0
  370. package/templates/starter/src/render/lighting.ts +26 -1
  371. package/templates/starter/src/render/materialAssignments.ts +160 -0
  372. package/templates/starter/src/render/materialLighting.ts +155 -0
  373. package/templates/starter/src/render/postprocessing.ts +90 -4
  374. package/templates/starter/src/render/quality.ts +80 -8
  375. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  376. package/templates/starter/src/render/rendererGate.ts +36 -0
  377. package/templates/starter/src/render/sky.ts +23 -1
  378. package/templates/starter/src/render/temporalAA.ts +197 -0
  379. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  380. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  381. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  382. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  383. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  384. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  385. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  386. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  387. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  388. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  389. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  390. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  391. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  392. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  393. package/templates/starter/src/render/temporalResolve.ts +139 -0
  394. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  395. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  396. package/templates/starter/src/render/volumetricFog.ts +124 -0
  397. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  398. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  399. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  400. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  401. package/templates/starter/src/scenes/Play.ts +110 -1
  402. package/templates/starter/src/state.ts +1 -0
  403. package/templates/starter/src/ui/Hud.tsx +1 -1
  404. package/templates/starter/src/ui/Menu.tsx +1 -1
  405. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  406. package/templates/starter/vite.config.ts +10 -2
  407. package/templates/tower-defense/AGENTS.md +10 -9
  408. package/templates/tower-defense/CLAUDE.md +10 -9
  409. package/templates/tower-defense/package.json +13 -10
  410. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  411. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  412. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  413. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  414. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  415. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  416. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  417. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  418. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  419. package/templates/tower-defense/src/render/exposure.ts +111 -0
  420. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  421. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  422. package/templates/tower-defense/src/render/lighting.ts +33 -1
  423. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  424. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  425. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  426. package/templates/tower-defense/src/render/quality.ts +61 -2
  427. package/templates/tower-defense/src/render/shapes.ts +0 -3
  428. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  429. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  430. package/templates/tower-defense/vite.config.ts +10 -2
  431. package/templates/minimal/src/scenes/Boot.ts +0 -5
@@ -0,0 +1,66 @@
1
+ import type { Camera, Color, Object3D, Vector3 } from "three";
2
+ import type { IBacklightControls } from "./backlightMaterial.js";
3
+ function finiteColor(color: Color) {
4
+ return (
5
+ Number.isFinite(color.r) &&
6
+ color.r >= 0 &&
7
+ Number.isFinite(color.g) &&
8
+ color.g >= 0 &&
9
+ Number.isFinite(color.b) &&
10
+ color.b >= 0
11
+ );
12
+ }
13
+ export function validateControls(controls: IBacklightControls) {
14
+ if (
15
+ !Number.isFinite(controls.rimGain) ||
16
+ controls.rimGain < 0 ||
17
+ !Number.isFinite(controls.key.intensity) ||
18
+ controls.key.intensity < 0 ||
19
+ !finiteColor(controls.key.color) ||
20
+ !Number.isFinite(controls.fillGain) ||
21
+ controls.fillGain < 0 ||
22
+ !Number.isFinite(controls.fillAngularSize) ||
23
+ controls.fillAngularSize <= 0 ||
24
+ controls.fillAngularSize > 1.5 ||
25
+ !Number.isFinite(controls.fillDirection.lengthSq()) ||
26
+ controls.fillDirection.lengthSq() === 0 ||
27
+ !finiteColor(controls.fillColor)
28
+ )
29
+ throw new Error(
30
+ "Backlight controls require finite nonnegative gains, a direction and angular size in (0, 1.5].",
31
+ );
32
+ }
33
+ export function resolveKey(
34
+ controls: IBacklightControls,
35
+ direction: Vector3,
36
+ target: Vector3,
37
+ camera: Camera = controls.camera,
38
+ ) {
39
+ validateControls(controls);
40
+ // Read the renderer/game-updated matrices, as upstream Three light uniforms do.
41
+ // Targets outside the scene must be updated by their owner before rendering.
42
+ // Never mutate shared light/ancestor matrices inside a material render callback.
43
+ target.setFromMatrixPosition(controls.key.target.matrixWorld);
44
+ direction.setFromMatrixPosition(controls.key.matrixWorld).sub(target);
45
+ if (
46
+ !Number.isFinite(direction.x) ||
47
+ !Number.isFinite(direction.y) ||
48
+ !Number.isFinite(direction.z)
49
+ )
50
+ throw new Error("Key endpoints must be finite.");
51
+ const lengthSq = direction.lengthSq();
52
+ if (!Number.isFinite(lengthSq)) throw new Error("Key direction magnitude must be finite.");
53
+ if (lengthSq <= 1e-12) {
54
+ direction.set(0, 1, 0);
55
+ return 0;
56
+ }
57
+ direction.normalize();
58
+ if (!controls.key.layers.test(camera.layers)) return 0;
59
+ let current: Object3D | null = controls.key;
60
+ while (current !== null) {
61
+ if (!current.visible) return 0;
62
+ if (current === controls.scene) return controls.key.intensity;
63
+ current = current.parent;
64
+ }
65
+ return 0;
66
+ }
@@ -0,0 +1,147 @@
1
+ // Generated for you. Ordinary Three.js; controls belong to your game.
2
+ import {
3
+ type Camera,
4
+ type Color,
5
+ type DirectionalLight,
6
+ Material,
7
+ type MeshStandardMaterial,
8
+ type Object3D,
9
+ type Scene,
10
+ Vector3,
11
+ } from "three";
12
+ import {
13
+ cameraViewMatrix,
14
+ clamp,
15
+ dot,
16
+ float,
17
+ materialColor,
18
+ materialEmissive,
19
+ materialMetalness,
20
+ materialRoughness,
21
+ max,
22
+ mix,
23
+ normalView,
24
+ positionViewDirection,
25
+ pow,
26
+ reflect,
27
+ smoothstep,
28
+ uniform,
29
+ vec3,
30
+ } from "three/tsl";
31
+ import { MeshStandardNodeMaterial } from "three/webgpu";
32
+ import { resolveKey, validateControls } from "./backlightControls.js";
33
+
34
+ export interface IBacklightControls {
35
+ readonly key: DirectionalLight;
36
+ readonly scene: Scene;
37
+ readonly camera: Camera;
38
+ /** Mutable game-owned controls: zero disables the rim, independent of source reporting. */
39
+ rimGain: number;
40
+ fillGain: number;
41
+ readonly fillColor: Color;
42
+ readonly fillDirection: Vector3;
43
+ /** Angular radius of the authored fill disc, in radians. */
44
+ fillAngularSize: number;
45
+ /** Caller admits fill only after a measured-dark or missing environment is qualified. */
46
+ fillAdmitted: boolean;
47
+ }
48
+
49
+ const graphs = new WeakMap<IBacklightControls, ReturnType<typeof createGraph>>();
50
+
51
+ /**
52
+ * Preserve the upstream standard PBR/normal/skinning paths and original material emissive.
53
+ * This is an additive artistic convention, not a physical subsurface model or IBL replacement.
54
+ * Cache at the caller to preserve shared source-material relationships; dispose only conversions
55
+ * it owns, never maps/source materials borrowed from a loaded model.
56
+ */
57
+ export function backlightMaterial(source: MeshStandardMaterial, controls: IBacklightControls) {
58
+ if (
59
+ ("isMeshPhysicalMaterial" in source && source.isMeshPhysicalMaterial === true) ||
60
+ source.onBeforeCompile !== Material.prototype.onBeforeCompile
61
+ )
62
+ throw new Error(
63
+ "Physical/custom standard materials require separate qualification; conversion refused.",
64
+ );
65
+ validateControls(controls);
66
+ const material = new MeshStandardNodeMaterial().copy(source);
67
+ // NodeMaterial.copy skips Material.copy, and `alphaTest` lives in `_alphaTest`, which it never copies.
68
+ material.alphaTest = source.alphaTest;
69
+ let graph = graphs.get(controls);
70
+ if (!graph) {
71
+ graph = createGraph(controls);
72
+ graphs.set(controls, graph);
73
+ }
74
+ material.emissiveNode = graph;
75
+ return material;
76
+ }
77
+
78
+ function createGraph(controls: IBacklightControls) {
79
+ const rimGain = uniform(controls.rimGain).onRenderUpdate(() => {
80
+ validateControls(controls);
81
+ return controls.rimGain;
82
+ });
83
+ const fillGain = uniform(0).onRenderUpdate(() => {
84
+ validateControls(controls);
85
+ return controls.fillAdmitted ? controls.fillGain : 0;
86
+ });
87
+ const fillColor = uniform(controls.fillColor).onRenderUpdate(() => {
88
+ validateControls(controls);
89
+ return controls.fillColor;
90
+ });
91
+ const fillDirection = uniform(controls.fillDirection).onRenderUpdate(() => {
92
+ validateControls(controls);
93
+ return controls.fillDirection;
94
+ });
95
+ const fillAngularSize = uniform(controls.fillAngularSize).onRenderUpdate(() => {
96
+ validateControls(controls);
97
+ return controls.fillAngularSize;
98
+ });
99
+ const keyColor = uniform(controls.key.color).onRenderUpdate(() => {
100
+ validateControls(controls);
101
+ return controls.key.color;
102
+ });
103
+ const keyDirectionValue = new Vector3(0, 1, 0);
104
+ const keyTargetValue = new Vector3();
105
+ const keyDirection = uniform(keyDirectionValue).onRenderUpdate((frame) => {
106
+ resolveKey(controls, keyDirectionValue, keyTargetValue, frame.camera ?? controls.camera);
107
+ return keyDirectionValue;
108
+ });
109
+ // Removal/visibility/intensity are live. A removed sun cannot leave an invented rim behind.
110
+ const keyGain = uniform(0).onRenderUpdate((frame) =>
111
+ resolveKey(controls, keyDirectionValue, keyTargetValue, frame.camera ?? controls.camera),
112
+ );
113
+ const N = normalView.normalize();
114
+ const V = positionViewDirection.normalize();
115
+ const L = cameraViewMatrix.transformDirection(keyDirection);
116
+ const grazing = pow(float(1).sub(clamp(dot(N, V), 0, 1)), 3);
117
+ const behind = max(dot(L, V).negate(), 0);
118
+ // Suppress broad surfaces already facing the key; back-facing edges retain wrap.
119
+ // Tint by base reflectance so dark surfaces do not inherit a white emissive wash.
120
+ const surfaceBacklit = float(1).sub(smoothstep(-0.15, 0.15, dot(N, L)));
121
+ const rim = keyColor
122
+ .mul(keyGain)
123
+ .mul(rimGain)
124
+ .mul(grazing)
125
+ .mul(behind)
126
+ .mul(surfaceBacklit)
127
+ .mul(clamp(materialColor, 0, 1));
128
+
129
+ const F = cameraViewMatrix.transformDirection(fillDirection.normalize());
130
+ const cosRadius = fillAngularSize.cos();
131
+ // Broaden a rough surface's reflected disc with approximate solid-angle attenuation,
132
+ // not a proven energy-conserving BRDF. A positive transition avoids equal smoothstep bounds.
133
+ const spread = fillAngularSize.add(max(materialRoughness.mul(1.2), 0.005)).min(Math.PI / 2);
134
+ const reflectedDisc = smoothstep(spread.cos(), cosRadius, dot(reflect(V.negate(), N), F));
135
+ const energy = float(1)
136
+ .sub(cosRadius)
137
+ .div(max(float(1).sub(spread.cos()), 0.0001));
138
+ const reflectance = mix(vec3(0.04), materialColor, materialMetalness);
139
+ const specularFill = reflectance.mul(reflectedDisc).mul(energy);
140
+ const diffuseFill = materialColor
141
+ .mul(float(1).sub(materialMetalness))
142
+ .mul(max(dot(N, F), 0))
143
+ .mul(float(1).sub(cosRadius))
144
+ .mul(2);
145
+ const fill = diffuseFill.add(specularFill).mul(fillColor).mul(fillGain);
146
+ return materialEmissive.add(rim).add(fill);
147
+ }
@@ -0,0 +1,188 @@
1
+ // Generated for you. Measure actual source radiance; unreadable environments stay unknown.
2
+ import {
3
+ type Color,
4
+ EquirectangularReflectionMapping,
5
+ FloatType,
6
+ LinearSRGBColorSpace,
7
+ NoColorSpace,
8
+ RGBAFormat,
9
+ SRGBColorSpace,
10
+ type Scene,
11
+ type Texture,
12
+ UnsignedByteType,
13
+ } from "three";
14
+
15
+ export interface IEnvironmentMeasurement {
16
+ readonly status: "measured" | "unknown";
17
+ readonly meanRadiance: number | null;
18
+ readonly meanRGB: readonly [number, number, number] | null;
19
+ readonly reason: string;
20
+ }
21
+ const unknown = (reason: string): IEnvironmentMeasurement => ({
22
+ status: "unknown",
23
+ meanRadiance: null,
24
+ meanRGB: null,
25
+ reason,
26
+ });
27
+ const linear = (value: number) =>
28
+ value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
29
+
30
+ function validSize(value: unknown): value is number {
31
+ return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
32
+ }
33
+ interface IReadableSource {
34
+ readonly status: "source";
35
+ readonly data: Uint8Array | Float32Array;
36
+ readonly width: number;
37
+ readonly height: number;
38
+ readonly bytes: boolean;
39
+ }
40
+ function readSource(
41
+ texture: Texture,
42
+ maxSourceTexels: number,
43
+ ): IReadableSource | IEnvironmentMeasurement {
44
+ if (texture.mapping !== EquirectangularReflectionMapping)
45
+ return unknown("Only CPU-readable equirectangular source radiance is qualified.");
46
+ const image: unknown = texture.image;
47
+ if (
48
+ image === null ||
49
+ typeof image !== "object" ||
50
+ !("data" in image) ||
51
+ !("width" in image) ||
52
+ !("height" in image)
53
+ )
54
+ return unknown("Environment source pixels are not CPU-readable; no radiance was inferred.");
55
+ const { data, width, height } = image;
56
+ if (!validSize(width) || !validSize(height))
57
+ return unknown("Environment source dimensions are invalid.");
58
+ if (width * height > maxSourceTexels)
59
+ return unknown("Environment CPU sample budget exceeded; no radiance was inferred.");
60
+ if (texture.format !== RGBAFormat)
61
+ return unknown("Only explicit RGBA source samples are qualified.");
62
+ const bytes = texture.type === UnsignedByteType && data instanceof Uint8Array;
63
+ const floats = texture.type === FloatType && data instanceof Float32Array;
64
+ if (!bytes && !floats) return unknown("Environment source sample type is not qualified.");
65
+ if (data.length !== width * height * 4)
66
+ return unknown("Environment source samples do not match their dimensions.");
67
+ if (
68
+ !new Set<string>([NoColorSpace, LinearSRGBColorSpace, SRGBColorSpace]).has(texture.colorSpace)
69
+ )
70
+ return unknown("Environment source color-space conversion is not qualified.");
71
+ return { status: "source", data, width, height, bytes };
72
+ }
73
+
74
+ function accumulate(source: IReadableSource, srgb: boolean) {
75
+ const { data, width, height, bytes } = source;
76
+ const sums = [0, 0, 0];
77
+ const weights = Array.from(
78
+ { length: height },
79
+ (_, y) => Math.cos((Math.PI * y) / height) - Math.cos((Math.PI * (y + 1)) / height),
80
+ );
81
+ for (let offset = 0; offset < data.length; offset += 4) {
82
+ const weight = weights[Math.floor(offset / (width * 4))] ?? 0;
83
+ for (let channel = 0; channel < 3; channel += 1) {
84
+ const sample = data[offset + channel];
85
+ if (sample === undefined || !Number.isFinite(sample) || sample < 0)
86
+ return unknown("Environment radiance samples must be finite and nonnegative.");
87
+ const value = bytes ? sample / 255 : sample;
88
+ sums[channel] = (sums[channel] ?? 0) + (srgb ? linear(value) : value) * weight;
89
+ }
90
+ }
91
+ return { sums, weightSum: weights.reduce((a, b) => a + b, 0) * width };
92
+ }
93
+
94
+ /**
95
+ * CPU-readable equirectangular source radiance only; no DOM/canvas or invented JPEG mean.
96
+ * Rows are weighted by their exact spherical solid angle, rather than overweighting the poles.
97
+ * Arbitrary GPU/compressed/HTML/cube sources remain explicitly unknown until separately proven.
98
+ */
99
+ export function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement {
100
+ if (!Number.isSafeInteger(maxSourceTexels) || maxSourceTexels < 1)
101
+ throw new Error("Environment CPU sample budget must be a positive safe integer.");
102
+ const texture = scene.environment;
103
+ if (texture === null)
104
+ return {
105
+ status: "measured",
106
+ meanRadiance: 0,
107
+ meanRGB: [0, 0, 0],
108
+ reason: "No environment is bound.",
109
+ };
110
+ if (!Number.isFinite(scene.environmentIntensity) || scene.environmentIntensity < 0)
111
+ return unknown("Environment intensity must be finite and nonnegative.");
112
+ const source = readSource(texture, maxSourceTexels);
113
+ if (source.status !== "source") return source;
114
+ const accumulated = accumulate(source, texture.colorSpace === SRGBColorSpace);
115
+ if ("status" in accumulated) return accumulated;
116
+ const { sums, weightSum } = accumulated;
117
+ const meanRGB = sums.map((sum) => (sum / weightSum) * scene.environmentIntensity) as [
118
+ number,
119
+ number,
120
+ number,
121
+ ];
122
+ const meanRadiance = meanRGB[0] * 0.2126 + meanRGB[1] * 0.7152 + meanRGB[2] * 0.0722;
123
+ if (!meanRGB.every(Number.isFinite) || !Number.isFinite(meanRadiance))
124
+ return unknown("Environment radiance accumulation overflowed.");
125
+ return {
126
+ status: "measured",
127
+ meanRadiance,
128
+ meanRGB,
129
+ reason: "Solid-angle-weighted linear source radiance, with active environment intensity.",
130
+ };
131
+ }
132
+
133
+ interface IContributionControls {
134
+ readonly darkThreshold: number;
135
+ readonly rimGain: number;
136
+ readonly fillGain: number;
137
+ readonly fillAdmitted: boolean;
138
+ readonly fillColor: Color;
139
+ readonly maxSourceTexels: number;
140
+ }
141
+ function fillReport(options: IContributionControls) {
142
+ const blackColorOverride = options.fillColor.toArray().every((value) => value === 0);
143
+ let reason = "analytic fill enabled by caller; contribution still needs pixel qualification";
144
+ if (!options.fillAdmitted) reason = "not admitted by this qualification";
145
+ else if (options.fillGain === 0) reason = "disabled by fillGain override";
146
+ else if (blackColorOverride) reason = "disabled by black fillColor override";
147
+ return {
148
+ requestedGain: options.fillGain,
149
+ admitted: options.fillAdmitted,
150
+ effectiveGain: options.fillAdmitted ? options.fillGain : 0,
151
+ color: options.fillColor.toArray(),
152
+ blackColorOverride,
153
+ reason,
154
+ };
155
+ }
156
+ /** Overrides change the look, never whether its source contribution is measured/reported. */
157
+ export function reportEnvironmentContribution(
158
+ scene: Scene,
159
+ options: IContributionControls,
160
+ measurement?: IEnvironmentMeasurement,
161
+ ) {
162
+ if (
163
+ ![
164
+ options.darkThreshold,
165
+ options.rimGain,
166
+ options.fillGain,
167
+ ...options.fillColor.toArray(),
168
+ ].every((value) => Number.isFinite(value) && value >= 0)
169
+ )
170
+ throw new Error("Backlight measurement controls must be finite and nonnegative.");
171
+ const measured = measurement ?? measureEnvironment(scene, options.maxSourceTexels);
172
+ const dark =
173
+ measured.meanRadiance === null ? null : measured.meanRadiance <= options.darkThreshold;
174
+ const environmentState =
175
+ scene.environment === null ? "missing" : dark === null ? "unknown" : dark ? "dark" : "bright";
176
+ const report = {
177
+ ...measured,
178
+ scope: "scene environment source availability; not material-specific reflected contribution",
179
+ environmentState,
180
+ ibl: dark === null ? "unknown" : dark ? "non-contributing" : "contributing",
181
+ analyticFill: fillReport(options),
182
+ rimGain: options.rimGain,
183
+ fillGain: options.fillGain,
184
+ darkThreshold: options.darkThreshold,
185
+ };
186
+ console.info(`TN_ENVIRONMENT_CONTRIBUTION:${JSON.stringify(report)}`);
187
+ return report;
188
+ }
@@ -0,0 +1,36 @@
1
+ // Generated for you. Spherical accumulation of bounded linear source samples.
2
+ import type { IEnvironmentMeasurement } from "./environmentContribution.js";
3
+ const WIDTH = 64;
4
+ const HEIGHT = 32;
5
+ function unmeasured(reason: string): IEnvironmentMeasurement {
6
+ return { status: "unknown", meanRadiance: null, meanRGB: null, reason };
7
+ }
8
+ export function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement {
9
+ if (!(samples instanceof Float32Array) || samples.length !== WIDTH * HEIGHT * 4)
10
+ return unmeasured("GPU readback did not provide the qualified float RGBA sample layout.");
11
+ const sums = [0, 0, 0];
12
+ const weights = Array.from(
13
+ { length: HEIGHT },
14
+ (_, y) => Math.cos((Math.PI * y) / HEIGHT) - Math.cos((Math.PI * (y + 1)) / HEIGHT),
15
+ );
16
+ const totalWeight = weights.reduce((sum, weight) => sum + weight, 0) * WIDTH;
17
+ for (const [offset, value] of samples.entries()) {
18
+ const channel = offset % 4;
19
+ if (channel === 3) continue;
20
+ if (!Number.isFinite(value) || value < 0)
21
+ return unmeasured("GPU radiance samples must be finite and nonnegative.");
22
+ const weight = weights[Math.floor(offset / (WIDTH * 4))] ?? 0;
23
+ sums[channel] = (sums[channel] ?? 0) + value * weight;
24
+ }
25
+ const meanRGB = sums.map((sum) => (sum / totalWeight) * intensity) as [number, number, number];
26
+ const meanRadiance = meanRGB[0] * 0.2126 + meanRGB[1] * 0.7152 + meanRGB[2] * 0.0722;
27
+ if (!meanRGB.every(Number.isFinite) || !Number.isFinite(meanRadiance))
28
+ return unmeasured("GPU radiance accumulation overflowed.");
29
+ return {
30
+ status: "measured",
31
+ meanRGB,
32
+ meanRadiance,
33
+ reason:
34
+ "Estimated linear scene-environment source radiance from 64x32 GPU samples, spherical row weighting and active intensity; not material-specific BRDF contribution.",
35
+ };
36
+ }
@@ -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
+ }