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,29 @@
1
+ import type { IGame } from "@threenative/core";
2
+ import { DebugOverlay, GameCanvas } from "@threenative/ui";
3
+ import { useEffect } from "react";
4
+ import type { GameState } from "../state.js";
5
+ import { GameUi } from "./GameUi.js";
6
+ import { installTempest } from "./tempest.js";
7
+
8
+ /**
9
+ * The study's page: the engine's canvas, and the interface from `./GameUi.js` over it.
10
+ *
11
+ * No physics context on the generic, because `game.ts` is `defineGame<GameState>` — a coastal
12
+ * weather study moves the air, not a rigid body. The UI is mounted from `src/main.ts`, so the
13
+ * canvas and the overlay share one root and one React tree.
14
+ *
15
+ * The automation facade is installed here rather than in `game.ts` because `window.tempest` and
16
+ * the query it reads are the UI realm's; the game module stays portable code.
17
+ */
18
+ export function App({ game }: { game: IGame<GameState> }) {
19
+ useEffect(() => {
20
+ installTempest(game);
21
+ }, [game]);
22
+ return (
23
+ <main className="canvas-root">
24
+ <GameCanvas className="canvas-fill" game={game} />
25
+ <GameUi />
26
+ <DebugOverlay />
27
+ </main>
28
+ );
29
+ }
@@ -0,0 +1,187 @@
1
+ import { UiLayer, useUiIntent, useUiState } from "@threenative/ui";
2
+ import { useCallback, useEffect, useRef, useState } from "react";
3
+ import { type GameState, VISIBILITY_INTENT } from "../state.js";
4
+ import { Hud, captureScene, toggleFullscreen } from "./Hud.js";
5
+ import { LoadingOverlay } from "./LoadingOverlay.js";
6
+ import { Menu } from "./Menu.js";
7
+ import { automationRequest } from "./automation.js";
8
+
9
+ const TOAST_MS = 3600;
10
+ /** Preserve the source study's one-time window-width default on hardware. */
11
+ const NARROW_PX = 700;
12
+
13
+ export function GameUi() {
14
+ return (
15
+ <UiLayer>
16
+ <RainInterface />
17
+ </UiLayer>
18
+ );
19
+ }
20
+
21
+ /**
22
+ * The interface, and the three things that are behaviour rather than markup.
23
+ *
24
+ * `useUiState` and `useUiIntent` need the bridge `UiLayer` opened, so they live in this inner
25
+ * component rather than in `GameUi` itself — a hook above the provider throws. Everything the page
26
+ * does that is not a control lives here: the status toast, the keyboard, and the two one-time
27
+ * defaults that have to be applied against a real snapshot rather than guessed at mount.
28
+ */
29
+ function RainInterface() {
30
+ const state = useUiState<GameState>();
31
+ const send = useUiIntent();
32
+ const [toast, setToast] = useState("");
33
+ const [toastVisible, setToastVisible] = useState(false);
34
+ const [panelOpen, setPanelOpen] = useState(false);
35
+ const toastTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
36
+
37
+ const say = useCallback((text: string) => {
38
+ setToast(text);
39
+ setToastVisible(true);
40
+ clearTimeout(toastTimer.current);
41
+ toastTimer.current = setTimeout(() => setToastVisible(false), TOAST_MS);
42
+ }, []);
43
+ useEffect(() => () => clearTimeout(toastTimer.current), []);
44
+
45
+ /** Photosensitivity mode; the intent itself also takes automatic lightning down. */
46
+ const setSafeMode = useCallback((on: boolean) => send("setSafe", on), [send]);
47
+
48
+ /**
49
+ * The status line, said on what the game reports rather than on what a control asked for: a
50
+ * shortcut from the game's input map and a click on the panel change the same state, so both are
51
+ * announced the same way, and a strike reads its distance and delay off the strike itself.
52
+ */
53
+ const previous = useRef<GameState | undefined>(undefined);
54
+ useEffect(() => {
55
+ const before = previous.current;
56
+ previous.current = state;
57
+ if (state === undefined || before === undefined) return;
58
+ const soundOn = state.audioEnabled && !state.muted;
59
+ if (state.safe !== before.safe)
60
+ say(state.safe ? "LIGHTNING DISABLED · photosensitivity mode" : "Lightning flashes enabled");
61
+ if (state.paused !== before.paused)
62
+ say(state.paused ? "SIMULATION PAUSED" : "SIMULATION RESUMED");
63
+ if (soundOn !== (before.audioEnabled && !before.muted))
64
+ say(soundOn ? "Stereo rain, wind and distance-delayed thunder enabled" : "Sound muted");
65
+ if (state.strikes > before.strikes) {
66
+ const { delay, metres } = state.lastStrike;
67
+ say(
68
+ `LIGHTNING · ${(metres / 1000).toFixed(2)} km${soundOn ? ` · thunder in ${delay.toFixed(1)} s` : ""}`,
69
+ );
70
+ }
71
+ }, [say, state]);
72
+
73
+ const toggleAutoLightning = useCallback(() => {
74
+ if (state?.safe === true) {
75
+ say("Disable photosensitivity mode first to enable lightning.");
76
+ return;
77
+ }
78
+ send("setAutoLightning", state?.autoLightning !== true);
79
+ }, [say, send, state?.autoLightning, state?.safe]);
80
+
81
+ /**
82
+ * The keyboard, and only the keys that are browser APIs. Everything else — `W A S D`, `Q E`,
83
+ * `Shift`, `R`, `L`, `X`, `H`, `M` and `Space` — is the game's input map, which a native host
84
+ * delivers too; handling them here as well would act twice per press.
85
+ */
86
+ useEffect(() => {
87
+ if (state === undefined) return;
88
+ const actions: Record<string, () => void> = {
89
+ KeyF: () => void toggleFullscreen(say),
90
+ KeyP: () => {
91
+ void captureScene(say).catch((why: Error) => say(`Scene image failed: ${why.message}`));
92
+ },
93
+ };
94
+ const onKeyDown = (event: KeyboardEvent) => {
95
+ if (event.code === "Escape") {
96
+ send("closeHelp");
97
+ return;
98
+ }
99
+ // A focused slider, select or text field owns its own keys.
100
+ const tag = document.activeElement?.tagName;
101
+ if (tag === "INPUT" || tag === "SELECT" || tag === "TEXTAREA") return;
102
+ if (event.repeat) return;
103
+ const run = actions[event.code];
104
+ if (run === undefined) return;
105
+ // Space scrolls the page and the shortcuts must not reach the browser's own bindings.
106
+ event.preventDefault();
107
+ run();
108
+ };
109
+ window.addEventListener("keydown", onKeyDown);
110
+ return () => window.removeEventListener("keydown", onKeyDown);
111
+ }, [say, send, state]);
112
+
113
+ /**
114
+ * Tab visibility, held in the UI realm because `document` is a browser API: this is the only
115
+ * place that knows whether the frame is still on screen, and a hidden tab stops the engine loop,
116
+ * so nothing in a scene frame would ever notice. Separate from the pause intent on purpose — the
117
+ * two clear independently, and a tab that comes back must not resume a paused storm.
118
+ */
119
+ useEffect(() => {
120
+ const report = () => send(VISIBILITY_INTENT, document.hidden);
121
+ document.addEventListener("visibilitychange", report);
122
+ return () => document.removeEventListener("visibilitychange", report);
123
+ }, [send]);
124
+
125
+ /**
126
+ * Reduced motion, read in the UI realm and applied once. A reader who then flips a switch has
127
+ * said something newer than their operating system, so the preference is never re-applied over a
128
+ * snapshot — which is also why it needs a ref rather than an effect dependency.
129
+ */
130
+ const reducedApplied = useRef(false);
131
+ useEffect(() => {
132
+ if (state === undefined || reducedApplied.current) return;
133
+ reducedApplied.current = true;
134
+ if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
135
+ send("setSafe", true);
136
+ send("setAutoLightning", false);
137
+ send("setCinematic", false);
138
+ }, [send, state]);
139
+
140
+ /** Scene loading owns the default; the query and later player choices override it. */
141
+ const qualityChosen = useRef(false);
142
+ useEffect(() => {
143
+ if (state === undefined || state.softwareRendering === undefined || qualityChosen.current)
144
+ return;
145
+ qualityChosen.current = true;
146
+ // An operator asking for high on a phone or software adapter keeps that explicit choice.
147
+ const asked = automationRequest(window.location.search).quality;
148
+ if (asked !== undefined) {
149
+ send("setQuality", asked);
150
+ return;
151
+ }
152
+ if (state.qualityExplicit === true || state.softwareRendering) return;
153
+ send("setQuality", window.innerWidth < NARROW_PX ? "performance" : "high");
154
+ }, [send, state]);
155
+
156
+ // Nothing yet from the game, so nothing is claimed: the engine's own loading screen is still up.
157
+ if (state === undefined) return null;
158
+
159
+ // Until the storm is ready, the curtain is all there is, as in the study: no controls over a
160
+ // world that is not on screen yet.
161
+ if (!state.loading.ready)
162
+ return <LoadingOverlay progress={state.loading.progress} ready={false} />;
163
+
164
+ return (
165
+ <>
166
+ <Hud
167
+ panelOpen={panelOpen}
168
+ say={say}
169
+ send={send}
170
+ setPanelOpen={setPanelOpen}
171
+ state={state}
172
+ toast={toast}
173
+ toastVisible={toastVisible}
174
+ />
175
+ <Menu
176
+ panelOpen={panelOpen}
177
+ say={say}
178
+ send={send}
179
+ setPanelOpen={setPanelOpen}
180
+ setSafeMode={setSafeMode}
181
+ state={state}
182
+ toggleAutoLightning={toggleAutoLightning}
183
+ />
184
+ <LoadingOverlay progress={state.loading.progress} ready={state.loading.ready} />
185
+ </>
186
+ );
187
+ }
@@ -0,0 +1,327 @@
1
+ import type { GameState } from "../state.js";
2
+
3
+ export interface IHudProps {
4
+ /** The game's published state. The mirror, never the live store, so it works on every target. */
5
+ readonly state: GameState;
6
+ readonly send: (intent: string, payload?: unknown) => void;
7
+ readonly say: (text: string) => void;
8
+ /** Whether the weather panel is open on a narrow screen. Pure presentation, so it is local. */
9
+ readonly panelOpen: boolean;
10
+ readonly setPanelOpen: (open: boolean) => void;
11
+ /** The toast line and whether it is showing. Held by `GameUi`, printed here in the sheet. */
12
+ readonly toast: string;
13
+ readonly toastVisible: boolean;
14
+ }
15
+
16
+ export interface ISceneSizes {
17
+ readonly height: number;
18
+ readonly width: number;
19
+ }
20
+
21
+ /** What a capture really produced: the encoded image's own size, or why there was none. */
22
+ export interface ICaptureResult extends ISceneSizes {
23
+ readonly blob?: Blob;
24
+ readonly bytes: number;
25
+ readonly ok: boolean;
26
+ readonly reason?: string;
27
+ }
28
+
29
+ /** The page's own scene canvas. Null where there is no canvas to read, which is the honest answer. */
30
+ export function sceneCanvas(): HTMLCanvasElement | null {
31
+ return document.querySelector<HTMLCanvasElement>('[data-threenative-canvas="true"] canvas');
32
+ }
33
+
34
+ /**
35
+ * Fullscreen, as the browser actually does it, reported as what the document says afterwards.
36
+ *
37
+ * There is no engine capability for this and no cross-platform promise to make here: this is the
38
+ * document's own fullscreen element, so the failure is reported in the toast rather than swallowed
39
+ * into a button that looks like it worked, and the returned answer is the element's own state.
40
+ */
41
+ export async function toggleFullscreen(say: (text: string) => void): Promise<boolean> {
42
+ try {
43
+ if (document.fullscreenElement === null) {
44
+ await document.documentElement.requestFullscreen();
45
+ } else {
46
+ await document.exitFullscreen();
47
+ }
48
+ } catch (why) {
49
+ say(`Fullscreen is not available in this viewer: ${(why as Error).message}`);
50
+ return false;
51
+ }
52
+ const on = document.fullscreenElement !== null;
53
+ say(on ? "Fullscreen on" : "Fullscreen off");
54
+ return on;
55
+ }
56
+
57
+ const PNG_MAGIC = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
58
+ const PROBE_PX = 32;
59
+
60
+ /**
61
+ * Prove the frame is a real image rather than guessing at it.
62
+ *
63
+ * A byte floor is a guess: it rejected a valid 390x844 phone capture for being small and would
64
+ * have accepted a large blank one. What a blank frame actually is, is a PNG that decodes to a
65
+ * single flat colour — so the guard decodes the bytes and counts distinct colours. The magic bytes
66
+ * are read too, because a renderer that hands the page a buffer which is not a PNG at all must be
67
+ * named as that rather than as a dark picture.
68
+ */
69
+ async function proveFrame(canvas: HTMLCanvasElement): Promise<ICaptureResult> {
70
+ const empty = { bytes: 0, height: 0, ok: false, width: 0 } as const;
71
+ const blob = await new Promise<Blob | null>((done) => {
72
+ canvas.toBlob(done, "image/png");
73
+ });
74
+ if (blob === null || blob.size === 0) return { ...empty, reason: "the canvas encoded no image" };
75
+ const magic = new Uint8Array(await blob.slice(0, PNG_MAGIC.length).arrayBuffer());
76
+ if (magic.length !== PNG_MAGIC.length || !magic.every((byte, at) => byte === PNG_MAGIC.at(at))) {
77
+ return { ...empty, reason: "the encoded bytes are not a PNG" };
78
+ }
79
+ const bitmap = await createImageBitmap(blob).catch(() => undefined);
80
+ if (bitmap === undefined) return { ...empty, reason: "the PNG did not decode" };
81
+ const probe = document.createElement("canvas");
82
+ probe.width = PROBE_PX;
83
+ probe.height = PROBE_PX;
84
+ const sampled = probe.getContext("2d", { willReadFrequently: true });
85
+ if (sampled === null) {
86
+ bitmap.close();
87
+ return { ...empty, reason: "no 2d context to sample the frame with" };
88
+ }
89
+ sampled.drawImage(bitmap, 0, 0, PROBE_PX, PROBE_PX);
90
+ bitmap.close();
91
+ const pixels = sampled.getImageData(0, 0, PROBE_PX, PROBE_PX).data;
92
+ const colours = new Set<number>();
93
+ for (let at = 0; at < pixels.length; at += 4) {
94
+ colours.add(
95
+ ((pixels.at(at) ?? 0) << 16) | ((pixels.at(at + 1) ?? 0) << 8) | (pixels.at(at + 2) ?? 0),
96
+ );
97
+ }
98
+ if (colours.size < 2) {
99
+ return { ...empty, reason: "the frame decoded to a single flat colour" };
100
+ }
101
+ return { blob, bytes: blob.size, height: canvas.height, ok: true, width: canvas.width };
102
+ }
103
+
104
+ /**
105
+ * Save the frame, through the page's own canvas, and report what was really written.
106
+ *
107
+ * A WebGPU canvas can hand the page a blank read, so the image is proved before the download is
108
+ * offered rather than after: the toast carries the encoded size and a failed read says why.
109
+ */
110
+ export async function captureScene(say: (text: string) => void): Promise<ICaptureResult> {
111
+ const canvas = sceneCanvas();
112
+ const result =
113
+ canvas === null
114
+ ? ({ bytes: 0, height: 0, ok: false, reason: "no scene canvas", width: 0 } as const)
115
+ : await proveFrame(canvas);
116
+ if (!result.ok || result.blob === undefined) {
117
+ say(`Scene image unavailable: ${result.reason ?? "unknown"}`);
118
+ return result;
119
+ }
120
+ const url = URL.createObjectURL(result.blob);
121
+ const link = document.createElement("a");
122
+ link.download = `rain-${Date.now()}.png`;
123
+ link.href = url;
124
+ link.click();
125
+ URL.revokeObjectURL(url);
126
+ say(`Scene image saved · ${result.width}x${result.height} · ${result.bytes} bytes`);
127
+ return result;
128
+ }
129
+
130
+ /**
131
+ * The parts of the interface that are not the weather panel: the topbar and its controls, the
132
+ * compass, the hero title, the sound pill, the telemetry footer, the status toast, and the button
133
+ * that brings a hidden interface back.
134
+ *
135
+ * Every readout is the game's published value — the live atmosphere for telemetry, the mirrored
136
+ * booleans for the controls — so nothing here can drift from what the simulation is doing.
137
+ */
138
+ export function Hud({ send, say, panelOpen, setPanelOpen, state, toast, toastVisible }: IHudProps) {
139
+ const soundOn = state.audioEnabled && !state.muted;
140
+ return (
141
+ <>
142
+ <div className={`interface${state.uiHidden ? " hidden" : ""}`}>
143
+ <header className="topbar">
144
+ <div className="brand">
145
+ <div className="mark">
146
+ <svg
147
+ width="20"
148
+ height="20"
149
+ viewBox="0 0 24 24"
150
+ fill="none"
151
+ stroke="currentColor"
152
+ strokeWidth="1"
153
+ aria-hidden="true"
154
+ >
155
+ <path d="M6 15a4 4 0 0 1 0-8 6 6 0 0 1 11.4-.5A4.5 4.5 0 0 1 18 15M10 12l-2 5h4l-2 5" />
156
+ </svg>
157
+ </div>
158
+ <div>
159
+ <div className="brand-title">ATMOSPHERICS</div>
160
+ <div className="brand-sub">INTERACTIVE FIELD STUDIES / 001</div>
161
+ </div>
162
+ </div>
163
+ <div className="top-actions">
164
+ <div className="status">
165
+ <span className="dot" />
166
+ REALTIME ENVIRONMENT
167
+ </div>
168
+ <button
169
+ aria-label="Toggle weather controls"
170
+ className="icon-btn panel-toggle"
171
+ data-tn-interactive
172
+ onClick={() => setPanelOpen(!panelOpen)}
173
+ title="Weather controls"
174
+ type="button"
175
+ >
176
+ <svg aria-hidden="true" viewBox="0 0 24 24">
177
+ <path d="M4 7h16M4 17h16" />
178
+ <circle cx="9" cy="7" r="2" />
179
+ <circle cx="15" cy="17" r="2" />
180
+ </svg>
181
+ </button>
182
+ <button
183
+ aria-label={state.paused ? "Resume simulation" : "Pause simulation"}
184
+ aria-pressed={state.paused}
185
+ className={`icon-btn${state.paused ? " active" : ""}`}
186
+ data-tn-interactive
187
+ onClick={() => send(state.paused ? "resume" : "pause")}
188
+ title="Pause [Space]"
189
+ type="button"
190
+ >
191
+ <svg aria-hidden="true" viewBox="0 0 24 24">
192
+ <path d="M9 5v14M15 5v14" />
193
+ </svg>
194
+ </button>
195
+ <button
196
+ aria-label="Save scene image"
197
+ className="icon-btn desktop"
198
+ data-tn-interactive
199
+ onClick={() => captureScene(say)}
200
+ title="Save scene image [P]"
201
+ type="button"
202
+ >
203
+ <svg aria-hidden="true" viewBox="0 0 24 24">
204
+ <path d="M4 7h4l2-3h4l2 3h4v13H4z" />
205
+ <circle cx="12" cy="13" r="4" />
206
+ </svg>
207
+ </button>
208
+ <button
209
+ aria-label="Fullscreen"
210
+ className="icon-btn desktop"
211
+ data-tn-interactive
212
+ onClick={() => {
213
+ void toggleFullscreen(say);
214
+ }}
215
+ title="Fullscreen [F]"
216
+ type="button"
217
+ >
218
+ <svg aria-hidden="true" viewBox="0 0 24 24">
219
+ <path d="M9 4H4v5m11-5h5v5M4 15v5h5m11-5v5h-5" />
220
+ </svg>
221
+ </button>
222
+ <button
223
+ aria-label="Controls and accessibility"
224
+ className="icon-btn"
225
+ data-tn-interactive
226
+ onClick={() => send("help")}
227
+ title="Controls and accessibility"
228
+ type="button"
229
+ >
230
+ <svg aria-hidden="true" viewBox="0 0 24 24">
231
+ <circle cx="12" cy="12" r="9" />
232
+ <path d="M9.5 8.5a2.5 2.5 0 0 1 5 0c0 2-2.5 2-2.5 4M12 16h.01" />
233
+ </svg>
234
+ </button>
235
+ </div>
236
+ </header>
237
+
238
+ <div className="compass">
239
+ <div className="letters">
240
+ <span>NW</span>
241
+ <span>{state.heading}°</span>
242
+ <span>NE</span>
243
+ </div>
244
+ <div className="ticks" />
245
+ </div>
246
+
247
+ <section className="hero">
248
+ <div className="eyebrow">A COASTAL WEATHER STUDY</div>
249
+ <h1>TEMPEST</h1>
250
+ <p>Somewhere between stillness and the storm.</p>
251
+ </section>
252
+
253
+ <footer className="bottom-bar">
254
+ <div className="telemetry">
255
+ <div>
256
+ <div className="metric-label">PRECIPITATION</div>
257
+ <div className="metric-value">
258
+ <span>{(state.weather.rain * 48).toFixed(1)}</span>
259
+ <small>mm/h</small>
260
+ </div>
261
+ </div>
262
+ <div>
263
+ <div className="metric-label">WIND SPEED</div>
264
+ <div className="metric-value">
265
+ <span>{(state.weather.wind * 72).toFixed(1)}</span>
266
+ <small>km/h</small>
267
+ </div>
268
+ </div>
269
+ <div>
270
+ <div className="metric-label">FRAME RATE</div>
271
+ <div className="metric-value">
272
+ <span>{state.fps > 0 ? Math.round(state.fps) : "—"}</span>
273
+ <small>fps</small>
274
+ </div>
275
+ </div>
276
+ </div>
277
+ {/* The pill and the key hints share one column, so neither can be drawn over the other or
278
+ over the panel above them however short the window is. */}
279
+ <div className="bottom-actions">
280
+ <button
281
+ aria-label={soundOn ? "Mute rain and thunder audio" : "Enable rain and thunder audio"}
282
+ aria-pressed={soundOn}
283
+ className={`sound-pill${soundOn ? " active" : ""}`}
284
+ data-tn-interactive
285
+ id="sound"
286
+ onClick={() => {
287
+ if (soundOn) {
288
+ send("setMuted", true);
289
+ return;
290
+ }
291
+ send("setAudioEnabled", true);
292
+ send("setMuted", false);
293
+ }}
294
+ type="button"
295
+ >
296
+ <span className="sound-wave">
297
+ <span />
298
+ <span />
299
+ <span />
300
+ <span />
301
+ </span>
302
+ <span>{soundOn ? "SOUND ON" : "ENABLE SOUND"}</span>
303
+ </button>
304
+ <div className="key-hint">
305
+ <kbd>DRAG</kbd> LOOK &nbsp; <kbd>W A S D</kbd> MOVE &nbsp; <kbd>Q E</kbd> ALTITUDE
306
+ <br />
307
+ <kbd>H</kbd> HIDE INTERFACE &nbsp; <kbd>R</kbd> RESET CAMERA
308
+ </div>
309
+ </div>
310
+ </footer>
311
+
312
+ <output aria-live="polite" className={`toast${toastVisible ? " visible" : ""}`}>
313
+ {toast}
314
+ </output>
315
+ </div>
316
+ {/* Outside the sheet, because the sheet is hidden when this is the way back. */}
317
+ <button
318
+ className={`restore${state.uiHidden ? " visible" : ""}`}
319
+ data-tn-interactive
320
+ onClick={() => send("showUi")}
321
+ type="button"
322
+ >
323
+ SHOW INTERFACE · H
324
+ </button>
325
+ </>
326
+ );
327
+ }
@@ -0,0 +1,46 @@
1
+ import { useEffect, useState } from "react";
2
+
3
+ /** How long the curtain fades once the storm is ready; matches `.loading`'s CSS transition. */
4
+ const FADE_MS = 800;
5
+
6
+ /**
7
+ * The study's staged loading overlay, over the engine's own loading bar until the frame the storm
8
+ * is ready. The stages are read off the engine's real startup progress, so the text never claims a
9
+ * stage the launch has not reached. It paints only its text over the engine's own opaque loading
10
+ * screen (the same night colour), and once faded it leaves the page entirely.
11
+ */
12
+ export function LoadingOverlay({ progress, ready }: { progress: number; ready: boolean }) {
13
+ const [removed, setRemoved] = useState(false);
14
+ useEffect(() => {
15
+ if (!ready) return;
16
+ const timer = setTimeout(() => setRemoved(true), FADE_MS);
17
+ return () => clearTimeout(timer);
18
+ }, [ready]);
19
+ if (removed) return null;
20
+
21
+ const stage = ready
22
+ ? "ENTERING THE STORM"
23
+ : progress < 0.34
24
+ ? "BUILDING THE CLOUD VOLUME"
25
+ : progress < 0.67
26
+ ? "LIGHTING THE COAST"
27
+ : "ENTERING THE STORM";
28
+ return (
29
+ <div aria-busy={!ready} aria-hidden={ready} className={`loading${ready ? " gone" : ""}`}>
30
+ {/* The progress line itself is the engine's canvas loading bar, centred between these two. */}
31
+ <div className="loading-head">
32
+ <div className="loading-title">TEMPEST</div>
33
+ <div aria-live="polite" className="loading-text">
34
+ {stage}
35
+ </div>
36
+ </div>
37
+ <div className="loading-note">
38
+ A procedural, real-time weather study.
39
+ <br />
40
+ Contains lightning flashes. Disable them in
41
+ <br />
42
+ Rendering &amp; Accessibility or press <kbd>X</kbd>.
43
+ </div>
44
+ </div>
45
+ );
46
+ }