create-threenative 0.2.7 → 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 (541) hide show
  1. package/README.md +3 -1
  2. package/agent-docs/references/assertion-reference.md +87 -35
  3. package/agent-docs/references/auto-exposure.md +57 -0
  4. package/agent-docs/references/capability-reference.md +1306 -62
  5. package/agent-docs/references/debug-surface.md +6 -0
  6. package/agent-docs/references/finding-assets.md +46 -10
  7. package/agent-docs/references/performance-basics.md +5 -4
  8. package/agent-docs/references/terrain-authoring.md +140 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  10. package/capabilities.json +1505 -79
  11. package/dist/index.d.ts +28 -3
  12. package/dist/index.js +402 -167
  13. package/dist/threenative.js +989 -237
  14. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  15. package/dist/web-engine-decal-geometry.js +184 -0
  16. package/dist/web-engine-gltf-loader.js +196 -0
  17. package/dist/web-engine-hdr-loader.js +190 -0
  18. package/dist/web-engine-lut-cube-loader.js +122 -0
  19. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  20. package/dist/web-engine-mesh-bvh.js +32 -0
  21. package/dist/web-engine-post-effects.js +168 -0
  22. package/dist/web-engine-runtime.js +42506 -0
  23. package/package.json +11 -8
  24. package/template-assets/autoExposure.ts +225 -0
  25. package/template-assets/exposure.ts +111 -0
  26. package/template-assets/exposureGraph.ts +178 -0
  27. package/template-assets/exposureReadback.ts +79 -0
  28. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  29. package/template-assets/patches/three@0.185.1.patch +6594 -700
  30. package/template-assets/patches/vite@8.2.0.patch +422 -0
  31. package/template-assets/worldEnvironment.ts +433 -30
  32. package/templates/action-rpg/AGENTS.md +11 -10
  33. package/templates/action-rpg/CLAUDE.md +11 -10
  34. package/templates/action-rpg/package.json +11 -9
  35. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  36. package/templates/action-rpg/src/progress.ts +0 -4
  37. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  38. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  39. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  40. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  41. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  42. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  43. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  44. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  45. package/templates/action-rpg/src/render/exposure.ts +111 -0
  46. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  47. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  48. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  49. package/templates/action-rpg/src/render/lighting.ts +26 -1
  50. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  51. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  52. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  53. package/templates/action-rpg/src/render/quality.ts +61 -2
  54. package/templates/action-rpg/src/render/sky.ts +21 -1
  55. package/templates/action-rpg/src/render/vfx.ts +133 -58
  56. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  57. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  58. package/templates/action-rpg/threenative.config.ts +3 -0
  59. package/templates/action-rpg/vite.config.ts +10 -2
  60. package/templates/minimal/AGENTS.md +9 -10
  61. package/templates/minimal/CLAUDE.md +9 -10
  62. package/templates/minimal/package.json +9 -8
  63. package/templates/minimal/playtests/play.playtest.json +7 -1
  64. package/templates/minimal/playtests/sky.playtest.json +10 -1
  65. package/templates/minimal/src/render/autoExposure.ts +225 -0
  66. package/templates/minimal/src/render/backlightControls.ts +66 -0
  67. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  68. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  69. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  70. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  71. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  72. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  73. package/templates/minimal/src/render/exposure.ts +111 -0
  74. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  75. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  76. package/templates/minimal/src/render/heightFog.ts +118 -0
  77. package/templates/minimal/src/render/lighting.ts +25 -1
  78. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  79. package/templates/minimal/src/render/materialLighting.ts +146 -0
  80. package/templates/minimal/src/render/postprocessing.ts +16 -2
  81. package/templates/minimal/src/render/quality.ts +60 -2
  82. package/templates/minimal/src/render/sky.ts +21 -1
  83. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  84. package/templates/minimal/src/scenes/Play.ts +50 -1
  85. package/templates/minimal/vite.config.ts +10 -2
  86. package/templates/platformer/AGENTS.md +7 -5
  87. package/templates/platformer/CLAUDE.md +7 -5
  88. package/templates/platformer/package.json +11 -9
  89. package/templates/platformer/playtests/performance.playtest.json +7 -1
  90. package/templates/platformer/src/render/autoExposure.ts +225 -0
  91. package/templates/platformer/src/render/backlightControls.ts +66 -0
  92. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  93. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  94. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  95. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  96. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  97. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  98. package/templates/platformer/src/render/exposure.ts +111 -0
  99. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  100. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  101. package/templates/platformer/src/render/heightFog.ts +118 -0
  102. package/templates/platformer/src/render/lighting.ts +26 -1
  103. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  104. package/templates/platformer/src/render/materialLighting.ts +155 -0
  105. package/templates/platformer/src/render/materials.ts +7 -2
  106. package/templates/platformer/src/render/palette.ts +3 -3
  107. package/templates/platformer/src/render/postprocessing.ts +17 -2
  108. package/templates/platformer/src/render/quality.ts +61 -2
  109. package/templates/platformer/src/render/sky.ts +72 -23
  110. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  111. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  112. package/templates/platformer/src/scenes/Play.ts +70 -6
  113. package/templates/platformer/vite.config.ts +10 -2
  114. package/templates/puzzle/AGENTS.md +10 -9
  115. package/templates/puzzle/CLAUDE.md +10 -9
  116. package/templates/puzzle/package.json +11 -9
  117. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  118. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  119. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  120. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  121. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  122. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  123. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  124. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  125. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  126. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  127. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  128. package/templates/puzzle/src/render/exposure.ts +111 -0
  129. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  130. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  131. package/templates/puzzle/src/render/heightFog.ts +118 -0
  132. package/templates/puzzle/src/render/lighting.ts +33 -1
  133. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  134. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  135. package/templates/puzzle/src/render/materials.ts +1 -1
  136. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  137. package/templates/puzzle/src/render/quality.ts +62 -1
  138. package/templates/puzzle/src/render/sky.ts +20 -1
  139. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  140. package/templates/puzzle/src/scenes/Play.ts +51 -2
  141. package/templates/puzzle/vite.config.ts +10 -2
  142. package/templates/racing/AGENTS.md +8 -7
  143. package/templates/racing/CLAUDE.md +8 -7
  144. package/templates/racing/package.json +11 -9
  145. package/templates/racing/playtests/performance.playtest.json +7 -1
  146. package/templates/racing/playtests/survives.playtest.json +6 -0
  147. package/templates/racing/src/render/autoExposure.ts +225 -0
  148. package/templates/racing/src/render/backlightControls.ts +66 -0
  149. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  150. package/templates/racing/src/render/environmentContribution.ts +188 -0
  151. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  152. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  153. package/templates/racing/src/render/environmentSampling.ts +193 -0
  154. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  155. package/templates/racing/src/render/exposure.ts +111 -0
  156. package/templates/racing/src/render/exposureGraph.ts +178 -0
  157. package/templates/racing/src/render/exposureReadback.ts +79 -0
  158. package/templates/racing/src/render/heightFog.ts +118 -0
  159. package/templates/racing/src/render/lighting.ts +29 -1
  160. package/templates/racing/src/render/materialAssignments.ts +160 -0
  161. package/templates/racing/src/render/materialLighting.ts +155 -0
  162. package/templates/racing/src/render/palette.ts +1 -10
  163. package/templates/racing/src/render/postprocessing.ts +17 -2
  164. package/templates/racing/src/render/quality.ts +61 -2
  165. package/templates/racing/src/render/shapes.ts +0 -25
  166. package/templates/racing/src/render/sky.ts +21 -1
  167. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  168. package/templates/racing/src/scenes/Race.ts +91 -3
  169. package/templates/racing/src/track/circuit.ts +0 -9
  170. package/templates/racing/vite.config.ts +10 -2
  171. package/templates/rain/.codex/config.toml +19 -0
  172. package/templates/rain/.cursor/mcp.json +32 -0
  173. package/templates/rain/.gemini/settings.json +32 -0
  174. package/templates/rain/.mcp.json +32 -0
  175. package/templates/rain/.vscode/mcp.json +36 -0
  176. package/templates/rain/.zed/settings.json +36 -0
  177. package/templates/rain/AGENTS.md +95 -0
  178. package/templates/rain/CLAUDE.md +97 -0
  179. package/templates/rain/assets/rain-loop.wav +0 -0
  180. package/templates/rain/assets/thunder.wav +0 -0
  181. package/templates/rain/assets/wind-loop.wav +0 -0
  182. package/templates/rain/index.html +18 -0
  183. package/templates/rain/kit.json +7 -0
  184. package/templates/rain/native-playtests/boot.playtest.json +23 -0
  185. package/templates/rain/native-playtests/lightning.playtest.json +173 -0
  186. package/templates/rain/opencode.json +41 -0
  187. package/templates/rain/package.json +59 -0
  188. package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
  189. package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
  190. package/templates/rain/playtests/automation.playtest.json +133 -0
  191. package/templates/rain/playtests/cinematic.playtest.json +59 -0
  192. package/templates/rain/playtests/flash.playtest.json +27 -0
  193. package/templates/rain/playtests/fly.playtest.json +54 -0
  194. package/templates/rain/playtests/lightning.playtest.json +220 -0
  195. package/templates/rain/playtests/loading.playtest.json +57 -0
  196. package/templates/rain/playtests/paused.playtest.json +59 -0
  197. package/templates/rain/playtests/performance.playtest.json +32 -0
  198. package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
  199. package/templates/rain/playtests/simulation.playtest.json +20 -0
  200. package/templates/rain/playtests/storm.playtest.json +150 -0
  201. package/templates/rain/playtests/survives.playtest.json +58 -0
  202. package/templates/rain/playtests/tiers.playtest.json +194 -0
  203. package/templates/rain/playtests/weather.playtest.json +77 -0
  204. package/templates/rain/public/favicon.svg +5 -0
  205. package/templates/rain/src/audio/storm.ts +314 -0
  206. package/templates/rain/src/game.ts +81 -0
  207. package/templates/rain/src/main.ts +15 -0
  208. package/templates/rain/src/render/autoExposure.ts +225 -0
  209. package/templates/rain/src/render/bloom-shader.ts +65 -0
  210. package/templates/rain/src/render/camera.ts +160 -0
  211. package/templates/rain/src/render/clouds-shader.ts +242 -0
  212. package/templates/rain/src/render/clouds.ts +142 -0
  213. package/templates/rain/src/render/exposure.ts +111 -0
  214. package/templates/rain/src/render/exposureGraph.ts +178 -0
  215. package/templates/rain/src/render/exposureReadback.ts +79 -0
  216. package/templates/rain/src/render/lighting.ts +39 -0
  217. package/templates/rain/src/render/lightning.ts +360 -0
  218. package/templates/rain/src/render/loading.ts +327 -0
  219. package/templates/rain/src/render/materials.ts +19 -0
  220. package/templates/rain/src/render/noise-volume.ts +159 -0
  221. package/templates/rain/src/render/palette.ts +18 -0
  222. package/templates/rain/src/render/post-shader.ts +178 -0
  223. package/templates/rain/src/render/postprocessing.ts +229 -0
  224. package/templates/rain/src/render/quality.ts +161 -0
  225. package/templates/rain/src/render/rain.ts +299 -0
  226. package/templates/rain/src/render/sky.ts +28 -0
  227. package/templates/rain/src/render/world-shader.ts +680 -0
  228. package/templates/rain/src/render/world.ts +146 -0
  229. package/templates/rain/src/render/worldEnvironment.ts +1212 -0
  230. package/templates/rain/src/scenes/Boot.ts +348 -0
  231. package/templates/rain/src/state.ts +261 -0
  232. package/templates/rain/src/style.css +1160 -0
  233. package/templates/rain/src/ui/App.tsx +29 -0
  234. package/templates/rain/src/ui/GameUi.tsx +187 -0
  235. package/templates/rain/src/ui/Hud.tsx +327 -0
  236. package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
  237. package/templates/rain/src/ui/Menu.tsx +370 -0
  238. package/templates/rain/src/ui/automation.ts +60 -0
  239. package/templates/rain/src/ui/main.tsx +7 -0
  240. package/templates/rain/src/ui/tempest.ts +149 -0
  241. package/templates/rain/tailwind.config.ts +2 -0
  242. package/templates/rain/threenative.config.ts +66 -0
  243. package/templates/rain/tools/generate-shaders.mjs +656 -0
  244. package/templates/rain/tools/make-storm-audio.mjs +387 -0
  245. package/templates/rain/tools/storm-dsp.mjs +177 -0
  246. package/templates/rain/tools/tempest-bloom.frag +10 -0
  247. package/templates/rain/tools/tempest-clouds.frag +86 -0
  248. package/templates/rain/tools/tempest-post.frag +47 -0
  249. package/templates/rain/tools/tempest-world.frag +210 -0
  250. package/templates/rain/tools/verify-noise-volume.mjs +61 -0
  251. package/templates/rain/tsconfig.json +17 -0
  252. package/templates/rain/vite.config.ts +45 -0
  253. package/templates/rts/AGENTS.md +10 -11
  254. package/templates/rts/CLAUDE.md +10 -11
  255. package/templates/rts/package.json +10 -8
  256. package/templates/rts/playtests/performance.playtest.json +7 -1
  257. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  258. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  259. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  260. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  261. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  262. package/templates/rts/src/render/army.ts +10 -2
  263. package/templates/rts/src/render/autoExposure.ts +225 -0
  264. package/templates/rts/src/render/backlightControls.ts +66 -0
  265. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  266. package/templates/rts/src/render/environmentContribution.ts +188 -0
  267. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  268. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  269. package/templates/rts/src/render/environmentSampling.ts +193 -0
  270. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  271. package/templates/rts/src/render/exposure.ts +111 -0
  272. package/templates/rts/src/render/exposureGraph.ts +178 -0
  273. package/templates/rts/src/render/exposureReadback.ts +79 -0
  274. package/templates/rts/src/render/heightFog.ts +118 -0
  275. package/templates/rts/src/render/lighting.ts +26 -1
  276. package/templates/rts/src/render/materialAssignments.ts +160 -0
  277. package/templates/rts/src/render/materialLighting.ts +155 -0
  278. package/templates/rts/src/render/postprocessing.ts +8 -2
  279. package/templates/rts/src/render/quality.ts +61 -2
  280. package/templates/rts/src/render/sky.ts +21 -1
  281. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  282. package/templates/rts/src/scenes/Play.ts +54 -3
  283. package/templates/rts/src/sim/ai.ts +0 -1
  284. package/templates/rts/src/sim/terrain.ts +0 -4
  285. package/templates/rts/vite.config.ts +10 -2
  286. package/templates/runner/AGENTS.md +10 -8
  287. package/templates/runner/CLAUDE.md +10 -8
  288. package/templates/runner/package.json +11 -9
  289. package/templates/runner/playtests/performance.playtest.json +10 -1
  290. package/templates/runner/src/physics.ts +0 -1
  291. package/templates/runner/src/render/autoExposure.ts +225 -0
  292. package/templates/runner/src/render/backlightControls.ts +66 -0
  293. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  294. package/templates/runner/src/render/environmentContribution.ts +188 -0
  295. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  296. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  297. package/templates/runner/src/render/environmentSampling.ts +193 -0
  298. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  299. package/templates/runner/src/render/exposure.ts +111 -0
  300. package/templates/runner/src/render/exposureGraph.ts +178 -0
  301. package/templates/runner/src/render/exposureReadback.ts +79 -0
  302. package/templates/runner/src/render/heightFog.ts +118 -0
  303. package/templates/runner/src/render/lighting.ts +26 -1
  304. package/templates/runner/src/render/materialAssignments.ts +160 -0
  305. package/templates/runner/src/render/materialLighting.ts +155 -0
  306. package/templates/runner/src/render/postprocessing.ts +17 -2
  307. package/templates/runner/src/render/quality.ts +61 -2
  308. package/templates/runner/src/render/sky.ts +21 -1
  309. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  310. package/templates/runner/src/scenes/Run.ts +67 -2
  311. package/templates/runner/threenative.config.ts +3 -0
  312. package/templates/runner/vite.config.ts +10 -2
  313. package/templates/sailing/AGENTS.md +14 -13
  314. package/templates/sailing/CLAUDE.md +14 -13
  315. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  316. package/templates/sailing/package.json +11 -9
  317. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  318. package/templates/sailing/src/entities/Ship.ts +38 -18
  319. package/templates/sailing/src/render/autoExposure.ts +225 -0
  320. package/templates/sailing/src/render/backlightControls.ts +66 -0
  321. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  322. package/templates/sailing/src/render/camera.ts +12 -4
  323. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  324. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  325. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  327. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  328. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  329. package/templates/sailing/src/render/exposure.ts +111 -0
  330. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  331. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  332. package/templates/sailing/src/render/heightFog.ts +118 -0
  333. package/templates/sailing/src/render/lighting.ts +26 -1
  334. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  335. package/templates/sailing/src/render/materialLighting.ts +155 -0
  336. package/templates/sailing/src/render/ocean.ts +71 -53
  337. package/templates/sailing/src/render/postprocessing.ts +16 -2
  338. package/templates/sailing/src/render/props.ts +0 -45
  339. package/templates/sailing/src/render/quality.ts +61 -1
  340. package/templates/sailing/src/render/sky.ts +21 -1
  341. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  342. package/templates/sailing/src/scenes/Boot.ts +12 -1
  343. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  344. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  345. package/templates/sailing/threenative.config.ts +3 -0
  346. package/templates/sailing/vite.config.ts +10 -2
  347. package/templates/shooter/AGENTS.md +8 -6
  348. package/templates/shooter/CLAUDE.md +8 -6
  349. package/templates/shooter/package.json +11 -9
  350. package/templates/shooter/playtests/performance.playtest.json +7 -1
  351. package/templates/shooter/src/entities/Enemy.ts +0 -15
  352. package/templates/shooter/src/entities/Rifle.ts +38 -1
  353. package/templates/shooter/src/render/autoExposure.ts +225 -0
  354. package/templates/shooter/src/render/backlightControls.ts +66 -0
  355. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  356. package/templates/shooter/src/render/camera.ts +1 -12
  357. package/templates/shooter/src/render/decals.ts +299 -5
  358. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  359. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  360. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  361. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  362. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  363. package/templates/shooter/src/render/exposure.ts +111 -0
  364. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  365. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  366. package/templates/shooter/src/render/gunfx.ts +0 -1
  367. package/templates/shooter/src/render/heightFog.ts +118 -0
  368. package/templates/shooter/src/render/lighting.ts +26 -1
  369. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  370. package/templates/shooter/src/render/materialLighting.ts +155 -0
  371. package/templates/shooter/src/render/postprocessing.ts +17 -2
  372. package/templates/shooter/src/render/quality.ts +61 -2
  373. package/templates/shooter/src/render/scale.ts +2 -93
  374. package/templates/shooter/src/render/sky.ts +21 -1
  375. package/templates/shooter/src/render/vehicles.ts +0 -17
  376. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  377. package/templates/shooter/src/scenes/Play.ts +64 -2
  378. package/templates/shooter/vite.config.ts +10 -2
  379. package/templates/snow/.codex/config.toml +19 -0
  380. package/templates/snow/.cursor/mcp.json +32 -0
  381. package/templates/snow/.gemini/settings.json +32 -0
  382. package/templates/snow/.mcp.json +32 -0
  383. package/templates/snow/.vscode/mcp.json +36 -0
  384. package/templates/snow/.zed/settings.json +36 -0
  385. package/templates/snow/AGENTS.md +90 -0
  386. package/templates/snow/CLAUDE.md +92 -0
  387. package/templates/snow/README.md +26 -0
  388. package/templates/snow/assets/crunch.wav +0 -0
  389. package/templates/snow/assets/wind.wav +0 -0
  390. package/templates/snow/index.html +12 -0
  391. package/templates/snow/kit.json +7 -0
  392. package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
  393. package/templates/snow/native-playtests/survives.playtest.json +47 -0
  394. package/templates/snow/opencode.json +41 -0
  395. package/templates/snow/package.json +60 -0
  396. package/templates/snow/playtests/footsteps.playtest.json +95 -0
  397. package/templates/snow/playtests/performance.playtest.json +36 -0
  398. package/templates/snow/playtests/snow-physics.playtest.json +154 -0
  399. package/templates/snow/playtests/survives.playtest.json +56 -0
  400. package/templates/snow/playtests/touch-controls.playtest.json +71 -0
  401. package/templates/snow/playtests/weather.playtest.json +119 -0
  402. package/templates/snow/public/favicon.svg +5 -0
  403. package/templates/snow/src/audio.ts +58 -0
  404. package/templates/snow/src/commands.ts +8 -0
  405. package/templates/snow/src/entities/Explorer.ts +279 -0
  406. package/templates/snow/src/game.ts +69 -0
  407. package/templates/snow/src/main.ts +15 -0
  408. package/templates/snow/src/render/autoExposure.ts +225 -0
  409. package/templates/snow/src/render/backlightControls.ts +66 -0
  410. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  411. package/templates/snow/src/render/bootPrint.ts +50 -0
  412. package/templates/snow/src/render/camera.ts +84 -0
  413. package/templates/snow/src/render/environmentContribution.ts +188 -0
  414. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  415. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  416. package/templates/snow/src/render/environmentSampling.ts +193 -0
  417. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  418. package/templates/snow/src/render/explorer.ts +321 -0
  419. package/templates/snow/src/render/exposure.ts +111 -0
  420. package/templates/snow/src/render/exposureGraph.ts +178 -0
  421. package/templates/snow/src/render/exposureReadback.ts +79 -0
  422. package/templates/snow/src/render/heightFog.ts +118 -0
  423. package/templates/snow/src/render/lighting.ts +82 -0
  424. package/templates/snow/src/render/loading.ts +325 -0
  425. package/templates/snow/src/render/materialAssignments.ts +160 -0
  426. package/templates/snow/src/render/materialLighting.ts +155 -0
  427. package/templates/snow/src/render/materials.ts +36 -0
  428. package/templates/snow/src/render/palette.ts +17 -0
  429. package/templates/snow/src/render/postprocessing.ts +58 -0
  430. package/templates/snow/src/render/props.ts +42 -0
  431. package/templates/snow/src/render/quality.ts +193 -0
  432. package/templates/snow/src/render/scenery.ts +244 -0
  433. package/templates/snow/src/render/sky.ts +76 -0
  434. package/templates/snow/src/render/snowSurface.ts +259 -0
  435. package/templates/snow/src/render/touch-controls.ts +143 -0
  436. package/templates/snow/src/render/weather.ts +279 -0
  437. package/templates/snow/src/render/worldEnvironment.ts +1212 -0
  438. package/templates/snow/src/scenes/Boot.ts +12 -0
  439. package/templates/snow/src/scenes/Snow.ts +663 -0
  440. package/templates/snow/src/state.ts +46 -0
  441. package/templates/snow/src/style.css +143 -0
  442. package/templates/snow/src/terrain.ts +64 -0
  443. package/templates/snow/src/ui/App.tsx +15 -0
  444. package/templates/snow/src/ui/Controls.tsx +322 -0
  445. package/templates/snow/src/ui/GameUi.tsx +354 -0
  446. package/templates/snow/src/ui/icons.tsx +54 -0
  447. package/templates/snow/src/ui/main.tsx +7 -0
  448. package/templates/snow/tailwind.config.ts +2 -0
  449. package/templates/snow/threenative.config.ts +54 -0
  450. package/templates/snow/tsconfig.json +17 -0
  451. package/templates/snow/vite.config.ts +45 -0
  452. package/templates/starter/AGENTS.md +11 -16
  453. package/templates/starter/CLAUDE.md +11 -16
  454. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  455. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  456. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  457. package/templates/starter/package.json +11 -9
  458. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  459. package/templates/starter/playtests/movement.playtest.json +192 -0
  460. package/templates/starter/playtests/play.playtest.json +18 -2
  461. package/templates/starter/playtests/production-readiness.playtest.json +1 -1
  462. package/templates/starter/public/grade.cube +735 -0
  463. package/templates/starter/src/entities/Crate.ts +4 -0
  464. package/templates/starter/src/entities/Player.ts +79 -18
  465. package/templates/starter/src/game.ts +1 -0
  466. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  467. package/templates/starter/src/render/autoExposure.ts +225 -0
  468. package/templates/starter/src/render/backlightControls.ts +66 -0
  469. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  470. package/templates/starter/src/render/environmentContribution.ts +188 -0
  471. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  472. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  473. package/templates/starter/src/render/environmentSampling.ts +193 -0
  474. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  475. package/templates/starter/src/render/exposure.ts +111 -0
  476. package/templates/starter/src/render/exposureGraph.ts +178 -0
  477. package/templates/starter/src/render/exposureReadback.ts +79 -0
  478. package/templates/starter/src/render/grade.ts +157 -0
  479. package/templates/starter/src/render/heightFog.ts +118 -0
  480. package/templates/starter/src/render/lighting.ts +26 -1
  481. package/templates/starter/src/render/materialAssignments.ts +160 -0
  482. package/templates/starter/src/render/materialLighting.ts +155 -0
  483. package/templates/starter/src/render/postprocessing.ts +84 -4
  484. package/templates/starter/src/render/quality.ts +80 -8
  485. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  486. package/templates/starter/src/render/rendererGate.ts +36 -0
  487. package/templates/starter/src/render/sky.ts +23 -1
  488. package/templates/starter/src/render/temporalAA.ts +197 -0
  489. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  490. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  491. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  492. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  493. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  494. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  495. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  496. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  497. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  498. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  499. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  500. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  501. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  502. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  503. package/templates/starter/src/render/temporalResolve.ts +139 -0
  504. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  505. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  506. package/templates/starter/src/render/volumetricFog.ts +124 -0
  507. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  508. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  509. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  510. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  511. package/templates/starter/src/scenes/Play.ts +110 -1
  512. package/templates/starter/src/state.ts +1 -0
  513. package/templates/starter/src/ui/Hud.tsx +1 -1
  514. package/templates/starter/src/ui/Menu.tsx +1 -1
  515. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  516. package/templates/starter/vite.config.ts +10 -2
  517. package/templates/tower-defense/AGENTS.md +10 -9
  518. package/templates/tower-defense/CLAUDE.md +10 -9
  519. package/templates/tower-defense/package.json +11 -9
  520. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  521. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  522. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  523. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  524. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  525. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  526. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  527. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  528. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  529. package/templates/tower-defense/src/render/exposure.ts +111 -0
  530. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  531. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  532. package/templates/tower-defense/src/render/lighting.ts +33 -1
  533. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  534. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  535. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  536. package/templates/tower-defense/src/render/quality.ts +61 -2
  537. package/templates/tower-defense/src/render/shapes.ts +0 -3
  538. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  539. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  540. package/templates/tower-defense/vite.config.ts +10 -2
  541. package/templates/minimal/src/scenes/Boot.ts +0 -5
@@ -0,0 +1,656 @@
1
+ // Regenerates src/render/*-shader.ts from the tempest-*.frag files.
2
+ //
3
+ // Two shaders come out of one pipeline: the raymarched coast and the cloud volume it stands under.
4
+ // Both are several hundred lines of GLSL from the Tempest single-file demo, so porting either by
5
+ // hand is a transcription exercise with no end state. The installed Three.js transpiler
6
+ // (`three/examples/jsm/transpiler`) does the port at authoring time and this file checks the
7
+ // result. Nothing is compiled or evaluated at runtime: the output is an ordinary `.ts` module that
8
+ // Vite and the native packager see like any other source file.
9
+ //
10
+ // Fails closed. A GLSL construct the upstream decoder does not understand, a uniform the emitted
11
+ // code reads but nothing binds, a local this file cannot materialise, a branch dropped at runtime,
12
+ // or any warning from the decoder stops the run instead of writing a file that quietly lost one.
13
+ //
14
+ // node tools/generate-shaders.mjs
15
+ import { execFileSync } from "node:child_process";
16
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
17
+ import { dirname, relative, resolve } from "node:path";
18
+ import { fileURLToPath } from "node:url";
19
+ import ts from "@typescript/typescript6";
20
+ import GLSLDecoder from "three/examples/jsm/transpiler/GLSLDecoder.js";
21
+ import TSLEncoder from "three/examples/jsm/transpiler/TSLEncoder.js";
22
+ import Transpiler from "three/examples/jsm/transpiler/Transpiler.js";
23
+
24
+ const here = dirname(fileURLToPath(import.meta.url));
25
+ // The repository this template lives in, four levels up from `tools/`. A scaffolded project has no
26
+ // Biome of its own, which is why the formatting step below is optional and says so.
27
+ const repoRoot = resolve(here, "../../../../..");
28
+ // Biome refuses paths outside the directory it is run from, so it runs from the repository root,
29
+ // which is also where the configuration that formats the generated file lives. The unsafe fixes
30
+ // are asked for on purpose and were diffed: for this output they are the import sort and the
31
+ // split of multi-name `const` declarators, both of which leave the graph alone.
32
+ const biome = resolve(repoRoot, "node_modules/.bin/biome");
33
+
34
+ /**
35
+ * A sampler the decoder turns into a texture node, and how each is declared here. Both start as a
36
+ * 1-voxel placeholder that the owning module replaces by assigning `.value`, because a sampled node
37
+ * needs a texture before the graph is built.
38
+ */
39
+ const SAMPLERS = {
40
+ sampler2D: { node: "texture", texture: "DataTexture", create: "1, 1" },
41
+ sampler3D: { node: "texture3D", texture: "Data3DTexture", create: "1, 1, 1" },
42
+ };
43
+
44
+ /** Uniform defaults, so nothing reads an unset value on the first frame. */
45
+ const DEFAULTS = {
46
+ float: "0",
47
+ int: "0",
48
+ vec2: "new Vector2()",
49
+ vec3: "new Vector3()",
50
+ vec4: "new Vector4()",
51
+ };
52
+
53
+ /**
54
+ * Applied to every emitted module. GLSL's `mat2(a, b, c, d)` is column-major — `(a, b)` is the first
55
+ * column — but TSL's `mat2(a, b, c, d)` with constants builds a `Matrix2`, whose constructor takes
56
+ * row-major arguments. Passed through unchanged, fbm's octave rotation comes out transposed: a
57
+ * rotation the other way, so every octave after the first lands somewhere else and the terrain's
58
+ * ridges, the puddles and the cloud shapes all drift from the study's. Swapping the off-diagonal
59
+ * pair is the transpose back.
60
+ */
61
+ const MAT2_COLUMN_MAJOR = {
62
+ what: "a constant mat2 in GLSL's column-major order",
63
+ find: /mat2\(\s*([^,()]+),\s*([^,()]+),\s*([^,()]+),\s*([^,()]+)\)/g,
64
+ replace: "mat2($1, $3, $2, $4)",
65
+ };
66
+
67
+ /**
68
+ * The shaders this generates. `rewrites` are edits to the GLSL text; each one is a rewrite with a
69
+ * named reason, and a rule that matches nothing stops the run. `entryOpen` turns the stage's
70
+ * `main` into the one function the module exports; `entryClose` covers what that function has to
71
+ * hand back.
72
+ */
73
+ const SHADERS = [
74
+ {
75
+ name: "world",
76
+ marker: "TN_WORLD_SHADER",
77
+ source: "tempest-world.frag",
78
+ target: "../src/render/world-shader.ts",
79
+ entry: "tempestWorld",
80
+ /** The coast raymarches with a depth term, so it seeds one the way a GLSL global would. */
81
+ entryOpen: ["void main(){", "vec4 tempestWorld(vec2 vUv){float worldDepth=1.;"],
82
+ entryClose: [
83
+ { what: "gl_FragDepth", find: "gl_FragDepth", replace: "worldDepth" },
84
+ {
85
+ what: "the fragment output",
86
+ find: "fragColor=vec4(max(color,vec3(0.)),1.);",
87
+ replace: "return vec4(max(color,vec3(0.)),worldDepth);",
88
+ },
89
+ ],
90
+ samplers: ["sampler2D"],
91
+ /** The ripple loop is a nested pair, which the decoder names in a way `LoopNode` cannot read. */
92
+ nestedLoop: true,
93
+ /**
94
+ * Edits to the code the transpiler emitted, rather than to the GLSL it read. This one is the
95
+ * coast's alone: the decoder turns `roadCenter`'s `-1.6` into `-(1.6).add(x)`, which asks a
96
+ * JavaScript number for a TSL method and throws on the first frame. `float(-1.6)` is the same
97
+ * value. The cloud volume has no literal in that position, so it declares none.
98
+ */
99
+ outputRewrites: [
100
+ MAT2_COLUMN_MAJOR,
101
+ {
102
+ what: "a negated literal with a TSL method call on it",
103
+ find: /- ?((?:\d+\.\d*|\.\d+|\d+))\.(?=[A-Za-z_$])/g,
104
+ replace: "float(-$1).",
105
+ },
106
+ {
107
+ // The one orientation rule this shader needs, and it is deliberately not a camera- or
108
+ // backend-name conditional. `vUv` is the screen quad's geometry uv: bottom-up, `y = 1` at
109
+ // the top of the frame. `uSky` is a `PassTextureNode` — a render target written by the
110
+ // cloud pass — and a render target's first row is the top of the image it holds, so its
111
+ // `y = 0` is the top of the frame. Sampling one with the other hands the coast the sky
112
+ // upside down: the deck's bright horizon band lands high in the frame, well above the
113
+ // world's own horizon, and the whole ceiling is mirrored. Normalising the coordinate at the
114
+ // fetch is the fix, and it is fetch-local: `ray(vUv)` still marches with the bottom-up uv
115
+ // the source was written against, so the cloud volume and every density in it are
116
+ // untouched. Both reads are rewritten, the direct sky sample and the reflected `suv`,
117
+ // because a flip on one and not the other would put the reflections somewhere the sky they
118
+ // mirror is not.
119
+ what: "the pass-texture sample coordinate",
120
+ find: /uSky\.sample\(\s*(\w+)\s*\)/g,
121
+ replace: "uSky.sample(vec2($1.x,$1.y.oneMinus()))",
122
+ imports: ["oneMinus"],
123
+ },
124
+ ],
125
+ rewrites: [
126
+ {
127
+ // The upstream decoder only reads the first name of a comma-separated uniform list, so every
128
+ // uniform after the first in `uniform float a,b,c;` is dropped from the emitted module and
129
+ // would be a ReferenceError at runtime. `boundUniforms` below re-adds and checks them all.
130
+ what: "the ripple loop braces",
131
+ find: "for(int j=-1;j<=1;j++)",
132
+ replace: "for(int j=-1;j<=1;j++){",
133
+ },
134
+ {
135
+ what: "the ripple loop close",
136
+ find: " }return sum*uRain;",
137
+ replace: " }}return sum*uRain;",
138
+ },
139
+ ],
140
+ header: `// The shader is the coast: terrain, road, sea, the rail and cabin on it, wet reflections and the
141
+ // fog that closes the distance. It is raymarched, so it is one full-screen quad and one function
142
+ // call — see src/render/world.ts for the uniforms and the camera basis it expects.`,
143
+ },
144
+ {
145
+ name: "clouds",
146
+ marker: "TN_CLOUDS_SHADER",
147
+ source: "tempest-clouds.frag",
148
+ target: "../src/render/clouds-shader.ts",
149
+ entry: "tempestClouds",
150
+ /** The cloud volume has no depth term; it is the colour the coast samples for its sky. */
151
+ entryOpen: ["void main(){", "vec4 tempestClouds(vec2 vUv){"],
152
+ entryClose: [],
153
+ samplers: ["sampler3D"],
154
+ nestedLoop: false,
155
+ outputRewrites: [
156
+ MAT2_COLUMN_MAJOR,
157
+ {
158
+ // The decoder's own `gl_FragCoord` polyfill reaches for `screenCoordinate.z`, which is not a
159
+ // member of a `vec2` screen coordinate: the fragment depth is its own node, and that is what
160
+ // `gl_FragCoord.z` is.
161
+ what: "the depth component of the decoded gl_FragCoord",
162
+ find: "screenCoordinate.z",
163
+ replace: "depth",
164
+ imports: ["depth"],
165
+ },
166
+ ],
167
+ rewrites: [],
168
+ header: `// The shader is the storm ceiling: a raymarched volume between 145 and 815 metres, lit by a
169
+ // five-tap march toward the sun and filled from a procedural 64³ noise volume. It is one full-screen
170
+ // pass into a render target the coast samples — see src/render/clouds.ts.`,
171
+ },
172
+ ];
173
+
174
+ /** Applied to every shader before it is parsed, because none of them is valid GLSL on its own. */
175
+ const COMMON_REWRITES = [
176
+ {
177
+ // `precision` is a GLSL-only qualifier with no TSL equivalent; TSL picks the precision itself.
178
+ what: "precision qualifiers",
179
+ find: /precision[^;]*;/g,
180
+ replace: "",
181
+ },
182
+ {
183
+ // The stage's own varyings become the generated function's parameters, not module state.
184
+ what: "stage declarations",
185
+ find: /\b(?:in|out)\s+\w+\s+\w+\s*;/g,
186
+ replace: "",
187
+ },
188
+ ];
189
+
190
+ // The emitted code is JavaScript, so the structural fixes below are made on its syntax tree rather
191
+ // than on its text: the transpiler's own output decides where they apply, and a shape this file
192
+ // does not recognise stops the run rather than being rewritten by a pattern that happened to fit.
193
+ // TypeScript is the template's own devDependency, so a scaffolded project has it.
194
+
195
+ const parse = (text) =>
196
+ ts.createSourceFile("shader.ts", text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
197
+
198
+ /**
199
+ * The name a call's callee is written as. Both spellings appear in TSL: `Fn(...)` for the imported
200
+ * functions and `node.toVar()` for the methods, and a declaration initialised by a method call has
201
+ * to be recognised as already materialised, so a property access counts too.
202
+ */
203
+ const callee = (node) => {
204
+ const { expression } = node;
205
+ if (ts.isIdentifier(expression)) return expression.text;
206
+ if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
207
+ return null;
208
+ };
209
+
210
+ /** `true` for the arrow or function the transpiler wrote as an argument to `Fn(...)`. */
211
+ const isFnBody = (node) =>
212
+ (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
213
+ ts.isCallExpression(node.parent) &&
214
+ callee(node.parent) === "Fn";
215
+
216
+ /**
217
+ * `Fn(fn, { p: 'vec2', return: 'float' })` is the transpiler's shorthand for a function taking one
218
+ * vec2, and as a second argument it is not a layout anything reads. `Fn`'s builder path takes that
219
+ * second argument as a shader-node builder to hand the callback, so the emitted functions capture
220
+ * every uniform they read into a struct that is never bound: the first compile reports a missing
221
+ * uniform member, and the frame group resolves no member at all. Nothing is lost by dropping it,
222
+ * because no function is ever emitted as a real shader function — all of them are inlined, and the
223
+ * types the layout spelled out are already on the callback parameters as typed tuples. Removed by
224
+ * span, from every `Fn` call.
225
+ */
226
+ function stripFnLayout(code) {
227
+ const file = parse(code);
228
+ const spans = [];
229
+ const walk = (node) => {
230
+ if (ts.isCallExpression(node) && callee(node) === "Fn") {
231
+ const [callback, layout] = node.arguments;
232
+ if (node.arguments.length === 1) {
233
+ if (!callback || !isFnBody(callback))
234
+ throw new Error("TN_TRANSPILER_FN_SHAPE: an Fn call lost its callback");
235
+ } else if (
236
+ node.arguments.length === 2 &&
237
+ callback &&
238
+ isFnBody(callback) &&
239
+ ts.isObjectLiteralExpression(layout)
240
+ ) {
241
+ spans.push([callback.end, layout.end]);
242
+ } else {
243
+ throw new Error(
244
+ `TN_TRANSPILER_FN_SHAPE: Fn takes ${node.arguments.length} arguments and none is a layout to remove`,
245
+ );
246
+ }
247
+ }
248
+ ts.forEachChild(node, walk);
249
+ };
250
+ walk(file);
251
+ if (spans.length === 0)
252
+ throw new Error("TN_TRANSPILER_NO_FN_LAYOUT: no Fn call carried a layout argument");
253
+ let out = code;
254
+ for (const [from, to] of spans.reverse()) out = out.slice(0, from) + out.slice(to);
255
+ return out;
256
+ }
257
+
258
+ /**
259
+ * A local GLSL variable is a mutable TSL node, but the transpiler writes it as a plain JavaScript
260
+ * `const` holding the expression it was initialised with. Every later `+=` or `.assign` then
261
+ * mutates a temporary nothing reads back, so the shader compiles and runs holding the first value
262
+ * it ever saw: the march never advances and the scene stays the sky it started on. `toVar()` is
263
+ * what names a node — it materialises the value into a shader variable the rest of the function can
264
+ * reassign — and it is needed on every initialised local, not only on the ones a parameter was
265
+ * assigned to. Applied inside function bodies only, so the module-level declarations, which are
266
+ * uniforms and the `Fn` calls themselves, are left as the transpiler wrote them.
267
+ */
268
+ function materializeLocals(code) {
269
+ const file = parse(code);
270
+ const inserts = [];
271
+ const destructured = [];
272
+ const walk = (node, inBody) => {
273
+ const body = inBody || isFnBody(node) || ts.isFunctionDeclaration(node);
274
+ if (body && ts.isVariableDeclaration(node) && node.initializer) {
275
+ if (ts.isIdentifier(node.name)) {
276
+ const { initializer } = node;
277
+ if (!(ts.isCallExpression(initializer) && callee(initializer) === "toVar")) {
278
+ inserts.push(initializer.end);
279
+ }
280
+ } else {
281
+ destructured.push(node.name.getText(file));
282
+ }
283
+ }
284
+ ts.forEachChild(node, (child) => walk(child, body));
285
+ };
286
+ walk(file, false);
287
+ if (destructured.length > 0) {
288
+ throw new Error(
289
+ `TN_TRANSPILER_DESTRUCTURED: ${destructured.join(", ")} destructures, so its value cannot be materialised`,
290
+ );
291
+ }
292
+ if (inserts.length === 0)
293
+ throw new Error("TN_TRANSPILER_NO_LOCALS: no local variable was found to materialise");
294
+ let out = code;
295
+ for (const at of inserts.reverse()) out = `${out.slice(0, at)}.toVar()${out.slice(at)}`;
296
+ return out;
297
+ }
298
+
299
+ /**
300
+ * A `return` inside an `If` or `Loop` callback is not the GLSL early return it was written as. Those
301
+ * callbacks run while the node graph is being built, so the `return` only leaves the callback and
302
+ * the node it was building is never assigned anywhere: the branch is dropped and the function keeps
303
+ * whatever its last line said. That is how the coast's `baseColor` ended up returning a flat
304
+ * `vec3(.1)` for every material and its `reflected` returning the sky for every ray. The sources
305
+ * normalise a helper to one final return over `else if` and `Break` instead, so a return still
306
+ * shaped like an early one is a mistake to stop on rather than to compile.
307
+ */
308
+ function assertNoNestedReturns(code) {
309
+ const file = parse(code);
310
+ const nested = [];
311
+ const walk = (node) => {
312
+ if (ts.isReturnStatement(node)) {
313
+ for (let parent = node.parent; parent; parent = parent.parent) {
314
+ if (isFnBody(parent)) break;
315
+ if (ts.isCallExpression(parent) && (callee(parent) === "If" || callee(parent) === "Loop")) {
316
+ nested.push(node.getText(file).split("\n")[0].trim());
317
+ break;
318
+ }
319
+ }
320
+ }
321
+ ts.forEachChild(node, walk);
322
+ };
323
+ walk(file);
324
+ if (nested.length > 0) {
325
+ throw new Error(
326
+ `TN_TRANSPILER_NESTED_RETURN: ${nested.length} return(s) inside If/Loop would be dropped at runtime: ${nested.join(" | ")}`,
327
+ );
328
+ }
329
+ }
330
+
331
+ /** Index of the `}` that closes the `{` at `open`, counting braces in the text between them. */
332
+ function closingBrace(text, open) {
333
+ let depth = 0;
334
+ for (let index = open; index < text.length; index += 1) {
335
+ if (text[index] === "{") {
336
+ depth += 1;
337
+ } else if (text[index] === "}") {
338
+ depth -= 1;
339
+ if (depth === 0) return index;
340
+ }
341
+ }
342
+ throw new Error("TN_TRANSPILER_UNCLOSED_BRACE");
343
+ }
344
+
345
+ const LOOP_BOUNDS = /Loop\(\s*\{[^{}]*?((?:start|end):\s*-?\d+(?:\.\d+)?)/g;
346
+ /**
347
+ * `Loop({ start: 0, end: 6 }, …)` leaves the counter's type to be inferred from a bare number, and
348
+ * nothing is left to infer it from. GLSL wrote `int i`, so the bounds are stated as `int` too.
349
+ */
350
+ function typeLoopBounds(body, injected) {
351
+ const typed = body.replaceAll(LOOP_BOUNDS, (match, bound) =>
352
+ match.replace(bound, `${bound.replace(":", ": int(")})`),
353
+ );
354
+ if (typed === body) throw new Error("TN_TRANSPILER_LOOP_BOUNDS: no bare loop bound was found");
355
+ // The decoder leaves the import list out of it: it emitted a bare number, so it never reached for
356
+ // `int`, and nothing else in a shader with no `int` local would have imported it either.
357
+ injected.add("int");
358
+ return typed;
359
+ }
360
+
361
+ /**
362
+ * The decoder names a loop counter through `params.name`, which `LoopNode` reads and the published
363
+ * types do not declare — their own source leaves that field commented out with a TODO saying it
364
+ * should be typed. The nested pair is therefore written as `Loop`'s two-parameter form, which the
365
+ * types do describe and which `LoopNode` builds from the same two `for` loops, naming the counters
366
+ * `i` and `j`. The GLSL ran both counters over the same range, so the order cannot matter.
367
+ */
368
+ function flattenNestedLoop(body) {
369
+ const pattern = /Loop\(\s*(\{[^{}]*name: 'j'[^{}]*\}),\s*\(\s*\{\s*j\s*\}\s*\)\s*=>\s*\{/;
370
+ const nested = body.match(pattern);
371
+ if (nested === null)
372
+ throw new Error("TN_TRANSPILER_NO_NESTED_LOOP: the ripple loop changed shape");
373
+ const outerOpen = body.indexOf("{", nested.index + nested[0].length - 1);
374
+ const outerClose = closingBrace(body, outerOpen);
375
+ const innerStart = body.indexOf("Loop(", outerOpen);
376
+ const innerBounds = closingBrace(body, body.indexOf("{", innerStart));
377
+ // The callback's own parameter list is destructured, so its braces come first; the body opens
378
+ // after the arrow, not after the bounds.
379
+ const innerOpen = body.indexOf("{", body.indexOf("=>", innerBounds));
380
+ const innerClose = closingBrace(body, innerOpen);
381
+ const innerParams = body.slice(body.indexOf("{", innerStart), innerBounds + 1);
382
+ const outerParams = nested[1].replace(/\s*name: 'j',?/, "");
383
+ return [
384
+ body.slice(0, nested.index),
385
+ `Loop(${outerParams}, ${innerParams}, ({ i, j }) => {`,
386
+ body.slice(innerOpen + 1, innerClose),
387
+ "});",
388
+ body.slice(body.indexOf(";", outerClose) + 1),
389
+ ].join("");
390
+ }
391
+
392
+ /**
393
+ * `Fn(fn, { p: 'vec2', return: 'float' })` states the parameter types as strings, so TypeScript
394
+ * infers nothing from them and settles for `Fn`'s first overload — the one whose callback receives
395
+ * the node builder — and every parameter then arrives typed as a NodeBuilder. Annotating the
396
+ * parameter with the type the layout already names makes that callback incompatible with the
397
+ * builder overload, so the argument-taking overload is the one that matches. No suppression, and the
398
+ * return type still comes from the body rather than being asserted.
399
+ */
400
+ const FN_SIGNATURE =
401
+ /(export const \w+ = \/\*@__PURE__\*\/ Fn\(\s*\(\s*)((?:\[[^\]]*\]|\w+))(\s*\)\s*=>\s*\{[\s\S]*?\n\}, \{)([^{}]*?)(\} \);)/g;
402
+ function typeCallbackParameters(body) {
403
+ let typed = 0;
404
+ const out = body.replace(FN_SIGNATURE, (match, head, parameters, middle, layout, tail) => {
405
+ const types = [...layout.matchAll(/(\w+)\s*:\s*'(\w+)'/g)]
406
+ .filter(([, name]) => name !== "return")
407
+ .map(([, , type]) => `Node<"${type}">`);
408
+ if (types.length === 0)
409
+ throw new Error("TN_TRANSPILER_NO_PARAMETERS: a function declares none");
410
+ if (types.length > 1 && !parameters.startsWith("[")) {
411
+ throw new Error(
412
+ `TN_TRANSPILER_PARAMETER_COUNT: ${parameters} has no ${types.length} parameters`,
413
+ );
414
+ }
415
+ typed += 1;
416
+ // The transpiler destructures every parameter from an array, so the annotation is a tuple
417
+ // whenever the code destructures and the bare node type when it does not.
418
+ const annotation = parameters.startsWith("[") ? `[ ${types.join(", ")} ]` : types[0];
419
+ return `${head}${parameters}: ${annotation}${middle}${layout}${tail}`;
420
+ });
421
+ if (typed === 0) throw new Error("TN_TRANSPILER_NO_FUNCTIONS: nothing to type");
422
+ return { body: out, typed };
423
+ }
424
+
425
+ function rewriteAll(text, rules, prefix) {
426
+ let out = text;
427
+ for (const rule of rules) {
428
+ const before = out;
429
+ out = out.replaceAll(rule.find, rule.replace);
430
+ if (out === before) throw new Error(`${prefix}_RULE_DEAD: ${rule.what} matched nothing`);
431
+ }
432
+ return out;
433
+ }
434
+
435
+ /** The decoder's own import list, plus whatever this file injected, as the double-quoted form. */
436
+ function mergeTslImport(importLine, injected) {
437
+ // `frameGroup` leads because every bound uniform below is set on it, and the decoder never emits
438
+ // it: it has no reason to, having written the uniforms itself.
439
+ const names = [
440
+ "frameGroup",
441
+ ...importLine
442
+ .match(/\{([^}]*)\}/)[1]
443
+ .split(",")
444
+ .map((name) => name.trim())
445
+ .filter((name) => name.length > 0),
446
+ ];
447
+ for (const name of injected) if (!names.includes(name)) names.push(name);
448
+ return `import { ${names.join(", ")} } from "three/tsl";`;
449
+ }
450
+
451
+ function generate(config) {
452
+ const target = resolve(here, config.target);
453
+ const raw = readFileSync(resolve(here, config.source), "utf8");
454
+ // The file opens with a provenance note in comment form; the transpiler copies comments through,
455
+ // so it is stripped before parsing rather than carried into the generated module.
456
+ const provenance = raw.match(/^(?:\/\/[^\n]*\n)+/);
457
+ if (provenance === null)
458
+ throw new Error(`${config.marker}_NO_PROVENANCE: the source has no header note`);
459
+ const normalized = rewriteAll(
460
+ raw.slice(provenance[0].length),
461
+ [
462
+ ...COMMON_REWRITES,
463
+ { what: "the GLSL entry point", find: config.entryOpen[0], replace: config.entryOpen[1] },
464
+ ...config.entryClose,
465
+ ...config.rewrites,
466
+ ],
467
+ config.marker,
468
+ );
469
+
470
+ // Uniform types the decoder turns into a TSL node, read before anything is parsed so a name the
471
+ // decoder would drop is still known here.
472
+ const declared = new Map();
473
+ for (const match of normalized.matchAll(/\buniform\s+(\w+)\s+([^;]+);/g)) {
474
+ const [, type, names] = match;
475
+ for (const name of names.split(",")) declared.set(name.trim(), type);
476
+ }
477
+ if (declared.size === 0)
478
+ throw new Error(`${config.marker}_NO_UNIFORMS: the source declares none`);
479
+
480
+ const warnings = [];
481
+ const quiet = (action) => {
482
+ for (const level of ["warn", "error"]) {
483
+ const original = console[level];
484
+ console[level] = (...args) => warnings.push(`${level}: ${args.join(" ")}`);
485
+ try {
486
+ return action();
487
+ } finally {
488
+ console[level] = original;
489
+ }
490
+ }
491
+ };
492
+ const emitted = quiet(() =>
493
+ new Transpiler(new GLSLDecoder(), new TSLEncoder()).parse(normalized),
494
+ );
495
+ if (warnings.length > 0) {
496
+ throw new Error(`${config.marker}_WARNINGS:\n${warnings.join("\n")}`);
497
+ }
498
+ if (!emitted.includes(`export const ${config.entry}`)) {
499
+ throw new Error(`${config.marker}_NO_ENTRY: the entry point was not emitted`);
500
+ }
501
+
502
+ // The decoder writes every global uniform as its own single-line `const`, and puts the TSL import
503
+ // first. Take the import, drop the uniform lines, and re-emit the ones the code actually reads.
504
+ const tslImport = emitted.match(/^import \{[^}]*\} from 'three\/tsl';$/m);
505
+ if (tslImport === null) throw new Error(`${config.marker}_NO_IMPORT: the TSL import is missing`);
506
+ let body = rewriteAll(
507
+ emitted
508
+ .replace(tslImport[0], "")
509
+ .split("\n")
510
+ .filter((line) => !/^const u[A-Za-z0-9]+ = (?:uniform|texture\w*)\(/.test(line))
511
+ .join("\n"),
512
+ config.outputRewrites,
513
+ config.marker,
514
+ );
515
+
516
+ const injected = new Set();
517
+ // A rewrite that substitutes a different TSL call brings its own import with it.
518
+ for (const rule of config.outputRewrites)
519
+ for (const name of rule.imports ?? []) injected.add(name);
520
+ body = typeLoopBounds(body, injected);
521
+ if (config.nestedLoop) {
522
+ body = flattenNestedLoop(body);
523
+ if (/name:\s*'[a-z]'/.test(body)) {
524
+ throw new Error(`${config.marker}_LOOP_NAME: a named loop counter survived the rewrite`);
525
+ }
526
+ }
527
+
528
+ const read = /[^A-Za-z0-9_$]?([A-Za-z_$][A-Za-z0-9_$]*)[^A-Za-z0-9_$]?/g;
529
+ const used = new Set([...body.matchAll(read)].map((match) => match[1]));
530
+
531
+ const threeImports = new Set(["Vector2", "Vector3", "Vector4"]);
532
+ const bound = [];
533
+ const missing = [];
534
+ for (const [name, type] of declared) {
535
+ if (!used.has(name)) continue;
536
+ if (type in DEFAULTS) {
537
+ // `frameGroup`, not the default per-object group: a stack node — every `If`, `Loop` and `Fn`
538
+ // in these shaders — builds through a sub-builder, and a uniform first reached inside one is
539
+ // registered on that sub-builder's group, leaving the shader's uniform struct short of members
540
+ // and the WGSL invalid. One frame-wide buffer, read once per frame, is also what these values
541
+ // are: each shader is a single quad, and every one of them is set by the same call each frame.
542
+ bound.push(
543
+ `export const ${name} = uniform(${DEFAULTS[type]}, "${type}").setGroup(frameGroup);`,
544
+ );
545
+ } else if (config.samplers.includes(type)) {
546
+ const sampler = SAMPLERS[type];
547
+ threeImports.add(sampler.texture);
548
+ // The decoder can only emit a placeholder for a sampler, and a sampled node needs a texture
549
+ // before the graph is built, so the placeholder is a single voxel. It is also the wrong kind
550
+ // of binding for a render target: a pass that is only ever fed to `.value` is no longer in
551
+ // the graph the renderer walks, so it never gets a frame to render into. The binding is
552
+ // therefore a rebindable `let` and the owning module swaps the whole node through
553
+ // `setX(node)` before the entry function is called — the shader's own `Fn` callbacks read
554
+ // it when the graph is built, which is the moment a rebind has to have happened. The sampled
555
+ // UVs and colour space are the caller's, as in any TSL material.
556
+ const setter = `set${name.replace(/^u([A-Z])/, (_, first) => first.toUpperCase())}`;
557
+ bound.push(
558
+ `const ${name}Placeholder = new ${sampler.texture}(new Uint8Array([0, 0, 0, 255]), ${sampler.create});`,
559
+ `${name}Placeholder.needsUpdate = true;`,
560
+ `export let ${name}: TextureNode = ${sampler.node}(${name}Placeholder).setGroup(frameGroup);`,
561
+ `export function ${setter}(value: TextureNode): void {`,
562
+ ` ${name} = value;`,
563
+ "}",
564
+ );
565
+ } else {
566
+ missing.push(`${name} (${type})`);
567
+ }
568
+ }
569
+ if (missing.length > 0) {
570
+ throw new Error(
571
+ `${config.marker}_UNBOUND: the shader reads ${missing.join(", ")} with no binding`,
572
+ );
573
+ }
574
+ if (bound.length === 0) throw new Error(`${config.marker}_NO_BOUND_UNIFORMS: nothing is bound`);
575
+
576
+ const { body: annotated, typed } = typeCallbackParameters(body);
577
+ const stripped = stripFnLayout(annotated);
578
+ const materialized = materializeLocals(stripped);
579
+ assertNoNestedReturns(materialized);
580
+
581
+ const mergedImport = mergeTslImport(tslImport[0], injected);
582
+ const header = `// GENERATED FILE — do not edit it. Every line below is the output of Three.js's own GLSL to
583
+ // TSL transpiler, run over tools/${config.source}. That .frag file
584
+ // is the source of truth; change it and the generator, never this file.
585
+ //
586
+ // node tools/generate-shaders.mjs
587
+ //
588
+ ${config.header}`;
589
+ const output = [
590
+ header,
591
+ `import { ${[...threeImports].sort().join(", ")} } from "three";`,
592
+ mergedImport,
593
+ `import type { Node, TextureNode } from "three/webgpu";`,
594
+ "",
595
+ "// Uniforms the shader reads. Values are assigned by src/render/world.ts and src/render/clouds.ts,",
596
+ "// which own the camera basis and the weather; the generated module only holds the nodes.",
597
+ ...bound,
598
+ "",
599
+ materialized.trim(),
600
+ "",
601
+ ].join("\n");
602
+
603
+ // Every name the emitted code calls is either a `three/tsl` import, a uniform, or a function the
604
+ // transpiler itself emitted. Anything else would be a silent ReferenceError in the template, which
605
+ // is the failure this whole check exists to catch.
606
+ const imported = new Set(
607
+ mergedImport
608
+ .match(/\{([^}]*)\}/)[1]
609
+ .split(",")
610
+ .map((name) => name.trim()),
611
+ );
612
+ const called = (text) =>
613
+ new Set(
614
+ [
615
+ ...text.replace(/\/\/[^\n]*/g, "").matchAll(/(?<![.\w$])([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g),
616
+ ].map((match) => match[1]),
617
+ );
618
+ const local = new Set(
619
+ [...materialized.matchAll(/(?:const|function)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g)].map((m) => m[1]),
620
+ );
621
+ const unimported = [...called(materialized)].filter(
622
+ (name) => !imported.has(name) && !declared.has(name) && !local.has(name),
623
+ );
624
+ if (unimported.length > 0) {
625
+ throw new Error(
626
+ `${config.marker}_UNIMPORTED: ${unimported.join(", ")} is called but never imported`,
627
+ );
628
+ }
629
+
630
+ mkdirSync(dirname(target), { recursive: true });
631
+ writeFileSync(target, output);
632
+ const formatted = existsSync(biome);
633
+ if (formatted) {
634
+ execFileSync(biome, ["check", "--fix", "--unsafe", relative(repoRoot, target)], {
635
+ cwd: repoRoot,
636
+ stdio: "inherit",
637
+ });
638
+ }
639
+ console.log(
640
+ `${config.marker}:${JSON.stringify({
641
+ declared: declared.size,
642
+ bound: bound.length,
643
+ bytes: output.length,
644
+ dropped: [...declared.keys()].filter(
645
+ (name) => !bound.some((line) => line.includes(` ${name} = `)),
646
+ ),
647
+ formatted,
648
+ functions: typed,
649
+ layoutsStripped: typed,
650
+ localsMaterialized: (materialized.match(/\.toVar\(\)/g) ?? []).length,
651
+ warnings: 0,
652
+ })}`,
653
+ );
654
+ }
655
+
656
+ for (const config of SHADERS) generate(config);