create-threenative 0.2.8 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (431) hide show
  1. package/agent-docs/references/assertion-reference.md +87 -35
  2. package/agent-docs/references/auto-exposure.md +57 -0
  3. package/agent-docs/references/capability-reference.md +1097 -23
  4. package/agent-docs/references/debug-surface.md +6 -0
  5. package/agent-docs/references/finding-assets.md +46 -10
  6. package/agent-docs/references/performance-basics.md +5 -4
  7. package/agent-docs/references/terrain-authoring.md +140 -0
  8. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  9. package/capabilities.json +1210 -27
  10. package/dist/index.d.ts +28 -3
  11. package/dist/index.js +396 -166
  12. package/dist/threenative.js +986 -235
  13. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  14. package/dist/web-engine-decal-geometry.js +184 -0
  15. package/dist/web-engine-gltf-loader.js +196 -0
  16. package/dist/web-engine-hdr-loader.js +190 -0
  17. package/dist/web-engine-lut-cube-loader.js +122 -0
  18. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  19. package/dist/web-engine-mesh-bvh.js +32 -0
  20. package/dist/web-engine-post-effects.js +168 -0
  21. package/dist/web-engine-runtime.js +42506 -0
  22. package/package.json +11 -8
  23. package/template-assets/autoExposure.ts +225 -0
  24. package/template-assets/exposure.ts +111 -0
  25. package/template-assets/exposureGraph.ts +178 -0
  26. package/template-assets/exposureReadback.ts +79 -0
  27. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  28. package/template-assets/patches/three@0.185.1.patch +6594 -700
  29. package/template-assets/patches/vite@8.2.0.patch +422 -0
  30. package/template-assets/worldEnvironment.ts +433 -30
  31. package/templates/action-rpg/AGENTS.md +11 -10
  32. package/templates/action-rpg/CLAUDE.md +11 -10
  33. package/templates/action-rpg/package.json +11 -9
  34. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  35. package/templates/action-rpg/src/progress.ts +0 -4
  36. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  37. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  38. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  39. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  40. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  41. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  42. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  43. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  44. package/templates/action-rpg/src/render/exposure.ts +111 -0
  45. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  46. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  47. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  48. package/templates/action-rpg/src/render/lighting.ts +26 -1
  49. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  50. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  51. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  52. package/templates/action-rpg/src/render/quality.ts +61 -2
  53. package/templates/action-rpg/src/render/sky.ts +21 -1
  54. package/templates/action-rpg/src/render/vfx.ts +133 -58
  55. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  56. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  57. package/templates/action-rpg/threenative.config.ts +3 -0
  58. package/templates/action-rpg/vite.config.ts +10 -2
  59. package/templates/minimal/AGENTS.md +9 -10
  60. package/templates/minimal/CLAUDE.md +9 -10
  61. package/templates/minimal/package.json +9 -8
  62. package/templates/minimal/playtests/play.playtest.json +7 -1
  63. package/templates/minimal/playtests/sky.playtest.json +10 -1
  64. package/templates/minimal/src/render/autoExposure.ts +225 -0
  65. package/templates/minimal/src/render/backlightControls.ts +66 -0
  66. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  67. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  68. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  69. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  70. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  71. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  72. package/templates/minimal/src/render/exposure.ts +111 -0
  73. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  74. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  75. package/templates/minimal/src/render/heightFog.ts +118 -0
  76. package/templates/minimal/src/render/lighting.ts +25 -1
  77. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  78. package/templates/minimal/src/render/materialLighting.ts +146 -0
  79. package/templates/minimal/src/render/postprocessing.ts +16 -2
  80. package/templates/minimal/src/render/quality.ts +60 -2
  81. package/templates/minimal/src/render/sky.ts +21 -1
  82. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  83. package/templates/minimal/src/scenes/Play.ts +50 -1
  84. package/templates/minimal/vite.config.ts +10 -2
  85. package/templates/platformer/AGENTS.md +7 -5
  86. package/templates/platformer/CLAUDE.md +7 -5
  87. package/templates/platformer/package.json +11 -9
  88. package/templates/platformer/playtests/performance.playtest.json +7 -1
  89. package/templates/platformer/src/render/autoExposure.ts +225 -0
  90. package/templates/platformer/src/render/backlightControls.ts +66 -0
  91. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  92. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  93. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  94. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  95. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  96. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  97. package/templates/platformer/src/render/exposure.ts +111 -0
  98. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  99. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  100. package/templates/platformer/src/render/heightFog.ts +118 -0
  101. package/templates/platformer/src/render/lighting.ts +26 -1
  102. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  103. package/templates/platformer/src/render/materialLighting.ts +155 -0
  104. package/templates/platformer/src/render/materials.ts +7 -2
  105. package/templates/platformer/src/render/palette.ts +3 -3
  106. package/templates/platformer/src/render/postprocessing.ts +17 -2
  107. package/templates/platformer/src/render/quality.ts +61 -2
  108. package/templates/platformer/src/render/sky.ts +72 -23
  109. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  110. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  111. package/templates/platformer/src/scenes/Play.ts +70 -6
  112. package/templates/platformer/vite.config.ts +10 -2
  113. package/templates/puzzle/AGENTS.md +10 -9
  114. package/templates/puzzle/CLAUDE.md +10 -9
  115. package/templates/puzzle/package.json +11 -9
  116. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  117. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  118. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  119. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  120. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  121. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  122. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  123. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  124. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  125. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  126. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  127. package/templates/puzzle/src/render/exposure.ts +111 -0
  128. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  129. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  130. package/templates/puzzle/src/render/heightFog.ts +118 -0
  131. package/templates/puzzle/src/render/lighting.ts +33 -1
  132. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  133. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  134. package/templates/puzzle/src/render/materials.ts +1 -1
  135. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  136. package/templates/puzzle/src/render/quality.ts +62 -1
  137. package/templates/puzzle/src/render/sky.ts +20 -1
  138. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  139. package/templates/puzzle/src/scenes/Play.ts +51 -2
  140. package/templates/puzzle/vite.config.ts +10 -2
  141. package/templates/racing/AGENTS.md +8 -7
  142. package/templates/racing/CLAUDE.md +8 -7
  143. package/templates/racing/package.json +11 -9
  144. package/templates/racing/playtests/performance.playtest.json +7 -1
  145. package/templates/racing/playtests/survives.playtest.json +6 -0
  146. package/templates/racing/src/render/autoExposure.ts +225 -0
  147. package/templates/racing/src/render/backlightControls.ts +66 -0
  148. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  149. package/templates/racing/src/render/environmentContribution.ts +188 -0
  150. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  151. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  152. package/templates/racing/src/render/environmentSampling.ts +193 -0
  153. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  154. package/templates/racing/src/render/exposure.ts +111 -0
  155. package/templates/racing/src/render/exposureGraph.ts +178 -0
  156. package/templates/racing/src/render/exposureReadback.ts +79 -0
  157. package/templates/racing/src/render/heightFog.ts +118 -0
  158. package/templates/racing/src/render/lighting.ts +29 -1
  159. package/templates/racing/src/render/materialAssignments.ts +160 -0
  160. package/templates/racing/src/render/materialLighting.ts +155 -0
  161. package/templates/racing/src/render/palette.ts +1 -10
  162. package/templates/racing/src/render/postprocessing.ts +17 -2
  163. package/templates/racing/src/render/quality.ts +61 -2
  164. package/templates/racing/src/render/shapes.ts +0 -25
  165. package/templates/racing/src/render/sky.ts +21 -1
  166. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  167. package/templates/racing/src/scenes/Race.ts +91 -3
  168. package/templates/racing/src/track/circuit.ts +0 -9
  169. package/templates/racing/vite.config.ts +10 -2
  170. package/templates/rain/AGENTS.md +8 -9
  171. package/templates/rain/CLAUDE.md +8 -9
  172. package/templates/rain/native-playtests/boot.playtest.json +11 -1
  173. package/templates/rain/package.json +12 -9
  174. package/templates/rain/playtests/automation.playtest.json +1 -1
  175. package/templates/rain/playtests/performance.playtest.json +11 -1
  176. package/templates/rain/playtests/tiers.playtest.json +15 -0
  177. package/templates/rain/playtests/weather.playtest.json +1 -1
  178. package/templates/rain/src/game.ts +1 -34
  179. package/templates/rain/src/render/autoExposure.ts +225 -0
  180. package/templates/rain/src/render/exposure.ts +111 -0
  181. package/templates/rain/src/render/exposureGraph.ts +178 -0
  182. package/templates/rain/src/render/exposureReadback.ts +79 -0
  183. package/templates/rain/src/render/postprocessing.ts +3 -0
  184. package/templates/rain/src/render/quality.ts +27 -1
  185. package/templates/rain/src/render/worldEnvironment.ts +433 -30
  186. package/templates/rain/src/scenes/Boot.ts +14 -0
  187. package/templates/rain/src/state.ts +5 -1
  188. package/templates/rain/src/ui/GameUi.tsx +6 -6
  189. package/templates/rain/tools/generate-shaders.mjs +1 -1
  190. package/templates/rain/vite.config.ts +10 -2
  191. package/templates/rts/AGENTS.md +10 -11
  192. package/templates/rts/CLAUDE.md +10 -11
  193. package/templates/rts/package.json +10 -8
  194. package/templates/rts/playtests/performance.playtest.json +7 -1
  195. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  196. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  197. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  198. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  199. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  200. package/templates/rts/src/render/army.ts +10 -2
  201. package/templates/rts/src/render/autoExposure.ts +225 -0
  202. package/templates/rts/src/render/backlightControls.ts +66 -0
  203. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  204. package/templates/rts/src/render/environmentContribution.ts +188 -0
  205. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  206. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  207. package/templates/rts/src/render/environmentSampling.ts +193 -0
  208. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  209. package/templates/rts/src/render/exposure.ts +111 -0
  210. package/templates/rts/src/render/exposureGraph.ts +178 -0
  211. package/templates/rts/src/render/exposureReadback.ts +79 -0
  212. package/templates/rts/src/render/heightFog.ts +118 -0
  213. package/templates/rts/src/render/lighting.ts +26 -1
  214. package/templates/rts/src/render/materialAssignments.ts +160 -0
  215. package/templates/rts/src/render/materialLighting.ts +155 -0
  216. package/templates/rts/src/render/postprocessing.ts +8 -2
  217. package/templates/rts/src/render/quality.ts +61 -2
  218. package/templates/rts/src/render/sky.ts +21 -1
  219. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  220. package/templates/rts/src/scenes/Play.ts +54 -3
  221. package/templates/rts/src/sim/ai.ts +0 -1
  222. package/templates/rts/src/sim/terrain.ts +0 -4
  223. package/templates/rts/vite.config.ts +10 -2
  224. package/templates/runner/AGENTS.md +10 -8
  225. package/templates/runner/CLAUDE.md +10 -8
  226. package/templates/runner/package.json +11 -9
  227. package/templates/runner/playtests/performance.playtest.json +10 -1
  228. package/templates/runner/src/physics.ts +0 -1
  229. package/templates/runner/src/render/autoExposure.ts +225 -0
  230. package/templates/runner/src/render/backlightControls.ts +66 -0
  231. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  232. package/templates/runner/src/render/environmentContribution.ts +188 -0
  233. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  234. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  235. package/templates/runner/src/render/environmentSampling.ts +193 -0
  236. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  237. package/templates/runner/src/render/exposure.ts +111 -0
  238. package/templates/runner/src/render/exposureGraph.ts +178 -0
  239. package/templates/runner/src/render/exposureReadback.ts +79 -0
  240. package/templates/runner/src/render/heightFog.ts +118 -0
  241. package/templates/runner/src/render/lighting.ts +26 -1
  242. package/templates/runner/src/render/materialAssignments.ts +160 -0
  243. package/templates/runner/src/render/materialLighting.ts +155 -0
  244. package/templates/runner/src/render/postprocessing.ts +17 -2
  245. package/templates/runner/src/render/quality.ts +61 -2
  246. package/templates/runner/src/render/sky.ts +21 -1
  247. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  248. package/templates/runner/src/scenes/Run.ts +67 -2
  249. package/templates/runner/threenative.config.ts +3 -0
  250. package/templates/runner/vite.config.ts +10 -2
  251. package/templates/sailing/AGENTS.md +14 -13
  252. package/templates/sailing/CLAUDE.md +14 -13
  253. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  254. package/templates/sailing/package.json +11 -9
  255. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  256. package/templates/sailing/src/entities/Ship.ts +38 -18
  257. package/templates/sailing/src/render/autoExposure.ts +225 -0
  258. package/templates/sailing/src/render/backlightControls.ts +66 -0
  259. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  260. package/templates/sailing/src/render/camera.ts +12 -4
  261. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  262. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  263. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  264. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  265. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  266. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  267. package/templates/sailing/src/render/exposure.ts +111 -0
  268. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  269. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  270. package/templates/sailing/src/render/heightFog.ts +118 -0
  271. package/templates/sailing/src/render/lighting.ts +26 -1
  272. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  273. package/templates/sailing/src/render/materialLighting.ts +155 -0
  274. package/templates/sailing/src/render/ocean.ts +71 -53
  275. package/templates/sailing/src/render/postprocessing.ts +16 -2
  276. package/templates/sailing/src/render/props.ts +0 -45
  277. package/templates/sailing/src/render/quality.ts +61 -1
  278. package/templates/sailing/src/render/sky.ts +21 -1
  279. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  280. package/templates/sailing/src/scenes/Boot.ts +12 -1
  281. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  282. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  283. package/templates/sailing/threenative.config.ts +3 -0
  284. package/templates/sailing/vite.config.ts +10 -2
  285. package/templates/shooter/AGENTS.md +8 -6
  286. package/templates/shooter/CLAUDE.md +8 -6
  287. package/templates/shooter/package.json +11 -9
  288. package/templates/shooter/playtests/performance.playtest.json +7 -1
  289. package/templates/shooter/src/entities/Enemy.ts +0 -15
  290. package/templates/shooter/src/entities/Rifle.ts +38 -1
  291. package/templates/shooter/src/render/autoExposure.ts +225 -0
  292. package/templates/shooter/src/render/backlightControls.ts +66 -0
  293. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  294. package/templates/shooter/src/render/camera.ts +1 -12
  295. package/templates/shooter/src/render/decals.ts +299 -5
  296. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  297. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  298. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  299. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  300. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  301. package/templates/shooter/src/render/exposure.ts +111 -0
  302. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  303. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  304. package/templates/shooter/src/render/gunfx.ts +0 -1
  305. package/templates/shooter/src/render/heightFog.ts +118 -0
  306. package/templates/shooter/src/render/lighting.ts +26 -1
  307. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  308. package/templates/shooter/src/render/materialLighting.ts +155 -0
  309. package/templates/shooter/src/render/postprocessing.ts +17 -2
  310. package/templates/shooter/src/render/quality.ts +61 -2
  311. package/templates/shooter/src/render/scale.ts +2 -93
  312. package/templates/shooter/src/render/sky.ts +21 -1
  313. package/templates/shooter/src/render/vehicles.ts +0 -17
  314. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  315. package/templates/shooter/src/scenes/Play.ts +64 -2
  316. package/templates/shooter/vite.config.ts +10 -2
  317. package/templates/snow/AGENTS.md +8 -6
  318. package/templates/snow/CLAUDE.md +8 -6
  319. package/templates/snow/package.json +11 -9
  320. package/templates/snow/src/render/autoExposure.ts +225 -0
  321. package/templates/snow/src/render/backlightControls.ts +66 -0
  322. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  323. package/templates/snow/src/render/environmentContribution.ts +188 -0
  324. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  325. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/snow/src/render/environmentSampling.ts +193 -0
  327. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  328. package/templates/snow/src/render/exposure.ts +111 -0
  329. package/templates/snow/src/render/exposureGraph.ts +178 -0
  330. package/templates/snow/src/render/exposureReadback.ts +79 -0
  331. package/templates/snow/src/render/heightFog.ts +118 -0
  332. package/templates/snow/src/render/lighting.ts +33 -1
  333. package/templates/snow/src/render/materialAssignments.ts +160 -0
  334. package/templates/snow/src/render/materialLighting.ts +155 -0
  335. package/templates/snow/src/render/postprocessing.ts +16 -2
  336. package/templates/snow/src/render/quality.ts +59 -1
  337. package/templates/snow/src/render/sky.ts +21 -2
  338. package/templates/snow/src/render/worldEnvironment.ts +433 -30
  339. package/templates/snow/src/scenes/Snow.ts +29 -1
  340. package/templates/snow/threenative.config.ts +3 -0
  341. package/templates/snow/vite.config.ts +10 -2
  342. package/templates/starter/AGENTS.md +11 -16
  343. package/templates/starter/CLAUDE.md +11 -16
  344. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  345. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  346. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  347. package/templates/starter/package.json +11 -9
  348. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  349. package/templates/starter/playtests/movement.playtest.json +192 -0
  350. package/templates/starter/playtests/play.playtest.json +18 -2
  351. package/templates/starter/playtests/production-readiness.playtest.json +1 -1
  352. package/templates/starter/public/grade.cube +735 -0
  353. package/templates/starter/src/entities/Crate.ts +4 -0
  354. package/templates/starter/src/entities/Player.ts +79 -18
  355. package/templates/starter/src/game.ts +1 -0
  356. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  357. package/templates/starter/src/render/autoExposure.ts +225 -0
  358. package/templates/starter/src/render/backlightControls.ts +66 -0
  359. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  360. package/templates/starter/src/render/environmentContribution.ts +188 -0
  361. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  362. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  363. package/templates/starter/src/render/environmentSampling.ts +193 -0
  364. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  365. package/templates/starter/src/render/exposure.ts +111 -0
  366. package/templates/starter/src/render/exposureGraph.ts +178 -0
  367. package/templates/starter/src/render/exposureReadback.ts +79 -0
  368. package/templates/starter/src/render/grade.ts +157 -0
  369. package/templates/starter/src/render/heightFog.ts +118 -0
  370. package/templates/starter/src/render/lighting.ts +26 -1
  371. package/templates/starter/src/render/materialAssignments.ts +160 -0
  372. package/templates/starter/src/render/materialLighting.ts +155 -0
  373. package/templates/starter/src/render/postprocessing.ts +84 -4
  374. package/templates/starter/src/render/quality.ts +80 -8
  375. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  376. package/templates/starter/src/render/rendererGate.ts +36 -0
  377. package/templates/starter/src/render/sky.ts +23 -1
  378. package/templates/starter/src/render/temporalAA.ts +197 -0
  379. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  380. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  381. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  382. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  383. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  384. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  385. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  386. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  387. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  388. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  389. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  390. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  391. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  392. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  393. package/templates/starter/src/render/temporalResolve.ts +139 -0
  394. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  395. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  396. package/templates/starter/src/render/volumetricFog.ts +124 -0
  397. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  398. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  399. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  400. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  401. package/templates/starter/src/scenes/Play.ts +110 -1
  402. package/templates/starter/src/state.ts +1 -0
  403. package/templates/starter/src/ui/Hud.tsx +1 -1
  404. package/templates/starter/src/ui/Menu.tsx +1 -1
  405. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  406. package/templates/starter/vite.config.ts +10 -2
  407. package/templates/tower-defense/AGENTS.md +10 -9
  408. package/templates/tower-defense/CLAUDE.md +10 -9
  409. package/templates/tower-defense/package.json +11 -9
  410. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  411. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  412. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  413. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  414. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  415. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  416. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  417. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  418. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  419. package/templates/tower-defense/src/render/exposure.ts +111 -0
  420. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  421. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  422. package/templates/tower-defense/src/render/lighting.ts +33 -1
  423. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  424. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  425. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  426. package/templates/tower-defense/src/render/quality.ts +61 -2
  427. package/templates/tower-defense/src/render/shapes.ts +0 -3
  428. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  429. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  430. package/templates/tower-defense/vite.config.ts +10 -2
  431. package/templates/minimal/src/scenes/Boot.ts +0 -5
@@ -0,0 +1,118 @@
1
+ // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
+ // ThreeNative does not read this file. `sky.ts` owns the numbers; this file is the fog maths.
3
+ import { Color, type FogExp2, type Vector3 } from "three";
4
+ import {
5
+ cameraPosition,
6
+ densityFogFactor,
7
+ dot,
8
+ exp2,
9
+ float,
10
+ fog,
11
+ max,
12
+ mix,
13
+ positionWorld,
14
+ pow,
15
+ saturate,
16
+ select,
17
+ uniform,
18
+ vec3,
19
+ } from "three/tsl";
20
+
21
+ /**
22
+ * Height fog, in metres, y up. Density falls off exponentially above `fogHeight`; the fog along the
23
+ * ray from the camera to a fragment is the closed-form integral of that density, so low ground
24
+ * reads hazier than a ridge at the same distance and a camera above the layer looks down through it.
25
+ * Every control says which way to move it.
26
+ */
27
+ export const HEIGHT_FOG = {
28
+ /** Optical depth per metre at `fogHeight` (base 2). Up: thicker ground mist. */
29
+ density: 0.0018,
30
+ /** Per metre above `fogHeight`. Up: a thinner, lower layer. Down: mist climbs the hills. */
31
+ heightFalloff: 0.08,
32
+ /** World y where density equals `density`. Move it to the ground of your world. */
33
+ fogHeight: 0,
34
+ /** Floor on the height term's transparency, 0..1. Below 1 leaves a clear window in the mist. */
35
+ maxOpacity: 1,
36
+ /** Metres from the camera before the mist starts. Up: a clear foreground. */
37
+ startDistance: 0,
38
+ /** Sun lobe sharpness. Up: a tighter glow around the sun. */
39
+ sunExponent: 4,
40
+ /** Metres before sun glow starts, so nearby objects are not tinted. */
41
+ sunStartDistance: 100,
42
+ /** Metres past which the height term is off. 0 = never. Never set it inside a streaming ring. */
43
+ cutoffDistance: 0,
44
+ } as const;
45
+ export type HeightFogParams = { -readonly [K in keyof typeof HEIGHT_FOG]: number };
46
+
47
+ const LN2 = Math.LN2;
48
+
49
+ // Camera density term, clamped so exp2 stays finite (Unreal clamps the exponent at -127).
50
+ const clampExponent = (x: number): number => Math.min(127, Math.max(-127, x));
51
+
52
+ /** `density` times the integral of 2^(-k t) over [a, b]; k is the ray's slope times `falloff`. */
53
+ function segment(density: number, k: number, a: number, b: number): number {
54
+ if (b <= a) return 0;
55
+ if (Math.abs(k * b) < 0.01) return density * (b - a - 0.5 * LN2 * k * (b * b - a * a));
56
+ return (density * (2 ** (-k * a) - 2 ** (-k * b))) / (k * LN2);
57
+ }
58
+
59
+ function rayTerms(p: HeightFogParams, cameraY: number, fragmentY: number, length: number) {
60
+ const camera = p.density * 2 ** clampExponent(-p.heightFalloff * (cameraY - p.fogHeight));
61
+ const k = length > 0 ? (p.heightFalloff * (fragmentY - cameraY)) / length : 0;
62
+ return { camera, k };
63
+ }
64
+
65
+ /** Base-2 optical depth (transmittance is 2^-depth) of the mist between the camera and a fragment. */
66
+ export function heightFogDepth(
67
+ p: HeightFogParams,
68
+ cameraY: number,
69
+ fragmentY: number,
70
+ length: number,
71
+ ): number {
72
+ if (p.cutoffDistance > 0 && length > p.cutoffDistance) return 0;
73
+ const { camera, k } = rayTerms(p, cameraY, fragmentY, length);
74
+ return segment(camera, k, p.startDistance, length);
75
+ }
76
+
77
+ const SUN_COLOUR = new Color(0xfff1d6);
78
+
79
+ /**
80
+ * `T_distance x T_height`, on `scene.fogNode`: three applies it to every material where `scene.fog`
81
+ * would be. The distance term reads the live `FogExp2`, so changing its colour or density at runtime
82
+ * still works. It is never more transparent than that term alone, so wherever the distance term
83
+ * reaches 0 the frame stays fully fogged. Pass `sun` for a glow toward it past `sunStartDistance`.
84
+ */
85
+ export function heightFogNode(distanceFog: FogExp2, p: HeightFogParams, sun?: Vector3) {
86
+ const color = uniform(new Color());
87
+ color.onRenderUpdate(() => color.value.copy(distanceFog.color));
88
+ const density = uniform(0);
89
+ density.onRenderUpdate(() => {
90
+ density.value = distanceFog.density;
91
+ });
92
+ // Density at the camera, once per frame instead of once per fragment.
93
+ const cameraDensity = uniform(0);
94
+ cameraDensity.onRenderUpdate(({ camera }) => {
95
+ const y = camera?.matrixWorld.elements[13] ?? 0;
96
+ cameraDensity.value = p.density * 2 ** clampExponent(-p.heightFalloff * (y - p.fogHeight));
97
+ });
98
+ const ray = positionWorld.sub(cameraPosition);
99
+ const length = ray.length().max(1e-4);
100
+ const k = float(p.heightFalloff).mul(positionWorld.y.sub(cameraPosition.y)).div(length);
101
+ const integral = (a: number) => {
102
+ const b = max(length, a);
103
+ const curved = cameraDensity
104
+ .mul(exp2(k.mul(a).negate()).sub(exp2(k.mul(b).negate())))
105
+ .div(k.mul(LN2));
106
+ return select(k.mul(b).abs().lessThan(0.01), cameraDensity.mul(b.sub(a)), curved);
107
+ };
108
+ const cut = p.cutoffDistance > 0 ? select(length.greaterThan(p.cutoffDistance), 0, 1) : float(1);
109
+ const heightT = max(exp2(integral(p.startDistance).mul(cut).negate()), 1 - p.maxOpacity);
110
+ const opacity = densityFogFactor(density).oneMinus().mul(heightT).oneMinus();
111
+ if (sun === undefined) return fog(color, opacity);
112
+ const lobe = pow(saturate(dot(ray.div(length), vec3(sun.x, sun.y, sun.z))), p.sunExponent);
113
+ const glow = float(1)
114
+ .sub(exp2(integral(Math.max(p.sunStartDistance, p.startDistance)).negate()))
115
+ .mul(lobe)
116
+ .mul(p.maxOpacity);
117
+ return fog(mix(color, vec3(SUN_COLOUR.r, SUN_COLOUR.g, SUN_COLOUR.b), glow), opacity);
118
+ }
@@ -3,7 +3,7 @@
3
3
  //
4
4
  // One sun. The sky image in `sky.ts` is the fill light — its environment reaches every face the
5
5
  // sun misses — so there is no hemisphere or ambient light stacked on top to flatten the frame.
6
- import { DirectionalLight, PCFSoftShadowMap, type Scene } from "three";
6
+ import { Color, DirectionalLight, PCFSoftShadowMap, type Scene, Vector3 } from "three";
7
7
  import { SUN_DIRECTION } from "./sky.js";
8
8
 
9
9
  type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
@@ -59,3 +59,28 @@ export function setupLighting(
59
59
  // shadow map, so `setupPost` needs the light itself.
60
60
  return { key };
61
61
  }
62
+
63
+ /** Material conventions are game-owned; each scene gets independent mutable controls. */
64
+ export interface ILightingConvention {
65
+ rimGain: number;
66
+ fillGain: number;
67
+ fillColor: Color;
68
+ fillDirection: Vector3;
69
+ fillAngularSize: number;
70
+ darkThreshold: number;
71
+ maxSourceTexels: number;
72
+ }
73
+ export function createLightingConvention(
74
+ overrides: Partial<ILightingConvention> = {},
75
+ ): ILightingConvention {
76
+ return {
77
+ rimGain: 0.12,
78
+ fillGain: 1,
79
+ fillColor: new Color(0x667b9d),
80
+ fillDirection: new Vector3(0, 1, 1).normalize(),
81
+ fillAngularSize: 0.7,
82
+ darkThreshold: 0.001,
83
+ maxSourceTexels: 65536,
84
+ ...overrides,
85
+ };
86
+ }
@@ -0,0 +1,160 @@
1
+ // Generated for you. Own converted materials; preserve borrowed and authored assignments.
2
+ import { Material, Mesh, MeshStandardMaterial, type Object3D, type Scene } from "three";
3
+ import { type IBacklightControls, backlightMaterial } from "./backlightMaterial.js";
4
+ interface IMaterialAssignment {
5
+ readonly mesh: Mesh;
6
+ readonly original: Mesh["material"];
7
+ applied?: Mesh["material"];
8
+ slots?: readonly Material[];
9
+ readonly owned: Set<MeshStandardMaterial>;
10
+ readonly exclusions: string[];
11
+ }
12
+ export function createMaterialAssignments(scene: Scene, controls: IBacklightControls) {
13
+ const assignments = new Map<Mesh, IMaterialAssignment>();
14
+ const references = new Map<MeshStandardMaterial, number>();
15
+ let enabled = false;
16
+ let disposed = false;
17
+ const converted = new Map<MeshStandardMaterial, ReturnType<typeof backlightMaterial>>();
18
+ const originalOf = new Map<Material, MeshStandardMaterial>();
19
+ function enroll(root: Object3D): void {
20
+ if (disposed) return;
21
+ root.traverse((object) => {
22
+ if (!(object instanceof Mesh) || assignments.has(object)) return;
23
+ const assignment: IMaterialAssignment = {
24
+ mesh: object,
25
+ original: object.material,
26
+ owned: new Set(),
27
+ exclusions: [],
28
+ };
29
+ assignments.set(object, assignment);
30
+ assignment.exclusions.push(...excludedSlots(object));
31
+ if (enabled) applyAssignment(assignment);
32
+ });
33
+ }
34
+ function release(root: Object3D): void {
35
+ root.traverse((object) => {
36
+ if (!(object instanceof Mesh)) return;
37
+ const assignment = assignments.get(object);
38
+ if (assignment === undefined) return;
39
+ restore(assignment);
40
+ assignments.delete(object);
41
+ for (const source of assignment.owned) releaseConversion(source);
42
+ });
43
+ }
44
+ function excludedSlots(mesh: Mesh): string[] {
45
+ const slots = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
46
+ return slots.flatMap((material) => {
47
+ const reason = unsupported(material);
48
+ return reason === undefined
49
+ ? []
50
+ : [`${mesh.name || mesh.type}:${material.name || material.type}:${reason}`];
51
+ });
52
+ }
53
+ function releaseConversion(source: MeshStandardMaterial): void {
54
+ const remaining = (references.get(source) ?? 1) - 1;
55
+ if (remaining > 0) {
56
+ references.set(source, remaining);
57
+ return;
58
+ }
59
+ const material = converted.get(source);
60
+ if (material !== undefined) {
61
+ material.dispose();
62
+ originalOf.delete(material);
63
+ }
64
+ references.delete(source);
65
+ converted.delete(source);
66
+ }
67
+ function unsupported(material: Material): string | undefined {
68
+ if (!(material instanceof MeshStandardMaterial) || material.type !== "MeshStandardMaterial")
69
+ return "unsupported material type";
70
+ if (
71
+ material.onBeforeCompile !== Material.prototype.onBeforeCompile ||
72
+ material.customProgramCacheKey !== Material.prototype.customProgramCacheKey
73
+ )
74
+ return "custom shader requires separate qualification";
75
+ return undefined;
76
+ }
77
+ function convert(material: Material, assignment: IMaterialAssignment): Material {
78
+ if (unsupported(material) !== undefined) return material;
79
+ const standard = material as MeshStandardMaterial;
80
+ let owned = converted.get(standard);
81
+ if (owned === undefined) {
82
+ owned = backlightMaterial(standard, controls);
83
+ converted.set(standard, owned);
84
+ originalOf.set(owned, standard);
85
+ }
86
+ if (!assignment.owned.has(standard)) {
87
+ assignment.owned.add(standard);
88
+ references.set(standard, (references.get(standard) ?? 0) + 1);
89
+ }
90
+ return owned;
91
+ }
92
+ function restore(assignment: IMaterialAssignment): void {
93
+ const current = assignment.mesh.material;
94
+ if (current === assignment.applied) {
95
+ const unchanged =
96
+ !Array.isArray(current) ||
97
+ (current.length === assignment.slots?.length &&
98
+ current.every((material, index) => material === assignment.slots?.[index]));
99
+ if (unchanged) {
100
+ assignment.mesh.material = assignment.original;
101
+ return;
102
+ }
103
+ }
104
+ // Preserve authored array edits/replacements, but never leave an owned conversion attached.
105
+ if (Array.isArray(current)) {
106
+ const restored = current.map((material) => originalOf.get(material) ?? material);
107
+ if (restored.some((material, index) => material !== current[index]))
108
+ assignment.mesh.material = restored;
109
+ } else assignment.mesh.material = originalOf.get(current) ?? current;
110
+ }
111
+ function applyAssignment(assignment: IMaterialAssignment): void {
112
+ // The game's later material override wins; never overwrite it on a tier recovery.
113
+ if (assignment.mesh.material !== assignment.original) return;
114
+ if (Array.isArray(assignment.original)) {
115
+ // Borrowed arrays may be edited in place during a fallback. Read their current slots.
116
+ const slots = assignment.original.map((material) => convert(material, assignment));
117
+ assignment.applied = slots.some(
118
+ (material, index) => material !== (assignment.original as Material[])[index],
119
+ )
120
+ ? slots
121
+ : assignment.original;
122
+ assignment.slots = [...slots];
123
+ } else if (assignment.applied === undefined) {
124
+ assignment.applied = convert(assignment.original, assignment);
125
+ }
126
+ assignment.mesh.material = assignment.applied;
127
+ }
128
+ enroll(scene);
129
+ return {
130
+ enroll,
131
+ release,
132
+ setEnabled(requested: boolean): void {
133
+ if (disposed) return;
134
+ enabled = requested;
135
+ for (const assignment of assignments.values()) {
136
+ if (enabled) applyAssignment(assignment);
137
+ else restore(assignment);
138
+ }
139
+ },
140
+ debug: () => ({
141
+ convertedMaterials: converted.size,
142
+ enrolledMeshes: assignments.size,
143
+ excludedSlots: [...assignments.values()].reduce(
144
+ (sum, value) => sum + value.exclusions.length,
145
+ 0,
146
+ ),
147
+ exclusions: [...assignments.values()].flatMap((value) => value.exclusions),
148
+ }),
149
+ dispose(): void {
150
+ if (disposed) return;
151
+ disposed = true;
152
+ for (const assignment of assignments.values()) restore(assignment);
153
+ assignments.clear();
154
+ references.clear();
155
+ for (const material of converted.values()) material.dispose();
156
+ converted.clear();
157
+ originalOf.clear();
158
+ },
159
+ };
160
+ }
@@ -0,0 +1,155 @@
1
+ // Generated for you. Scene-owned material assignments; no engine appearance hooks.
2
+ import {
3
+ type Camera,
4
+ type DirectionalLight,
5
+ Material,
6
+ Mesh,
7
+ MeshStandardMaterial,
8
+ type Object3D,
9
+ type Scene,
10
+ type Texture,
11
+ } from "three";
12
+ import { type IBacklightControls, backlightMaterial } from "./backlightMaterial.js";
13
+ import {
14
+ type IEnvironmentMeasurement,
15
+ measureEnvironment,
16
+ reportEnvironmentContribution,
17
+ } from "./environmentContribution.js";
18
+ import {
19
+ type IEnvironmentSourceSnapshot,
20
+ captureEnvironmentSnapshot,
21
+ environmentSnapshotCurrent,
22
+ } from "./environmentSnapshot.js";
23
+ import { type ILightingConvention, createLightingConvention } from "./lighting.js";
24
+ import { createMaterialAssignments } from "./materialAssignments.js";
25
+ import { type IMaterialLightingEnvironment, materialLightingEnabled } from "./quality.js";
26
+ interface IMaterialLightingOptions extends IMaterialLightingEnvironment {
27
+ readonly enabled: boolean;
28
+ readonly overrides?: Partial<ILightingConvention>;
29
+ }
30
+ /** Call once AFTER the scene's loaded character, arena and props are attached. */
31
+ export function createMaterialLighting(
32
+ scene: Scene,
33
+ camera: Camera,
34
+ key: DirectionalLight,
35
+ options: IMaterialLightingOptions,
36
+ ) {
37
+ const settings = createLightingConvention(options.overrides);
38
+ let enabled = false;
39
+ let disposed = false;
40
+ let fillApproved = false;
41
+ let measured = measureEnvironment(scene, settings.maxSourceTexels);
42
+ let measurementSnapshot = captureEnvironmentSnapshot(scene);
43
+ const controls: IBacklightControls = {
44
+ key,
45
+ scene,
46
+ camera,
47
+ get rimGain() {
48
+ return settings.rimGain;
49
+ },
50
+ set rimGain(value) {
51
+ settings.rimGain = value;
52
+ },
53
+ get fillGain() {
54
+ return settings.fillGain;
55
+ },
56
+ set fillGain(value) {
57
+ settings.fillGain = value;
58
+ },
59
+ fillColor: settings.fillColor,
60
+ fillDirection: settings.fillDirection,
61
+ get fillAngularSize() {
62
+ return settings.fillAngularSize;
63
+ },
64
+ set fillAngularSize(value) {
65
+ settings.fillAngularSize = value;
66
+ },
67
+ get fillAdmitted() {
68
+ return enabled && fillApproved && environmentSnapshotCurrent(scene, measurementSnapshot);
69
+ },
70
+ };
71
+ const assignments = createMaterialAssignments(scene, controls);
72
+ function report() {
73
+ if (!environmentSnapshotCurrent(scene, measurementSnapshot)) {
74
+ measured = measureEnvironment(scene, settings.maxSourceTexels);
75
+ measurementSnapshot = captureEnvironmentSnapshot(scene);
76
+ }
77
+ fillApproved =
78
+ measured.status === "measured" &&
79
+ measured.meanRadiance !== null &&
80
+ measured.meanRadiance <= settings.darkThreshold;
81
+ return reportEnvironmentContribution(
82
+ scene,
83
+ {
84
+ ...settings,
85
+ rimGain: controls.rimGain,
86
+ fillGain: controls.fillGain,
87
+ fillColor: controls.fillColor,
88
+ fillAdmitted: controls.fillAdmitted,
89
+ },
90
+ measured,
91
+ );
92
+ }
93
+ let observation: ReturnType<typeof report>;
94
+ function setEnabled(requested: boolean): void {
95
+ if (disposed) return;
96
+ enabled = requested && materialLightingEnabled("high", options);
97
+ assignments.setEnabled(enabled);
98
+ observation = report();
99
+ }
100
+ setEnabled(options.enabled);
101
+ return {
102
+ controls,
103
+ setEnabled,
104
+ /** Enroll a newly attached game-owned subtree. */
105
+ enroll(root: Object3D): void {
106
+ if (!disposed) assignments.enroll(root);
107
+ },
108
+ /** Restore assignments before removing a subtree or disposing borrowed materials. */
109
+ release(root: Object3D): void {
110
+ if (!disposed) assignments.release(root);
111
+ },
112
+ report() {
113
+ observation = report();
114
+ return observation;
115
+ },
116
+ /** Root's later GPU sampler can provide a measured snapshot of the current environment. */
117
+ setEnvironmentMeasurement(
118
+ measurement: IEnvironmentMeasurement,
119
+ source: Texture | null = scene.environment,
120
+ intensity = scene.environmentIntensity,
121
+ snapshot: IEnvironmentSourceSnapshot = captureEnvironmentSnapshot(scene),
122
+ ): void {
123
+ if (disposed) return;
124
+ if (
125
+ measurement.status === "measured" &&
126
+ (measurement.meanRadiance === null ||
127
+ !Number.isFinite(measurement.meanRadiance) ||
128
+ measurement.meanRadiance < 0 ||
129
+ measurement.meanRGB === null ||
130
+ !measurement.meanRGB.every((value) => Number.isFinite(value) && value >= 0))
131
+ )
132
+ throw new Error("Measured environment radiance must be finite and nonnegative.");
133
+ if (
134
+ source !== snapshot.source ||
135
+ intensity !== snapshot.intensity ||
136
+ !environmentSnapshotCurrent(scene, snapshot)
137
+ )
138
+ return;
139
+ measured = measurement;
140
+ measurementSnapshot = snapshot;
141
+ observation = report();
142
+ },
143
+ debug: () => ({
144
+ ...observation,
145
+ enabled,
146
+ ...assignments.debug(),
147
+ }),
148
+ dispose(): void {
149
+ if (disposed) return;
150
+ enabled = false;
151
+ disposed = true;
152
+ assignments.dispose();
153
+ },
154
+ };
155
+ }
@@ -24,12 +24,17 @@ export function setupPost(
24
24
  mobile?: boolean;
25
25
  /** The renderer named a software adapter; this game's answer is its `low` tier. */
26
26
  software?: boolean;
27
+ /** The renderer's GPU family (`ctx.renderer.gpuClass?.class`); `quality.ts` maps it to a start tier. */
28
+ gpuClass?: string;
27
29
  /** Forces a tier, ignoring `mobile`. An unknown name throws rather than falling back. */
28
30
  tier?: QualityTier;
31
+ /** Scene-owned material assignments follow the resolved tier. */
32
+ onTierChanged?: (tier: QualityTier) => void;
29
33
  } = {},
30
- ): void {
34
+ ): { readonly tier: QualityTier; dispose(): void } {
31
35
  const tier = resolveQualityTier({
32
36
  mobile: environment.mobile,
37
+ gpuClass: environment.gpuClass,
33
38
  software: environment.software,
34
39
  tier: environment.tier,
35
40
  });
@@ -40,7 +45,17 @@ export function setupPost(
40
45
  } source=${source}`,
41
46
  );
42
47
  const world = new WorldEnvironment(qualityPreset(tier));
43
- world.apply(renderer, scene, camera, {
48
+ const applied = world.apply(renderer, scene, camera, {
44
49
  godraysLight: environment.godraysLight,
45
50
  });
51
+ environment.onTierChanged?.(tier);
52
+ let disposed = false;
53
+ return {
54
+ tier,
55
+ dispose(): void {
56
+ if (disposed) return;
57
+ disposed = true;
58
+ applied.dispose?.();
59
+ },
60
+ };
46
61
  }
@@ -46,6 +46,23 @@ function isQualityTier(value: string): value is QualityTier {
46
46
  return (QUALITY_TIERS as readonly string[]).includes(value);
47
47
  }
48
48
 
49
+ /**
50
+ * Where each GPU family starts, from `ctx.renderer.gpuClass`.
51
+ *
52
+ * A start, not a ceiling: the measured frame-budget windows move the look from here, and an
53
+ * explicit `tier` above still wins. A class absent from this table — `unknown`, an adapter no
54
+ * family rule matched — falls back to the `mobile` flag, exactly as before families existed.
55
+ * Edit the right-hand side to change what a family looks like; nothing outside this file reads it.
56
+ */
57
+ const START_TIER_BY_GPU_CLASS: Readonly<Record<string, QualityTier | undefined>> = {
58
+ software: "low",
59
+ "mobile-low": "low",
60
+ "mobile-mid": "low",
61
+ "mobile-high": "medium",
62
+ integrated: "medium",
63
+ discrete: "high",
64
+ };
65
+
49
66
  /**
50
67
  * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
51
68
  *
@@ -54,7 +71,12 @@ function isQualityTier(value: string): value is QualityTier {
54
71
  * turned out to have no effect.
55
72
  */
56
73
  export function resolveQualityTier(
57
- request: { readonly mobile?: boolean; readonly software?: boolean; readonly tier?: string } = {},
74
+ request: {
75
+ readonly gpuClass?: string;
76
+ readonly mobile?: boolean;
77
+ readonly software?: boolean;
78
+ readonly tier?: string;
79
+ } = {},
58
80
  ): QualityTier {
59
81
  const requested = request.tier;
60
82
  if (requested !== undefined) {
@@ -71,6 +93,9 @@ export function resolveQualityTier(
71
93
  // fact the renderer read from `adapter.info`, not a guess from a driver string, and an explicit
72
94
  // `tier` above still wins over it.
73
95
  if (request.software === true) return "low";
96
+ const family =
97
+ request.gpuClass === undefined ? undefined : START_TIER_BY_GPU_CLASS[request.gpuClass];
98
+ if (family !== undefined) return family;
74
99
  return request.mobile === true ? "low" : "high";
75
100
  }
76
101
 
@@ -90,6 +115,7 @@ const shared: IWorldEnvironmentOptions = {
90
115
  bloomRadius: 0.6,
91
116
  bloomStrength: 0.22,
92
117
  bloomThreshold: 1,
118
+ autoExposureEnabled: false,
93
119
  exposure: 0.62,
94
120
  tonemapMode: "aces",
95
121
  vignetteAmount: 0.22,
@@ -109,7 +135,7 @@ const high: IWorldEnvironmentOptions = {
109
135
  };
110
136
 
111
137
  /** The rung in between: the same occlusion at half the directions. Saving unmeasured. */
112
- const medium: IWorldEnvironmentOptions = { ...high, gtaoSamples: 8 };
138
+ const medium: IWorldEnvironmentOptions = { ...high, gtaoSamples: 8, renderChainTier: "medium" };
113
139
 
114
140
  /** What a phone gets: bloom, vignette and the tone curve, nothing screen-space. */
115
141
  const low: IWorldEnvironmentOptions = { ...shared, renderChainTier: "low" };
@@ -126,3 +152,36 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
126
152
  }
127
153
  return preset;
128
154
  }
155
+
156
+ /** First admitted material lane: high desktop hardware WebGPU in the browser only. */
157
+ export interface IMaterialLightingEnvironment {
158
+ readonly web: boolean;
159
+ readonly rendererKind: string;
160
+ readonly mobile?: boolean;
161
+ readonly software?: boolean;
162
+ readonly webglFallback?: boolean;
163
+ }
164
+ export function materialLightingEnabled(
165
+ tier: QualityTier,
166
+ environment: IMaterialLightingEnvironment,
167
+ ): boolean {
168
+ return (
169
+ tier === "high" &&
170
+ environment.web &&
171
+ environment.rendererKind === "webgpu" &&
172
+ environment.mobile !== true &&
173
+ environment.software !== true &&
174
+ environment.webglFallback !== true
175
+ );
176
+ }
177
+
178
+ /** A WebGPURenderer wrapper may run an ordinary WebGL fallback backend. */
179
+ export function isWebGLFallbackRenderer(renderer: unknown): boolean {
180
+ if (renderer === null || typeof renderer !== "object") return false;
181
+ const backend = Reflect.get(renderer, "backend");
182
+ return (
183
+ backend !== null &&
184
+ typeof backend === "object" &&
185
+ Reflect.get(backend, "isWebGLBackend") === true
186
+ );
187
+ }