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,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,16 @@ 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
+ onTierChanged?: (tier: QualityTier) => void;
29
32
  } = {},
30
- ): void {
33
+ ): { readonly tier: QualityTier; dispose(): void } {
31
34
  const tier = resolveQualityTier({
32
35
  mobile: environment.mobile,
36
+ gpuClass: environment.gpuClass,
33
37
  software: environment.software,
34
38
  tier: environment.tier,
35
39
  });
@@ -40,5 +44,15 @@ export function setupPost(
40
44
  } source=${source}`,
41
45
  );
42
46
  const world = new WorldEnvironment(qualityPreset(tier));
43
- world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
47
+ const applied = world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
48
+ environment.onTierChanged?.(tier);
49
+ let disposed = false;
50
+ return {
51
+ tier,
52
+ dispose(): void {
53
+ if (disposed) return;
54
+ disposed = true;
55
+ applied.dispose?.();
56
+ },
57
+ };
44
58
  }
@@ -45,6 +45,23 @@ function isQualityTier(value: string): value is QualityTier {
45
45
  return (QUALITY_TIERS as readonly string[]).includes(value);
46
46
  }
47
47
 
48
+ /**
49
+ * Where each GPU family starts, from `ctx.renderer.gpuClass`.
50
+ *
51
+ * A start, not a ceiling: the measured frame-budget windows move the look from here, and an
52
+ * explicit `tier` above still wins. A class absent from this table — `unknown`, an adapter no
53
+ * family rule matched — falls back to the `mobile` flag, exactly as before families existed.
54
+ * Edit the right-hand side to change what a family looks like; nothing outside this file reads it.
55
+ */
56
+ const START_TIER_BY_GPU_CLASS: Readonly<Record<string, QualityTier | undefined>> = {
57
+ software: "low",
58
+ "mobile-low": "low",
59
+ "mobile-mid": "low",
60
+ "mobile-high": "medium",
61
+ integrated: "medium",
62
+ discrete: "high",
63
+ };
64
+
48
65
  /**
49
66
  * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
50
67
  *
@@ -53,7 +70,12 @@ function isQualityTier(value: string): value is QualityTier {
53
70
  * turned out to have no effect.
54
71
  */
55
72
  export function resolveQualityTier(
56
- request: { readonly mobile?: boolean; readonly software?: boolean; readonly tier?: string } = {},
73
+ request: {
74
+ readonly gpuClass?: string;
75
+ readonly mobile?: boolean;
76
+ readonly software?: boolean;
77
+ readonly tier?: string;
78
+ } = {},
57
79
  ): QualityTier {
58
80
  const requested = request.tier;
59
81
  if (requested !== undefined) {
@@ -70,6 +92,9 @@ export function resolveQualityTier(
70
92
  // fact the renderer read from `adapter.info`, not a guess from a driver string, and an explicit
71
93
  // `tier` above still wins over it.
72
94
  if (request.software === true) return "low";
95
+ const family =
96
+ request.gpuClass === undefined ? undefined : START_TIER_BY_GPU_CLASS[request.gpuClass];
97
+ if (family !== undefined) return family;
73
98
  return request.mobile === true ? "low" : "high";
74
99
  }
75
100
 
@@ -87,6 +112,7 @@ const high: IWorldEnvironmentOptions = {
87
112
  bloomEnabled: false,
88
113
  // No SSGI runs here, so there is nothing for the denoiser to clean up. Off, explicitly.
89
114
  denoiseEnabled: false,
115
+ autoExposureEnabled: false,
90
116
  exposure: 0.95,
91
117
  // Off at every tier — see the note at the top of this file.
92
118
  ssgiEnabled: false,
@@ -133,3 +159,35 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
133
159
  }
134
160
  return preset;
135
161
  }
162
+
163
+ export interface IMaterialLightingEnvironment {
164
+ readonly web: boolean;
165
+ readonly rendererKind: string;
166
+ readonly mobile?: boolean;
167
+ readonly software?: boolean;
168
+ readonly webglFallback?: boolean;
169
+ }
170
+ export function materialLightingEnabled(
171
+ tier: QualityTier,
172
+ environment: IMaterialLightingEnvironment,
173
+ ): boolean {
174
+ return (
175
+ tier === "high" &&
176
+ environment.web &&
177
+ environment.rendererKind === "webgpu" &&
178
+ environment.mobile !== true &&
179
+ environment.software !== true &&
180
+ environment.webglFallback !== true
181
+ );
182
+ }
183
+
184
+ /** A WebGPURenderer wrapper may run an ordinary WebGL fallback backend. */
185
+ export function isWebGLFallbackRenderer(renderer: unknown): boolean {
186
+ if (renderer === null || typeof renderer !== "object") return false;
187
+ const backend = Reflect.get(renderer, "backend");
188
+ return (
189
+ backend !== null &&
190
+ typeof backend === "object" &&
191
+ Reflect.get(backend, "isWebGLBackend") === true
192
+ );
193
+ }
@@ -8,12 +8,30 @@ import {
8
8
  MeshBasicMaterial,
9
9
  type Scene,
10
10
  SphereGeometry,
11
+ Vector3,
11
12
  } from "three";
13
+ import { HEIGHT_FOG, type HeightFogParams, heightFogDepth, heightFogNode } from "./heightFog.js";
12
14
  import { palette } from "./palette.js";
13
15
 
14
16
  const CLEAR_FOG = new Color(palette.skyLow);
15
17
  const STORM_FOG = new Color(0xafc3d1);
16
18
 
19
+ /** The look this fog replaced: FogExp2 at 0.016, measured at 40 m from 2 m up. */
20
+ const EYE_LEVEL = { density: 0.016, distance: 40, cameraHeight: 2 };
21
+
22
+ /**
23
+ * The distance term's density that, with the height term, keeps the old eye-level haze: at
24
+ * `EYE_LEVEL.distance` along the horizon from `EYE_LEVEL.cameraHeight` the two together transmit what
25
+ * FogExp2 at `EYE_LEVEL.density` did. The distance term is lowered, never removed, so the ground
26
+ * still ends in fog at a kilometre.
27
+ */
28
+ function distanceDensity(p: HeightFogParams = HEIGHT_FOG): number {
29
+ const { distance, density, cameraHeight } = EYE_LEVEL;
30
+ const old = (density * distance) ** 2;
31
+ const height = heightFogDepth(p, cameraHeight, cameraHeight, distance) * Math.LN2;
32
+ return Math.sqrt(Math.max(0, old - height)) / distance;
33
+ }
34
+
17
35
  /** A graded dome with a warm sun glow, plus the haze; returns how to darken both for a storm. */
18
36
  export function setupSky(scene: Scene): (storm: number) => void {
19
37
  const RADIUS = 450;
@@ -46,12 +64,13 @@ export function setupSky(scene: Scene): (storm: number) => void {
46
64
  dome.renderOrder = -100;
47
65
  scene.background = bottom;
48
66
  scene.add(dome);
49
- const fog = new FogExp2(CLEAR_FOG.getHex(), 0.016);
67
+ const fog = new FogExp2(CLEAR_FOG.getHex(), distanceDensity());
50
68
  scene.fog = fog;
69
+ scene.fogNode = heightFogNode(fog, HEIGHT_FOG, new Vector3(sun.x, sun.y, sun.z));
51
70
  return (storm) => {
52
71
  fog.color.copy(CLEAR_FOG).lerp(STORM_FOG, storm);
53
72
  // Thick enough to swallow the far forest, thin enough that the explorer stays readable.
54
- fog.density = 0.016 + storm * 0.05;
73
+ fog.density = distanceDensity() + storm * 0.05;
55
74
  material.color.setScalar(1 - storm * 0.3);
56
75
  };
57
76
  }