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
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# Capability reference
|
|
5
5
|
|
|
6
|
-
Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:starter`, and `three`,
|
|
6
|
+
Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
|
|
7
7
|
generated from the doc tags the engine itself compiles, so this page cannot disagree with
|
|
8
8
|
the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
|
|
9
9
|
MCP server is available.
|
|
@@ -427,7 +427,7 @@ export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, ind
|
|
|
427
427
|
|
|
428
428
|
- **Use when:** add hundreds of built objects to the scene without one multi-second frame · stream a detail tier in behind a loading curtain without the page looking hung
|
|
429
429
|
- **Constraints:** the objects, and where each one goes, stay the game's; this decides only when each joins the graph · input order is the attach order and cannot be changed · a false `while` stops the run and is reported as `stopped`, never thrown
|
|
430
|
-
- **Overrides:** sliceSize
|
|
430
|
+
- **Overrides:** a slice ends on an 8 ms budget unless the game gives `sliceSize`, and the reported sliceSize is then the measured average; `marker: false` silences the TN_ADD_SLICES line, not the report
|
|
431
431
|
|
|
432
432
|
```ts
|
|
433
433
|
const report = await addInSlices(objects, (object) => ctx.add(object), {
|
|
@@ -531,6 +531,22 @@ import { alwaysRender } from "@threenative/core";
|
|
|
531
531
|
alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
|
|
532
532
|
```
|
|
533
533
|
|
|
534
|
+
### `AnimationComposer`
|
|
535
|
+
|
|
536
|
+
`class` — Compose game-authored locomotion and masked actions on one Three.js mixer.
|
|
537
|
+
|
|
538
|
+
```ts
|
|
539
|
+
export class AnimationComposer { … }
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
- **Use when:** synchronize walk/run/strafe clips with different durations · reload with the upper body while locomotion continues · apply an additive recoil clip with an explicit reference pose · route root motion through collision-aware character movement
|
|
543
|
+
- **Constraints:** one base phase, one masked override, at most two additive layers and eight actions · root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK · root motion excludes velocity-driven stride sync; unsupported parent transforms throw · source clips remain immutable; dispose at scene exit
|
|
544
|
+
|
|
545
|
+
```ts
|
|
546
|
+
const animation = new AnimationComposer({ root: rig, clips, samples: ["walk", "run"] });
|
|
547
|
+
animation.setWeights([0.5, 0.5]); animation.update(dt);
|
|
548
|
+
```
|
|
549
|
+
|
|
534
550
|
### `AnimationPlayer`
|
|
535
551
|
|
|
536
552
|
`class` — Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
|
|
@@ -618,8 +634,8 @@ model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
|
618
634
|
export class AudioBus { … }
|
|
619
635
|
```
|
|
620
636
|
|
|
621
|
-
- **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · play cannon, wave, and ship sound effects
|
|
622
|
-
- **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only
|
|
637
|
+
- **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · hold a loud mix below clipping with a compressor on the bus · play cannon, wave, and ship sound effects
|
|
638
|
+
- **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only · compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum
|
|
623
639
|
- **Supersedes (writing this fails `pnpm budgets`):** new Audio(
|
|
624
640
|
|
|
625
641
|
```ts
|
|
@@ -671,6 +687,36 @@ const billboard = new Billboard3D(label, { camera });
|
|
|
671
687
|
billboard.update();
|
|
672
688
|
```
|
|
673
689
|
|
|
690
|
+
### `BlendSpace1D`
|
|
691
|
+
|
|
692
|
+
`class` — Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
|
|
693
|
+
|
|
694
|
+
```ts
|
|
695
|
+
export class BlendSpace1D { … }
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
- **Use when:** calculate 1D walk/run blend weights from speed · calculate 2D locomotion weights from forward and strafe intent
|
|
699
|
+
- **Constraints:** duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization · outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
|
|
700
|
+
|
|
701
|
+
```ts
|
|
702
|
+
const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
### `BlendSpace2D`
|
|
706
|
+
|
|
707
|
+
`class` — Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
|
|
708
|
+
|
|
709
|
+
```ts
|
|
710
|
+
export class BlendSpace2D { … }
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
- **Use when:** calculate 1D walk/run blend weights from speed · calculate 2D locomotion weights from forward and strafe intent
|
|
714
|
+
- **Constraints:** duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization · outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
|
|
715
|
+
|
|
716
|
+
```ts
|
|
717
|
+
const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
|
|
718
|
+
```
|
|
719
|
+
|
|
674
720
|
### `boneContact`
|
|
675
721
|
|
|
676
722
|
`function` — Measure whether a named bone reaches the object it is supposed to be touching, in metres.
|
|
@@ -1170,6 +1216,24 @@ ctx.add(field);
|
|
|
1170
1216
|
field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
|
|
1171
1217
|
```
|
|
1172
1218
|
|
|
1219
|
+
### `FluidParticles3D`
|
|
1220
|
+
|
|
1221
|
+
`class` — Simulate liquid as GPU particles (pour, splash, dam break, waterfall) and expose positions, a density volume and a surface height while the game owns every look.
|
|
1222
|
+
|
|
1223
|
+
```ts
|
|
1224
|
+
export class FluidParticles3D extends Group { … }
|
|
1225
|
+
```
|
|
1226
|
+
|
|
1227
|
+
- **Use when:** pour, splash, or dam-break water that fills a container and flows around obstacles · simulate water or another liquid as particles in a fluid simulation · drop a ball or box into liquid and let it displace and float on the water · emit a stream or waterfall of particle fluid and drain it somewhere else · sample particle-fluid density or surface height in a game-owned render node
|
|
1228
|
+
- **Constraints:** add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic · a renderer without WebGPU compute throws a named error at attach; it never draws nothing · `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity · `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
|
|
1229
|
+
- **Overrides:** iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
|
|
1230
|
+
|
|
1231
|
+
```ts
|
|
1232
|
+
const water = new FluidParticles3D({ capacity: 6000 });
|
|
1233
|
+
ctx.add(water);
|
|
1234
|
+
water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
|
|
1235
|
+
```
|
|
1236
|
+
|
|
1173
1237
|
### `formatSceneWarning`
|
|
1174
1238
|
|
|
1175
1239
|
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
@@ -1200,6 +1264,22 @@ export function formatSpansWindow(window: ISpanWindow): string { … }
|
|
|
1200
1264
|
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
1201
1265
|
```
|
|
1202
1266
|
|
|
1267
|
+
### `formatUnlitFoliageWarning`
|
|
1268
|
+
|
|
1269
|
+
`function` — Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.
|
|
1270
|
+
|
|
1271
|
+
```ts
|
|
1272
|
+
export function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string { … }
|
|
1273
|
+
```
|
|
1274
|
+
|
|
1275
|
+
- **Use when:** catch the "why does my forest look like cardboard" question before a human plays it · audit a scene a game built from imported GLB foliage
|
|
1276
|
+
- **Constraints:** derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material · it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
|
|
1277
|
+
- **Overrides:** `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
|
|
1278
|
+
|
|
1279
|
+
```ts
|
|
1280
|
+
defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
|
|
1281
|
+
```
|
|
1282
|
+
|
|
1203
1283
|
### `formatValidationReport`
|
|
1204
1284
|
|
|
1205
1285
|
`function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
|
|
@@ -1223,8 +1303,8 @@ if (renderListValidationRequested()) console.log(formatValidationReport(report))
|
|
|
1223
1303
|
export class FrameBudget { … }
|
|
1224
1304
|
```
|
|
1225
1305
|
|
|
1226
|
-
- **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass
|
|
1227
|
-
- **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
|
|
1306
|
+
- **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass · retain every asynchronous GPU render frame for a complete paired benchmark
|
|
1307
|
+
- **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero · `ctx.renderer.observeGpuFrames({ maxFrames, maxQueries })` is opt-in, bounded and fail-closed; `take()` delivers immutable complete render-query groups once, while `status()` reports pending/undrained/queued membership and losses · observation preserves ordinary sampling; a complete benchmark explicitly requests `renderer.gpuTimestampFrameInterval: 1` and joins Three query IDs to actual world renders, including separate overlay IDs · `stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement
|
|
1228
1308
|
|
|
1229
1309
|
```ts
|
|
1230
1310
|
defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
|
|
@@ -1284,11 +1364,13 @@ if (isMobile()) showTouchControls();
|
|
|
1284
1364
|
export class GPUParticles3D extends Sprite implements IComputeDriven { … }
|
|
1285
1365
|
```
|
|
1286
1366
|
|
|
1287
|
-
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
|
|
1288
|
-
- **Constraints:** geometry, color, and timing remain supplied by the game
|
|
1367
|
+
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles · splash spray droplets with lifetime and gravity · spawn water droplets, mist, or foam bubbles above a fluid surface · falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard · kick up a spray of powder snow or dust where a foot or a ball lands · a hit, impact or explosion burst that starts at the point and moment it is asked for, and a second hit that must not move the first hit's live particles · emitParticle a burst of GPU particles at a world position with its own free slots
|
|
1368
|
+
- **Constraints:** geometry, color, and timing remain supplied by the game · a `spawn` kernel makes bursts requests: `emitParticle({ count, origin })` reserves ring slots, the engine stamps `buffers.births` and `process` reads age as `runtime.time - births[i]`; there is no readback · a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent · requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option · the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view · a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view · when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget
|
|
1369
|
+
- **Overrides:** localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring · onCull: "clear" restarts a returning effect, the default "pause" resumes it with buffers intact · bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence · graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling
|
|
1289
1370
|
|
|
1290
1371
|
```ts
|
|
1291
1372
|
const particles = new GPUParticles3D(particleOptions);
|
|
1373
|
+
particles.emitParticle({ count: 220, origin: hit.position });
|
|
1292
1374
|
```
|
|
1293
1375
|
|
|
1294
1376
|
### `GPUReadback`
|
|
@@ -1377,9 +1459,9 @@ const uninstall = installSpanProbes(renderer.raw, scene);
|
|
|
1377
1459
|
export class InstancedBatch { … }
|
|
1378
1460
|
```
|
|
1379
1461
|
|
|
1380
|
-
- **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
|
|
1381
|
-
- **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed
|
|
1382
|
-
- **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
|
|
1462
|
+
- **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · automatically select instanced prop detail from projected screen error using baked AutoLOD chains · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
|
|
1463
|
+
- **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed · baked AutoLOD chains survive geometry clone/transform preparation and partition instances automatically into spatially bounded draws in the engine frame loop at 4 px projected error; public instance slots remain stable · unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE
|
|
1464
|
+
- **Overrides:** autoLod: false leaves selection to the game; autoLod.maxPixelError and hysteresis override the measured-camera budget; lods supplies authored distance/geometry levels and wins over the baked chain · castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
|
|
1383
1465
|
|
|
1384
1466
|
```ts
|
|
1385
1467
|
const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
|
|
@@ -1931,6 +2013,21 @@ export class RenderListValidator { … }
|
|
|
1931
2013
|
if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
1932
2014
|
```
|
|
1933
2015
|
|
|
2016
|
+
### `renderTrapAudit`
|
|
2017
|
+
|
|
2018
|
+
`function` — Catch scene state that silently loses environment fill or ignores authored opacity. After `enter()` the game first applies the opacity convention: a drawn material with `opacity < 1` turns transparent and one `TN_OPACITY_TRANSPARENT` console warning names it (override: `alphaHash: true`, or `opacity: 1`). It then prints `TN_ENVIRONMENT_TOO_SMALL` as a console error with the fix, so playtest `noConsoleErrors` rejects it.
|
|
2019
|
+
|
|
2020
|
+
```ts
|
|
2021
|
+
export function renderTrapAudit(scene: Object3D & { … }
|
|
2022
|
+
```
|
|
2023
|
+
|
|
2024
|
+
- **Use when:** audit an equirectangular sky too narrow for three's WebGPU PMREM · find visible opaque materials whose authored opacity is ignored
|
|
2025
|
+
- **Constraints:** structural scene reads only, one visible-tree walk per entry, at most five material examples · the audit itself changes no scene state; the game loop's opacity convention is the only writer
|
|
2026
|
+
|
|
2027
|
+
```ts
|
|
2028
|
+
renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array
|
|
2029
|
+
```
|
|
2030
|
+
|
|
1934
2031
|
### `replay`
|
|
1935
2032
|
|
|
1936
2033
|
`function` — Record or replay deterministic game input and state.
|
|
@@ -2093,7 +2190,7 @@ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
|
2093
2190
|
export class Scheduler { … }
|
|
2094
2191
|
```
|
|
2095
2192
|
|
|
2096
|
-
- **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
|
|
2193
|
+
- **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve · a countdown timer: end the level when its time limit runs out
|
|
2097
2194
|
- **Constraints:** dispose returned handles when the owning scene exits · ease receives progress in the range 0 to 1 and its return value is the interpolation factor
|
|
2098
2195
|
|
|
2099
2196
|
```ts
|
|
@@ -2358,7 +2455,7 @@ invalidateStatic(drawbridge);
|
|
|
2358
2455
|
export class TracerPool3D { … }
|
|
2359
2456
|
```
|
|
2360
2457
|
|
|
2361
|
-
- **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
|
|
2458
|
+
- **Use when:** show where a hitscan round went · show each round a weapon fires, one tracer per trigger press · draw incoming fire without spawning projectiles
|
|
2362
2459
|
- **Constraints:** the surface comes from the game; pooling, travel, and fading belong to the engine · update once per frame and dispose with the owning scene
|
|
2363
2460
|
|
|
2364
2461
|
```ts
|
|
@@ -2366,6 +2463,22 @@ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
|
|
|
2366
2463
|
tracers.spawn(muzzle, shotDirection, hit.distance);
|
|
2367
2464
|
```
|
|
2368
2465
|
|
|
2466
|
+
### `unlitFoliageWarning`
|
|
2467
|
+
|
|
2468
|
+
`function` — Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.
|
|
2469
|
+
|
|
2470
|
+
```ts
|
|
2471
|
+
export function unlitFoliageWarning( scene: Object3D & { … }
|
|
2472
|
+
```
|
|
2473
|
+
|
|
2474
|
+
- **Use when:** catch the "why does my forest look like cardboard" question before a human plays it · audit a scene a game built from imported GLB foliage
|
|
2475
|
+
- **Constraints:** derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material · it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
|
|
2476
|
+
- **Overrides:** `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
|
|
2477
|
+
|
|
2478
|
+
```ts
|
|
2479
|
+
defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
|
|
2480
|
+
```
|
|
2481
|
+
|
|
2369
2482
|
### `unmarkStatic`
|
|
2370
2483
|
|
|
2371
2484
|
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
@@ -2494,8 +2607,8 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
|
|
|
2494
2607
|
```
|
|
2495
2608
|
|
|
2496
2609
|
- **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
|
|
2497
|
-
- **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing ·
|
|
2498
|
-
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
|
|
2610
|
+
- **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left · `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region · call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
|
|
2611
|
+
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
|
|
2499
2612
|
|
|
2500
2613
|
```ts
|
|
2501
2614
|
const sun = new DirectionalLight(0xffffff, 3);
|
|
@@ -2525,12 +2638,12 @@ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) })
|
|
|
2525
2638
|
export class WaterSurface3D { … }
|
|
2526
2639
|
```
|
|
2527
2640
|
|
|
2528
|
-
- **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame
|
|
2529
|
-
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only ·
|
|
2641
|
+
- **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame · automatically reflect terrain and large casters without redrawing instanced small props
|
|
2642
|
+
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only · omitted reflection.layers automatically reflects terrain-sized surfaces and large non-instanced casters, excluding instanced/skinned props; TN_WATER_REFLECTION_DEFAULT reports the set once · reflection.refreshInterval is in presented frames; 1 is every frame, and the default · the mirror plane is level, from level alone; do not parent target to a scaled mesh
|
|
2643
|
+
- **Overrides:** reflection.layers is an explicit Three Layers mask and wins over automatic filtering, including layer-0 mask 1; reflection.minSize overrides the default 10 metre minimum extent
|
|
2530
2644
|
|
|
2531
2645
|
```ts
|
|
2532
|
-
const
|
|
2533
|
-
const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });
|
|
2646
|
+
const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
|
|
2534
2647
|
material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
|
|
2535
2648
|
```
|
|
2536
2649
|
|
|
@@ -2741,6 +2854,24 @@ export function View(props: IViewProps): ReactNode { … }
|
|
|
2741
2854
|
<View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>
|
|
2742
2855
|
```
|
|
2743
2856
|
|
|
2857
|
+
## `@threenative/core/react-css`
|
|
2858
|
+
|
|
2859
|
+
### `createCssUiRoot`
|
|
2860
|
+
|
|
2861
|
+
`function` — Mount React into a native CSS engine.
|
|
2862
|
+
|
|
2863
|
+
```ts
|
|
2864
|
+
export function createCssUiRoot(options: ICssUiRootOptions = { … }
|
|
2865
|
+
```
|
|
2866
|
+
|
|
2867
|
+
- **Use when:** mount a React HUD on the desktop host with no DOM in the runtime · write one React component and run it on the web and on the desktop host
|
|
2868
|
+
- **Constraints:** desktop only, and the game host must be built with the CSS backend (`TN_ENABLE_CSS_UI=1`); Android, iOS and web phones render a React HUD in a web overlay instead · import `react`, never `react-dom`, from a native entry · styling is CSS resolved by the native engine; JS only mirrors the element tree
|
|
2869
|
+
|
|
2870
|
+
```ts
|
|
2871
|
+
const root = createCssUiRoot();
|
|
2872
|
+
root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
|
|
2873
|
+
```
|
|
2874
|
+
|
|
2744
2875
|
## `@threenative/core/ui-layer`
|
|
2745
2876
|
|
|
2746
2877
|
### `connectUiBridge`
|
|
@@ -2874,7 +3005,7 @@ const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackI
|
|
|
2874
3005
|
export class Heightfield extends Group implements IComputeDriven { … }
|
|
2875
3006
|
```
|
|
2876
3007
|
|
|
2877
|
-
- **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain
|
|
3008
|
+
- **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain · keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)
|
|
2878
3009
|
- **Constraints:** sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output · rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
|
|
2879
3010
|
- **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
|
|
2880
3011
|
|
|
@@ -2899,18 +3030,18 @@ const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorld
|
|
|
2899
3030
|
|
|
2900
3031
|
### `loadTerrainSplat`
|
|
2901
3032
|
|
|
2902
|
-
`function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Nothing here is a look choice: textures, tiles, tints, thresholds and noise scales all come from the package's table, which the game authors once and its DCC shares.
|
|
3033
|
+
`function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.
|
|
2903
3034
|
|
|
2904
3035
|
```ts
|
|
2905
3036
|
export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }
|
|
2906
3037
|
```
|
|
2907
3038
|
|
|
2908
3039
|
- **Use when:** terrain textured by splat masks exported from Blender with the world package · the game's terrain should match the DCC's terrain material without a second copy
|
|
2909
|
-
- **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `
|
|
3040
|
+
- **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe · WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
|
|
2910
3041
|
- **Overrides:** every value comes from the package's table; the returned material is the game's to adjust
|
|
2911
3042
|
|
|
2912
3043
|
```ts
|
|
2913
|
-
const surface = await loadTerrainSplat({ assets: ctx.assets, url: "world/world.json" });
|
|
3044
|
+
const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
|
|
2914
3045
|
const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
|
|
2915
3046
|
```
|
|
2916
3047
|
|
|
@@ -2929,6 +3060,43 @@ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
|
|
|
2929
3060
|
const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
|
|
2930
3061
|
```
|
|
2931
3062
|
|
|
3063
|
+
### `snowDiscFootprint`
|
|
3064
|
+
|
|
3065
|
+
`function` — A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.
|
|
3066
|
+
|
|
3067
|
+
```ts
|
|
3068
|
+
export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }
|
|
3069
|
+
```
|
|
3070
|
+
|
|
3071
|
+
- **Use when:** press a ball, wheel or probe into snow · give a sphere a physically sized snow contact instead of a boot shape
|
|
3072
|
+
- **Constraints:** radius is metres; the footprint never grows with load, only deeper
|
|
3073
|
+
- **Overrides:** softness widens the eased edge without changing the contact radius
|
|
3074
|
+
|
|
3075
|
+
```ts
|
|
3076
|
+
const footprint = snowDiscFootprint(0.25);
|
|
3077
|
+
```
|
|
3078
|
+
|
|
3079
|
+
### `SnowField`
|
|
3080
|
+
|
|
3081
|
+
`class` — Persistent snow deformation over one canonical heightfield. Snow keeps four channels per cell — indentation, displaced bank, compaction and disturbance — and writes the combined surface (`terrain + depth + bank - indent`) back into the heightfield it was given. Queries, rendered geometry and collider export therefore all read one surface, and no second terrain representation exists. The field is numeric only: it never chooses a boot, a tread, a particle, a material or a camera. Games supply terrain heights, the snow depth, the contact profile and the response coefficients; this class owns the storage, the load-dependent penetration and the bounded recovery. It is a heightfield approximation — not granular snow, displaced-volume conservation, avalanches, melting or a calibrated material law.
|
|
3082
|
+
|
|
3083
|
+
```ts
|
|
3084
|
+
export class SnowField { … }
|
|
3085
|
+
```
|
|
3086
|
+
|
|
3087
|
+
- **Use when:** leave footprints, tracks and tyre ruts in snow that persist and fill in over time · let a pushed sphere carve a connected track and a dropped one settle into a crater · store snow deformation that rendered geometry and collision both read · reset a snowfield between rounds or change its depth at runtime · show how packed the snow is where people have walked or objects have rested
|
|
3088
|
+
- **Constraints:** the field composes onto a Heightfield; construct the terrain first and let this own the surface · zero depth is bare ground: contacts register no indentation at all · out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros
|
|
3089
|
+
- **Requires:** @threenative/core/world Heightfield as the canonical terrain and surface
|
|
3090
|
+
- **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
|
|
3091
|
+
|
|
3092
|
+
```ts
|
|
3093
|
+
import { Heightfield } from "@threenative/core/world";
|
|
3094
|
+
const terrain = Heightfield.fromSampler({ rows: 129, columns: 129, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: (x, z) => Math.sin(x * 0.1) * 0.5 });
|
|
3095
|
+
const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
|
|
3096
|
+
snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
|
|
3097
|
+
snow.recover(1 / 60, 0.0012, 0.4);
|
|
3098
|
+
```
|
|
3099
|
+
|
|
2932
3100
|
### `TerrainTiles`
|
|
2933
3101
|
|
|
2934
3102
|
`class` — Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.
|
|
@@ -2939,7 +3107,7 @@ export class TerrainTiles extends Object3D implements IComputeDriven { … }
|
|
|
2939
3107
|
|
|
2940
3108
|
- **Use when:** stream terrain without cracks · keep generated terrain resident around a moving player · put a generated terrain tile into a game-owned physics world
|
|
2941
3109
|
- **Constraints:** sampleHeight and surface are required game choices; no landform or surface preset is installed · residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws · seam gap, LOD pop and the rendered-vertex finiteness scan are measurements that are off by default; TN_TERRAIN_VALIDATE=1, ?tnTerrainValidate=1 or validate: true runs them, and maxSeamGap, maxVisualSeamGap and maxLodPop report undefined while they are off
|
|
2942
|
-
- **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets
|
|
3110
|
+
- **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets
|
|
2943
3111
|
|
|
2944
3112
|
```ts
|
|
2945
3113
|
const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
|
|
@@ -2980,15 +3148,15 @@ const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer
|
|
|
2980
3148
|
|
|
2981
3149
|
### `WorldCells`
|
|
2982
3150
|
|
|
2983
|
-
`class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, per-asset `maxDistance` filtering, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset
|
|
3151
|
+
`class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.
|
|
2984
3152
|
|
|
2985
3153
|
```ts
|
|
2986
3154
|
export class WorldCells extends Group implements IComputeDriven { … }
|
|
2987
3155
|
```
|
|
2988
3156
|
|
|
2989
3157
|
- **Use when:** stream a large Blender-authored world by cell instead of one huge GLB · keep scattered props and hand-placed chunks resident around a moving player · honour per-asset draw distances and hard streaming budgets without a mid-frame throw
|
|
2990
|
-
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with authored `lods` never consults it · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
|
|
2991
|
-
- **Overrides:** ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
|
|
3158
|
+
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts · eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
|
|
3159
|
+
- **Overrides:** `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
|
|
2992
3160
|
|
|
2993
3161
|
```ts
|
|
2994
3162
|
const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
|
|
@@ -3094,12 +3262,47 @@ export class Area3D { … }
|
|
|
3094
3262
|
|
|
3095
3263
|
- **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
|
|
3096
3264
|
- **Constraints:** add the area to the physics context before stepping the world
|
|
3265
|
+
- **Requires:** npm i @threenative/physics
|
|
3097
3266
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated.
|
|
3098
3267
|
|
|
3099
3268
|
```ts
|
|
3100
3269
|
const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });
|
|
3101
3270
|
```
|
|
3102
3271
|
|
|
3272
|
+
### `attachSnowPhysics`
|
|
3273
|
+
|
|
3274
|
+
`function` — Drive a `SnowField` from real solved contacts. The binding creates the snow surface collider from the field's own canonical samples and keeps it in step with them, so a body lands on the surface a query would report. Each fixed step it reads the solver's persistent contacts — not collision start/stop events, which carry no point or load — deforms the snow only where a contact is supported and loaded downward, then republishes the surface before the next step. Airborne bodies, side contacts and unrelated colliders never deform anything. A dropped sphere settles on the surface it made; a pushed one rotates and carves a connected track without its transform being copied anywhere. Footprints come from the body's own collision shape and orientation unless the game supplies one. Contact load is `impulse / deltaTime * loadScale`: a solver impulse over a step, which estimates a contact force and is not measured. `observe().loadProvenance` says so.
|
|
3275
|
+
|
|
3276
|
+
```ts
|
|
3277
|
+
export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }
|
|
3278
|
+
```
|
|
3279
|
+
|
|
3280
|
+
- **Use when:** leave footprints and tracks where physical bodies actually touch snow · let a dropped or pushed sphere carve and settle into deformable snow · make a crate, capsule or ball compress the surface it rests on
|
|
3281
|
+
- **Constraints:** register `rapier()` before attaching, and call `step` once per fixed step after the physics step · the backend must expose persistent solved contacts and in-place shape refresh; one that does not fails at attach · verified on browser WebGPU and the native Linux desktop host; Android and iOS share the native seam but have not run it · automatic profiles cover sphere, box and capsule; any other shape needs an explicit footprint
|
|
3282
|
+
- **Requires:** @threenative/core/world SnowField as the surface it deforms
|
|
3283
|
+
- **Overrides:** loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour
|
|
3284
|
+
|
|
3285
|
+
```ts
|
|
3286
|
+
const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });
|
|
3287
|
+
afterPhysics(ctx, (dt) => snowPhysics.step(dt));
|
|
3288
|
+
```
|
|
3289
|
+
|
|
3290
|
+
### `boxFootprint`
|
|
3291
|
+
|
|
3292
|
+
`function` — A rectangular contact: the face a box rests on, in the contact's own frame. Coverage is full across the face and fades just outside it; the bank rises beyond that.
|
|
3293
|
+
|
|
3294
|
+
```ts
|
|
3295
|
+
export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }
|
|
3296
|
+
```
|
|
3297
|
+
|
|
3298
|
+
- **Use when:** let a crate, platform or plank press a rectangular pit into snow · imprint a box's own footprint rather than a circle around it
|
|
3299
|
+
- **Constraints:** halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint
|
|
3300
|
+
- **Requires:** npm i @threenative/physics
|
|
3301
|
+
|
|
3302
|
+
```ts
|
|
3303
|
+
const footprint = boxFootprint(0.4, 0.25);
|
|
3304
|
+
```
|
|
3305
|
+
|
|
3103
3306
|
### `buildStaticColliders`
|
|
3104
3307
|
|
|
3105
3308
|
`function` — Build fixed trimesh bodies from the meshes a game authored in a scene root.
|
|
@@ -3110,6 +3313,7 @@ export function buildStaticColliders( context: IStaticColliderContext, root: Obj
|
|
|
3110
3313
|
|
|
3111
3314
|
- **Use when:** make the level I built stop the player · turn a cathedral or map scene into static collision
|
|
3112
3315
|
- **Constraints:** supply the game-owned predicate for decorative meshes; the helper throws when it selects nothing · generated bodies use trimesh geometry and world-space instance transforms
|
|
3316
|
+
- **Requires:** npm i @threenative/physics
|
|
3113
3317
|
|
|
3114
3318
|
```ts
|
|
3115
3319
|
const colliders = buildStaticColliders(ctx, level, { predicate: (object) => object.name.startsWith("wall") });
|
|
@@ -3125,12 +3329,29 @@ export class Buoyancy3D { … }
|
|
|
3125
3329
|
|
|
3126
3330
|
- **Use when:** float a boat on waves · keep a hull above a moving water surface
|
|
3127
3331
|
- **Constraints:** supply hull points, density, drag, and the height source
|
|
3332
|
+
- **Requires:** npm i @threenative/physics
|
|
3128
3333
|
- **Overrides:** buoyancy disables force application while submergedFraction remains measured
|
|
3129
3334
|
|
|
3130
3335
|
```ts
|
|
3131
3336
|
new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
|
|
3132
3337
|
```
|
|
3133
3338
|
|
|
3339
|
+
### `capsuleFootprint`
|
|
3340
|
+
|
|
3341
|
+
`function` — A stadium contact: a rectangle of half-length `halfHeight` and half-width `radius`, capped by two half-discs of `radius`. The shape a capsule lies on, so a knocked-over body sinks along a line instead of at a point. Coverage is full across the body's own width and fades just outside it, so the body's edge never rests on a half-pressed rim; the bank rises beyond that.
|
|
3342
|
+
|
|
3343
|
+
```ts
|
|
3344
|
+
export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }
|
|
3345
|
+
```
|
|
3346
|
+
|
|
3347
|
+
- **Use when:** let a fallen capsule, limb or barrel leave a linear imprint in snow · give a capsule a shape-appropriate snow contact instead of a sphere's dot
|
|
3348
|
+
- **Constraints:** radius and halfHeight are metres and never grow with load
|
|
3349
|
+
- **Requires:** npm i @threenative/physics
|
|
3350
|
+
|
|
3351
|
+
```ts
|
|
3352
|
+
const footprint = capsuleFootprint(0.5, 0.2);
|
|
3353
|
+
```
|
|
3354
|
+
|
|
3134
3355
|
### `CharacterBody3D`
|
|
3135
3356
|
|
|
3136
3357
|
`class` — Move a character body with collision-aware sliding.
|
|
@@ -3141,6 +3362,7 @@ export class CharacterBody3D { … }
|
|
|
3141
3362
|
|
|
3142
3363
|
- **Use when:** move an enemy or player through a level · keep a character from walking through walls
|
|
3143
3364
|
- **Constraints:** use moveAndSlide inside the physics update
|
|
3365
|
+
- **Requires:** npm i @threenative/physics
|
|
3144
3366
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
|
|
3145
3367
|
|
|
3146
3368
|
```ts
|
|
@@ -3157,6 +3379,7 @@ export class CollisionShape3D { … }
|
|
|
3157
3379
|
|
|
3158
3380
|
- **Use when:** add a capsule or box collider to a character · configure the shape used by a rigid body
|
|
3159
3381
|
- **Constraints:** create shapes through the owning physics context
|
|
3382
|
+
- **Requires:** npm i @threenative/physics
|
|
3160
3383
|
|
|
3161
3384
|
```ts
|
|
3162
3385
|
const shape = CollisionShape3D.capsule(0.5, 0.35);
|
|
@@ -3171,6 +3394,7 @@ export function interactionGroups(layer: number, mask: number): number { … }
|
|
|
3171
3394
|
```
|
|
3172
3395
|
|
|
3173
3396
|
- **Use when:** make an enemy collide with the world but not pickups · configure which physics layers interact
|
|
3397
|
+
- **Requires:** npm i @threenative/physics
|
|
3174
3398
|
|
|
3175
3399
|
```ts
|
|
3176
3400
|
const groups = interactionGroups(1, 3);
|
|
@@ -3186,6 +3410,7 @@ export class Joint3D { … }
|
|
|
3186
3410
|
|
|
3187
3411
|
- **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism · swing a pendulum, wrecking ball, or hinged door on a joint
|
|
3188
3412
|
- **Constraints:** both bodies must belong to the same physics context
|
|
3413
|
+
- **Requires:** npm i @threenative/physics
|
|
3189
3414
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated.
|
|
3190
3415
|
|
|
3191
3416
|
```ts
|
|
@@ -3202,6 +3427,7 @@ export class PhysicsDirectSpaceState3D { … }
|
|
|
3202
3427
|
|
|
3203
3428
|
- **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
|
|
3204
3429
|
- **Constraints:** query results are bounded by the configured result limit
|
|
3430
|
+
- **Requires:** npm i @threenative/physics
|
|
3205
3431
|
|
|
3206
3432
|
```ts
|
|
3207
3433
|
const space = new PhysicsDirectSpaceState3D(context);
|
|
@@ -3217,6 +3443,7 @@ export function rapier(options: IPhysicsOptions = { … }
|
|
|
3217
3443
|
|
|
3218
3444
|
- **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
|
|
3219
3445
|
- **Constraints:** place rapier() before recast() in the plugin list
|
|
3446
|
+
- **Requires:** npm i @threenative/physics
|
|
3220
3447
|
|
|
3221
3448
|
```ts
|
|
3222
3449
|
const game = defineGame({ plugins: [rapier()] });
|
|
@@ -3232,6 +3459,7 @@ export class RigidBody3D { … }
|
|
|
3232
3459
|
|
|
3233
3460
|
- **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
|
|
3234
3461
|
- **Constraints:** register rapier() in the game plugin list before using bodies
|
|
3462
|
+
- **Requires:** npm i @threenative/physics
|
|
3235
3463
|
- **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
|
|
3236
3464
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated.
|
|
3237
3465
|
|
|
@@ -3249,6 +3477,7 @@ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyC
|
|
|
3249
3477
|
|
|
3250
3478
|
- **Use when:** stop a cloth flag, cape, or curtain at an existing physics wall · collide SoftBody3D with fixed box bodies
|
|
3251
3479
|
- **Constraints:** every body must use CollisionShape3D.box and retain its Three.js object transform · rotated boxes become conservative cloth-local axis-aligned bounds
|
|
3480
|
+
- **Requires:** npm i @threenative/physics
|
|
3252
3481
|
|
|
3253
3482
|
```ts
|
|
3254
3483
|
const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
|
|
@@ -3264,6 +3493,7 @@ export class VehicleBody3D extends RigidBody3D { … }
|
|
|
3264
3493
|
|
|
3265
3494
|
- **Use when:** drive a car, truck or bike around a track · make a vehicle roll over kerbs, brake into a corner or stop at a wall
|
|
3266
3495
|
- **Constraints:** write engineForce, brake and steering every physics update; a car with no input does not move · suspensionStiffness is a frequency squared, not newtons per metre; 100 is a road car and 20 bottoms out
|
|
3496
|
+
- **Requires:** npm i @threenative/physics
|
|
3267
3497
|
- **Overrides:** a wheel ray never hits the chassis it hangs from, and it honours the chassis collision mask · continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall
|
|
3268
3498
|
|
|
3269
3499
|
```ts
|
|
@@ -3282,6 +3512,7 @@ export class NavigationAgent3D { … }
|
|
|
3282
3512
|
|
|
3283
3513
|
- **Use when:** enemy walks around a wall · enemy patrols a level and chases the player · enemy walks around a patrol path and chases the player when it sees them · enemy patrols and chases while avoiding obstacles · enemy chases the player with line of sight and obstacle avoidance · NPC walks to a destination · move crew around a ship deck
|
|
3284
3514
|
- **Constraints:** import NavigationAgent3D from exactly `@threenative/physics/navigation`; `@threenative/physics` is not a valid import for this symbol; use this capability instead of hand-written A*; requires recast() after rapier(), plus a baked NavigationRegion3D
|
|
3515
|
+
- **Requires:** npm i @threenative/physics
|
|
3285
3516
|
|
|
3286
3517
|
```ts
|
|
3287
3518
|
import { NavigationAgent3D } from "@threenative/physics/navigation";
|
|
@@ -3302,6 +3533,7 @@ export class NavigationObstacle3D { … }
|
|
|
3302
3533
|
|
|
3303
3534
|
- **Use when:** keep navigation agents away from a blocking prop · make a stationary character affect crowd avoidance
|
|
3304
3535
|
- **Constraints:** create it after recast() and dispose it with the scene
|
|
3536
|
+
- **Requires:** npm i @threenative/physics
|
|
3305
3537
|
|
|
3306
3538
|
```ts
|
|
3307
3539
|
const obstacle = new NavigationObstacle3D({ navigation, object });
|
|
@@ -3317,6 +3549,7 @@ export class NavigationRegion3D { … }
|
|
|
3317
3549
|
|
|
3318
3550
|
- **Use when:** let enemies walk around level geometry · create the baked navmesh required by NavigationAgent3D
|
|
3319
3551
|
- **Constraints:** bake before creating agents or obstacles
|
|
3552
|
+
- **Requires:** npm i @threenative/physics
|
|
3320
3553
|
|
|
3321
3554
|
```ts
|
|
3322
3555
|
const region = new NavigationRegion3D({ navigation, meshes: [floor] });
|
|
@@ -3332,6 +3565,7 @@ export function recast(): NavigationPlugin { … }
|
|
|
3332
3565
|
|
|
3333
3566
|
- **Use when:** enemy walks around a wall · NPC patrols a level and chases a player
|
|
3334
3567
|
- **Constraints:** requires rapier() earlier in the plugins array
|
|
3568
|
+
- **Requires:** npm i @threenative/physics
|
|
3335
3569
|
|
|
3336
3570
|
```ts
|
|
3337
3571
|
const game = defineGame({ plugins: [rapier(), recast()] });
|
|
@@ -3674,6 +3908,21 @@ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrame
|
|
|
3674
3908
|
assertCaptureNotBlank(png, "first frame");
|
|
3675
3909
|
```
|
|
3676
3910
|
|
|
3911
|
+
### `assertDesktopCaptureNotBlank`
|
|
3912
|
+
|
|
3913
|
+
`function` — Fail closed when a desktop-host frame shows no rendered content. A native desktop frame has no HTML overlay, so the browser bright-pixel floor does not apply.
|
|
3914
|
+
|
|
3915
|
+
```ts
|
|
3916
|
+
export function assertDesktopCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }
|
|
3917
|
+
```
|
|
3918
|
+
|
|
3919
|
+
- **Use when:** guard a native desktop capture of a 3D scene
|
|
3920
|
+
- **Constraints:** keeps the uniform-frame checks and replaces only the bright-pixel floor
|
|
3921
|
+
|
|
3922
|
+
```ts
|
|
3923
|
+
assertDesktopCaptureNotBlank(png, "panned-culled.png");
|
|
3924
|
+
```
|
|
3925
|
+
|
|
3677
3926
|
### `assertFrameShowsSomething`
|
|
3678
3927
|
|
|
3679
3928
|
`function` — Fail closed when a screenshot is blank or uniform.
|
|
@@ -3703,6 +3952,21 @@ export class CaptureGuardError extends Error { … }
|
|
|
3703
3952
|
throw new CaptureGuardError("menu", "no bright pixels");
|
|
3704
3953
|
```
|
|
3705
3954
|
|
|
3955
|
+
### `collectRegionalTone`
|
|
3956
|
+
|
|
3957
|
+
`function` — Collect opt-in regional tone observations from the same acquired PNG.
|
|
3958
|
+
|
|
3959
|
+
```ts
|
|
3960
|
+
export function collectRegionalTone( png: Buffer, assertions: readonly IPlaytestToneAssertion[], label: string, atStep?: string, ): IPlaytestRegionalToneObservation[] { … }
|
|
3961
|
+
```
|
|
3962
|
+
|
|
3963
|
+
- **Use when:** measure a specified pixel crop in a captured playtest frame
|
|
3964
|
+
- **Constraints:** does not acquire another screenshot or alter frame timing
|
|
3965
|
+
|
|
3966
|
+
```ts
|
|
3967
|
+
collectRegionalTone(png, assertions, "character", "posed");
|
|
3968
|
+
```
|
|
3969
|
+
|
|
3706
3970
|
### `inspectFrame`
|
|
3707
3971
|
|
|
3708
3972
|
`function` — Inspect a PNG frame for visible pixels and luminance variation.
|
|
@@ -3748,6 +4012,21 @@ export function jsonByteLength(value: JsonValue): number { … }
|
|
|
3748
4012
|
const bytes = jsonByteLength(observation);
|
|
3749
4013
|
```
|
|
3750
4014
|
|
|
4015
|
+
### `requestedPlaytestClockMode`
|
|
4016
|
+
|
|
4017
|
+
`function` — The clock the host asked for, or `undefined` for the default deterministic run. `wall-clock` is the production profile's opt-in and the only one this protocol has. An unrecognised value throws instead of falling back, because a misspelling that quietly left the loop frozen would publish a frame rate for a game that was not playing. Read at the moment it is needed rather than once at install: a request that arrives after the producer was installed is still a request, and a producer that missed it would judge a live frame pump by a count it never asked for.
|
|
4018
|
+
|
|
4019
|
+
```ts
|
|
4020
|
+
export function requestedPlaytestClockMode(): PlaytestClockMode | undefined { … }
|
|
4021
|
+
```
|
|
4022
|
+
|
|
4023
|
+
- **Use when:** report which clock a playtest producer is really running on, before judging its ticks
|
|
4024
|
+
- **Constraints:** throws on an unrecognised value instead of falling back to a fixed-step run
|
|
4025
|
+
|
|
4026
|
+
```ts
|
|
4027
|
+
if (requestedPlaytestClockMode() === "wall-clock") host.pumpDrivesTheSimulation();
|
|
4028
|
+
```
|
|
4029
|
+
|
|
3751
4030
|
## `@threenative/playtest/runner`
|
|
3752
4031
|
|
|
3753
4032
|
### `AdbAndroidDriver`
|
|
@@ -3770,7 +4049,7 @@ const adb = discoverAdb(process.env);
|
|
|
3770
4049
|
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
3771
4050
|
|
|
3772
4051
|
```ts
|
|
3773
|
-
export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, ): Promise<void> { … }
|
|
4052
|
+
export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, render = false, ): Promise<void> { … }
|
|
3774
4053
|
```
|
|
3775
4054
|
|
|
3776
4055
|
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
@@ -3947,6 +4226,21 @@ const lane = decideDisplayStrategy({ env: process.env, platform: "linux" });
|
|
|
3947
4226
|
if (lane.kind === "private-xvfb") throw new Error("refuse to judge this frame rate");
|
|
3948
4227
|
```
|
|
3949
4228
|
|
|
4229
|
+
### `desktopConsoleType`
|
|
4230
|
+
|
|
4231
|
+
`function` — Drive a local desktop playtest mailbox.
|
|
4232
|
+
|
|
4233
|
+
```ts
|
|
4234
|
+
export function desktopConsoleType(stream: "stderr" | "stdout", line: string): string { … }
|
|
4235
|
+
```
|
|
4236
|
+
|
|
4237
|
+
- **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
|
|
4238
|
+
- **Constraints:** the mailbox lifecycle must be disposed after the run
|
|
4239
|
+
|
|
4240
|
+
```ts
|
|
4241
|
+
const driver = new DesktopPlaytestDriver(options);
|
|
4242
|
+
```
|
|
4243
|
+
|
|
3950
4244
|
### `DesktopPlaytestDriver`
|
|
3951
4245
|
|
|
3952
4246
|
`class` — Drive a local desktop playtest mailbox.
|
|
@@ -4869,6 +5163,122 @@ export class ThreePlaytestPhysicsRecorder { … }
|
|
|
4869
5163
|
const physics = new ThreePlaytestPhysicsRecorder(worldPhysics);
|
|
4870
5164
|
```
|
|
4871
5165
|
|
|
5166
|
+
## `@threenative/procedural-animals`
|
|
5167
|
+
|
|
5168
|
+
### `createAnimalActor`
|
|
5169
|
+
|
|
5170
|
+
`function` — Own one actor's pose/lifetime, accepting the completed physics state as its only root writer.
|
|
5171
|
+
|
|
5172
|
+
```ts
|
|
5173
|
+
export function createAnimalActor(bake: IAnimalBake, options: IAnimalActorOptions) { … }
|
|
5174
|
+
```
|
|
5175
|
+
|
|
5176
|
+
- **Use when:** follow a baked animal from accepted fixed-step Rapier state
|
|
5177
|
+
- **Constraints:** identity parent required; material and motion are editable game source; no move/Mixer/composer writer exists
|
|
5178
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5179
|
+
|
|
5180
|
+
```ts
|
|
5181
|
+
const wolf = createAnimalActor(bake, { motion, material, ground });
|
|
5182
|
+
```
|
|
5183
|
+
|
|
5184
|
+
### `createAnimalGeometry`
|
|
5185
|
+
|
|
5186
|
+
`function` — Validates all bytes before constructing geometry with the bake's skin and rig attributes.
|
|
5187
|
+
|
|
5188
|
+
```ts
|
|
5189
|
+
export function createAnimalGeometry(buffer: ArrayBuffer): { … }
|
|
5190
|
+
```
|
|
5191
|
+
|
|
5192
|
+
- **Use when:** construct a Three.js geometry from a validated procedural wolf bake
|
|
5193
|
+
- **Constraints:** this creates bind geometry only; game-owned DQS material and animated bounds remain required
|
|
5194
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5195
|
+
|
|
5196
|
+
```ts
|
|
5197
|
+
const { bake, geometry } = createAnimalGeometry(bytes);
|
|
5198
|
+
```
|
|
5199
|
+
|
|
5200
|
+
### `loadAnimalBake`
|
|
5201
|
+
|
|
5202
|
+
`function` — Resolves and loads a prebuilt wolf through the game's ordinary asset resolver.
|
|
5203
|
+
|
|
5204
|
+
```ts
|
|
5205
|
+
export async function loadAnimalBake( assets: IAnimalAssetResolver, logicalPath: string, options: { … }
|
|
5206
|
+
```
|
|
5207
|
+
|
|
5208
|
+
- **Use when:** load a cooked animal from ctx.assets without runtime generation
|
|
5209
|
+
- **Constraints:** a corrupt served bake rejects rather than falling back to a different file
|
|
5210
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5211
|
+
|
|
5212
|
+
```ts
|
|
5213
|
+
const bake = await loadAnimalBake(ctx.assets, "wolf.animal");
|
|
5214
|
+
```
|
|
5215
|
+
|
|
5216
|
+
### `parseAnimalBake`
|
|
5217
|
+
|
|
5218
|
+
`function` — Validates a pinned wolf PANM bake before constructing any renderer resource.
|
|
5219
|
+
|
|
5220
|
+
```ts
|
|
5221
|
+
export function parseAnimalBake(buffer: ArrayBuffer): IAnimalBake { … }
|
|
5222
|
+
```
|
|
5223
|
+
|
|
5224
|
+
- **Use when:** validate a baked procedural animal before allocating geometry
|
|
5225
|
+
- **Constraints:** unknown revisions, malformed sections, indices and skin weights throw by name
|
|
5226
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5227
|
+
|
|
5228
|
+
```ts
|
|
5229
|
+
const bake = parseAnimalBake(bytes);
|
|
5230
|
+
```
|
|
5231
|
+
|
|
5232
|
+
## `@threenative/procedural-animals/build`
|
|
5233
|
+
|
|
5234
|
+
### `animalBakePass`
|
|
5235
|
+
|
|
5236
|
+
`function` — Validate staged PANM sources inside the existing asset compiler; it owns the hashed manifest.
|
|
5237
|
+
|
|
5238
|
+
```ts
|
|
5239
|
+
export function animalBakePass() { … }
|
|
5240
|
+
```
|
|
5241
|
+
|
|
5242
|
+
- **Use when:** cook staged animal bakes through the ordinary asset pipeline
|
|
5243
|
+
- **Constraints:** only .animal inputs are interpreted; corruption fails the cook, without regeneration
|
|
5244
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5245
|
+
|
|
5246
|
+
```ts
|
|
5247
|
+
await compileAssets({ passes: [animalBakePass()] });
|
|
5248
|
+
```
|
|
5249
|
+
|
|
5250
|
+
### `bakeWolf`
|
|
5251
|
+
|
|
5252
|
+
`function` — Bake the pinned wolf on the build machine, never on the portable runtime path.
|
|
5253
|
+
|
|
5254
|
+
```ts
|
|
5255
|
+
export async function bakeWolf(options: IWolfBakeOptions): Promise<ArrayBuffer> { … }
|
|
5256
|
+
```
|
|
5257
|
+
|
|
5258
|
+
- **Use when:** bake high and crowd wolf geometry before the ordinary asset cook
|
|
5259
|
+
- **Constraints:** exact pinned Node runtime, donor revision, options and generated bytes are validated; no worker is created
|
|
5260
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5261
|
+
|
|
5262
|
+
```ts
|
|
5263
|
+
const bytes = await bakeWolf({ seed: 7, tier: "crowd" });
|
|
5264
|
+
```
|
|
5265
|
+
|
|
5266
|
+
### `bakeWolfToFile`
|
|
5267
|
+
|
|
5268
|
+
`function` — Stage a validated source bake with a same-directory atomic rename, then use compileAssets.
|
|
5269
|
+
|
|
5270
|
+
```ts
|
|
5271
|
+
export async function bakeWolfToFile( options: IWolfBakeOptions, destination: string, ): Promise<string> { … }
|
|
5272
|
+
```
|
|
5273
|
+
|
|
5274
|
+
- **Use when:** publish a generated wolf without replacing the last valid bake on interruption
|
|
5275
|
+
- **Constraints:** validation and generation complete before the destination is touched; temporary files are removed on failure
|
|
5276
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5277
|
+
|
|
5278
|
+
```ts
|
|
5279
|
+
await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
|
|
5280
|
+
```
|
|
5281
|
+
|
|
4872
5282
|
## `@threenative/raw-unreal`
|
|
4873
5283
|
|
|
4874
5284
|
### `createThreeGeometry`
|
|
@@ -5258,82 +5668,825 @@ function sparkle
|
|
|
5258
5668
|
sparkle(...)
|
|
5259
5669
|
```
|
|
5260
5670
|
|
|
5261
|
-
## `@threenative/
|
|
5671
|
+
## `@threenative/terrain`
|
|
5262
5672
|
|
|
5263
|
-
### `
|
|
5673
|
+
### `applyPlacementOverrides`
|
|
5264
5674
|
|
|
5265
|
-
`function` —
|
|
5675
|
+
`function` — Attach manual transforms to raw evaluated candidates and report orphan keys.
|
|
5266
5676
|
|
|
5267
5677
|
```ts
|
|
5268
|
-
export function
|
|
5678
|
+
export function applyPlacementOverrides(state: ITerrainState, value: unknown): ITerrainState { … }
|
|
5269
5679
|
```
|
|
5270
5680
|
|
|
5271
|
-
- **Use when:**
|
|
5272
|
-
- **Constraints:**
|
|
5273
|
-
- **Requires:** npm i @threenative/
|
|
5681
|
+
- **Use when:** retain manual prop transforms across terrain scatter re-evaluation
|
|
5682
|
+
- **Constraints:** headless authoring; game applies transforms against its model bounds and actual terrain surface
|
|
5683
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
5684
|
+
- **Overrides:** transform.grounding=false preserves requested Y while the game still measures clearance
|
|
5274
5685
|
|
|
5275
5686
|
```ts
|
|
5276
|
-
const
|
|
5687
|
+
const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
|
|
5277
5688
|
```
|
|
5278
5689
|
|
|
5279
|
-
### `
|
|
5690
|
+
### `bakeMesh`
|
|
5280
5691
|
|
|
5281
|
-
`function` —
|
|
5692
|
+
`function` — Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
|
|
5282
5693
|
|
|
5283
5694
|
```ts
|
|
5284
|
-
export function
|
|
5695
|
+
export function bakeMesh( state: ITerrainState, { … }
|
|
5285
5696
|
```
|
|
5286
5697
|
|
|
5287
|
-
- **Use when:**
|
|
5288
|
-
- **Constraints:**
|
|
5289
|
-
- **Requires:** npm i @threenative/
|
|
5698
|
+
- **Use when:** bake an authored terrain into portable indexed mesh arrays
|
|
5699
|
+
- **Constraints:** no material is chosen; vertex colours exist only with a caller-supplied palette
|
|
5700
|
+
- **Requires:** npm i @threenative/terrain
|
|
5701
|
+
- **Overrides:** step, chunk bounds, skirtDepth and palette belong to the caller
|
|
5290
5702
|
|
|
5291
5703
|
```ts
|
|
5292
|
-
const
|
|
5704
|
+
const mesh = bakeMesh(new Terrain({ resolution: 17 }).evaluate());
|
|
5293
5705
|
```
|
|
5294
5706
|
|
|
5295
|
-
### `
|
|
5707
|
+
### `bakeTerrain`
|
|
5296
5708
|
|
|
5297
|
-
`function` —
|
|
5709
|
+
`function` — Bakes finite LOD chunks, the same collision samples and resolved placements.
|
|
5298
5710
|
|
|
5299
5711
|
```ts
|
|
5300
|
-
export function
|
|
5712
|
+
export function bakeTerrain( state: ITerrainState, { … }
|
|
5301
5713
|
```
|
|
5302
5714
|
|
|
5303
|
-
- **Use when:**
|
|
5304
|
-
- **Constraints:**
|
|
5305
|
-
- **Requires:** npm i @threenative/
|
|
5715
|
+
- **Use when:** prepare terrain arrays and collision before a game starts
|
|
5716
|
+
- **Constraints:** collision origin is the southwest corner; engine Heightfield origin is its centre
|
|
5717
|
+
- **Requires:** npm i @threenative/terrain
|
|
5718
|
+
- **Overrides:** chunkCells, lodSteps, skirtDepth and palette are explicit authoring choices
|
|
5306
5719
|
|
|
5307
5720
|
```ts
|
|
5308
|
-
const
|
|
5721
|
+
const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCells: 64 });
|
|
5309
5722
|
```
|
|
5310
5723
|
|
|
5311
|
-
### `
|
|
5724
|
+
### `bakeWorldPackage`
|
|
5312
5725
|
|
|
5313
|
-
`function` —
|
|
5726
|
+
`function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
|
|
5314
5727
|
|
|
5315
5728
|
```ts
|
|
5316
|
-
export function
|
|
5729
|
+
export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }
|
|
5317
5730
|
```
|
|
5318
5731
|
|
|
5319
|
-
- **Use when:**
|
|
5320
|
-
- **Constraints:**
|
|
5321
|
-
- **Requires:** npm i @threenative/
|
|
5732
|
+
- **Use when:** hand an evaluated Strata terrain to a game without a Blender round trip
|
|
5733
|
+
- **Constraints:** headless authoring; no three, no DOM, and nothing here decides how the world looks
|
|
5734
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
5735
|
+
- **Overrides:** every asset path, bound, LOD distance and cell size comes from the caller's options
|
|
5322
5736
|
|
|
5323
5737
|
```ts
|
|
5324
|
-
const
|
|
5738
|
+
const { manifest, files } = bakeWorldPackage(state, { assets });
|
|
5325
5739
|
```
|
|
5326
5740
|
|
|
5327
|
-
### `
|
|
5741
|
+
### `createSegmentIndex`
|
|
5328
5742
|
|
|
5329
|
-
`
|
|
5743
|
+
`function` — Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
|
|
5330
5744
|
|
|
5331
5745
|
```ts
|
|
5332
|
-
export
|
|
5746
|
+
export function createSegmentIndex<T>( segments: readonly IWaterSegment<T>[], cellSize: number, ): ISegmentIndex<T> { … }
|
|
5333
5747
|
```
|
|
5334
5748
|
|
|
5335
|
-
- **Use when:**
|
|
5336
|
-
- **Constraints:**
|
|
5749
|
+
- **Use when:** test scatter candidates or terrain vertices against rivers and lakes without scanning every segment · find which river stations can reach a heightfield vertex when baking a wet margin
|
|
5750
|
+
- **Constraints:** returns candidates only; the caller applies its own exact distance and level test
|
|
5751
|
+
- **Requires:** npm i @threenative/terrain
|
|
5752
|
+
|
|
5753
|
+
```ts
|
|
5754
|
+
const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);
|
|
5755
|
+
```
|
|
5756
|
+
|
|
5757
|
+
### `decodeHeightPNG`
|
|
5758
|
+
|
|
5759
|
+
`function` — CRC-checked bounded non-interlaced grayscale PNG height decoder.
|
|
5760
|
+
|
|
5761
|
+
```ts
|
|
5762
|
+
export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options: IDecodeHeightPngOptions = { … }
|
|
5763
|
+
```
|
|
5764
|
+
|
|
5765
|
+
- **Use when:** import numerical PNG8 or PNG16 terrain elevations
|
|
5766
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5767
|
+
- **Requires:** npm i @threenative/terrain
|
|
5768
|
+
|
|
5769
|
+
```ts
|
|
5770
|
+
const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);
|
|
5771
|
+
```
|
|
5772
|
+
|
|
5773
|
+
### `decodeRAW16`
|
|
5774
|
+
|
|
5775
|
+
`function` — Validates dimensions and range before decoding numerical height samples.
|
|
5776
|
+
|
|
5777
|
+
```ts
|
|
5778
|
+
export function decodeRAW16( input: Uint8Array | ArrayBuffer, { … }
|
|
5779
|
+
```
|
|
5780
|
+
|
|
5781
|
+
- **Use when:** import a RAW16 terrain height buffer with explicit dimensions
|
|
5782
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5783
|
+
- **Requires:** npm i @threenative/terrain
|
|
5784
|
+
|
|
5785
|
+
```ts
|
|
5786
|
+
const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });
|
|
5787
|
+
```
|
|
5788
|
+
|
|
5789
|
+
### `encodeGLB`
|
|
5790
|
+
|
|
5791
|
+
`function` — Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.
|
|
5792
|
+
|
|
5793
|
+
```ts
|
|
5794
|
+
export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }
|
|
5795
|
+
```
|
|
5796
|
+
|
|
5797
|
+
- **Use when:** export baked terrain geometry without engine extensions
|
|
5798
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5799
|
+
- **Requires:** npm i @threenative/terrain
|
|
5800
|
+
|
|
5801
|
+
```ts
|
|
5802
|
+
const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
|
|
5803
|
+
```
|
|
5804
|
+
|
|
5805
|
+
### `encodeHeightPNG`
|
|
5806
|
+
|
|
5807
|
+
`function` — Encodes numerical grayscale PNG16 with embedded elevation range.
|
|
5808
|
+
|
|
5809
|
+
```ts
|
|
5810
|
+
export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }
|
|
5811
|
+
```
|
|
5812
|
+
|
|
5813
|
+
- **Use when:** export a terrain heightmap without an eight-bit colour conversion
|
|
5814
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5815
|
+
- **Requires:** npm i @threenative/terrain
|
|
5816
|
+
|
|
5817
|
+
```ts
|
|
5818
|
+
const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());
|
|
5819
|
+
```
|
|
5820
|
+
|
|
5821
|
+
### `encodeRAW16`
|
|
5822
|
+
|
|
5823
|
+
`function` — Encodes finite metre elevations as an explicit-range RAW16 buffer.
|
|
5824
|
+
|
|
5825
|
+
```ts
|
|
5826
|
+
export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }
|
|
5827
|
+
```
|
|
5828
|
+
|
|
5829
|
+
- **Use when:** export terrain heights with a numerical range sidecar
|
|
5830
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5831
|
+
- **Requires:** npm i @threenative/terrain
|
|
5832
|
+
|
|
5833
|
+
```ts
|
|
5834
|
+
const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });
|
|
5835
|
+
```
|
|
5836
|
+
|
|
5837
|
+
### `encodeSplatPNGs`
|
|
5838
|
+
|
|
5839
|
+
`function` — Encodes the eight linear material-weight channels as two RGBA images.
|
|
5840
|
+
|
|
5841
|
+
```ts
|
|
5842
|
+
export async function encodeSplatPNGs(state: ITerrainState) { … }
|
|
5843
|
+
```
|
|
5844
|
+
|
|
5845
|
+
- **Use when:** export terrain splat weights as linear data
|
|
5846
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5847
|
+
- **Requires:** npm i @threenative/terrain
|
|
5848
|
+
|
|
5849
|
+
```ts
|
|
5850
|
+
const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());
|
|
5851
|
+
```
|
|
5852
|
+
|
|
5853
|
+
### `encodeZIP`
|
|
5854
|
+
|
|
5855
|
+
`function` — Deterministic store-method ZIP with safe unique relative filenames.
|
|
5856
|
+
|
|
5857
|
+
```ts
|
|
5858
|
+
export function encodeZIP(files: readonly IExportFile[]) { … }
|
|
5859
|
+
```
|
|
5860
|
+
|
|
5861
|
+
- **Use when:** archive derived terrain files without another dependency
|
|
5862
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5863
|
+
- **Requires:** npm i @threenative/terrain
|
|
5864
|
+
|
|
5865
|
+
```ts
|
|
5866
|
+
const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
|
|
5867
|
+
```
|
|
5868
|
+
|
|
5869
|
+
### `gradientAt`
|
|
5870
|
+
|
|
5871
|
+
`function` — World-space height gradient from the canonical samples.
|
|
5872
|
+
|
|
5873
|
+
```ts
|
|
5874
|
+
export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }
|
|
5875
|
+
```
|
|
5876
|
+
|
|
5877
|
+
- **Use when:** measure an authored terrain gradient in metres
|
|
5878
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5879
|
+
- **Requires:** npm i @threenative/terrain
|
|
5880
|
+
|
|
5881
|
+
```ts
|
|
5882
|
+
const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
5883
|
+
```
|
|
5884
|
+
|
|
5885
|
+
### `makeExport`
|
|
5886
|
+
|
|
5887
|
+
`function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
|
|
5888
|
+
|
|
5889
|
+
```ts
|
|
5890
|
+
export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }
|
|
5891
|
+
```
|
|
5892
|
+
|
|
5893
|
+
- **Use when:** export a terrain recipe and its numerical runtime data
|
|
5894
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5895
|
+
- **Requires:** npm i @threenative/terrain
|
|
5896
|
+
|
|
5897
|
+
```ts
|
|
5898
|
+
const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
|
|
5899
|
+
```
|
|
5900
|
+
|
|
5901
|
+
### `sampleHeight`
|
|
5902
|
+
|
|
5903
|
+
`function` — Bilinear query of canonical height samples; triangle sampling is a separate contract.
|
|
5904
|
+
|
|
5905
|
+
```ts
|
|
5906
|
+
sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid( grid.height, grid.resolution, grid.resolution, x / grid.size + 0.5, z / grid.size + 0.5, )
|
|
5907
|
+
```
|
|
5908
|
+
|
|
5909
|
+
- **Use when:** query an authored heightfield at world coordinates
|
|
5910
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5911
|
+
- **Requires:** npm i @threenative/terrain
|
|
5912
|
+
|
|
5913
|
+
```ts
|
|
5914
|
+
const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
5915
|
+
```
|
|
5916
|
+
|
|
5917
|
+
### `slopeAtIndex`
|
|
5918
|
+
|
|
5919
|
+
`function` — Slope in degrees at a heightfield sample.
|
|
5920
|
+
|
|
5921
|
+
```ts
|
|
5922
|
+
export function slopeAtIndex(grid: ISampledGrid, i: number): number { … }
|
|
5923
|
+
```
|
|
5924
|
+
|
|
5925
|
+
- **Use when:** measure terrain slope for authoring diagnostics
|
|
5926
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5927
|
+
- **Requires:** npm i @threenative/terrain
|
|
5928
|
+
|
|
5929
|
+
```ts
|
|
5930
|
+
const slope = slopeAtIndex(new Terrain({ resolution: 17 }).evaluate(), 0);
|
|
5931
|
+
```
|
|
5932
|
+
|
|
5933
|
+
### `slopeQuantile`
|
|
5934
|
+
|
|
5935
|
+
`function` — A slope, in degrees, that the given share of this terrain's interior vertices lie at or below. Placement rules keyed to fixed degrees break when a world is rebaked smoother or rougher: an outcrop rule of "over 30 degrees" placed nothing on a forest whose 98th percentile is 22. Asking the terrain for its own steepest share keeps the rule meaning the same thing on every world.
|
|
5936
|
+
|
|
5937
|
+
```ts
|
|
5938
|
+
export function slopeQuantile(grid: ISampledGrid, quantile: number): number { … }
|
|
5939
|
+
```
|
|
5940
|
+
|
|
5941
|
+
- **Use when:** place rocks or cliffs on a terrain's own steepest ground instead of a fixed slope in degrees
|
|
5942
|
+
- **Constraints:** interior vertices only (edges have one-sided differences); quantile must be in [0, 1]
|
|
5943
|
+
- **Requires:** npm i @threenative/terrain
|
|
5944
|
+
|
|
5945
|
+
```ts
|
|
5946
|
+
const steep = slopeQuantile(grid, 0.98); if (slopeAt(x, z) > Math.min(30, steep)) placeRock(x, z);
|
|
5947
|
+
```
|
|
5948
|
+
|
|
5949
|
+
### `splinePoints`
|
|
5950
|
+
|
|
5951
|
+
`function` — Recovered horizontal Catmull–Rom and vertically linear profile sampler.
|
|
5952
|
+
|
|
5953
|
+
```ts
|
|
5954
|
+
export function splinePoints( points: readonly (readonly [number, number, number])[], step = 3, smooth = true, ): [number, number, number][] { … }
|
|
5955
|
+
```
|
|
5956
|
+
|
|
5957
|
+
- **Use when:** sample a road or river profile without vertical overshoot
|
|
5958
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5959
|
+
- **Requires:** npm i @threenative/terrain
|
|
5960
|
+
|
|
5961
|
+
```ts
|
|
5962
|
+
const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
|
|
5963
|
+
```
|
|
5964
|
+
|
|
5965
|
+
### `Terrain`
|
|
5966
|
+
|
|
5967
|
+
`class` — Ordered, stable-ID terrain authoring with synchronous atomic transactions.
|
|
5968
|
+
|
|
5969
|
+
```ts
|
|
5970
|
+
export class Terrain { … }
|
|
5971
|
+
```
|
|
5972
|
+
|
|
5973
|
+
- **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game
|
|
5974
|
+
- **Constraints:** authoring stays outside the game's steady-play graph; no renderer or physics is created · units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin · `resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025 · `seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays · `evaluate()` is synchronous on the calling thread: run it in a build script, never per frame · no art is chosen or shipped: materials, models and texture paths belong to the game
|
|
5975
|
+
- **Requires:** npm i @threenative/terrain
|
|
5976
|
+
- **Overrides:** size, resolution, seed and all layer parameters are caller choices
|
|
5977
|
+
|
|
5978
|
+
```ts
|
|
5979
|
+
const terrain = new Terrain({ size: 512, resolution: 257, seed: 73 }).noise({ id: "hills", amplitude: 35 });
|
|
5980
|
+
```
|
|
5981
|
+
|
|
5982
|
+
### `TerrainEvaluator`
|
|
5983
|
+
|
|
5984
|
+
`class` — Recovered prefix-caching authoring evaluator. Returned buffers belong to the caller.
|
|
5985
|
+
|
|
5986
|
+
```ts
|
|
5987
|
+
export class TerrainEvaluator { … }
|
|
5988
|
+
```
|
|
5989
|
+
|
|
5990
|
+
- **Use when:** reuse terrain evaluation prefixes while authoring a finite heightfield
|
|
5991
|
+
- **Constraints:** evaluates authoring documents only; games consume pre-baked arrays
|
|
5992
|
+
- **Requires:** npm i @threenative/terrain
|
|
5993
|
+
- **Overrides:** cacheMB bounds retained prefix data
|
|
5994
|
+
|
|
5995
|
+
```ts
|
|
5996
|
+
const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());
|
|
5997
|
+
```
|
|
5998
|
+
|
|
5999
|
+
### `validateDocument`
|
|
6000
|
+
|
|
6001
|
+
`function` — Validates the recovered recipe schema, operation allow-lists and numeric bounds.
|
|
6002
|
+
|
|
6003
|
+
```ts
|
|
6004
|
+
export function validateDocument(doc: ITerrainDocument): void { … }
|
|
6005
|
+
```
|
|
6006
|
+
|
|
6007
|
+
- **Use when:** validate a terrain document before accepting an authoring write
|
|
6008
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
6009
|
+
- **Requires:** npm i @threenative/terrain
|
|
6010
|
+
|
|
6011
|
+
```ts
|
|
6012
|
+
validateDocument(new Terrain({ resolution: 17 }).toJSON());
|
|
6013
|
+
```
|
|
6014
|
+
|
|
6015
|
+
### `validatePlacementOverrides`
|
|
6016
|
+
|
|
6017
|
+
`function` — Validate and clone stable-key placement transforms before saving or previewing them.
|
|
6018
|
+
|
|
6019
|
+
```ts
|
|
6020
|
+
export function validatePlacementOverrides( value: unknown = { … }
|
|
6021
|
+
```
|
|
6022
|
+
|
|
6023
|
+
- **Use when:** validate finite positive manual prop transforms before a terrain authoring transaction
|
|
6024
|
+
- **Constraints:** grounding defaults on only when omitted; position and scale have three components and quaternion is unit length
|
|
6025
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6026
|
+
- **Overrides:** grounding=false preserves authored Y and keeps clearance observable
|
|
6027
|
+
|
|
6028
|
+
```ts
|
|
6029
|
+
const transforms = validatePlacementOverrides(document.placementOverrides);
|
|
6030
|
+
```
|
|
6031
|
+
|
|
6032
|
+
## `@threenative/terrain/editor`
|
|
6033
|
+
|
|
6034
|
+
### `checkEnvironmentAssets`
|
|
6035
|
+
|
|
6036
|
+
`function` — Check that the images an environment names are registered environment or image assets. @summary Validate the assets a preview environment refers to
|
|
6037
|
+
|
|
6038
|
+
```ts
|
|
6039
|
+
export function checkEnvironmentAssets( environment: IEnvironment, assets: readonly { … }
|
|
6040
|
+
```
|
|
6041
|
+
|
|
6042
|
+
- **Use when:** refuse a saved environment whose sky or lighting image is not a registered file
|
|
6043
|
+
- **Constraints:** throws by name; HDR/EXR environment files and ordinary images are accepted, models are not
|
|
6044
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6045
|
+
- **Overrides:** the project owns which images it registers
|
|
6046
|
+
|
|
6047
|
+
```ts
|
|
6048
|
+
checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
|
|
6049
|
+
```
|
|
6050
|
+
|
|
6051
|
+
### `focusCamera`
|
|
6052
|
+
|
|
6053
|
+
`function` — Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera
|
|
6054
|
+
|
|
6055
|
+
```ts
|
|
6056
|
+
export function focusCamera( camera: ISavedCamera, request: IFocusRequest, resolve: IFocusResolver, ): IFocusOutcome { … }
|
|
6057
|
+
```
|
|
6058
|
+
|
|
6059
|
+
- **Use when:** frame one selected prop, a registered landmark, a terrain region or a local point
|
|
6060
|
+
- **Constraints:** framing only; an unknown target returns a named diagnostic and no camera
|
|
6061
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6062
|
+
- **Overrides:** the view supplies target bounds, the live aspect and the camera to keep
|
|
6063
|
+
|
|
6064
|
+
```ts
|
|
6065
|
+
const outcome = focusCamera(camera, { target: { kind: "prop", id: "pine-3" }, aspect: 16 / 9 }, resolve);
|
|
6066
|
+
```
|
|
6067
|
+
|
|
6068
|
+
### `inspectImage`
|
|
6069
|
+
|
|
6070
|
+
`function` — Validate a PNG, JPEG, WebP, Radiance HDR or OpenEXR container and read its pixel size. @summary Inspect an image file's container and pixel size without decoding it
|
|
6071
|
+
|
|
6072
|
+
```ts
|
|
6073
|
+
export function inspectImage( bytes: Uint8Array, format: string, limits: { … }
|
|
6074
|
+
```
|
|
6075
|
+
|
|
6076
|
+
- **Use when:** check an imported surface or environment image for damage and for the project's size limit
|
|
6077
|
+
- **Constraints:** headers and checksums only; throws by name for a damaged, truncated or oversize file
|
|
6078
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6079
|
+
- **Overrides:** the project sets the dimension limit
|
|
6080
|
+
|
|
6081
|
+
```ts
|
|
6082
|
+
const report = inspectImage(bytes, "png", { maxDimension: 8192 });
|
|
6083
|
+
```
|
|
6084
|
+
|
|
6085
|
+
### `inspectSpatial`
|
|
6086
|
+
|
|
6087
|
+
`function` — Read-only spatial inspection of one evaluated terrain revision.
|
|
6088
|
+
|
|
6089
|
+
```ts
|
|
6090
|
+
export function inspectSpatial( state: ITerrainState, revision: string, query: ISpatialQuery, ): ISpatialObservation { … }
|
|
6091
|
+
```
|
|
6092
|
+
|
|
6093
|
+
- **Use when:** measure a point, profile a transect or score a saved reference against the world
|
|
6094
|
+
- **Constraints:** authoring data only; queries outside the extent or without observations throw
|
|
6095
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6096
|
+
- **Overrides:** the caller owns the revision identity and the evaluated state being inspected
|
|
6097
|
+
|
|
6098
|
+
```ts
|
|
6099
|
+
const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
|
|
6100
|
+
```
|
|
6101
|
+
|
|
6102
|
+
### `mountTerrainEditor`
|
|
6103
|
+
|
|
6104
|
+
`function` — Mount recovered terrain controls around the project-owned ThreeNative view.
|
|
6105
|
+
|
|
6106
|
+
```ts
|
|
6107
|
+
export async function mountTerrainEditor(options: { … }
|
|
6108
|
+
```
|
|
6109
|
+
|
|
6110
|
+
- **Use when:** open the terrain brush and layer GUI around game-owned rendering
|
|
6111
|
+
- **Constraints:** browser authoring only; createView and materialColours are required game choices
|
|
6112
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6113
|
+
- **Overrides:** createView owns the renderer scene, materials, lighting and camera
|
|
6114
|
+
|
|
6115
|
+
```ts
|
|
6116
|
+
await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
|
|
6117
|
+
```
|
|
6118
|
+
|
|
6119
|
+
### `probeTerrain`
|
|
6120
|
+
|
|
6121
|
+
`function` — Probe the evaluated surface at one world point, separating bilinear from triangle values.
|
|
6122
|
+
|
|
6123
|
+
```ts
|
|
6124
|
+
export function probeTerrain( state: ITerrainState, revision: string, at: readonly number[], ): IPointObservation { … }
|
|
6125
|
+
```
|
|
6126
|
+
|
|
6127
|
+
- **Use when:** measure an authored terrain point with provenance and a revision identity
|
|
6128
|
+
- **Constraints:** authoring data only; non-finite, malformed and out-of-extent queries throw
|
|
6129
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6130
|
+
- **Overrides:** the caller owns the revision identity and the evaluated state being inspected
|
|
6131
|
+
|
|
6132
|
+
```ts
|
|
6133
|
+
const probe = probeTerrain(state, revision, [12, -4]);
|
|
6134
|
+
```
|
|
6135
|
+
|
|
6136
|
+
### `runCameraOperation`
|
|
6137
|
+
|
|
6138
|
+
`function` — Run one create / get / list / update / delete / activate operation over saved cameras. @summary Apply an editor camera operation to a saved camera set
|
|
6139
|
+
|
|
6140
|
+
```ts
|
|
6141
|
+
export function runCameraOperation(set: ICameraSet, operation: unknown): ICameraResult { … }
|
|
6142
|
+
```
|
|
6143
|
+
|
|
6144
|
+
- **Use when:** drive the terrain editor camera list from an agent or the GUI through one shared dispatch
|
|
6145
|
+
- **Constraints:** pure: the input set is never mutated, an unknown id throws, and deleting the live camera falls back
|
|
6146
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6147
|
+
- **Overrides:** the caller persists the returned set against its own revision
|
|
6148
|
+
|
|
6149
|
+
```ts
|
|
6150
|
+
const next = runCameraOperation(set, { op: "activate", id: "survey" });
|
|
6151
|
+
```
|
|
6152
|
+
|
|
6153
|
+
### `runEnvironmentOperation`
|
|
6154
|
+
|
|
6155
|
+
`function` — Apply one get / patch / reset against the saved environment overrides; the caller commits it. @summary Run one preview-environment operation
|
|
6156
|
+
|
|
6157
|
+
```ts
|
|
6158
|
+
export function runEnvironmentOperation( current: IEnvironment, operation: unknown, ): IEnvironmentResult { … }
|
|
6159
|
+
```
|
|
6160
|
+
|
|
6161
|
+
- **Use when:** patch sun, haze, exposure or sea overrides from a controller or the editor GUI
|
|
6162
|
+
- **Constraints:** authoring metadata only; a null field returns to the project's own value
|
|
6163
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6164
|
+
- **Overrides:** the project's render source decides what each value does
|
|
6165
|
+
|
|
6166
|
+
```ts
|
|
6167
|
+
const result = runEnvironmentOperation({}, { op: "patch", values: { sun: { elevation: 25 } } });
|
|
6168
|
+
```
|
|
6169
|
+
|
|
6170
|
+
### `sniff`
|
|
6171
|
+
|
|
6172
|
+
`function` — The kind and format a file's own bytes declare, whatever its name says. @summary Identify a GLB, PNG, JPEG, WebP, HDR or EXR file by its header
|
|
6173
|
+
|
|
6174
|
+
```ts
|
|
6175
|
+
export function sniff( bytes: Uint8Array, ): { … }
|
|
6176
|
+
```
|
|
6177
|
+
|
|
6178
|
+
- **Use when:** decide whether a dropped or downloaded file is a model, surface image or environment image
|
|
6179
|
+
- **Constraints:** reads only the first bytes; a file it cannot name returns undefined and must be refused
|
|
6180
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6181
|
+
- **Overrides:** the caller decides what to do with an unknown file
|
|
6182
|
+
|
|
6183
|
+
```ts
|
|
6184
|
+
const kind = sniff(new Uint8Array(await file.arrayBuffer()))?.kind;
|
|
6185
|
+
```
|
|
6186
|
+
|
|
6187
|
+
### `surfaceSpace`
|
|
6188
|
+
|
|
6189
|
+
`function` — The colour space an input's pixels are read in, from the channel its name ends with. @summary Resolve a surface input name to sRGB or linear
|
|
6190
|
+
|
|
6191
|
+
```ts
|
|
6192
|
+
export function surfaceSpace(input: string): "srgb" | "linear" { … }
|
|
6193
|
+
```
|
|
6194
|
+
|
|
6195
|
+
- **Use when:** decide how an imported image bound to a named surface input must be sampled
|
|
6196
|
+
- **Constraints:** throws by name for an input that is not <surface>.<channel> with a known channel
|
|
6197
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6198
|
+
- **Overrides:** the project owns which surface inputs exist
|
|
6199
|
+
|
|
6200
|
+
```ts
|
|
6201
|
+
const space = surfaceSpace("bark.normal");
|
|
6202
|
+
```
|
|
6203
|
+
|
|
6204
|
+
### `TerrainEditorController`
|
|
6205
|
+
|
|
6206
|
+
`class` — HTTP controller for the project-local terrain editor.
|
|
6207
|
+
|
|
6208
|
+
```ts
|
|
6209
|
+
export class TerrainEditorController { … }
|
|
6210
|
+
```
|
|
6211
|
+
|
|
6212
|
+
- **Use when:** inspect and atomically edit the terrain editor from an agent
|
|
6213
|
+
- **Constraints:** optional tooling; only subscribe/mount touches DOM; stale revisions fail explicitly
|
|
6214
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6215
|
+
- **Overrides:** editorUrl is the activation-returned project URL
|
|
6216
|
+
|
|
6217
|
+
```ts
|
|
6218
|
+
const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
|
|
6219
|
+
```
|
|
6220
|
+
|
|
6221
|
+
### `validateAsset`
|
|
6222
|
+
|
|
6223
|
+
`function` — Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry
|
|
6224
|
+
|
|
6225
|
+
```ts
|
|
6226
|
+
export function validateAsset(input: unknown): IProjectAsset { … }
|
|
6227
|
+
```
|
|
6228
|
+
|
|
6229
|
+
- **Use when:** check a model, image or environment asset entry before saving it in the authoring document
|
|
6230
|
+
- **Constraints:** authoring metadata only; ids, content-hashed paths, bounds and unit adjustments are checked, files are not read
|
|
6231
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6232
|
+
- **Overrides:** the project owns its asset directory and which entries it keeps
|
|
6233
|
+
|
|
6234
|
+
```ts
|
|
6235
|
+
const asset = validateAsset({ id: "oak", kind: "model", name: "oak.glb", path: "models/0123456789ab-oak.glb", sha256: "0123456789ab".padEnd(64, "0"), bytes: 2180, status: "ready" });
|
|
6236
|
+
```
|
|
6237
|
+
|
|
6238
|
+
### `validateAssets`
|
|
6239
|
+
|
|
6240
|
+
`function` — Validate the whole asset list of an authoring document. @summary Validate the registered terrain-editor assets
|
|
6241
|
+
|
|
6242
|
+
```ts
|
|
6243
|
+
export function validateAssets(input: unknown): IProjectAsset[] { … }
|
|
6244
|
+
```
|
|
6245
|
+
|
|
6246
|
+
- **Use when:** check every registered model, image and environment entry together, with unique ids
|
|
6247
|
+
- **Constraints:** at most 64 entries; unique ids; each entry as validateAsset
|
|
6248
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6249
|
+
- **Overrides:** the project owns its asset directory and which entries it keeps
|
|
6250
|
+
|
|
6251
|
+
```ts
|
|
6252
|
+
const assets = validateAssets(document.assets ?? []);
|
|
6253
|
+
```
|
|
6254
|
+
|
|
6255
|
+
### `validateCamera`
|
|
6256
|
+
|
|
6257
|
+
`function` — Normalise and validate one saved camera, exactly as a document commit would store it. @summary Validate an editor observation camera bookmark
|
|
6258
|
+
|
|
6259
|
+
```ts
|
|
6260
|
+
export function validateCamera( input: unknown, existing: readonly ISavedCamera[] = [], ): ISavedCamera { … }
|
|
6261
|
+
```
|
|
6262
|
+
|
|
6263
|
+
- **Use when:** create or update a named terrain-editor camera in the shared authoring document
|
|
6264
|
+
- **Constraints:** authoring metadata only; finite noncoincident poses, usable up, valid projection, ordered planes
|
|
6265
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6266
|
+
- **Overrides:** the caller owns the document revision and the live viewport aspect
|
|
6267
|
+
|
|
6268
|
+
```ts
|
|
6269
|
+
const camera = validateCamera({ id: "survey", name: "Survey", position: [40, 60, 40], target: [0, 12, 0], up: [0, 1, 0], projection: "perspective", fov: 50, near: 0.5, far: 900 });
|
|
6270
|
+
```
|
|
6271
|
+
|
|
6272
|
+
### `validateCameras`
|
|
6273
|
+
|
|
6274
|
+
`function` — Validate a document's saved camera list, keeping ids unique across it. @summary Validate the saved editor camera list of an authoring document
|
|
6275
|
+
|
|
6276
|
+
```ts
|
|
6277
|
+
export function validateCameras(input: unknown): ISavedCamera[] { … }
|
|
6278
|
+
```
|
|
6279
|
+
|
|
6280
|
+
- **Use when:** reject a disk document whose saved cameras are malformed or duplicated
|
|
6281
|
+
- **Constraints:** authoring metadata only; the same validation the camera operations apply
|
|
6282
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6283
|
+
- **Overrides:** the document owns how many cameras it keeps; the list bound is the editor's own
|
|
6284
|
+
|
|
6285
|
+
```ts
|
|
6286
|
+
const cameras = validateCameras(JSON.parse(saved).cameras ?? []);
|
|
6287
|
+
```
|
|
6288
|
+
|
|
6289
|
+
### `validateEnvironment`
|
|
6290
|
+
|
|
6291
|
+
`function` — Validate a complete overrides object exactly as a document commit stores it. @summary Validate preview environment overrides
|
|
6292
|
+
|
|
6293
|
+
```ts
|
|
6294
|
+
export function validateEnvironment(input: unknown): IEnvironment { … }
|
|
6295
|
+
```
|
|
6296
|
+
|
|
6297
|
+
- **Use when:** save sun, sky, haze, exposure or ocean overrides in the shared authoring document
|
|
6298
|
+
- **Constraints:** authoring metadata only; unknown fields and unsupported fog modes are refused by name
|
|
6299
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6300
|
+
- **Overrides:** the project's render source defines what each value does; absent fields keep its own
|
|
6301
|
+
|
|
6302
|
+
```ts
|
|
6303
|
+
const environment = validateEnvironment({ sun: { elevation: 25, intensity: 3 } });
|
|
6304
|
+
```
|
|
6305
|
+
|
|
6306
|
+
### `validateSpatialReference`
|
|
6307
|
+
|
|
6308
|
+
`function` — Normalise and validate one saved reference, exactly as a document commit would store it.
|
|
6309
|
+
|
|
6310
|
+
```ts
|
|
6311
|
+
export function validateSpatialReference(input: unknown): ISavedSpatialReference { … }
|
|
6312
|
+
```
|
|
6313
|
+
|
|
6314
|
+
- **Use when:** accept a bounded local reference image registration into the shared document
|
|
6315
|
+
- **Constraints:** authoring metadata only; rejects unknown fields, malformed points and unknown scale
|
|
6316
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6317
|
+
- **Overrides:** a project owns the image file; only its hash and provenance travel in the document
|
|
6318
|
+
|
|
6319
|
+
```ts
|
|
6320
|
+
const reference = validateSpatialReference(JSON.parse(saved));
|
|
6321
|
+
```
|
|
6322
|
+
|
|
6323
|
+
### `validateSurfaces`
|
|
6324
|
+
|
|
6325
|
+
`function` — Validate surface mappings against the registered images they name. @summary Validate terrain-editor surface image mappings
|
|
6326
|
+
|
|
6327
|
+
```ts
|
|
6328
|
+
export function validateSurfaces( input: unknown, assets: readonly IProjectAsset[], ): ISurfaceMappings { … }
|
|
6329
|
+
```
|
|
6330
|
+
|
|
6331
|
+
- **Use when:** save which imported PBR image replaces which named surface input of the project's render source
|
|
6332
|
+
- **Constraints:** authoring metadata only; each input is <surface>.<channel>; every asset must be a registered image
|
|
6333
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6334
|
+
- **Overrides:** the project's render source defines which surface inputs exist and what they draw
|
|
6335
|
+
|
|
6336
|
+
```ts
|
|
6337
|
+
const surfaces = validateSurfaces({ "bark.normal": { asset: "my-normal" } }, document.assets ?? []);
|
|
6338
|
+
```
|
|
6339
|
+
|
|
6340
|
+
## `@threenative/terrain/editor/server`
|
|
6341
|
+
|
|
6342
|
+
### `terrainEditor`
|
|
6343
|
+
|
|
6344
|
+
`function` — Mount the optional terrain document API on an existing loopback Vite server.
|
|
6345
|
+
|
|
6346
|
+
```ts
|
|
6347
|
+
export function terrainEditor(options: { … }
|
|
6348
|
+
```
|
|
6349
|
+
|
|
6350
|
+
- **Use when:** share terrain recipe edits between an agent and the live terrain editor
|
|
6351
|
+
- **Constraints:** dev tooling only; serve a project-owned /terrain-editor/index.html; no runtime import
|
|
6352
|
+
- **Requires:** npm i -D @threenative/terrain vite
|
|
6353
|
+
- **Overrides:** documentPath and optional configured viewerUrl belong to the project
|
|
6354
|
+
|
|
6355
|
+
```ts
|
|
6356
|
+
const editor = terrainEditor({ documentPath: resolve("terrain/world.json") });
|
|
6357
|
+
```
|
|
6358
|
+
|
|
6359
|
+
### `TerrainEditorDocument`
|
|
6360
|
+
|
|
6361
|
+
`class` — Project-local terrain document authority; no renderer or game dependency.
|
|
6362
|
+
|
|
6363
|
+
```ts
|
|
6364
|
+
export class TerrainEditorDocument { … }
|
|
6365
|
+
```
|
|
6366
|
+
|
|
6367
|
+
- **Use when:** validate atomic revision-based project-local terrain document edits
|
|
6368
|
+
- **Constraints:** Node authoring only; documentPath is a configured absolute regular file; input is bounded to 64 MiB
|
|
6369
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6370
|
+
- **Overrides:** the project chooses its document path; revisions come from validated content
|
|
6371
|
+
|
|
6372
|
+
```ts
|
|
6373
|
+
const document = new TerrainEditorDocument("/project/terrain/world.json"); const snapshot = document.snapshot();
|
|
6374
|
+
```
|
|
6375
|
+
|
|
6376
|
+
## `@threenative/terrain/export`
|
|
6377
|
+
|
|
6378
|
+
### `exportWorldGLB`
|
|
6379
|
+
|
|
6380
|
+
`function` — Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.
|
|
6381
|
+
|
|
6382
|
+
```ts
|
|
6383
|
+
export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }
|
|
6384
|
+
```
|
|
6385
|
+
|
|
6386
|
+
- **Use when:** export terrain, resolved models and final manual placement transforms as a portable GLB · export the whole terrain world as one glb for another three.js project
|
|
6387
|
+
- **Constraints:** browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless
|
|
6388
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6389
|
+
- **Overrides:** actual static models, final matrices and baked PBR maps are supplied by the game
|
|
6390
|
+
|
|
6391
|
+
```ts
|
|
6392
|
+
const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });
|
|
6393
|
+
```
|
|
6394
|
+
|
|
6395
|
+
## `@threenative/terrain/three`
|
|
6396
|
+
|
|
6397
|
+
### `toGeometry`
|
|
6398
|
+
|
|
6399
|
+
`function` — Converts baked arrays to ordinary geometry using the consumer's installed Three.js.
|
|
6400
|
+
|
|
6401
|
+
```ts
|
|
6402
|
+
export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }
|
|
6403
|
+
```
|
|
6404
|
+
|
|
6405
|
+
- **Use when:** put an authored terrain mesh in a game-owned Three.js scene
|
|
6406
|
+
- **Constraints:** creates only geometry; the caller owns its material, scene and disposal
|
|
6407
|
+
- **Requires:** npm i @threenative/terrain
|
|
6408
|
+
- **Overrides:** every surface choice remains in game source
|
|
6409
|
+
|
|
6410
|
+
```ts
|
|
6411
|
+
const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
|
|
6412
|
+
```
|
|
6413
|
+
|
|
6414
|
+
## `@threenative/ueformat`
|
|
6415
|
+
|
|
6416
|
+
### `createThreeGeometry`
|
|
6417
|
+
|
|
6418
|
+
`function` — Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.
|
|
6419
|
+
|
|
6420
|
+
```ts
|
|
6421
|
+
export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }
|
|
6422
|
+
```
|
|
6423
|
+
|
|
6424
|
+
- **Use when:** convert one Unreal mesh LOD into a three.js BufferGeometry by hand · build custom scene objects from Unreal mesh data instead of a whole model
|
|
6425
|
+
- **Constraints:** rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed
|
|
6426
|
+
- **Requires:** npm i @threenative/ueformat
|
|
6427
|
+
|
|
6428
|
+
```ts
|
|
6429
|
+
const geometry = createThreeGeometry(model.lods[0]);
|
|
6430
|
+
```
|
|
6431
|
+
|
|
6432
|
+
### `createThreeObject`
|
|
6433
|
+
|
|
6434
|
+
`function` — Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.
|
|
6435
|
+
|
|
6436
|
+
```ts
|
|
6437
|
+
export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }
|
|
6438
|
+
```
|
|
6439
|
+
|
|
6440
|
+
- **Use when:** put a mesh exported from an Unreal package on screen · load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry
|
|
6441
|
+
- **Constraints:** every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial · parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job
|
|
6442
|
+
- **Requires:** npm i @threenative/ueformat
|
|
6443
|
+
|
|
6444
|
+
```ts
|
|
6445
|
+
const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });
|
|
6446
|
+
```
|
|
6447
|
+
|
|
6448
|
+
### `parseUEModel`
|
|
6449
|
+
|
|
6450
|
+
`function` — Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.
|
|
6451
|
+
|
|
6452
|
+
```ts
|
|
6453
|
+
export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }
|
|
6454
|
+
```
|
|
6455
|
+
|
|
6456
|
+
- **Use when:** parse a mesh exported from an Unreal package without Unreal installed · inspect the LODs, skeleton, sockets, and collision inside a .uemodel file
|
|
6457
|
+
- **Constraints:** only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset · ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation
|
|
6458
|
+
- **Requires:** npm i @threenative/ueformat
|
|
6459
|
+
|
|
6460
|
+
```ts
|
|
6461
|
+
const model = parseUEModel(await file.arrayBuffer());
|
|
6462
|
+
```
|
|
6463
|
+
|
|
6464
|
+
### `summarizeUEModel`
|
|
6465
|
+
|
|
6466
|
+
`function` — Summarizes a parsed `.uemodel` — LOD, material, skeleton, collision, and unknown-attribute counts — without dumping vertex arrays, for logs, validation, and build reports.
|
|
6467
|
+
|
|
6468
|
+
```ts
|
|
6469
|
+
export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }
|
|
6470
|
+
```
|
|
6471
|
+
|
|
6472
|
+
- **Use when:** report what a UEFormat model contains without dumping its vertex data · validate a .uemodel file before building geometry from it
|
|
6473
|
+
- **Constraints:** the summary reflects one already-parsed model; it does not read files itself
|
|
6474
|
+
- **Requires:** npm i @threenative/ueformat
|
|
6475
|
+
|
|
6476
|
+
```ts
|
|
6477
|
+
const summary = summarizeUEModel(parseUEModel(buffer));
|
|
6478
|
+
```
|
|
6479
|
+
|
|
6480
|
+
### `UEFormatError`
|
|
6481
|
+
|
|
6482
|
+
`class` — The error thrown for every malformed, truncated, or unsupported `.uemodel` input, carrying a stable `code` and the byte offset where validation stopped.
|
|
6483
|
+
|
|
6484
|
+
```ts
|
|
6485
|
+
export class UEFormatError extends Error { … }
|
|
6486
|
+
```
|
|
6487
|
+
|
|
6488
|
+
- **Use when:** tell why a .uemodel file failed to load · report a malformed Unreal export with its byte offset instead of a generic error
|
|
6489
|
+
- **Constraints:** every parse and geometry failure surfaces as this error; nothing malformed is silently skipped
|
|
5337
6490
|
- **Requires:** npm i @threenative/ueformat
|
|
5338
6491
|
|
|
5339
6492
|
```ts
|
|
@@ -5368,6 +6521,7 @@ export function DebugOverlay() { … }
|
|
|
5368
6521
|
|
|
5369
6522
|
- **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene · find out which scene object is submitting the frame's triangles · tell a cheap foreground character from an expensive distant prop
|
|
5370
6523
|
- **Constraints:** the Geometry tab captures only on an explicit press; nothing is collected while idle · per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden
|
|
6524
|
+
- **Requires:** npm i @threenative/ui
|
|
5371
6525
|
|
|
5372
6526
|
```ts
|
|
5373
6527
|
<DebugOverlay />
|
|
@@ -5383,6 +6537,7 @@ export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( {
|
|
|
5383
6537
|
|
|
5384
6538
|
- **Use when:** add a game viewport to a React application · connect a game canvas to the web UI shell
|
|
5385
6539
|
- **Constraints:** keep the portable game entry free of React DOM code
|
|
6540
|
+
- **Requires:** npm i @threenative/ui
|
|
5386
6541
|
|
|
5387
6542
|
```ts
|
|
5388
6543
|
<GameCanvas game={game} />
|
|
@@ -5398,6 +6553,7 @@ export function UiLayer( { … }
|
|
|
5398
6553
|
|
|
5399
6554
|
- **Use when:** write one HUD that looks the same on the web build and on a phone · mount a React UI over the game surface on Android or iOS
|
|
5400
6555
|
- **Constraints:** mark every control the player touches with data-tn-interactive
|
|
6556
|
+
- **Requires:** npm i @threenative/ui
|
|
5401
6557
|
|
|
5402
6558
|
```ts
|
|
5403
6559
|
<UiLayer><Hud /></UiLayer>
|
|
@@ -5413,6 +6569,7 @@ export function useGameState<TState extends Record<string, unknown>, TPhysics, T
|
|
|
5413
6569
|
|
|
5414
6570
|
- **Use when:** bind a HUD component to game state · select a slice of state for a React panel
|
|
5415
6571
|
- **Constraints:** use this hook only from the web UI entry
|
|
6572
|
+
- **Requires:** npm i @threenative/ui
|
|
5416
6573
|
|
|
5417
6574
|
```ts
|
|
5418
6575
|
const score = useGameState(game, (state) => state.score);
|
|
@@ -5428,6 +6585,7 @@ export function useUiIntent(): (intent: string, payload?: unknown) => void { …
|
|
|
5428
6585
|
|
|
5429
6586
|
- **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu rendered over its surface
|
|
5430
6587
|
- **Constraints:** the game decides what each intent name means; it may ignore one
|
|
6588
|
+
- **Requires:** npm i @threenative/ui
|
|
5431
6589
|
|
|
5432
6590
|
```ts
|
|
5433
6591
|
const send = useUiIntent(); send("restart");
|
|
@@ -5443,11 +6601,29 @@ export function useUiState<TState extends object>(): TState | undefined;
|
|
|
5443
6601
|
|
|
5444
6602
|
- **Use when:** bind a HUD to game state on web and native alike · show score or health in a UI rendered over the game surface
|
|
5445
6603
|
- **Constraints:** returns undefined until the game publishes its first state
|
|
6604
|
+
- **Requires:** npm i @threenative/ui
|
|
5446
6605
|
|
|
5447
6606
|
```ts
|
|
5448
6607
|
const score = useUiState<GameState, number>((state) => state.score);
|
|
5449
6608
|
```
|
|
5450
6609
|
|
|
6610
|
+
## `src/audio/storm.ts`
|
|
6611
|
+
|
|
6612
|
+
### `createStormAudio`
|
|
6613
|
+
|
|
6614
|
+
`function` — The storm's sound as generated source, mixed through the engine's own `AudioBus`: a rain hiss, a wind bed, and thunder queued strike by strike and delayed and filtered by how far away it was struck.
|
|
6615
|
+
|
|
6616
|
+
```ts
|
|
6617
|
+
createStormAudio(ctx: ICtx<GameState>): IStormAudio
|
|
6618
|
+
```
|
|
6619
|
+
|
|
6620
|
+
- **Use when:** rain hiss, wind bed, thunder, a storm you can hear · delay thunder by the distance it was struck · sound that follows pause, mute and tab visibility · audio that queues strikes instead of cutting each other off
|
|
6621
|
+
- **Constraints:** `queueStrike({ at, metres })` queues: a second strike does not overwrite one still crossing the air, and `at` is absolute simulation time, which is what lets a strike survive a freeze. · Two holds, kept apart so neither latches the other: `setSilenced` is the game's own pause intent, `setHidden` is the UI realm or engine lifecycle visibility. The bus is released only when both are clear. · `update(state)` is the frame's truth and is called once per frame after the simulation advances; `debug()` is what a playtest reads back. · The caller owns entity registration, updates and disposal; creating the helper does not register it. · Audio begins only after a user gesture — the bus's unlock error is surfaced rather than swallowed. · The three clips are baked by `tools/make-storm-audio.mjs` from the study's own maths; this file plays them, it does not synthesise them live. · The helper requests the source's compressor settings ahead of master gain: threshold -15 dB, knee 30 dB, ratio 5, attack 0.003 s and release 0.25 s. · Each thunder voice is a labelled `thunder` cue, so a playtest's `audio` assertion reads it from the runtime ledger; the rain kit's `playtests/lightning.playtest.json` proves one cue after a strike, sounded only once the strike's `distance / 343` delay had passed. · This entry describes the Rain starter scaffold's own generated `src/audio/storm.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
6622
|
+
|
|
6623
|
+
```ts
|
|
6624
|
+
src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene
|
|
6625
|
+
```
|
|
6626
|
+
|
|
5451
6627
|
## `src/game.ts`
|
|
5452
6628
|
|
|
5453
6629
|
### `renderer.matrixWorld`
|
|
@@ -5498,6 +6674,74 @@ renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }
|
|
|
5498
6674
|
renderer: { projection: false } // in threenative.config.ts
|
|
5499
6675
|
```
|
|
5500
6676
|
|
|
6677
|
+
## `src/render/lightning.ts`
|
|
6678
|
+
|
|
6679
|
+
### `createStormLightning`
|
|
6680
|
+
|
|
6681
|
+
`function` — A branching lightning bolt as generated Rain source: `makeBolt(end, random)` walks a 30-segment channel down from the cloud deck with side branches, and one additive camera-facing ribbon draw (gaussian core inside a wide halo) shows it while the caller's flash envelope is above zero. `strike(position, random)` returns where the bolt entered the sky.
|
|
6682
|
+
|
|
6683
|
+
```ts
|
|
6684
|
+
createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning
|
|
6685
|
+
```
|
|
6686
|
+
|
|
6687
|
+
- **Use when:** generate branching lightning ribbon geometry · a lightning strike that lights the scene and the clouds · a camera-facing ribbon or beam that stays the same pixel width at any distance · a flash envelope that stutters rather than fades once
|
|
6688
|
+
- **Constraints:** Pass the game's seeded random so a strike is reproducible; a non-finite position or random value throws rather than drawing NaN geometry. · The buffers hold the worst case (30 channel segments plus 24 branches of 9) and are allocated once; a strike rewrites them and opens the draw range, never reallocating. · `update(flash)` takes an envelope already gated on photosensitivity mode by the caller; below 0.003 the mesh is hidden. Register it with `alwaysRender`: its quads are projected by its own vertex stage, so its bounds say nothing about where it lands. · It depth-tests against the coast's written depth, so a bolt behind the headland is hidden by it. · This entry describes the Rain starter scaffold's own generated `src/render/lightning.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
6689
|
+
|
|
6690
|
+
```ts
|
|
6691
|
+
src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay
|
|
6692
|
+
```
|
|
6693
|
+
|
|
6694
|
+
## `src/render/noise-volume.ts`
|
|
6695
|
+
|
|
6696
|
+
### `createNoiseVolume`
|
|
6697
|
+
|
|
6698
|
+
`function` — The 64³ RGBA cloud noise volume as generated Rain source: `{ data: Uint8Array, texture: Data3DTexture }`. Its authored seed, octave weights and source-exact generator define the storm's cloud shapes.
|
|
6699
|
+
|
|
6700
|
+
```ts
|
|
6701
|
+
createNoiseVolume(): INoiseVolume
|
|
6702
|
+
```
|
|
6703
|
+
|
|
6704
|
+
- **Use when:** generate a 3D noise volume instead of shipping one as an asset · rebuild the storm's clouds procedurally at startup · tileable 3D noise that does not crease at the edges · four octave scales packed into one texture
|
|
6705
|
+
- **Constraints:** Seed 13291 uses the source's mulberry32 sequence. The generated volume matches all 1,048,576 reference bytes; changing the authored seed or generator changes its appearance. · Two distinct failure channels, not one: `TN_NOISE_CHANNEL` is a channel value that does not fit a byte, `TN_NOISE_LENGTH` is a byte count that does not fill the volume. Both throw rather than uploading a volume the shader would read wrong. · 64³ of RGBA is 1 MiB, and `NOISE_SIZE` is what the loops and the byte count are written against; changing the size changes the memory cost with it. · Indices wrap at every face, which is what makes the volume tile, and the fractional part is smoothed by `f²(3 − 2f)` so lattice edges do not show as creases in the cloud. · This entry describes the Rain starter scaffold's own generated `src/render/noise-volume.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
6706
|
+
|
|
6707
|
+
```ts
|
|
6708
|
+
src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there
|
|
6709
|
+
```
|
|
6710
|
+
|
|
6711
|
+
## `src/render/rain.ts`
|
|
6712
|
+
|
|
6713
|
+
### `createStormRain`
|
|
6714
|
+
|
|
6715
|
+
`function` — Camera-anchored falling rain as generated Rain source: one instanced draw whose vertex stage hashes each drop from its index, wraps it in a 66 × 30 × 66 m cell that follows the camera in 12 m steps, and projects a quad stretched along its own fall — no particle simulation, no texture.
|
|
6716
|
+
|
|
6717
|
+
```ts
|
|
6718
|
+
createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain
|
|
6719
|
+
```
|
|
6720
|
+
|
|
6721
|
+
- **Use when:** rain streaks around the camera · thousands of falling drops in one draw · rain that leans with the wind and lights up in a lightning flash
|
|
6722
|
+
- **Constraints:** The drawn count is `round(rainBudget × weather.rain)` for the tier, read back from `geometry.instanceCount` (`instanceCount`), not from the budget. · Stateless by design: a drop's position is a function of its index and the clock, so pausing the clock freezes the rain and nothing accumulates. `GPUParticles3D` is the engine's emitter with lifetimes; reach for it when drops must spawn, live and die. · Register it with `alwaysRender`: the vertex stage places every drop, so the geometry's own bounds do not. · This entry describes the Rain starter scaffold's own generated `src/render/rain.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
6723
|
+
|
|
6724
|
+
```ts
|
|
6725
|
+
src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget
|
|
6726
|
+
```
|
|
6727
|
+
|
|
6728
|
+
## `src/render/world.ts`
|
|
6729
|
+
|
|
6730
|
+
### `createWeatherWorld`
|
|
6731
|
+
|
|
6732
|
+
`function` — The raymarched coastal storm as generated source: one screen quad whose TSL shader draws the sky, the sea, the coast, the road, the forest and the lamps, and whose wet ground reflects them, written from the uniforms the game feeds it each frame. The sky it samples is the live cloud pass this call builds, not a stand-in gradient. Returns `{ quad, update(options), dispose() }`.
|
|
6733
|
+
|
|
6734
|
+
```ts
|
|
6735
|
+
createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
|
|
6736
|
+
```
|
|
6737
|
+
|
|
6738
|
+
- **Use when:** a procedural storm, sea, coastline or open horizon drawn from maths rather than geometry · rain and wind that change how a scene looks without swapping a mesh · a lightning flash that lights the coast and the sky at once · wet reflections on a ground plane · sky that darkens as cloud cover rises
|
|
6739
|
+
- **Constraints:** `update` takes `{ elapsed, flash, weather, strike, quality }`: absolute seconds, a flash envelope already gated on the photosensitivity switch by the caller, the bolt's entry point in the cloud deck in metres (what the clouds glow around and the coast is lit from), and a quality name of `performance | balanced | high | ultra`. · The tier's cloud resolution share, march steps and reflection switch come from `STUDY_TIERS` in src/render/quality.ts; `performance` skips the 36-step reflection march, so a low tier loses reflections, not the coast. `clouds()` reads back the cloud target the renderer really drew and its steps. · Its colours and lights are uniforms set once from src/render/palette.ts, sky.ts, lighting.ts and materials.ts; the shader itself is generated from tools/tempest-*.frag by tools/generate-shaders.mjs — edit the .frag, not the generated file. · The engine's `Scene` and `PerspectiveCamera` are injected as arguments; the file holds no engine lifetime of its own. `dispose()` removes the quad and disposes the geometry, material and sky texture — the scene does not do it for you. · The quad has `frustumCulled = false`, because its two-metre bounds would otherwise be culled the moment the camera looks along the coast. · The cloud pass is built first and its texture feeds the world shader (sampled with the render-target flip); `update` also drives the clouds. Rain streaks and the bolt are separate draws: `createStormRain`, `createStormLightning`. · This entry describes the Rain starter scaffold's own generated `src/render/world.ts`, not a `@threenative/` or three export — there is no installed package to import it from. Appearance lives in that source with no package import at all; nothing in packages/ decides how this storm looks.
|
|
6740
|
+
|
|
6741
|
+
```ts
|
|
6742
|
+
src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
|
|
6743
|
+
```
|
|
6744
|
+
|
|
5501
6745
|
## `src/render/worldEnvironment.ts`
|
|
5502
6746
|
|
|
5503
6747
|
### `WorldEnvironment`
|