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
@@ -48,6 +48,12 @@ Present only under the native runtime. The host injects its side; core's viewpor
48
48
  `@threenative/playtest/three`'s device reporting read it (adapter identity, host snapshot).
49
49
  On web this global does not exist — do not probe for it in portable code.
50
50
 
51
+ ## Scene-entry markers
52
+
53
+ `TN_ENVIRONMENT_TOO_SMALL`: scene-entry console error; use an equirectangular environment at least 64 pixels wide for PMREM.
54
+ `TN_OPACITY_TRANSPARENT`: scene-entry console warning; the engine turned `transparent` on for visible materials with `opacity < 1` so the authored opacity takes effect. Override on the material: `alphaHash: true`, or `opacity: 1` for an opaque surface.
55
+ `TN_OPACITY_IGNORED`: printed by a direct `renderTrapAudit(scene)` call for a material that still ignores its opacity.
56
+
51
57
  ## Runner-side markers
52
58
 
53
59
  Two further globals are set by tooling, not the game, and are named here so a stray
@@ -42,16 +42,20 @@ without optional preview dependencies while a complete preview/check loop may no
42
42
  ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
43
43
  CC0 per asset page, and audio and bundle licenses are per pack.
44
44
 
45
- **For a Poly Haven *model*, steps 3-4 collapse into `polyhaven_import_model`.** Poly Haven
46
- publishes models as a `.gltf` beside a `.bin` and loose texture files and **never as a `.glb`**, so
47
- doing it by hand means fetching five to eight URLs and rebuilding the directory layout the glTF's
48
- relative URIs expect before anything will load. Pass `assetId`, an `outputPath` ending in `.glb`,
49
- a `resolution` (it defaults to `1k`, which is what a game floor wants), and `acceptLicense: true`;
50
- it downloads through the same guarded path, packs one self-contained GLB that
51
- `ctx.assets.model()` loads directly, and returns **triangle count and per-texture dimensions** —
52
- the two numbers `create-threenative inspect` does not report and that every triangle and texture
53
- budget is written in. Ask for a resolution the asset does not publish and it names the ones that
54
- exist. Textures and HDRIs still use `asset_download_file`.
45
+ **A Poly Haven *model* takes one extra step, and no tool does it for you.** Poly Haven publishes
46
+ models as a `.gltf` beside a `.bin` and loose texture files and **never as a `.glb`**, so the file
47
+ list is the whole model: call `polyhaven_list_files` with the `assetId`, a `resolution` such as
48
+ `1k`, and `includeDependencies: true`, then `asset_download_file` once per entry — the `.gltf` and
49
+ every URL the tool reported as a dependency — with `provider: "polyhaven"`, the `url` and `fileName`
50
+ the listing gave, and `acceptLicense: true`. Keep the downloaded names exactly as the listing
51
+ spelled them: the glTF's relative URIs resolve against them, so a renamed texture loads as a
52
+ missing file rather than as an error. Serve that directory from `public/` and load it with
53
+ `ctx.assets.model()`.
54
+
55
+ No tool packs those files into one self-contained GLB. If you want one, convert the downloaded
56
+ `.gltf` in Blender or with `gltf-transform` in a build step, and report the triangle count and
57
+ per-texture dimensions yourself — `create-threenative inspect` does not read a Poly Haven listing,
58
+ so those two numbers come from the conversion. Textures and HDRIs stay on `asset_download_file`.
55
59
 
56
60
  **Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
57
61
  `ambientcg_search_assets` did not tell you, you do not know it.
@@ -135,6 +139,23 @@ Then load the returned path the ordinary way:
135
139
  `ctx.assets.model("fab/soul-cave/.../SM_S_Soul_Statue.glb")`. The normal asset compiler picks the
136
140
  GLBs up from `assets/` with no extra configuration.
137
141
 
142
+ **Cook the pack with the default settings. `models: "none"` and `textures: "none"` in
143
+ `threenative.config.ts` are not a fix, and a reason to reach for them is a bug report, not a
144
+ workaround.** A converted Fab pack is ordinary input to that cook, and the cook is where an
145
+ expensive import stops being expensive: embedded PNG and WebP maps are transcoded to KTX2 and
146
+ capped, mesh attributes are quantized and Meshopt-compressed, and a `MASK` (alpha-cutout)
147
+ primitive is handed a discrete LOD chain, so the LOD0 triangle count in the GLB is not the
148
+ triangle count the scene pays for. One measured tree: `SM_EuropeanHornbeam_Forest_01.glb` cooks
149
+ 126,934,280 → 26,428,684 B, its six embedded PNGs → KTX2 (45.4 MB → 16.4 MB), and its
150
+ 755,677-triangle foliage primitive down to a 5.1% far rung. Turning a pass off ships every source
151
+ byte verbatim instead, counts all of them against `assets.budget.uncooked`, and is precisely what
152
+ makes `threenative build` fail with `TN_ASSETS_BUDGET_EXCEEDED` — read `dist.build-report.json`
153
+ before you conclude a pack is too big. An extension the cook owns no pass for (`.dna`,
154
+ `.strands.bin`, a vendor data file) is copied through and still resolves through the same manifest
155
+ entry, so nothing needs `public/` to serve it. Ignore what the cook writes beside the manifest —
156
+ `public/basis/`, `public/shared/` and `public/bake.receipt.json` are outputs too, and a
157
+ content-addressed name is not the only output name.
158
+
138
159
  What the import will and will not do:
139
160
 
140
161
  - **A pack of uncooked editor assets cannot be converted at all**, and this is the common case for
@@ -162,6 +183,21 @@ What the import will and will not do:
162
183
  copy, print, or persist cookies or tokens; interact with the login page instead.
163
184
  Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
164
185
  authenticated path it is guarding.
186
+ - **If the WebView login fails, use the manual paste flow.** On Wayland the WebView dies with Gdk
187
+ "Error 71 (Protocol error)", and `GDK_BACKEND=x11` still may not let the user sign in.
188
+ `fabcli auth login --manual` refuses a non-TTY stdin, so run it under a pty fed by a FIFO:
189
+ `mkfifo f; (sleep 1200 > f &); (script -qfec "fabcli auth login --manual" /dev/null < f > log &)`.
190
+ The user opens Epic's redirect endpoint
191
+ (`https://www.epicgames.com/id/api/redirect?clientId=<fabcli's client id>&responseType=code`;
192
+ `strings "$(command -v fabcli)" | grep epicgames.com/id/login` prints the full login URL) in
193
+ their own signed-in browser. It returns JSON with an `authorizationCode`; the user pastes that
194
+ value to the agent (or, when asked, the agent reads it from the page through browser control),
195
+ and the agent writes it with `printf '%s\n' "$CODE" > f` without echoing it. The pty echoes the
196
+ code into `log`, so keep that file private and delete it once `fabcli auth status` reports
197
+ `authenticated: true`. The separate Fab web session can still read `session_present: false`;
198
+ `fab_import_asset` resolves ownership through the library and works regardless. Never run
199
+ `pkill -f <pattern>` in the same shell command that names the pattern: it matches its own
200
+ command line and kills the shell.
165
201
  - **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
166
202
  `THREENATIVE_TOOLCHAIN_AUTOINSTALL=0` to require you install them instead. Linux and Windows only.
167
203
  - **`packages` is not optional in practice.** A marketplace pack converts to many gigabytes of
@@ -39,9 +39,10 @@ revisit later is the engine's job, not yours.
39
39
  how many objects it actually drops. Shadow casters are never dropped on the main view alone, so a
40
40
  scene of small casters stays expensive — `castShadow = false` on props the cut would otherwise
41
41
  drop is the game's call.
42
- - **Resolution.** `render.resolutionScale: "auto"` holds GPU headroom and never lowers resolution
43
- on a CPU overrun; `TN_FRAME_BUDGET` reports the scale actually used. A number is the named pin
44
- override.
42
+ - **Resolution.** `render.resolutionScale` defaults to `"auto"`: it starts at 0.85 for
43
+ `mobile-low`, otherwise 1, then measured windows adapt it. `TN_GPU_CLASS` reports the WebGPU
44
+ family once per launch. It holds GPU headroom and never lowers resolution on a CPU overrun; `TN_FRAME_BUDGET` reports the scale actually used. A number
45
+ is the named pin override.
45
46
  - **Quality.** Each template ships `src/render/quality.ts` (three tiers, platform default,
46
47
  `TN_QUALITY_TIER`) and `adaptiveQuality.ts` (measured frame windows). Use the tiers; do not invent
47
48
  a fourth switch.
@@ -84,7 +85,7 @@ A GPU that is idle with a slow `render` phase is an object-count problem, not a
84
85
  | A particle surface | `GPUParticles3D` | Pooled dispatch, game-owned appearance |
85
86
  | Bullet streaks | `TracerPool3D` | Pooled travelling meshes |
86
87
  | A sprite that faces the camera | `Billboard3D` | No hand-written per-frame orientation |
87
- | One directional shadow over an open world | `VirtualShadowNode` | Camera-centred, texel-snapped clip levels; `trackCaster` for movers |
88
+ | One directional shadow over an open world | `VirtualShadowNode` | Camera-centred, texel-snapped clip levels; movers sort themselves; `trackCaster` pins one, `pinStatic` excludes one |
88
89
  | Distance detail swaps | three's `LOD` | Standard, and the engine can still batch it |
89
90
  | Raycasts over a large static scene | `GPUSceneBVH` / `ScenePicker` | Built once, queried many times |
90
91
 
@@ -0,0 +1,140 @@
1
+ # Optional terrain authoring
2
+
3
+ For authored terrain, install `@threenative/terrain` as a development dependency:
4
+
5
+ ```sh
6
+ npm install --save-dev @threenative/terrain
7
+ ```
8
+
9
+ Search `engine_search_capabilities` for terrain authoring and inspect the returned
10
+ `engine_capability_detail` before creating a terrain generator. Use the installed
11
+ terrain operations rather than writing noise, erosion, masks, roads or rivers again.
12
+
13
+ ## Asked for a ready world? Start from a starter kit
14
+
15
+ A kit is a whole playable world as game source: recipe, bake script, CC0 art, terrain surface,
16
+ sky, props and colliders. `@threenative/terrain` ships them under `starter/<world>/` (today:
17
+ `forest`). Copy one into the game, bake, add it to a scene:
18
+
19
+ ```sh
20
+ cp -r node_modules/@threenative/terrain/starter/forest src/terrain/forest
21
+ node src/terrain/forest/bake.mjs --out assets/terrain/forest
22
+ ```
23
+
24
+ Then `await addForest(ctx, player)` in `Scene.load` and `ctx.add(forestDaylight(ctx.camera))` in
25
+ `Scene.enter`; the kit's `README.md` says what each file decides. Edit `recipe.json` for layout,
26
+ `COLLIDERS` in `world.ts` for what stops the player, `surface.json` and `sky.ts` for the look, and
27
+ re-run the bake. The bake writes the engine's `WorldCells` package (`bakeWorldPackage`).
28
+
29
+ ## Generate once, play the bake
30
+
31
+ Run this in an authoring/build script, outside the game loop:
32
+
33
+ ```js
34
+ import { Terrain, Mask, bakeMesh, bakeTerrain } from "@threenative/terrain";
35
+
36
+ const terrain = new Terrain({ size: 512, resolution: 257, seed: 42 })
37
+ .noise({ id: "hills", amplitude: 30, scale: 180 })
38
+ .flatten({ id: "spawn", height: 8, mask: Mask.circle([0, 0], 12) });
39
+ const state = terrain.evaluate();
40
+ const mesh = bakeMesh(state);
41
+ const collision = bakeTerrain(state).collision;
42
+ ```
43
+
44
+ Persist the recipe with `terrain.toJSON()` for later editing, and save the baked
45
+ arrays for the game. Stable layer IDs let an agent replace an operation instead of
46
+ appending duplicate layers. `Terrain.fromJSON(recipe)` restores the authored stack;
47
+ `terrain.applyPatch(commands)` applies a validated edit atomically.
48
+
49
+ ## Keep the game's appearance editable
50
+
51
+ `toGeometry(mesh)` from `@threenative/terrain/three` creates an ordinary caller-owned
52
+ Three.js `BufferGeometry`. Choose its material, lighting, water and vegetation in
53
+ this game's `src/render/`. Colours are only baked when you provide an explicit
54
+ palette; the package does not choose a material or a renderer. Dispose the geometry
55
+ and material when the scene releases them.
56
+
57
+ For collision, reuse `Heightfield` from `@threenative/core/world` and
58
+ `CollisionShape3D.heightfield` from `@threenative/physics`. Supply the same baked
59
+ height samples and extent to rendering and collision. Heightfield dimensions count
60
+ vertices; `toColliderHeights()` converts the canonical row-major samples once for
61
+ Rapier. One unit is one metre. Bilinear `heightAt()` is an interpolation aid; compare
62
+ actual triangles and physics contacts when verifying ground alignment.
63
+
64
+ Keep terrain evaluation, erosion and editor tooling out of the shipped game graph.
65
+ The runtime consumes baked arrays and assets. The legacy `encodeGLB`/`makeExport`
66
+ terrain export contains the terrain mesh only; it is not a full-world export of
67
+ vegetation, rocks, water and imported assets.
68
+
69
+ ## Optional live terrain editor
70
+
71
+ Install the authoring dependency above; Vite remains the project's development
72
+ server. Save `terrain/world.json` as `{ "version": 1, "recipe": terrain.toJSON() }`.
73
+ Add the optional plugin to this project's Vite configuration:
74
+
75
+ ```ts
76
+ import { resolve } from "node:path";
77
+ import { terrainEditor } from "@threenative/terrain/editor/server";
78
+
79
+ const editor = terrainEditor({ documentPath: resolve("terrain/world.json") });
80
+ // Add editor to the existing Vite plugins. Bind the server to 127.0.0.1/localhost.
81
+ // Add "@threenative/terrain/editor" to optimizeDeps.exclude so its adjacent
82
+ // evaluator worker remains a separate module.
83
+ ```
84
+
85
+ The project supplies `/terrain-editor/index.html`. Its browser entry calls
86
+ `mountTerrainEditor` from `@threenative/terrain/editor` with `createView(host, controller)` and
87
+ an explicit eight-channel material colour palette. Implement the exported
88
+ `IEditorView` around this game's ThreeNative scene and `src/render/` helpers; keep
89
+ that authoring entry separate from `src/game.ts`. The addon reuses the recovered
90
+ brush, layer, recipe, cancellation and data-export controls around that view.
91
+ It does not create a second renderer or silently choose the game's appearance.
92
+ The view's `setDocument(document, revision)` applies metadata changes separately
93
+ from its terrain `update(state)` path. Keep camera and placement edits out of the
94
+ evaluator worker.
95
+ Track the accepted document and the successfully rendered recipe separately. While
96
+ a rebuild is pending or has failed, metadata must retain the last valid scene and
97
+ rendered revision; apply deferred transforms when that recipe renders successfully.
98
+
99
+ After the server listens and the route is ready, `await editor.activate()` returns
100
+ `editorUrl`, `projectId`, `sessionId` and the current content-hashed `revision`.
101
+ The development server also prints the bound editor URL. Present that returned
102
+ link; do not invent a port or give a user `0.0.0.0`. On a remote machine, configure
103
+ `viewerUrl` with the existing port-forwarded editor URL; without forwarding the
104
+ loopback link is local to that machine. Activation probes the advertised route;
105
+ an unreachable or failed private forward returns an error. Only the explicitly
106
+ configured viewer host/origin is additionally trusted; the server still binds to
107
+ loopback.
108
+
109
+ An agent can edit the same document without clicking the GUI:
110
+
111
+ ```ts
112
+ import { TerrainEditorController } from "@threenative/terrain/editor";
113
+
114
+ const controller = new TerrainEditorController(activation.editorUrl);
115
+ const current = await controller.snapshot();
116
+ await controller.commit({
117
+ baseRevision: current.revision,
118
+ commands: [{ op: "update", id: "hills", patch: { params: { amplitude: 35 } } }],
119
+ });
120
+ ```
121
+
122
+ Stale bases conflict. Read the latest snapshot and merge the intended semantic
123
+ edit; do not overwrite another agent/human's work with an old document. Complete
124
+ atomic JSON saves also update the shared view. Invalid disk saves retain the last
125
+ valid preview and show a diagnostic; restore a valid save before submitting more
126
+ patches. Editor imports, workers, watchers and the document stay out of the game
127
+ runtime. Bake committed data before handing it to the game. The editor's GLB action and
128
+ `exportWorldGLB` from `@threenative/terrain/export` write the whole resolved world (terrain,
129
+ props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. The full
130
+ operation list, units and patch rules ship in `node_modules/@threenative/terrain/AGENT_GUIDE.md`.
131
+
132
+ For individual props, save `placementOverrides` in the authoring document, keyed
133
+ by evaluated placement `id`. Each entry contains `position: [x,y,z]`, a unit
134
+ `quaternion: [x,y,z,w]`, positive `scale: [sx,sy,sz]` and `grounding: true|false`.
135
+ Use `validatePlacementOverrides` and `applyPlacementOverrides` from the headless
136
+ addon. Grounding defaults on; the game uses its actual model bounds and terrain
137
+ triangles. A free Y lift records `grounding: false` and still measures clearance.
138
+ The resolved state and `bakeTerrain` retain transforms; the game must consume
139
+ them. Never use an instance-buffer index as a saved key. Keep unmatched overrides
140
+ visible until the author explicitly removes or reassigns them.
@@ -24,7 +24,8 @@ need Unreal Editor export and cannot be recovered by retrying the converter.
24
24
 
25
25
  If FabCLI needs a session, proactively run `fabcli auth login`. Use Claude browser, or Codex's
26
26
  `chrome:control-chrome`, to complete the login with the user's active browser session, then retry
27
- the MCP call. Never read, copy, print, or persist browser cookies or tokens. The MCP checks
27
+ the MCP call. If the WebView login fails (it crashes on Wayland), use the `--manual` pty flow in
28
+ the reference below. Never read, copy, print, or persist browser cookies or tokens. The MCP checks
28
29
  entitlement and accepts only Fab Standard or CC-BY; it never claims or buys. Full arguments:
29
30
  `node_modules/create-threenative/agent-docs/references/finding-assets.md`.
30
31