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,111 @@
1
+ // Generated for you: these controls and this metric are the game's look. Edit freely.
2
+ import { dot, float, vec2, vec3 } from "three/tsl";
3
+ import type { Node } from "three/webgpu";
4
+
5
+ export interface IExposureSettings {
6
+ enabled: boolean;
7
+ /** Middle-grey target; increase to brighten the metered subject. */
8
+ key: number;
9
+ /** Exposure limits in stops. Expand only if the scene needs more range. */
10
+ minStops: number;
11
+ maxStops: number;
12
+ /**
13
+ * Percent of metered weight, dark to bright, ignored at each end of the histogram.
14
+ * Raise highPercent's gap (lower it) when a large bright backdrop still sets the exposure.
15
+ */
16
+ lowPercent: number;
17
+ highPercent: number;
18
+ /** Exponential response per second in log2 space. Up opens the eye; down squints. */
19
+ rateUp: number;
20
+ rateDown: number;
21
+ /** Stop error where cut acceleration begins / reaches its authored maximum. */
22
+ snapLo: number;
23
+ snapHi: number;
24
+ snapGain: number;
25
+ /** Seed for known cuts. reset() without a value adopts the next measured target. */
26
+ initialExposure: number;
27
+ settleStops: number;
28
+ /** Limit catch-up after a suspended frame, avoiding an unrequested cut. */
29
+ maxDelta: number;
30
+ /** Readback/marker cadence in seconds. Metering still runs on every drawn frame. */
31
+ reportInterval: number;
32
+ }
33
+
34
+ export const exposureSettings: Readonly<IExposureSettings> = {
35
+ enabled: false, // Opt in after qualifying this game's bright and dark captures.
36
+ key: 0.18,
37
+ minStops: -12,
38
+ maxStops: 12,
39
+ lowPercent: 10,
40
+ highPercent: 90,
41
+ rateUp: 2,
42
+ rateDown: 4,
43
+ snapLo: 3,
44
+ snapHi: 8,
45
+ snapGain: 1,
46
+ initialExposure: 1,
47
+ settleStops: 0.25,
48
+ maxDelta: 0.1,
49
+ reportInterval: 0.5,
50
+ };
51
+
52
+ /**
53
+ * Return weighted luminance and weight. The histogram's percent clip, not a clamp here, rejects
54
+ * small bright sources. The upper bound only keeps a half-float overflow from poisoning a block.
55
+ */
56
+ export function exposureMeter(colour: Node<"vec4">, uv: Node<"vec2">): Node<"vec2"> {
57
+ const luminance = dot(colour.rgb, vec3(0.2126, 0.7152, 0.0722)).clamp(0.0001, 65504);
58
+ // Larger bottom-of-frame preference favours ground over bright sky (WebGPU UV y is down).
59
+ const weight = float(1).add(uv.y);
60
+ return vec2(luminance.mul(weight), weight);
61
+ }
62
+
63
+ /** Receives the clipped histogram's linear mean luminance. Change it if the game encodes RMS. */
64
+ export function exposureLuminance(mean: Node<"float">): Node<"float"> {
65
+ return mean.max(0.0001);
66
+ }
67
+
68
+ export function validateExposureSettings(value: IExposureSettings): void {
69
+ for (const key of Object.keys(exposureSettings) as (keyof IExposureSettings)[]) {
70
+ if (key === "enabled") continue;
71
+ const number = value[key];
72
+ if (typeof number !== "number" || !Number.isFinite(Math.fround(number)))
73
+ throw new Error(`Invalid exposure ${key}: expected a finite float32 number.`);
74
+ }
75
+ if (
76
+ typeof value.enabled !== "boolean" ||
77
+ Math.fround(value.key) <= 0 ||
78
+ Math.fround(value.initialExposure) <= 0 ||
79
+ value.rateUp < 0 ||
80
+ value.rateDown < 0 ||
81
+ value.snapLo < 0 ||
82
+ value.snapHi <= value.snapLo ||
83
+ value.snapGain < 0 ||
84
+ value.snapGain > 1 ||
85
+ value.lowPercent < 0 ||
86
+ value.highPercent > 100 ||
87
+ value.lowPercent >= value.highPercent ||
88
+ value.minStops >= value.maxStops ||
89
+ value.minStops < -126 ||
90
+ value.maxStops > 126 ||
91
+ value.settleStops < 0 ||
92
+ value.maxDelta <= 0 ||
93
+ value.reportInterval <= 0
94
+ )
95
+ throw new Error("Invalid exposure settings: check limits, rates and thresholds.");
96
+ }
97
+
98
+ /** Resize only the meter. The separate history targets always remain 1x1. */
99
+ export function exposureReductionSizes(width: number, height: number): [number, number][] {
100
+ if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1)
101
+ throw new Error("Exposure drawing buffer dimensions must be positive integers.");
102
+ const sizes: [number, number][] = [];
103
+ let w = width;
104
+ let h = height;
105
+ do {
106
+ w = Math.ceil(w / 4);
107
+ h = Math.ceil(h / 4);
108
+ sizes.push([w, h]);
109
+ } while (w > 1 || h > 1);
110
+ return sizes;
111
+ }
@@ -0,0 +1,178 @@
1
+ // Generated for you: GPU reduction and adaptation; exposure.ts owns the game's look.
2
+ import { FloatType, NearestFilter, RenderTarget } from "three";
3
+ import {
4
+ Fn,
5
+ If,
6
+ Loop,
7
+ float,
8
+ int,
9
+ ivec2,
10
+ mix,
11
+ screenCoordinate,
12
+ smoothstep,
13
+ type texture,
14
+ textureLoad,
15
+ vec2,
16
+ vec4,
17
+ } from "three/tsl";
18
+ import type { Node } from "three/webgpu";
19
+ import type { IExposureSettings } from "./exposure.js";
20
+
21
+ export type ColourTexture = ReturnType<typeof texture>;
22
+ export type Meter = (colour: Node<"vec4">, uv: Node<"vec2">) => Node<"vec2">;
23
+ export type Decode = (mean: Node<"float">) => Node<"float">;
24
+
25
+ export function exposureTarget(): RenderTarget {
26
+ return new RenderTarget(1, 1, {
27
+ type: FloatType,
28
+ minFilter: NearestFilter,
29
+ magFilter: NearestFilter,
30
+ depthBuffer: false,
31
+ });
32
+ }
33
+
34
+ /** Sum/16 at each level keeps values bounded. Mask partial blocks; never replicate edge texels. */
35
+ export function reduceExposure(
36
+ input: ColourTexture,
37
+ size: Node<"vec2">,
38
+ meter?: Meter,
39
+ ): Node<"vec4"> {
40
+ return Fn(() => {
41
+ const sum = vec2(0).toVar();
42
+ const origin = screenCoordinate.xy.floor().mul(4);
43
+ for (let y = 0; y < 4; y++)
44
+ for (let x = 0; x < 4; x++) {
45
+ const pixel = origin.add(vec2(x, y));
46
+ If(pixel.x.lessThan(size.x).and(pixel.y.lessThan(size.y)), () => {
47
+ const colour = textureLoad(input, ivec2(pixel));
48
+ sum.addAssign(meter === undefined ? colour.rg : meter(colour, pixel.add(0.5).div(size)));
49
+ });
50
+ }
51
+ return vec4(sum.div(16), 0, 1);
52
+ })();
53
+ }
54
+
55
+ /** The histogram has 64 bins. Each bin spans (maxStops - minStops) / 64 stops of scene luminance. */
56
+ export const exposureBins = 64;
57
+ /** The gather splits the blocks over 64 tiles, so a bin is summed by 64 short loops, not one long. */
58
+ export const exposureTiles = 64;
59
+
60
+ /**
61
+ * Stage one of the histogram, drawn as a 64 (bins) x 64 (tiles) target. Texel (bin, tile) gathers
62
+ * its tile of the block means of `blocks` (the second reduction level, about 8 000 texels at
63
+ * 1080p, so about 130 per tile) that fall in its bin.
64
+ * r = summed weight, g = summed weight * log2 luminance, so a bin keeps its exact mean.
65
+ */
66
+ export function histogramTiles(
67
+ blocks: ColourTexture,
68
+ size: Node<"vec2">,
69
+ policy: Readonly<IExposureSettings>,
70
+ ): Node<"vec4"> {
71
+ // Range follows the authored stops: goal = log2(key) - log2(L), clamped to [min, max].
72
+ const low = Math.log2(policy.key) - policy.maxStops;
73
+ const span = policy.maxStops - policy.minStops;
74
+ return Fn(() => {
75
+ const bin = screenCoordinate.x.floor();
76
+ const weight = float(0).toVar();
77
+ const logSum = float(0).toVar();
78
+ const width = int(size.x);
79
+ const total = int(size.x.mul(size.y));
80
+ const perTile = total.add(exposureTiles - 1).div(exposureTiles);
81
+ const first = int(screenCoordinate.y.floor()).mul(perTile);
82
+ Loop({ start: 0, end: perTile }, ({ i: offset }) => {
83
+ const i = first.add(offset);
84
+ If(i.lessThan(total), () => {
85
+ const block = textureLoad(blocks, ivec2(i.mod(width), i.div(width)));
86
+ const log = block.r
87
+ .div(block.g.max(1e-20))
88
+ .max(1e-20)
89
+ .log2()
90
+ .clamp(low, low + span);
91
+ const index = log
92
+ .sub(low)
93
+ .mul(exposureBins / span)
94
+ .floor()
95
+ .min(exposureBins - 1);
96
+ If(block.g.greaterThan(0).and(index.equal(bin)), () => {
97
+ weight.addAssign(block.g);
98
+ logSum.addAssign(block.g.mul(log));
99
+ });
100
+ });
101
+ });
102
+ return vec4(weight, logSum, 0, 1);
103
+ })();
104
+ }
105
+
106
+ /** Stage two, drawn as a 64x1 target: one texel per bin, summing that bin over every tile. */
107
+ export function histogramExposure(tiles: ColourTexture): Node<"vec4"> {
108
+ return Fn(() => {
109
+ const bin = int(screenCoordinate.x.floor());
110
+ const sum = vec2(0).toVar();
111
+ Loop(exposureTiles, ({ i }) => {
112
+ sum.addAssign(textureLoad(tiles, ivec2(bin, i)).rg);
113
+ });
114
+ return vec4(sum, 0, 1);
115
+ })();
116
+ }
117
+
118
+ /**
119
+ * UE's average without outliers: drop the darkest lowPercent of the weight, stop at
120
+ * highPercent, take the weighted log2 mean of what is left. Returns (log2 mean, kept weight).
121
+ */
122
+ function clippedLog2Mean(
123
+ histogram: ColourTexture,
124
+ policy: Readonly<IExposureSettings>,
125
+ ): Node<"vec2"> {
126
+ const total = float(0).toVar();
127
+ Loop(exposureBins, ({ i }) => {
128
+ total.addAssign(textureLoad(histogram, ivec2(i, 0)).r);
129
+ });
130
+ const dropLow = total.mul(policy.lowPercent / 100).toVar();
131
+ const keepUpTo = total.mul(policy.highPercent / 100).toVar();
132
+ const kept = float(0).toVar();
133
+ const logSum = float(0).toVar();
134
+ Loop(exposureBins, ({ i }) => {
135
+ const bin = textureLoad(histogram, ivec2(i, 0));
136
+ const removed = bin.r.min(dropLow);
137
+ dropLow.subAssign(removed);
138
+ keepUpTo.subAssign(removed);
139
+ const keep = bin.r.sub(removed).min(keepUpTo);
140
+ keepUpTo.subAssign(keep);
141
+ kept.addAssign(keep);
142
+ logSum.addAssign(bin.g.mul(keep.div(bin.r.max(1e-20))));
143
+ });
144
+ return vec2(logSum.div(kept.max(1e-20)), kept);
145
+ }
146
+
147
+ export function adaptExposure(
148
+ histogram: ColourTexture,
149
+ previous: ColourTexture,
150
+ resetMode: Node<"float">,
151
+ seed: Node<"float">,
152
+ delta: Node<"float">,
153
+ policy: Readonly<IExposureSettings>,
154
+ decode: Decode,
155
+ ): Node<"vec4"> {
156
+ return Fn(() => {
157
+ const measure = clippedLog2Mean(histogram, policy);
158
+ const luminance = decode(measure.x.exp2());
159
+ const valid = measure.y
160
+ .greaterThan(0)
161
+ .and(luminance.greaterThan(0))
162
+ .and(luminance.lessThan(3.4e38));
163
+ const goal = float(Math.log2(policy.key))
164
+ .sub(luminance.max(1e-20).log2())
165
+ .clamp(policy.minStops, policy.maxStops);
166
+ const old = resetMode.equal(1).select(seed, textureLoad(previous, ivec2(0)).r);
167
+ const error = goal.sub(old);
168
+ const rate = error.greaterThan(0).select(float(policy.rateUp), float(policy.rateDown));
169
+ const normal = float(1).sub(delta.mul(rate).negate().exp());
170
+ const cut = smoothstep(policy.snapLo, policy.snapHi, error.abs()).mul(policy.snapGain);
171
+ const adapted = valid.select(
172
+ resetMode.equal(2).select(goal, mix(old, goal, mix(normal, float(1), cut))),
173
+ old,
174
+ );
175
+ const settled = goal.sub(adapted).abs().lessThanEqual(policy.settleStops).select(1, 0);
176
+ return vec4(adapted, valid.select(luminance, -1), goal, settled);
177
+ })();
178
+ }
@@ -0,0 +1,79 @@
1
+ // Generated for you: async GPU observations stay tied to their owner's live generation.
2
+ import type { RenderTarget } from "three";
3
+ import type { Renderer } from "three/webgpu";
4
+
5
+ export class ExposureReadback {
6
+ #pending = false;
7
+ #generation = 0;
8
+ #lastReport = Number.NEGATIVE_INFINITY;
9
+ #disposed = false;
10
+ #value: Record<string, unknown>;
11
+ constructor(
12
+ readonly constant: number,
13
+ readonly enabled: () => boolean,
14
+ ) {
15
+ this.#value = { measured: false, applied: enabled() };
16
+ }
17
+ invalidate(): void {
18
+ this.#generation++;
19
+ this.#value = { measured: false, applied: this.enabled() };
20
+ this.#lastReport = Number.NEGATIVE_INFINITY;
21
+ }
22
+ get(): Record<string, unknown> {
23
+ return { ...this.#value };
24
+ }
25
+ dispose(): void {
26
+ this.#disposed = true;
27
+ this.#generation++;
28
+ }
29
+ report(renderer: Renderer, result: RenderTarget, time: number, interval: number): void {
30
+ if (this.#pending || time - this.#lastReport < interval) return;
31
+ this.#pending = true;
32
+ this.#lastReport = time;
33
+ const generation = this.#generation;
34
+ const current = () => !this.#disposed && generation === this.#generation;
35
+ const enabled = this.enabled;
36
+ const constant = this.constant;
37
+ const publish = (observation: Record<string, unknown>) => {
38
+ this.#value = observation;
39
+ };
40
+ const finished = () => {
41
+ this.#pending = false;
42
+ };
43
+ void renderer
44
+ .readRenderTargetPixelsAsync(result, 0, 0, 1, 1)
45
+ .then((values) => {
46
+ if (!current()) return;
47
+ if (
48
+ !(values instanceof Float32Array) ||
49
+ values.length < 4 ||
50
+ !Array.from(values).every(Number.isFinite) ||
51
+ (values[1] ?? 0) <= 0
52
+ )
53
+ throw new Error("Exposure readback is invalid; measurement is unavailable.");
54
+ const observation = {
55
+ measured: true,
56
+ applied: enabled(),
57
+ luminance: values[1],
58
+ exposureStops: enabled() ? values[0] : Math.log2(constant),
59
+ targetStops: values[2],
60
+ settled: values[3] === 1,
61
+ };
62
+ publish(observation);
63
+ console.info(`TN_AUTO_EXPOSURE:${JSON.stringify(observation)}`);
64
+ })
65
+ .catch((error: unknown) => {
66
+ if (!current()) return;
67
+ const observation = {
68
+ measured: false,
69
+ applied: enabled(),
70
+ reason: String(error),
71
+ };
72
+ publish(observation);
73
+ console.error(`TN_AUTO_EXPOSURE:${JSON.stringify(observation)}`);
74
+ })
75
+ .finally(() => {
76
+ finished();
77
+ });
78
+ }
79
+ }
@@ -0,0 +1,118 @@
1
+ // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
+ // ThreeNative does not read this file. `sky.ts` owns the numbers; this file is the fog maths.
3
+ import { Color, type FogExp2, type Vector3 } from "three";
4
+ import {
5
+ cameraPosition,
6
+ densityFogFactor,
7
+ dot,
8
+ exp2,
9
+ float,
10
+ fog,
11
+ max,
12
+ mix,
13
+ positionWorld,
14
+ pow,
15
+ saturate,
16
+ select,
17
+ uniform,
18
+ vec3,
19
+ } from "three/tsl";
20
+
21
+ /**
22
+ * Height fog, in metres, y up. Density falls off exponentially above `fogHeight`; the fog along the
23
+ * ray from the camera to a fragment is the closed-form integral of that density, so low ground
24
+ * reads hazier than a ridge at the same distance and a camera above the layer looks down through it.
25
+ * Every control says which way to move it.
26
+ */
27
+ export const HEIGHT_FOG = {
28
+ /** Optical depth per metre at `fogHeight` (base 2). Up: thicker ground mist. */
29
+ density: 0.0018,
30
+ /** Per metre above `fogHeight`. Up: a thinner, lower layer. Down: mist climbs the hills. */
31
+ heightFalloff: 0.08,
32
+ /** World y where density equals `density`. Move it to the ground of your world. */
33
+ fogHeight: 0,
34
+ /** Floor on the height term's transparency, 0..1. Below 1 leaves a clear window in the mist. */
35
+ maxOpacity: 1,
36
+ /** Metres from the camera before the mist starts. Up: a clear foreground. */
37
+ startDistance: 0,
38
+ /** Sun lobe sharpness. Up: a tighter glow around the sun. */
39
+ sunExponent: 4,
40
+ /** Metres before sun glow starts, so nearby objects are not tinted. */
41
+ sunStartDistance: 100,
42
+ /** Metres past which the height term is off. 0 = never. Never set it inside a streaming ring. */
43
+ cutoffDistance: 0,
44
+ } as const;
45
+ export type HeightFogParams = { -readonly [K in keyof typeof HEIGHT_FOG]: number };
46
+
47
+ const LN2 = Math.LN2;
48
+
49
+ // Camera density term, clamped so exp2 stays finite (Unreal clamps the exponent at -127).
50
+ const clampExponent = (x: number): number => Math.min(127, Math.max(-127, x));
51
+
52
+ /** `density` times the integral of 2^(-k t) over [a, b]; k is the ray's slope times `falloff`. */
53
+ function segment(density: number, k: number, a: number, b: number): number {
54
+ if (b <= a) return 0;
55
+ if (Math.abs(k * b) < 0.01) return density * (b - a - 0.5 * LN2 * k * (b * b - a * a));
56
+ return (density * (2 ** (-k * a) - 2 ** (-k * b))) / (k * LN2);
57
+ }
58
+
59
+ function rayTerms(p: HeightFogParams, cameraY: number, fragmentY: number, length: number) {
60
+ const camera = p.density * 2 ** clampExponent(-p.heightFalloff * (cameraY - p.fogHeight));
61
+ const k = length > 0 ? (p.heightFalloff * (fragmentY - cameraY)) / length : 0;
62
+ return { camera, k };
63
+ }
64
+
65
+ /** Base-2 optical depth (transmittance is 2^-depth) of the mist between the camera and a fragment. */
66
+ export function heightFogDepth(
67
+ p: HeightFogParams,
68
+ cameraY: number,
69
+ fragmentY: number,
70
+ length: number,
71
+ ): number {
72
+ if (p.cutoffDistance > 0 && length > p.cutoffDistance) return 0;
73
+ const { camera, k } = rayTerms(p, cameraY, fragmentY, length);
74
+ return segment(camera, k, p.startDistance, length);
75
+ }
76
+
77
+ const SUN_COLOUR = new Color(0xfff1d6);
78
+
79
+ /**
80
+ * `T_distance x T_height`, on `scene.fogNode`: three applies it to every material where `scene.fog`
81
+ * would be. The distance term reads the live `FogExp2`, so changing its colour or density at runtime
82
+ * still works. It is never more transparent than that term alone, so wherever the distance term
83
+ * reaches 0 the frame stays fully fogged. Pass `sun` for a glow toward it past `sunStartDistance`.
84
+ */
85
+ export function heightFogNode(distanceFog: FogExp2, p: HeightFogParams, sun?: Vector3) {
86
+ const color = uniform(new Color());
87
+ color.onRenderUpdate(() => color.value.copy(distanceFog.color));
88
+ const density = uniform(0);
89
+ density.onRenderUpdate(() => {
90
+ density.value = distanceFog.density;
91
+ });
92
+ // Density at the camera, once per frame instead of once per fragment.
93
+ const cameraDensity = uniform(0);
94
+ cameraDensity.onRenderUpdate(({ camera }) => {
95
+ const y = camera?.matrixWorld.elements[13] ?? 0;
96
+ cameraDensity.value = p.density * 2 ** clampExponent(-p.heightFalloff * (y - p.fogHeight));
97
+ });
98
+ const ray = positionWorld.sub(cameraPosition);
99
+ const length = ray.length().max(1e-4);
100
+ const k = float(p.heightFalloff).mul(positionWorld.y.sub(cameraPosition.y)).div(length);
101
+ const integral = (a: number) => {
102
+ const b = max(length, a);
103
+ const curved = cameraDensity
104
+ .mul(exp2(k.mul(a).negate()).sub(exp2(k.mul(b).negate())))
105
+ .div(k.mul(LN2));
106
+ return select(k.mul(b).abs().lessThan(0.01), cameraDensity.mul(b.sub(a)), curved);
107
+ };
108
+ const cut = p.cutoffDistance > 0 ? select(length.greaterThan(p.cutoffDistance), 0, 1) : float(1);
109
+ const heightT = max(exp2(integral(p.startDistance).mul(cut).negate()), 1 - p.maxOpacity);
110
+ const opacity = densityFogFactor(density).oneMinus().mul(heightT).oneMinus();
111
+ if (sun === undefined) return fog(color, opacity);
112
+ const lobe = pow(saturate(dot(ray.div(length), vec3(sun.x, sun.y, sun.z))), p.sunExponent);
113
+ const glow = float(1)
114
+ .sub(exp2(integral(Math.max(p.sunStartDistance, p.startDistance)).negate()))
115
+ .mul(lobe)
116
+ .mul(p.maxOpacity);
117
+ return fog(mix(color, vec3(SUN_COLOUR.r, SUN_COLOUR.g, SUN_COLOUR.b), glow), opacity);
118
+ }
@@ -6,7 +6,7 @@
6
6
  // flattens exactly the shadow side the sun was there to make. The low-poly geometry keeps its own
7
7
  // separation through `flatShading` and baked vertex mottle, which is why this level reads as
8
8
  // facetted without a second light.
9
- import { DirectionalLight, PCFSoftShadowMap, type Scene, type Vector3 } from "three";
9
+ import { Color, DirectionalLight, PCFSoftShadowMap, type Scene, Vector3 } from "three";
10
10
  import { SUN_DIRECTION } from "./sky.js";
11
11
 
12
12
  type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
@@ -53,3 +53,28 @@ export function setupLighting(scene: Scene, renderer: ShadowRenderer, mobile = f
53
53
  key,
54
54
  };
55
55
  }
56
+
57
+ /** Material conventions are game-owned; each scene gets independent mutable controls. */
58
+ export interface ILightingConvention {
59
+ rimGain: number;
60
+ fillGain: number;
61
+ fillColor: Color;
62
+ fillDirection: Vector3;
63
+ fillAngularSize: number;
64
+ darkThreshold: number;
65
+ maxSourceTexels: number;
66
+ }
67
+ export function createLightingConvention(
68
+ overrides: Partial<ILightingConvention> = {},
69
+ ): ILightingConvention {
70
+ return {
71
+ rimGain: 0.12,
72
+ fillGain: 1,
73
+ fillColor: new Color(0x667b9d),
74
+ fillDirection: new Vector3(0, 1, 1).normalize(),
75
+ fillAngularSize: 0.7,
76
+ darkThreshold: 0.001,
77
+ maxSourceTexels: 65536,
78
+ ...overrides,
79
+ };
80
+ }
@@ -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
+ }