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,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
+ }
@@ -10,22 +10,34 @@
10
10
  // run — a desktop that is dropping frames, a capture you want to compare — pass it:
11
11
  // `setupPost(renderer, scene, camera, { tier: "low" })`. Overriding does not silence the report:
12
12
  // `TN_QUALITY_TIER` names the tier that ran either way.
13
- import type { Camera, DirectionalLight, Scene } from "three";
13
+ import { type Camera, type DirectionalLight, FloatType, type Scene } from "three";
14
+ import { LUTCubeLoader } from "three/addons/loaders/LUTCubeLoader.js";
14
15
  import {
15
16
  type IAdaptiveQualityOptions,
16
17
  type IQualityWindow,
17
18
  createAdaptiveQuality,
18
19
  formatQualityAdaptation,
19
20
  } from "./adaptiveQuality.js";
20
- import { type QualityTier, qualityPreset } from "./quality.js";
21
+ import { type IGradeTable, filterableTable, gradeStages } from "./grade.js";
22
+ import { type QualityTier, gradePreset, qualityPreset } from "./quality.js";
23
+ import { type TemporalAAProvider, temporalAAStages } from "./temporalAAStage.js";
24
+ import type { FogMedium } from "./volumetricFog.js";
21
25
  import { type OutputRenderer, WorldEnvironment } from "./worldEnvironment.js";
22
26
 
23
27
  interface IPostController {
28
+ readonly tier: QualityTier;
24
29
  debug(): Record<string, unknown>;
25
30
  observe(window: IQualityWindow): void;
26
31
  dispose(): void;
27
32
  }
28
33
 
34
+ /**
35
+ * This game's colour table, relative to the page so it resolves the same way served and packaged.
36
+ * `public/grade.cube` is written by `tools/make-grade-lut.mjs`, and replacing it with a `.cube`
37
+ * from any grading tool is the whole of "change the grade".
38
+ */
39
+ const GRADE_TABLE_URL = "grade.cube";
40
+
29
41
  let active: IPostController | undefined;
30
42
 
31
43
  /** The starter's game.ts connects its existing completed frame-window callback here. */
@@ -42,14 +54,29 @@ export function setupPost(
42
54
  mobile?: boolean;
43
55
  /** The renderer named a software adapter; this game's answer is its `low` tier. */
44
56
  software?: boolean;
57
+ /** The renderer's GPU family (`ctx.renderer.gpuClass?.class`); `quality.ts` maps it to a start tier. */
58
+ gpuClass?: string;
45
59
  /** Forces a tier while keeping its costs observed. Unknown names throw. */
46
60
  tier?: QualityTier;
61
+ /** Scene-owned material assignments follow the same resolved tier. */
62
+ onTierChanged?: (tier: QualityTier) => void;
63
+ /**
64
+ * The bounded participating medium from `volumetricFog.ts`, built once per graph: a tier change
65
+ * replaces the graph, and a fog controller owns one graph, so it is released and rebuilt here
66
+ * rather than composed twice. Omit it and the chain starts from the beauty pass unchanged.
67
+ */
68
+ fog?: () => FogMedium | undefined;
47
69
  } = {},
48
70
  ): IPostController {
49
71
  const policy = createAdaptiveQuality(environment, environment);
50
72
  active?.dispose();
51
73
  let disposed = false;
52
74
  let disposeGraph: (() => void) | undefined;
75
+ let medium: FogMedium | undefined;
76
+ let table: IGradeTable | undefined;
77
+ // The opt-in `traa` stage publishes its provider here once the chain has built it, so `debug()`
78
+ // reports the live reconstruction state and a scene can reset history on a teleport.
79
+ let temporal: TemporalAAProvider | undefined;
53
80
  let observation: Record<string, unknown> = {
54
81
  tier: policy.tier,
55
82
  source: policy.pinned ? "pinned" : "auto",
@@ -57,15 +84,58 @@ export function setupPost(
57
84
  function apply(): void {
58
85
  // Replacement is serialized: no old graph or subscription remains alive beside the new one.
59
86
  disposeGraph?.();
87
+ medium?.dispose();
88
+ medium = environment.fog?.();
89
+ const composed = medium;
60
90
  const settings = qualityPreset(policy.tier);
61
- const world = new WorldEnvironment(settings);
91
+ const world = new WorldEnvironment({
92
+ ...settings,
93
+ // Two stages this game owns, not the chain's: `grade.ts` builds them, `WorldEnvironment`
94
+ // orders and reports them, and `quality.ts` decides whether each tier runs them. The opt-in
95
+ // `traa` stage is offered beside them and runs only when a tier names it.
96
+ authoredStageNames: ["grade", "grain"],
97
+ authoredStages: (stage) => [
98
+ ...gradeStages(gradePreset(policy.tier), table),
99
+ ...temporalAAStages(stage, {
100
+ onProvider: (provider) => {
101
+ temporal = provider;
102
+ },
103
+ }),
104
+ ],
105
+ });
62
106
  const applied = world.apply(renderer, scene, camera, {
63
107
  godraysLight: environment.godraysLight,
108
+ // Ahead of exposure and every stage, which is the only place a participating medium can go.
109
+ baseColour: composed === undefined ? undefined : (scenePass) => composed.compose(scenePass),
64
110
  });
65
111
  disposeGraph = applied.dispose;
66
112
  observation = { ...observation, stages: applied.stages, dropped: applied.dropped };
113
+ environment.onTierChanged?.(policy.tier);
67
114
  }
68
115
  apply();
116
+ // The table is a file, so it lands after the chain that would read it. Until then both stages
117
+ // are refused with a reason rather than grading nothing, and the chain is rebuilt once it does.
118
+ // The loader parses `FloatType`, because the default 8-bit load *truncates* `value * 255` into a
119
+ // `Uint8Array`. An identity table then reads low by up to 0.875 of a step, and the round trip
120
+ // through the grade is never the frame the game drew. Parsed floats keep the file's own numbers.
121
+ // `filterableTable` then uploads them as half floats. A float32 3D texture is not filterable
122
+ // without the optional `float32-filterable` feature, so the lookup would sample the nearest of
123
+ // the nine cells. The arithmetic in `__tests__/grade.spec.ts` runs on those half floats.
124
+ const tableLoader = new LUTCubeLoader().setType(FloatType);
125
+ void tableLoader.loadAsync(GRADE_TABLE_URL).then(
126
+ (loaded) => {
127
+ table?.texture.dispose();
128
+ table = { size: loaded.size, texture: filterableTable(loaded.texture3D) };
129
+ if (!disposed) apply();
130
+ },
131
+ (error: unknown) => {
132
+ // A missing table is this game's file, not the harness's: name it and leave the frame
133
+ // ungraded rather than reporting a stage as applied that never ran.
134
+ console.error(
135
+ `TN_GRADE_TABLE ${GRADE_TABLE_URL}: ${error instanceof Error ? error.message : String(error)}`,
136
+ );
137
+ },
138
+ );
69
139
  const source = environment.tier === undefined ? "platform" : "override";
70
140
  console.info(
71
141
  `TN_QUALITY_TIER ${policy.tier} mobile=${environment.mobile === true} software=${
@@ -73,7 +143,10 @@ export function setupPost(
73
143
  } source=${source}`,
74
144
  );
75
145
  const controller = {
76
- debug: () => observation,
146
+ get tier(): QualityTier {
147
+ return policy.tier;
148
+ },
149
+ debug: () => (temporal ? { ...observation, temporal: temporal.report() } : { ...observation }),
77
150
  observe(window: IQualityWindow): void {
78
151
  if (disposed) return;
79
152
  const decision = policy.observe(window);
@@ -91,6 +164,13 @@ export function setupPost(
91
164
  disposed = true;
92
165
  disposeGraph?.();
93
166
  disposeGraph = undefined;
167
+ medium?.dispose();
168
+ medium = undefined;
169
+ // The table outlives any one chain — a tier change rebuilds the graph around the same one —
170
+ // so it is released here and not by a stage that would take it with the first replacement.
171
+ table?.texture.dispose();
172
+ table = undefined;
173
+ temporal = undefined;
94
174
  if (active === controller) active = undefined;
95
175
  },
96
176
  };
@@ -19,15 +19,12 @@
19
19
  // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
20
  // in `sky.ts`, not in this file.
21
21
  //
22
+ import type { IGradeSettings } from "./grade.js";
22
23
  import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
23
24
 
24
25
  /**
25
- * The three names this game's look comes in.
26
- *
27
- * `low` is what a phone gets and `high` what a desktop gets — those two are this template's
28
- * shipped looks. `medium` is the rung in between for a machine that is neither: a laptop iGPU, a
29
- * handheld, a desktop that is dropping frames. Nothing outside this file decides what any of them
30
- * mean.
26
+ * This game's authored looks. GPU family picks the start; measured frame budgets refine it.
27
+ * Edit these presets to change the look without changing the framework.
31
28
  */
32
29
  export type QualityTier = "low" | "medium" | "high";
33
30
 
@@ -41,6 +38,23 @@ function isQualityTier(value: string): value is QualityTier {
41
38
  return (QUALITY_TIERS as readonly string[]).includes(value);
42
39
  }
43
40
 
41
+ /**
42
+ * Where each GPU family starts, from `ctx.renderer.gpuClass`.
43
+ *
44
+ * A start, not a ceiling: the measured frame-budget windows move the look from here, and an
45
+ * explicit `tier` above still wins. A class absent from this table — `unknown`, an adapter no
46
+ * family rule matched — falls back to the `mobile` flag, exactly as before families existed.
47
+ * Edit the right-hand side to change what a family looks like; nothing outside this file reads it.
48
+ */
49
+ const START_TIER_BY_GPU_CLASS: Readonly<Record<string, QualityTier | undefined>> = {
50
+ software: "low",
51
+ "mobile-low": "low",
52
+ "mobile-mid": "low",
53
+ "mobile-high": "medium",
54
+ integrated: "medium",
55
+ discrete: "high",
56
+ };
57
+
44
58
  /**
45
59
  * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
46
60
  *
@@ -49,7 +63,12 @@ function isQualityTier(value: string): value is QualityTier {
49
63
  * turned out to have no effect.
50
64
  */
51
65
  export function resolveQualityTier(
52
- request: { readonly mobile?: boolean; readonly software?: boolean; readonly tier?: string } = {},
66
+ request: {
67
+ readonly gpuClass?: string;
68
+ readonly mobile?: boolean;
69
+ readonly software?: boolean;
70
+ readonly tier?: string;
71
+ } = {},
53
72
  ): QualityTier {
54
73
  const requested = request.tier;
55
74
  if (requested !== undefined) {
@@ -66,6 +85,9 @@ export function resolveQualityTier(
66
85
  // fact the renderer read from `adapter.info`, not a guess from a driver string, and an explicit
67
86
  // `tier` above still wins over it.
68
87
  if (request.software === true) return "low";
88
+ const family =
89
+ request.gpuClass === undefined ? undefined : START_TIER_BY_GPU_CLASS[request.gpuClass];
90
+ if (family !== undefined) return family;
69
91
  return request.mobile === true ? "low" : "high";
70
92
  }
71
93
 
@@ -80,6 +102,7 @@ export function resolveQualityTier(
80
102
  * smooth sky gradient into visible bands. Both are one line to turn back on for a glossy scene.
81
103
  */
82
104
  const shared: IWorldEnvironmentOptions = {
105
+ autoExposureEnabled: false,
83
106
  // Bloom cost: ~4.6 ms in the reference ablation — the second most expensive stage there.
84
107
  bloomEnabled: true,
85
108
  bloomRadius: 0.6,
@@ -102,19 +125,51 @@ const high: IWorldEnvironmentOptions = {
102
125
  gtaoEnabled: true,
103
126
  gtaoRadius: 0.35,
104
127
  renderChainTier: "high",
128
+ // Temporal AA is opt-in and no shipped tier names it: add `authoredStageNames: ["traa"]` here to
129
+ // reconstruct at the display raster, and read `setupPost(...).debug().temporal` for the reset and
130
+ // raster state it reports. Its rejection fraction, ghosting and frame-time cost are unqualified.
105
131
  };
106
132
 
107
133
  /**
108
134
  * The rung in between: the same occlusion at half the directions. Saving unmeasured, and the
109
135
  * chain's own antialiasing one notch cheaper.
110
136
  */
111
- const medium: IWorldEnvironmentOptions = { ...high, gtaoSamples: 8, renderChainTier: "medium" };
137
+ // SMAA owns medium edges; another four-sample world resolve adds mobile bandwidth.
138
+ const medium: IWorldEnvironmentOptions = {
139
+ ...high,
140
+ gtaoSamples: 8,
141
+ renderChainTier: "medium",
142
+ samples: 0,
143
+ };
112
144
 
113
145
  /** What a phone gets: bloom, vignette and the tone curve, nothing screen-space. */
114
146
  const low: IWorldEnvironmentOptions = { ...shared, renderChainTier: "low" };
115
147
 
116
148
  const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
117
149
 
150
+ /**
151
+ * This game's colour grade and grain, per tier. The table itself lives in `public/grade.cube` and
152
+ * the maths in `grade.ts`; these are the four numbers the look is dialled with.
153
+ *
154
+ * **The grain default is 1/255, and that is the point.** `film()` scales its noise by
155
+ * the pixel's own value, so on mid-grey concrete this moves a channel by well under half an 8-bit
156
+ * step — below what the framebuffer can show. It shipped at 0.12, and a blind judge called the
157
+ * result "grain clearly visible as speckle over sky and flat walls and behind HUD text". A default
158
+ * must never degrade the look, so raise this number when you want the film look: 0.12 is a visible
159
+ * grain, 0.3 a heavy one.
160
+ *
161
+ * A zero refuses its stage rather than running it at zero strength, so `low` — a phone, where a
162
+ * moving grain is the first thing to go — reports `grain` as refused with its reason instead of
163
+ * reading as applied. The grade survives there: it is one texture fetch and the frame is the
164
+ * same frame without it. `high` keeps a non-zero grain on purpose, so `TN_RENDER_CHAIN` can still
165
+ * name it as applied there rather than reporting the stage a default deliberately declined to run.
166
+ */
167
+ const GRADE_PRESETS: Record<QualityTier, IGradeSettings> = {
168
+ high: { gradeIntensity: 1, grainAnimated: true, grainIntensity: 0.0039, tier: "high" },
169
+ medium: { gradeIntensity: 1, grainAnimated: false, grainIntensity: 0.0039, tier: "medium" },
170
+ low: { gradeIntensity: 1, grainAnimated: false, grainIntensity: 0, tier: "low" },
171
+ };
172
+
118
173
  /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
119
174
  export function qualityPreset(tier: string): IWorldEnvironmentOptions {
120
175
  const preset = QUALITY_PRESETS[tier as QualityTier];
@@ -125,3 +180,20 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
125
180
  }
126
181
  return preset;
127
182
  }
183
+
184
+ /** The grade and grain a tier runs. Throws on a name that is not a tier, for the same reason. */
185
+ export function gradePreset(tier: string): IGradeSettings {
186
+ const preset = GRADE_PRESETS[tier as QualityTier];
187
+ if (preset === undefined) {
188
+ throw new Error(
189
+ `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
190
+ );
191
+ }
192
+ return preset;
193
+ }
194
+
195
+ export {
196
+ type IMaterialLightingEnvironment,
197
+ isWebGLFallbackRenderer,
198
+ materialLightingEnabled,
199
+ } from "./rendererGate.js";
@@ -0,0 +1,54 @@
1
+ /** The adaptive-quality numeric policy: the defaults, the author's overrides, and their limits. */
2
+ export interface IQualityPolicy {
3
+ readonly targetFps: number;
4
+ readonly overloadedWindows: number;
5
+ readonly healthyWindows: number;
6
+ readonly headroom: number;
7
+ readonly presentationTolerance: number;
8
+ readonly cooldownMs: number;
9
+ readonly startupWindows: number;
10
+ readonly minFrames: number;
11
+ readonly maxGpuAgeFrames: number;
12
+ }
13
+
14
+ /** Merges the overrides onto the defaults, then rejects any value the policy cannot use. */
15
+ export function resolveQualityPolicy(options: Partial<IQualityPolicy>): IQualityPolicy {
16
+ const policy: IQualityPolicy = {
17
+ targetFps: 60,
18
+ overloadedWindows: 2,
19
+ healthyWindows: 5,
20
+ headroom: 0.2,
21
+ presentationTolerance: 0.05,
22
+ cooldownMs: 5000,
23
+ startupWindows: 1,
24
+ minFrames: 30,
25
+ maxGpuAgeFrames: 4,
26
+ ...options,
27
+ };
28
+ for (const key of ["targetFps", "overloadedWindows", "healthyWindows", "minFrames"] as const) {
29
+ if (!Number.isFinite(policy[key]) || policy[key] <= 0)
30
+ throw new Error(`quality ${key} must be positive.`);
31
+ }
32
+ for (const key of ["cooldownMs", "startupWindows", "maxGpuAgeFrames"] as const) {
33
+ if (!Number.isFinite(policy[key]) || policy[key] < 0)
34
+ throw new Error(`quality ${key} must be non-negative.`);
35
+ }
36
+ for (const key of [
37
+ "overloadedWindows",
38
+ "healthyWindows",
39
+ "startupWindows",
40
+ "minFrames",
41
+ "maxGpuAgeFrames",
42
+ ] as const) {
43
+ if (!Number.isInteger(policy[key])) throw new Error(`quality ${key} must be an integer.`);
44
+ }
45
+ if (!Number.isFinite(policy.headroom) || policy.headroom <= 0 || policy.headroom >= 1)
46
+ throw new Error("quality headroom must be between zero and one.");
47
+ if (
48
+ !Number.isFinite(policy.presentationTolerance) ||
49
+ policy.presentationTolerance < 0 ||
50
+ policy.presentationTolerance >= 1
51
+ )
52
+ throw new Error("quality presentationTolerance must be between zero and one.");
53
+ return policy;
54
+ }