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.
- package/README.md +3 -1
- package/agent-docs/references/assertion-reference.md +87 -35
- package/agent-docs/references/auto-exposure.md +57 -0
- package/agent-docs/references/capability-reference.md +1306 -62
- package/agent-docs/references/debug-surface.md +6 -0
- package/agent-docs/references/finding-assets.md +46 -10
- package/agent-docs/references/performance-basics.md +5 -4
- package/agent-docs/references/terrain-authoring.md +140 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
- package/capabilities.json +1505 -79
- package/dist/index.d.ts +28 -3
- package/dist/index.js +402 -167
- package/dist/threenative.js +989 -237
- package/dist/web-engine-buffer-geometry-utils.js +281 -0
- package/dist/web-engine-decal-geometry.js +184 -0
- package/dist/web-engine-gltf-loader.js +196 -0
- package/dist/web-engine-hdr-loader.js +190 -0
- package/dist/web-engine-lut-cube-loader.js +122 -0
- package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
- package/dist/web-engine-mesh-bvh.js +32 -0
- package/dist/web-engine-post-effects.js +168 -0
- package/dist/web-engine-runtime.js +42506 -0
- package/package.json +11 -8
- package/template-assets/autoExposure.ts +225 -0
- package/template-assets/exposure.ts +111 -0
- package/template-assets/exposureGraph.ts +178 -0
- package/template-assets/exposureReadback.ts +79 -0
- package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
- package/template-assets/patches/three@0.185.1.patch +6594 -700
- package/template-assets/patches/vite@8.2.0.patch +422 -0
- package/template-assets/worldEnvironment.ts +433 -30
- package/templates/action-rpg/AGENTS.md +11 -10
- package/templates/action-rpg/CLAUDE.md +11 -10
- package/templates/action-rpg/package.json +11 -9
- package/templates/action-rpg/playtests/performance.playtest.json +7 -1
- package/templates/action-rpg/src/progress.ts +0 -4
- package/templates/action-rpg/src/render/autoExposure.ts +225 -0
- package/templates/action-rpg/src/render/backlightControls.ts +66 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
- package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
- package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
- package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
- package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
- package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
- package/templates/action-rpg/src/render/exposure.ts +111 -0
- package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
- package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
- package/templates/action-rpg/src/render/heightFog.ts +118 -0
- package/templates/action-rpg/src/render/lighting.ts +26 -1
- package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
- package/templates/action-rpg/src/render/materialLighting.ts +155 -0
- package/templates/action-rpg/src/render/postprocessing.ts +17 -2
- package/templates/action-rpg/src/render/quality.ts +61 -2
- package/templates/action-rpg/src/render/sky.ts +21 -1
- package/templates/action-rpg/src/render/vfx.ts +133 -58
- package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
- package/templates/action-rpg/src/scenes/Play.ts +81 -16
- package/templates/action-rpg/threenative.config.ts +3 -0
- package/templates/action-rpg/vite.config.ts +10 -2
- package/templates/minimal/AGENTS.md +9 -10
- package/templates/minimal/CLAUDE.md +9 -10
- package/templates/minimal/package.json +9 -8
- package/templates/minimal/playtests/play.playtest.json +7 -1
- package/templates/minimal/playtests/sky.playtest.json +10 -1
- package/templates/minimal/src/render/autoExposure.ts +225 -0
- package/templates/minimal/src/render/backlightControls.ts +66 -0
- package/templates/minimal/src/render/backlightMaterial.ts +147 -0
- package/templates/minimal/src/render/environmentContribution.ts +188 -0
- package/templates/minimal/src/render/environmentRadiance.ts +36 -0
- package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
- package/templates/minimal/src/render/environmentSampling.ts +193 -0
- package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
- package/templates/minimal/src/render/exposure.ts +111 -0
- package/templates/minimal/src/render/exposureGraph.ts +178 -0
- package/templates/minimal/src/render/exposureReadback.ts +79 -0
- package/templates/minimal/src/render/heightFog.ts +118 -0
- package/templates/minimal/src/render/lighting.ts +25 -1
- package/templates/minimal/src/render/materialAssignments.ts +102 -0
- package/templates/minimal/src/render/materialLighting.ts +146 -0
- package/templates/minimal/src/render/postprocessing.ts +16 -2
- package/templates/minimal/src/render/quality.ts +60 -2
- package/templates/minimal/src/render/sky.ts +21 -1
- package/templates/minimal/src/render/worldEnvironment.ts +433 -30
- package/templates/minimal/src/scenes/Play.ts +50 -1
- package/templates/minimal/vite.config.ts +10 -2
- package/templates/platformer/AGENTS.md +7 -5
- package/templates/platformer/CLAUDE.md +7 -5
- package/templates/platformer/package.json +11 -9
- package/templates/platformer/playtests/performance.playtest.json +7 -1
- package/templates/platformer/src/render/autoExposure.ts +225 -0
- package/templates/platformer/src/render/backlightControls.ts +66 -0
- package/templates/platformer/src/render/backlightMaterial.ts +147 -0
- package/templates/platformer/src/render/environmentContribution.ts +188 -0
- package/templates/platformer/src/render/environmentRadiance.ts +36 -0
- package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
- package/templates/platformer/src/render/environmentSampling.ts +193 -0
- package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
- package/templates/platformer/src/render/exposure.ts +111 -0
- package/templates/platformer/src/render/exposureGraph.ts +178 -0
- package/templates/platformer/src/render/exposureReadback.ts +79 -0
- package/templates/platformer/src/render/heightFog.ts +118 -0
- package/templates/platformer/src/render/lighting.ts +26 -1
- package/templates/platformer/src/render/materialAssignments.ts +160 -0
- package/templates/platformer/src/render/materialLighting.ts +155 -0
- package/templates/platformer/src/render/materials.ts +7 -2
- package/templates/platformer/src/render/palette.ts +3 -3
- package/templates/platformer/src/render/postprocessing.ts +17 -2
- package/templates/platformer/src/render/quality.ts +61 -2
- package/templates/platformer/src/render/sky.ts +72 -23
- package/templates/platformer/src/render/skyEnvironment.ts +50 -0
- package/templates/platformer/src/render/worldEnvironment.ts +433 -30
- package/templates/platformer/src/scenes/Play.ts +70 -6
- package/templates/platformer/vite.config.ts +10 -2
- package/templates/puzzle/AGENTS.md +10 -9
- package/templates/puzzle/CLAUDE.md +10 -9
- package/templates/puzzle/package.json +11 -9
- package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
- package/templates/puzzle/playtests/lit.playtest.json +7 -1
- package/templates/puzzle/playtests/performance.playtest.json +7 -1
- package/templates/puzzle/src/render/autoExposure.ts +225 -0
- package/templates/puzzle/src/render/backlightControls.ts +66 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
- package/templates/puzzle/src/render/environmentContribution.ts +188 -0
- package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
- package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
- package/templates/puzzle/src/render/environmentSampling.ts +193 -0
- package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
- package/templates/puzzle/src/render/exposure.ts +111 -0
- package/templates/puzzle/src/render/exposureGraph.ts +178 -0
- package/templates/puzzle/src/render/exposureReadback.ts +79 -0
- package/templates/puzzle/src/render/heightFog.ts +118 -0
- package/templates/puzzle/src/render/lighting.ts +33 -1
- package/templates/puzzle/src/render/materialAssignments.ts +160 -0
- package/templates/puzzle/src/render/materialLighting.ts +155 -0
- package/templates/puzzle/src/render/materials.ts +1 -1
- package/templates/puzzle/src/render/postprocessing.ts +8 -2
- package/templates/puzzle/src/render/quality.ts +62 -1
- package/templates/puzzle/src/render/sky.ts +20 -1
- package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
- package/templates/puzzle/src/scenes/Play.ts +51 -2
- package/templates/puzzle/vite.config.ts +10 -2
- package/templates/racing/AGENTS.md +8 -7
- package/templates/racing/CLAUDE.md +8 -7
- package/templates/racing/package.json +11 -9
- package/templates/racing/playtests/performance.playtest.json +7 -1
- package/templates/racing/playtests/survives.playtest.json +6 -0
- package/templates/racing/src/render/autoExposure.ts +225 -0
- package/templates/racing/src/render/backlightControls.ts +66 -0
- package/templates/racing/src/render/backlightMaterial.ts +147 -0
- package/templates/racing/src/render/environmentContribution.ts +188 -0
- package/templates/racing/src/render/environmentRadiance.ts +36 -0
- package/templates/racing/src/render/environmentSampleCache.ts +43 -0
- package/templates/racing/src/render/environmentSampling.ts +193 -0
- package/templates/racing/src/render/environmentSnapshot.ts +53 -0
- package/templates/racing/src/render/exposure.ts +111 -0
- package/templates/racing/src/render/exposureGraph.ts +178 -0
- package/templates/racing/src/render/exposureReadback.ts +79 -0
- package/templates/racing/src/render/heightFog.ts +118 -0
- package/templates/racing/src/render/lighting.ts +29 -1
- package/templates/racing/src/render/materialAssignments.ts +160 -0
- package/templates/racing/src/render/materialLighting.ts +155 -0
- package/templates/racing/src/render/palette.ts +1 -10
- package/templates/racing/src/render/postprocessing.ts +17 -2
- package/templates/racing/src/render/quality.ts +61 -2
- package/templates/racing/src/render/shapes.ts +0 -25
- package/templates/racing/src/render/sky.ts +21 -1
- package/templates/racing/src/render/worldEnvironment.ts +433 -30
- package/templates/racing/src/scenes/Race.ts +91 -3
- package/templates/racing/src/track/circuit.ts +0 -9
- package/templates/racing/vite.config.ts +10 -2
- package/templates/rain/.codex/config.toml +19 -0
- package/templates/rain/.cursor/mcp.json +32 -0
- package/templates/rain/.gemini/settings.json +32 -0
- package/templates/rain/.mcp.json +32 -0
- package/templates/rain/.vscode/mcp.json +36 -0
- package/templates/rain/.zed/settings.json +36 -0
- package/templates/rain/AGENTS.md +95 -0
- package/templates/rain/CLAUDE.md +97 -0
- package/templates/rain/assets/rain-loop.wav +0 -0
- package/templates/rain/assets/thunder.wav +0 -0
- package/templates/rain/assets/wind-loop.wav +0 -0
- package/templates/rain/index.html +18 -0
- package/templates/rain/kit.json +7 -0
- package/templates/rain/native-playtests/boot.playtest.json +23 -0
- package/templates/rain/native-playtests/lightning.playtest.json +173 -0
- package/templates/rain/opencode.json +41 -0
- package/templates/rain/package.json +59 -0
- package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
- package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
- package/templates/rain/playtests/automation.playtest.json +133 -0
- package/templates/rain/playtests/cinematic.playtest.json +59 -0
- package/templates/rain/playtests/flash.playtest.json +27 -0
- package/templates/rain/playtests/fly.playtest.json +54 -0
- package/templates/rain/playtests/lightning.playtest.json +220 -0
- package/templates/rain/playtests/loading.playtest.json +57 -0
- package/templates/rain/playtests/paused.playtest.json +59 -0
- package/templates/rain/playtests/performance.playtest.json +32 -0
- package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
- package/templates/rain/playtests/simulation.playtest.json +20 -0
- package/templates/rain/playtests/storm.playtest.json +150 -0
- package/templates/rain/playtests/survives.playtest.json +58 -0
- package/templates/rain/playtests/tiers.playtest.json +194 -0
- package/templates/rain/playtests/weather.playtest.json +77 -0
- package/templates/rain/public/favicon.svg +5 -0
- package/templates/rain/src/audio/storm.ts +314 -0
- package/templates/rain/src/game.ts +81 -0
- package/templates/rain/src/main.ts +15 -0
- package/templates/rain/src/render/autoExposure.ts +225 -0
- package/templates/rain/src/render/bloom-shader.ts +65 -0
- package/templates/rain/src/render/camera.ts +160 -0
- package/templates/rain/src/render/clouds-shader.ts +242 -0
- package/templates/rain/src/render/clouds.ts +142 -0
- package/templates/rain/src/render/exposure.ts +111 -0
- package/templates/rain/src/render/exposureGraph.ts +178 -0
- package/templates/rain/src/render/exposureReadback.ts +79 -0
- package/templates/rain/src/render/lighting.ts +39 -0
- package/templates/rain/src/render/lightning.ts +360 -0
- package/templates/rain/src/render/loading.ts +327 -0
- package/templates/rain/src/render/materials.ts +19 -0
- package/templates/rain/src/render/noise-volume.ts +159 -0
- package/templates/rain/src/render/palette.ts +18 -0
- package/templates/rain/src/render/post-shader.ts +178 -0
- package/templates/rain/src/render/postprocessing.ts +229 -0
- package/templates/rain/src/render/quality.ts +161 -0
- package/templates/rain/src/render/rain.ts +299 -0
- package/templates/rain/src/render/sky.ts +28 -0
- package/templates/rain/src/render/world-shader.ts +680 -0
- package/templates/rain/src/render/world.ts +146 -0
- package/templates/rain/src/render/worldEnvironment.ts +1212 -0
- package/templates/rain/src/scenes/Boot.ts +348 -0
- package/templates/rain/src/state.ts +261 -0
- package/templates/rain/src/style.css +1160 -0
- package/templates/rain/src/ui/App.tsx +29 -0
- package/templates/rain/src/ui/GameUi.tsx +187 -0
- package/templates/rain/src/ui/Hud.tsx +327 -0
- package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
- package/templates/rain/src/ui/Menu.tsx +370 -0
- package/templates/rain/src/ui/automation.ts +60 -0
- package/templates/rain/src/ui/main.tsx +7 -0
- package/templates/rain/src/ui/tempest.ts +149 -0
- package/templates/rain/tailwind.config.ts +2 -0
- package/templates/rain/threenative.config.ts +66 -0
- package/templates/rain/tools/generate-shaders.mjs +656 -0
- package/templates/rain/tools/make-storm-audio.mjs +387 -0
- package/templates/rain/tools/storm-dsp.mjs +177 -0
- package/templates/rain/tools/tempest-bloom.frag +10 -0
- package/templates/rain/tools/tempest-clouds.frag +86 -0
- package/templates/rain/tools/tempest-post.frag +47 -0
- package/templates/rain/tools/tempest-world.frag +210 -0
- package/templates/rain/tools/verify-noise-volume.mjs +61 -0
- package/templates/rain/tsconfig.json +17 -0
- package/templates/rain/vite.config.ts +45 -0
- package/templates/rts/AGENTS.md +10 -11
- package/templates/rts/CLAUDE.md +10 -11
- package/templates/rts/package.json +10 -8
- package/templates/rts/playtests/performance.playtest.json +7 -1
- package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-build.playtest.json +10 -1
- package/templates/rts/playtests/rts-orders.playtest.json +7 -1
- package/templates/rts/playtests/rts-train.playtest.json +10 -1
- package/templates/rts/src/render/army.ts +10 -2
- package/templates/rts/src/render/autoExposure.ts +225 -0
- package/templates/rts/src/render/backlightControls.ts +66 -0
- package/templates/rts/src/render/backlightMaterial.ts +147 -0
- package/templates/rts/src/render/environmentContribution.ts +188 -0
- package/templates/rts/src/render/environmentRadiance.ts +36 -0
- package/templates/rts/src/render/environmentSampleCache.ts +43 -0
- package/templates/rts/src/render/environmentSampling.ts +193 -0
- package/templates/rts/src/render/environmentSnapshot.ts +53 -0
- package/templates/rts/src/render/exposure.ts +111 -0
- package/templates/rts/src/render/exposureGraph.ts +178 -0
- package/templates/rts/src/render/exposureReadback.ts +79 -0
- package/templates/rts/src/render/heightFog.ts +118 -0
- package/templates/rts/src/render/lighting.ts +26 -1
- package/templates/rts/src/render/materialAssignments.ts +160 -0
- package/templates/rts/src/render/materialLighting.ts +155 -0
- package/templates/rts/src/render/postprocessing.ts +8 -2
- package/templates/rts/src/render/quality.ts +61 -2
- package/templates/rts/src/render/sky.ts +21 -1
- package/templates/rts/src/render/worldEnvironment.ts +433 -30
- package/templates/rts/src/scenes/Play.ts +54 -3
- package/templates/rts/src/sim/ai.ts +0 -1
- package/templates/rts/src/sim/terrain.ts +0 -4
- package/templates/rts/vite.config.ts +10 -2
- package/templates/runner/AGENTS.md +10 -8
- package/templates/runner/CLAUDE.md +10 -8
- package/templates/runner/package.json +11 -9
- package/templates/runner/playtests/performance.playtest.json +10 -1
- package/templates/runner/src/physics.ts +0 -1
- package/templates/runner/src/render/autoExposure.ts +225 -0
- package/templates/runner/src/render/backlightControls.ts +66 -0
- package/templates/runner/src/render/backlightMaterial.ts +147 -0
- package/templates/runner/src/render/environmentContribution.ts +188 -0
- package/templates/runner/src/render/environmentRadiance.ts +36 -0
- package/templates/runner/src/render/environmentSampleCache.ts +43 -0
- package/templates/runner/src/render/environmentSampling.ts +193 -0
- package/templates/runner/src/render/environmentSnapshot.ts +53 -0
- package/templates/runner/src/render/exposure.ts +111 -0
- package/templates/runner/src/render/exposureGraph.ts +178 -0
- package/templates/runner/src/render/exposureReadback.ts +79 -0
- package/templates/runner/src/render/heightFog.ts +118 -0
- package/templates/runner/src/render/lighting.ts +26 -1
- package/templates/runner/src/render/materialAssignments.ts +160 -0
- package/templates/runner/src/render/materialLighting.ts +155 -0
- package/templates/runner/src/render/postprocessing.ts +17 -2
- package/templates/runner/src/render/quality.ts +61 -2
- package/templates/runner/src/render/sky.ts +21 -1
- package/templates/runner/src/render/worldEnvironment.ts +433 -30
- package/templates/runner/src/scenes/Run.ts +67 -2
- package/templates/runner/threenative.config.ts +3 -0
- package/templates/runner/vite.config.ts +10 -2
- package/templates/sailing/AGENTS.md +14 -13
- package/templates/sailing/CLAUDE.md +14 -13
- package/templates/sailing/native-playtests/survives.playtest.json +7 -0
- package/templates/sailing/package.json +11 -9
- package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
- package/templates/sailing/src/entities/Ship.ts +38 -18
- package/templates/sailing/src/render/autoExposure.ts +225 -0
- package/templates/sailing/src/render/backlightControls.ts +66 -0
- package/templates/sailing/src/render/backlightMaterial.ts +147 -0
- package/templates/sailing/src/render/camera.ts +12 -4
- package/templates/sailing/src/render/environmentContribution.ts +188 -0
- package/templates/sailing/src/render/environmentRadiance.ts +36 -0
- package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
- package/templates/sailing/src/render/environmentSampling.ts +193 -0
- package/templates/sailing/src/render/environmentSetup.ts +24 -0
- package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
- package/templates/sailing/src/render/exposure.ts +111 -0
- package/templates/sailing/src/render/exposureGraph.ts +178 -0
- package/templates/sailing/src/render/exposureReadback.ts +79 -0
- package/templates/sailing/src/render/heightFog.ts +118 -0
- package/templates/sailing/src/render/lighting.ts +26 -1
- package/templates/sailing/src/render/materialAssignments.ts +160 -0
- package/templates/sailing/src/render/materialLighting.ts +155 -0
- package/templates/sailing/src/render/ocean.ts +71 -53
- package/templates/sailing/src/render/postprocessing.ts +16 -2
- package/templates/sailing/src/render/props.ts +0 -45
- package/templates/sailing/src/render/quality.ts +61 -1
- package/templates/sailing/src/render/sky.ts +21 -1
- package/templates/sailing/src/render/worldEnvironment.ts +433 -30
- package/templates/sailing/src/scenes/Boot.ts +12 -1
- package/templates/sailing/src/scenes/Sailing.ts +87 -2
- package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
- package/templates/sailing/threenative.config.ts +3 -0
- package/templates/sailing/vite.config.ts +10 -2
- package/templates/shooter/AGENTS.md +8 -6
- package/templates/shooter/CLAUDE.md +8 -6
- package/templates/shooter/package.json +11 -9
- package/templates/shooter/playtests/performance.playtest.json +7 -1
- package/templates/shooter/src/entities/Enemy.ts +0 -15
- package/templates/shooter/src/entities/Rifle.ts +38 -1
- package/templates/shooter/src/render/autoExposure.ts +225 -0
- package/templates/shooter/src/render/backlightControls.ts +66 -0
- package/templates/shooter/src/render/backlightMaterial.ts +147 -0
- package/templates/shooter/src/render/camera.ts +1 -12
- package/templates/shooter/src/render/decals.ts +299 -5
- package/templates/shooter/src/render/environmentContribution.ts +188 -0
- package/templates/shooter/src/render/environmentRadiance.ts +36 -0
- package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
- package/templates/shooter/src/render/environmentSampling.ts +193 -0
- package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
- package/templates/shooter/src/render/exposure.ts +111 -0
- package/templates/shooter/src/render/exposureGraph.ts +178 -0
- package/templates/shooter/src/render/exposureReadback.ts +79 -0
- package/templates/shooter/src/render/gunfx.ts +0 -1
- package/templates/shooter/src/render/heightFog.ts +118 -0
- package/templates/shooter/src/render/lighting.ts +26 -1
- package/templates/shooter/src/render/materialAssignments.ts +160 -0
- package/templates/shooter/src/render/materialLighting.ts +155 -0
- package/templates/shooter/src/render/postprocessing.ts +17 -2
- package/templates/shooter/src/render/quality.ts +61 -2
- package/templates/shooter/src/render/scale.ts +2 -93
- package/templates/shooter/src/render/sky.ts +21 -1
- package/templates/shooter/src/render/vehicles.ts +0 -17
- package/templates/shooter/src/render/worldEnvironment.ts +433 -30
- package/templates/shooter/src/scenes/Play.ts +64 -2
- package/templates/shooter/vite.config.ts +10 -2
- package/templates/snow/.codex/config.toml +19 -0
- package/templates/snow/.cursor/mcp.json +32 -0
- package/templates/snow/.gemini/settings.json +32 -0
- package/templates/snow/.mcp.json +32 -0
- package/templates/snow/.vscode/mcp.json +36 -0
- package/templates/snow/.zed/settings.json +36 -0
- package/templates/snow/AGENTS.md +90 -0
- package/templates/snow/CLAUDE.md +92 -0
- package/templates/snow/README.md +26 -0
- package/templates/snow/assets/crunch.wav +0 -0
- package/templates/snow/assets/wind.wav +0 -0
- package/templates/snow/index.html +12 -0
- package/templates/snow/kit.json +7 -0
- package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
- package/templates/snow/native-playtests/survives.playtest.json +47 -0
- package/templates/snow/opencode.json +41 -0
- package/templates/snow/package.json +60 -0
- package/templates/snow/playtests/footsteps.playtest.json +95 -0
- package/templates/snow/playtests/performance.playtest.json +36 -0
- package/templates/snow/playtests/snow-physics.playtest.json +154 -0
- package/templates/snow/playtests/survives.playtest.json +56 -0
- package/templates/snow/playtests/touch-controls.playtest.json +71 -0
- package/templates/snow/playtests/weather.playtest.json +119 -0
- package/templates/snow/public/favicon.svg +5 -0
- package/templates/snow/src/audio.ts +58 -0
- package/templates/snow/src/commands.ts +8 -0
- package/templates/snow/src/entities/Explorer.ts +279 -0
- package/templates/snow/src/game.ts +69 -0
- package/templates/snow/src/main.ts +15 -0
- package/templates/snow/src/render/autoExposure.ts +225 -0
- package/templates/snow/src/render/backlightControls.ts +66 -0
- package/templates/snow/src/render/backlightMaterial.ts +147 -0
- package/templates/snow/src/render/bootPrint.ts +50 -0
- package/templates/snow/src/render/camera.ts +84 -0
- package/templates/snow/src/render/environmentContribution.ts +188 -0
- package/templates/snow/src/render/environmentRadiance.ts +36 -0
- package/templates/snow/src/render/environmentSampleCache.ts +43 -0
- package/templates/snow/src/render/environmentSampling.ts +193 -0
- package/templates/snow/src/render/environmentSnapshot.ts +53 -0
- package/templates/snow/src/render/explorer.ts +321 -0
- package/templates/snow/src/render/exposure.ts +111 -0
- package/templates/snow/src/render/exposureGraph.ts +178 -0
- package/templates/snow/src/render/exposureReadback.ts +79 -0
- package/templates/snow/src/render/heightFog.ts +118 -0
- package/templates/snow/src/render/lighting.ts +82 -0
- package/templates/snow/src/render/loading.ts +325 -0
- package/templates/snow/src/render/materialAssignments.ts +160 -0
- package/templates/snow/src/render/materialLighting.ts +155 -0
- package/templates/snow/src/render/materials.ts +36 -0
- package/templates/snow/src/render/palette.ts +17 -0
- package/templates/snow/src/render/postprocessing.ts +58 -0
- package/templates/snow/src/render/props.ts +42 -0
- package/templates/snow/src/render/quality.ts +193 -0
- package/templates/snow/src/render/scenery.ts +244 -0
- package/templates/snow/src/render/sky.ts +76 -0
- package/templates/snow/src/render/snowSurface.ts +259 -0
- package/templates/snow/src/render/touch-controls.ts +143 -0
- package/templates/snow/src/render/weather.ts +279 -0
- package/templates/snow/src/render/worldEnvironment.ts +1212 -0
- package/templates/snow/src/scenes/Boot.ts +12 -0
- package/templates/snow/src/scenes/Snow.ts +663 -0
- package/templates/snow/src/state.ts +46 -0
- package/templates/snow/src/style.css +143 -0
- package/templates/snow/src/terrain.ts +64 -0
- package/templates/snow/src/ui/App.tsx +15 -0
- package/templates/snow/src/ui/Controls.tsx +322 -0
- package/templates/snow/src/ui/GameUi.tsx +354 -0
- package/templates/snow/src/ui/icons.tsx +54 -0
- package/templates/snow/src/ui/main.tsx +7 -0
- package/templates/snow/tailwind.config.ts +2 -0
- package/templates/snow/threenative.config.ts +54 -0
- package/templates/snow/tsconfig.json +17 -0
- package/templates/snow/vite.config.ts +45 -0
- package/templates/starter/AGENTS.md +11 -16
- package/templates/starter/CLAUDE.md +11 -16
- package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
- package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
- package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
- package/templates/starter/package.json +11 -9
- package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
- package/templates/starter/playtests/movement.playtest.json +192 -0
- package/templates/starter/playtests/play.playtest.json +18 -2
- package/templates/starter/playtests/production-readiness.playtest.json +1 -1
- package/templates/starter/public/grade.cube +735 -0
- package/templates/starter/src/entities/Crate.ts +4 -0
- package/templates/starter/src/entities/Player.ts +79 -18
- package/templates/starter/src/game.ts +1 -0
- package/templates/starter/src/render/adaptiveQuality.ts +28 -41
- package/templates/starter/src/render/autoExposure.ts +225 -0
- package/templates/starter/src/render/backlightControls.ts +66 -0
- package/templates/starter/src/render/backlightMaterial.ts +147 -0
- package/templates/starter/src/render/environmentContribution.ts +188 -0
- package/templates/starter/src/render/environmentRadiance.ts +36 -0
- package/templates/starter/src/render/environmentSampleCache.ts +43 -0
- package/templates/starter/src/render/environmentSampling.ts +193 -0
- package/templates/starter/src/render/environmentSnapshot.ts +53 -0
- package/templates/starter/src/render/exposure.ts +111 -0
- package/templates/starter/src/render/exposureGraph.ts +178 -0
- package/templates/starter/src/render/exposureReadback.ts +79 -0
- package/templates/starter/src/render/grade.ts +157 -0
- package/templates/starter/src/render/heightFog.ts +118 -0
- package/templates/starter/src/render/lighting.ts +26 -1
- package/templates/starter/src/render/materialAssignments.ts +160 -0
- package/templates/starter/src/render/materialLighting.ts +155 -0
- package/templates/starter/src/render/postprocessing.ts +84 -4
- package/templates/starter/src/render/quality.ts +80 -8
- package/templates/starter/src/render/qualityPolicy.ts +54 -0
- package/templates/starter/src/render/rendererGate.ts +36 -0
- package/templates/starter/src/render/sky.ts +23 -1
- package/templates/starter/src/render/temporalAA.ts +197 -0
- package/templates/starter/src/render/temporalAAFrame.ts +179 -0
- package/templates/starter/src/render/temporalAAHooks.ts +101 -0
- package/templates/starter/src/render/temporalAAInput.ts +56 -0
- package/templates/starter/src/render/temporalAAResolve.ts +65 -0
- package/templates/starter/src/render/temporalAAStage.ts +76 -0
- package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
- package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
- package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
- package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
- package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
- package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
- package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
- package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
- package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
- package/templates/starter/src/render/temporalResolve.ts +139 -0
- package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
- package/templates/starter/src/render/temporalResolveMath.ts +196 -0
- package/templates/starter/src/render/volumetricFog.ts +124 -0
- package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
- package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
- package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
- package/templates/starter/src/render/worldEnvironment.ts +433 -30
- package/templates/starter/src/scenes/Play.ts +110 -1
- package/templates/starter/src/state.ts +1 -0
- package/templates/starter/src/ui/Hud.tsx +1 -1
- package/templates/starter/src/ui/Menu.tsx +1 -1
- package/templates/starter/tools/make-grade-lut.mjs +101 -0
- package/templates/starter/vite.config.ts +10 -2
- package/templates/tower-defense/AGENTS.md +10 -9
- package/templates/tower-defense/CLAUDE.md +10 -9
- package/templates/tower-defense/package.json +11 -9
- package/templates/tower-defense/playtests/performance.playtest.json +7 -1
- package/templates/tower-defense/src/render/autoExposure.ts +225 -0
- package/templates/tower-defense/src/render/backlightControls.ts +66 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
- package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
- package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
- package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
- package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
- package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
- package/templates/tower-defense/src/render/exposure.ts +111 -0
- package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
- package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
- package/templates/tower-defense/src/render/lighting.ts +33 -1
- package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
- package/templates/tower-defense/src/render/materialLighting.ts +155 -0
- package/templates/tower-defense/src/render/postprocessing.ts +8 -2
- package/templates/tower-defense/src/render/quality.ts +61 -2
- package/templates/tower-defense/src/render/shapes.ts +0 -3
- package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
- package/templates/tower-defense/src/scenes/Battle.ts +65 -2
- package/templates/tower-defense/vite.config.ts +10 -2
- 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
|
-
**
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
|
43
|
-
|
|
44
|
-
|
|
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`
|
|
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.
|
|
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
|
|