create-threenative 0.2.15 → 0.2.18
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/agent-docs/kit-mcp.md +10 -0
- package/agent-docs/kit-router.md +14 -0
- package/agent-docs/kit-stuck.md +7 -0
- package/agent-docs/references/assertion-reference.md +54 -110
- package/agent-docs/references/capability-reference.md +1740 -254
- package/agent-docs/references/conventions.md +299 -0
- package/agent-docs/references/kit-action-rpg.md +40 -0
- package/agent-docs/references/kit-adventure.md +40 -0
- package/agent-docs/references/kit-collectathon.md +38 -0
- package/agent-docs/references/kit-kart.md +31 -0
- package/agent-docs/references/kit-minimal.md +29 -0
- package/agent-docs/references/kit-platformer.md +34 -0
- package/agent-docs/references/kit-puzzle.md +22 -0
- package/agent-docs/references/kit-racing.md +26 -0
- package/agent-docs/references/kit-rain.md +31 -0
- package/agent-docs/references/kit-rts.md +34 -0
- package/agent-docs/references/kit-runner.md +32 -0
- package/agent-docs/references/kit-sailing.md +41 -0
- package/agent-docs/references/kit-shooter.md +33 -0
- package/agent-docs/references/kit-snow.md +33 -0
- package/agent-docs/references/kit-starter.md +55 -0
- package/agent-docs/references/kit-tower-defense.md +27 -0
- package/agent-docs/references/performance-basics.md +8 -4
- package/agent-docs/references/terrain-authoring.md +2 -1
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +84 -59
- package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/.claude/settings.json +25 -0
- package/agent-files/.codex/hooks.json +18 -1
- package/dist/index.d.ts +97 -6
- package/dist/index.js +899 -271
- package/dist/terrain-kit.d.ts +7 -0
- package/dist/terrain-kit.js +82 -0
- package/dist/threenative.js +114 -16
- package/dist/web-engine-ccd-ik-solver.js +127 -0
- package/dist/web-engine-gltf-loader.js +71 -20
- package/dist/web-engine-post-effects.js +39 -14
- package/dist/web-engine-runtime.js +10011 -4101
- package/package.json +15 -9
- package/template-assets/clearwater/README.md +1 -1
- package/template-assets/patches/manifest.json +18 -0
- package/template-assets/patches/three@0.187.0.patch +2004 -407
- package/template-assets/terrain/alpine/assets.json +12 -0
- package/template-assets/terrain/alpine/bake.mjs +6 -0
- package/template-assets/terrain/alpine/credits.json +164 -0
- package/template-assets/terrain/alpine/heightmap.r16 +0 -0
- package/template-assets/terrain/alpine/recipe.json +119 -0
- package/template-assets/terrain/alpine/surface.json +53 -0
- package/template-assets/terrain/coastal/assets.json +11 -0
- package/template-assets/terrain/coastal/bake.mjs +6 -0
- package/template-assets/terrain/coastal/credits.json +117 -0
- package/template-assets/terrain/coastal/heightmap.r16 +0 -0
- package/template-assets/terrain/coastal/recipe.json +113 -0
- package/template-assets/terrain/coastal/surface.json +41 -0
- package/template-assets/terrain/desert/assets.json +12 -0
- package/template-assets/terrain/desert/bake.mjs +6 -0
- package/template-assets/terrain/desert/credits.json +164 -0
- package/template-assets/terrain/desert/heightmap.r16 +0 -0
- package/template-assets/terrain/desert/recipe.json +108 -0
- package/template-assets/terrain/desert/surface.json +54 -0
- package/template-assets/terrain/forest/assets.json +65 -0
- package/template-assets/terrain/forest/bake.mjs +8 -0
- package/template-assets/terrain/forest/credits.json +225 -0
- package/template-assets/terrain/forest/heightmap.r16 +0 -0
- package/template-assets/terrain/forest/recipe.json +350 -0
- package/template-assets/terrain/forest/surface.json +79 -0
- package/template-assets/terrain/tundra/assets.json +12 -0
- package/template-assets/terrain/tundra/bake.mjs +6 -0
- package/template-assets/terrain/tundra/credits.json +164 -0
- package/template-assets/terrain/tundra/heightmap.r16 +0 -0
- package/template-assets/terrain/tundra/recipe.json +277 -0
- package/template-assets/terrain/tundra/surface.json +54 -0
- package/templates/action-rpg/AGENTS.md +103 -84
- package/templates/action-rpg/CLAUDE.md +103 -84
- package/templates/action-rpg/kit.json +1 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/spells.playtest.json +20 -0
- package/templates/action-rpg/src/game.ts +2 -1
- package/templates/action-rpg/src/render/atmosphere.ts +11 -16
- package/templates/action-rpg/src/render/backlightControls.ts +10 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
- package/templates/action-rpg/src/render/clouds.ts +13 -0
- package/templates/action-rpg/src/render/gpuSky.ts +4 -7
- package/templates/action-rpg/src/render/materialLighting.ts +5 -5
- package/templates/action-rpg/src/render/quality.ts +10 -33
- package/templates/action-rpg/src/scenes/Play.ts +30 -1
- package/templates/action-rpg/src/style.css +4 -0
- package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
- package/templates/action-rpg/threenative.config.ts +0 -3
- package/templates/action-rpg/vite.config.ts +2 -0
- package/templates/adventure/AGENTS.md +92 -44
- package/templates/adventure/CLAUDE.md +92 -44
- package/templates/adventure/kit.json +5 -1
- package/templates/adventure/package.json +7 -7
- package/templates/adventure/src/game.ts +1 -1
- package/templates/adventure/src/style.css +4 -0
- package/templates/adventure/tsconfig.json +1 -1
- package/templates/adventure/vite.config.ts +2 -0
- package/templates/collectathon/AGENTS.md +93 -42
- package/templates/collectathon/CLAUDE.md +93 -42
- package/templates/collectathon/package.json +7 -7
- package/templates/collectathon/src/game.ts +1 -1
- package/templates/collectathon/src/level/Course.ts +55 -9
- package/templates/collectathon/src/level/terrain.ts +27 -6
- package/templates/collectathon/src/main.ts +1 -0
- package/templates/collectathon/src/render/foliage.ts +359 -98
- package/templates/collectathon/src/render/sky.ts +76 -12
- package/templates/collectathon/src/render/water.ts +32 -10
- package/templates/collectathon/src/scenes/Play.ts +18 -5
- package/templates/collectathon/src/style.css +4 -0
- package/templates/collectathon/tsconfig.json +1 -1
- package/templates/collectathon/vite.config.ts +2 -0
- package/templates/kart/AGENTS.md +87 -42
- package/templates/kart/CLAUDE.md +87 -42
- package/templates/kart/package.json +6 -6
- package/templates/kart/src/game.ts +1 -1
- package/templates/kart/src/main.ts +1 -0
- package/templates/kart/src/style.css +4 -0
- package/templates/kart/tsconfig.json +1 -1
- package/templates/kart/vite.config.ts +2 -0
- package/templates/minimal/AGENTS.md +105 -84
- package/templates/minimal/CLAUDE.md +105 -84
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/playtests/stands-still.playtest.json +30 -0
- package/templates/minimal/src/game.ts +1 -1
- package/templates/minimal/src/render/atmosphere.ts +11 -16
- package/templates/minimal/src/render/backlightControls.ts +10 -0
- package/templates/minimal/src/render/backlightMaterial.ts +4 -4
- package/templates/minimal/src/render/camera.ts +13 -2
- package/templates/minimal/src/render/clouds.ts +13 -0
- package/templates/minimal/src/render/gpuSky.ts +4 -7
- package/templates/minimal/src/render/lighting.ts +4 -2
- package/templates/minimal/src/render/materialLighting.ts +5 -5
- package/templates/minimal/src/render/materials.ts +10 -0
- package/templates/minimal/src/render/quality.ts +7 -32
- package/templates/minimal/src/scenes/Play.ts +4 -1
- package/templates/minimal/vite.config.ts +7 -1
- package/templates/platformer/AGENTS.md +95 -46
- package/templates/platformer/CLAUDE.md +95 -46
- package/templates/platformer/index.html +1 -1
- package/templates/platformer/main.html +12 -0
- package/templates/platformer/package.json +7 -7
- package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
- package/templates/platformer/playtests/gamepad.playtest.json +30 -0
- package/templates/platformer/src/entities/Fox.ts +21 -6
- package/templates/platformer/src/game.ts +1 -1
- package/templates/platformer/src/main.ts +1 -0
- package/templates/platformer/src/render/backlightControls.ts +10 -0
- package/templates/platformer/src/render/backlightMaterial.ts +4 -4
- package/templates/platformer/src/render/materialLighting.ts +5 -5
- package/templates/platformer/src/render/quality.ts +7 -32
- package/templates/platformer/src/scenes/Play.ts +2 -1
- package/templates/platformer/src/style.css +4 -0
- package/templates/platformer/src/worker-page.ts +29 -0
- package/templates/platformer/src/worker.ts +5 -0
- package/templates/platformer/tsconfig.json +1 -1
- package/templates/platformer/vite.config.ts +4 -0
- package/templates/puzzle/AGENTS.md +97 -80
- package/templates/puzzle/CLAUDE.md +97 -80
- package/templates/puzzle/package.json +7 -7
- package/templates/puzzle/src/game.ts +1 -1
- package/templates/puzzle/src/render/backlightControls.ts +10 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
- package/templates/puzzle/src/render/materialLighting.ts +5 -5
- package/templates/puzzle/src/render/quality.ts +7 -32
- package/templates/puzzle/src/scenes/Play.ts +1 -1
- package/templates/puzzle/src/style.css +4 -0
- package/templates/puzzle/tsconfig.json +1 -1
- package/templates/puzzle/vite.config.ts +2 -0
- package/templates/racing/AGENTS.md +100 -82
- package/templates/racing/CLAUDE.md +100 -82
- package/templates/racing/package.json +7 -7
- package/templates/racing/src/game.ts +1 -1
- package/templates/racing/src/render/atmosphere.ts +11 -16
- package/templates/racing/src/render/backlightControls.ts +10 -0
- package/templates/racing/src/render/backlightMaterial.ts +4 -4
- package/templates/racing/src/render/clouds.ts +13 -0
- package/templates/racing/src/render/gpuSky.ts +4 -7
- package/templates/racing/src/render/materialLighting.ts +5 -5
- package/templates/racing/src/render/quality.ts +7 -32
- package/templates/racing/src/scenes/Race.ts +4 -1
- package/templates/racing/src/style.css +4 -0
- package/templates/racing/tsconfig.json +1 -1
- package/templates/racing/vite.config.ts +2 -0
- package/templates/rain/AGENTS.md +96 -84
- package/templates/rain/CLAUDE.md +96 -84
- package/templates/rain/native-playtests/lightning.playtest.json +85 -10
- package/templates/rain/package.json +6 -6
- package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
- package/templates/rain/src/game.ts +1 -1
- package/templates/rain/src/scenes/Boot.ts +1 -0
- package/templates/rain/src/state.ts +7 -0
- package/templates/rain/src/ui/GameUi.tsx +7 -1
- package/templates/rain/vite.config.ts +6 -0
- package/templates/rts/AGENTS.md +100 -85
- package/templates/rts/CLAUDE.md +100 -85
- package/templates/rts/package.json +6 -6
- package/templates/rts/src/game.ts +1 -1
- package/templates/rts/src/render/backlightControls.ts +10 -0
- package/templates/rts/src/render/backlightMaterial.ts +4 -4
- package/templates/rts/src/render/materialLighting.ts +5 -5
- package/templates/rts/src/render/quality.ts +7 -31
- package/templates/rts/src/scenes/Play.ts +1 -1
- package/templates/rts/src/style.css +4 -0
- package/templates/rts/vite.config.ts +2 -0
- package/templates/runner/AGENTS.md +97 -80
- package/templates/runner/CLAUDE.md +97 -80
- package/templates/runner/package.json +7 -7
- package/templates/runner/playtests/performance.playtest.json +1 -1
- package/templates/runner/src/game.ts +1 -1
- package/templates/runner/src/render/atmosphere.ts +11 -16
- package/templates/runner/src/render/backlightControls.ts +10 -0
- package/templates/runner/src/render/backlightMaterial.ts +4 -4
- package/templates/runner/src/render/clouds.ts +13 -0
- package/templates/runner/src/render/gpuSky.ts +4 -7
- package/templates/runner/src/render/lighting.ts +53 -11
- package/templates/runner/src/render/materialLighting.ts +5 -5
- package/templates/runner/src/render/quality.ts +7 -32
- package/templates/runner/src/scenes/Run.ts +8 -4
- package/templates/runner/src/style.css +4 -0
- package/templates/runner/threenative.config.ts +0 -3
- package/templates/runner/tsconfig.json +1 -1
- package/templates/runner/vite.config.ts +2 -0
- package/templates/sailing/AGENTS.md +96 -79
- package/templates/sailing/CLAUDE.md +96 -79
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/playtests/sails.playtest.json +1 -0
- package/templates/sailing/src/game.ts +1 -1
- package/templates/sailing/src/render/backlightControls.ts +10 -0
- package/templates/sailing/src/render/backlightMaterial.ts +4 -4
- package/templates/sailing/src/render/environmentSetup.ts +1 -1
- package/templates/sailing/src/render/materialLighting.ts +5 -5
- package/templates/sailing/src/render/quality.ts +7 -32
- package/templates/sailing/src/render/sky.ts +4 -0
- package/templates/sailing/src/style.css +5 -0
- package/templates/sailing/threenative.config.ts +0 -3
- package/templates/sailing/vite.config.ts +6 -0
- package/templates/shooter/AGENTS.md +97 -68
- package/templates/shooter/CLAUDE.md +97 -68
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/game.ts +3 -2
- package/templates/shooter/src/render/atmosphere.ts +11 -16
- package/templates/shooter/src/render/backlightControls.ts +10 -0
- package/templates/shooter/src/render/backlightMaterial.ts +4 -4
- package/templates/shooter/src/render/clouds.ts +13 -0
- package/templates/shooter/src/render/gpuSky.ts +4 -7
- package/templates/shooter/src/render/materialLighting.ts +5 -5
- package/templates/shooter/src/render/quality.ts +10 -33
- package/templates/shooter/src/scenes/Play.ts +4 -1
- package/templates/shooter/src/style.css +4 -0
- package/templates/shooter/vite.config.ts +2 -0
- package/templates/snow/AGENTS.md +95 -76
- package/templates/snow/CLAUDE.md +95 -76
- package/templates/snow/package.json +7 -7
- package/templates/snow/src/game.ts +1 -1
- package/templates/snow/src/render/backlightControls.ts +10 -0
- package/templates/snow/src/render/backlightMaterial.ts +4 -4
- package/templates/snow/src/render/materialLighting.ts +5 -5
- package/templates/snow/src/render/quality.ts +7 -32
- package/templates/snow/src/style.css +5 -0
- package/templates/snow/threenative.config.ts +0 -3
- package/templates/snow/vite.config.ts +6 -0
- package/templates/starter/AGENTS.md +109 -88
- package/templates/starter/CLAUDE.md +109 -88
- package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
- package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Crate.ts +5 -2
- package/templates/starter/src/entities/Player.ts +10 -22
- package/templates/starter/src/game.ts +4 -3
- package/templates/starter/src/render/adaptiveQuality.ts +17 -0
- package/templates/starter/src/render/atmosphere.ts +11 -16
- package/templates/starter/src/render/backlightControls.ts +10 -0
- package/templates/starter/src/render/backlightMaterial.ts +4 -4
- package/templates/starter/src/render/clouds.ts +13 -0
- package/templates/starter/src/render/contactShadow.ts +1 -1
- package/templates/starter/src/render/gpuSky.ts +4 -7
- package/templates/starter/src/render/lighting.ts +54 -4
- package/templates/starter/src/render/materialLighting.ts +5 -5
- package/templates/starter/src/render/postprocessing.ts +11 -10
- package/templates/starter/src/render/quality.ts +14 -1
- package/templates/starter/src/render/temporalAA.ts +8 -7
- package/templates/starter/src/render/temporalAAFrame.ts +30 -9
- package/templates/starter/src/render/temporalAAResolve.ts +15 -1
- package/templates/starter/src/render/temporalClampRelease.ts +183 -0
- package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
- package/templates/starter/src/render/temporalMoire.ts +190 -0
- package/templates/starter/src/render/temporalResolve.ts +75 -16
- package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
- package/templates/starter/src/scenes/Play.ts +53 -32
- package/templates/starter/src/state.ts +2 -0
- package/templates/starter/src/style.css +4 -0
- package/templates/starter/src/ui/Menu.tsx +5 -1
- package/templates/starter/vite.config.ts +2 -0
- package/templates/tower-defense/AGENTS.md +97 -81
- package/templates/tower-defense/CLAUDE.md +97 -81
- package/templates/tower-defense/package.json +7 -7
- package/templates/tower-defense/src/game.ts +1 -1
- package/templates/tower-defense/src/render/backlightControls.ts +10 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
- package/templates/tower-defense/src/render/materialLighting.ts +5 -5
- package/templates/tower-defense/src/render/quality.ts +7 -32
- package/templates/tower-defense/src/scenes/Battle.ts +1 -1
- package/templates/tower-defense/src/style.css +4 -0
- package/templates/tower-defense/tsconfig.json +1 -1
- package/templates/tower-defense/vite.config.ts +2 -0
- package/capabilities.json +0 -9197
- package/templates/AGENTS.md +0 -21
- package/templates/CLAUDE.md +0 -23
- package/templates/action-rpg/.codex/config.toml +0 -23
- package/templates/action-rpg/.cursor/mcp.json +0 -38
- package/templates/action-rpg/.gemini/settings.json +0 -38
- package/templates/action-rpg/.mcp.json +0 -38
- package/templates/action-rpg/.vscode/mcp.json +0 -43
- package/templates/action-rpg/.zed/settings.json +0 -43
- package/templates/action-rpg/opencode.json +0 -49
- package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
- package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
- package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
- package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
- package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
- package/templates/adventure/.codex/config.toml +0 -23
- package/templates/adventure/.cursor/mcp.json +0 -38
- package/templates/adventure/.gemini/settings.json +0 -38
- package/templates/adventure/.mcp.json +0 -38
- package/templates/adventure/.vscode/mcp.json +0 -43
- package/templates/adventure/.zed/settings.json +0 -43
- package/templates/adventure/opencode.json +0 -49
- package/templates/collectathon/.codex/config.toml +0 -23
- package/templates/collectathon/.cursor/mcp.json +0 -38
- package/templates/collectathon/.gemini/settings.json +0 -38
- package/templates/collectathon/.mcp.json +0 -38
- package/templates/collectathon/.vscode/mcp.json +0 -43
- package/templates/collectathon/.zed/settings.json +0 -43
- package/templates/collectathon/opencode.json +0 -49
- package/templates/kart/.codex/config.toml +0 -23
- package/templates/kart/.cursor/mcp.json +0 -38
- package/templates/kart/.gemini/settings.json +0 -38
- package/templates/kart/.mcp.json +0 -38
- package/templates/kart/.vscode/mcp.json +0 -43
- package/templates/kart/.zed/settings.json +0 -43
- package/templates/kart/opencode.json +0 -49
- package/templates/minimal/.codex/config.toml +0 -23
- package/templates/minimal/.cursor/mcp.json +0 -38
- package/templates/minimal/.gemini/settings.json +0 -38
- package/templates/minimal/.mcp.json +0 -38
- package/templates/minimal/.vscode/mcp.json +0 -43
- package/templates/minimal/.zed/settings.json +0 -43
- package/templates/minimal/opencode.json +0 -49
- package/templates/minimal/src/render/environmentContribution.ts +0 -188
- package/templates/minimal/src/render/environmentRadiance.ts +0 -36
- package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
- package/templates/minimal/src/render/environmentSampling.ts +0 -193
- package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
- package/templates/platformer/.codex/config.toml +0 -23
- package/templates/platformer/.cursor/mcp.json +0 -38
- package/templates/platformer/.gemini/settings.json +0 -38
- package/templates/platformer/.mcp.json +0 -38
- package/templates/platformer/.vscode/mcp.json +0 -43
- package/templates/platformer/.zed/settings.json +0 -43
- package/templates/platformer/opencode.json +0 -49
- package/templates/platformer/src/render/environmentContribution.ts +0 -188
- package/templates/platformer/src/render/environmentRadiance.ts +0 -36
- package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
- package/templates/platformer/src/render/environmentSampling.ts +0 -193
- package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
- package/templates/puzzle/.codex/config.toml +0 -23
- package/templates/puzzle/.cursor/mcp.json +0 -38
- package/templates/puzzle/.gemini/settings.json +0 -38
- package/templates/puzzle/.mcp.json +0 -38
- package/templates/puzzle/.vscode/mcp.json +0 -43
- package/templates/puzzle/.zed/settings.json +0 -43
- package/templates/puzzle/opencode.json +0 -49
- package/templates/puzzle/src/render/environmentContribution.ts +0 -188
- package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
- package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
- package/templates/puzzle/src/render/environmentSampling.ts +0 -193
- package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
- package/templates/racing/.codex/config.toml +0 -23
- package/templates/racing/.cursor/mcp.json +0 -38
- package/templates/racing/.gemini/settings.json +0 -38
- package/templates/racing/.mcp.json +0 -38
- package/templates/racing/.vscode/mcp.json +0 -43
- package/templates/racing/.zed/settings.json +0 -43
- package/templates/racing/opencode.json +0 -49
- package/templates/racing/src/render/environmentContribution.ts +0 -188
- package/templates/racing/src/render/environmentRadiance.ts +0 -36
- package/templates/racing/src/render/environmentSampleCache.ts +0 -43
- package/templates/racing/src/render/environmentSampling.ts +0 -193
- package/templates/racing/src/render/environmentSnapshot.ts +0 -53
- package/templates/rain/.codex/config.toml +0 -23
- package/templates/rain/.cursor/mcp.json +0 -38
- package/templates/rain/.gemini/settings.json +0 -38
- package/templates/rain/.mcp.json +0 -38
- package/templates/rain/.vscode/mcp.json +0 -43
- package/templates/rain/.zed/settings.json +0 -43
- package/templates/rain/opencode.json +0 -49
- package/templates/rts/.codex/config.toml +0 -23
- package/templates/rts/.cursor/mcp.json +0 -38
- package/templates/rts/.gemini/settings.json +0 -38
- package/templates/rts/.mcp.json +0 -38
- package/templates/rts/.vscode/mcp.json +0 -43
- package/templates/rts/.zed/settings.json +0 -43
- package/templates/rts/opencode.json +0 -49
- package/templates/rts/src/render/environmentContribution.ts +0 -188
- package/templates/rts/src/render/environmentRadiance.ts +0 -36
- package/templates/rts/src/render/environmentSampleCache.ts +0 -43
- package/templates/rts/src/render/environmentSampling.ts +0 -193
- package/templates/rts/src/render/environmentSnapshot.ts +0 -53
- package/templates/runner/.codex/config.toml +0 -23
- package/templates/runner/.cursor/mcp.json +0 -38
- package/templates/runner/.gemini/settings.json +0 -38
- package/templates/runner/.mcp.json +0 -38
- package/templates/runner/.vscode/mcp.json +0 -43
- package/templates/runner/.zed/settings.json +0 -43
- package/templates/runner/README.md +0 -43
- package/templates/runner/opencode.json +0 -49
- package/templates/runner/src/render/environmentContribution.ts +0 -188
- package/templates/runner/src/render/environmentRadiance.ts +0 -36
- package/templates/runner/src/render/environmentSampleCache.ts +0 -43
- package/templates/runner/src/render/environmentSampling.ts +0 -193
- package/templates/runner/src/render/environmentSnapshot.ts +0 -53
- package/templates/sailing/.codex/config.toml +0 -23
- package/templates/sailing/.cursor/mcp.json +0 -38
- package/templates/sailing/.gemini/settings.json +0 -38
- package/templates/sailing/.mcp.json +0 -38
- package/templates/sailing/.vscode/mcp.json +0 -43
- package/templates/sailing/.zed/settings.json +0 -43
- package/templates/sailing/README.md +0 -28
- package/templates/sailing/opencode.json +0 -49
- package/templates/sailing/src/render/environmentContribution.ts +0 -188
- package/templates/sailing/src/render/environmentRadiance.ts +0 -36
- package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
- package/templates/sailing/src/render/environmentSampling.ts +0 -193
- package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
- package/templates/shooter/.codex/config.toml +0 -23
- package/templates/shooter/.cursor/mcp.json +0 -38
- package/templates/shooter/.gemini/settings.json +0 -38
- package/templates/shooter/.mcp.json +0 -38
- package/templates/shooter/.vscode/mcp.json +0 -43
- package/templates/shooter/.zed/settings.json +0 -43
- package/templates/shooter/opencode.json +0 -49
- package/templates/shooter/src/render/environmentContribution.ts +0 -188
- package/templates/shooter/src/render/environmentRadiance.ts +0 -36
- package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
- package/templates/shooter/src/render/environmentSampling.ts +0 -193
- package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
- package/templates/snow/.codex/config.toml +0 -23
- package/templates/snow/.cursor/mcp.json +0 -38
- package/templates/snow/.gemini/settings.json +0 -38
- package/templates/snow/.mcp.json +0 -38
- package/templates/snow/.vscode/mcp.json +0 -43
- package/templates/snow/.zed/settings.json +0 -43
- package/templates/snow/README.md +0 -26
- package/templates/snow/opencode.json +0 -49
- package/templates/snow/src/render/environmentContribution.ts +0 -188
- package/templates/snow/src/render/environmentRadiance.ts +0 -36
- package/templates/snow/src/render/environmentSampleCache.ts +0 -43
- package/templates/snow/src/render/environmentSampling.ts +0 -193
- package/templates/snow/src/render/environmentSnapshot.ts +0 -53
- package/templates/starter/.codex/config.toml +0 -23
- package/templates/starter/.cursor/mcp.json +0 -38
- package/templates/starter/.gemini/settings.json +0 -38
- package/templates/starter/.mcp.json +0 -38
- package/templates/starter/.vscode/mcp.json +0 -43
- package/templates/starter/.zed/settings.json +0 -43
- package/templates/starter/opencode.json +0 -49
- package/templates/starter/src/render/environmentContribution.ts +0 -188
- package/templates/starter/src/render/environmentRadiance.ts +0 -36
- package/templates/starter/src/render/environmentSampleCache.ts +0 -43
- package/templates/starter/src/render/environmentSampling.ts +0 -193
- package/templates/starter/src/render/environmentSnapshot.ts +0 -53
- package/templates/starter/src/render/rendererGate.ts +0 -36
- package/templates/tower-defense/.codex/config.toml +0 -23
- package/templates/tower-defense/.cursor/mcp.json +0 -38
- package/templates/tower-defense/.gemini/settings.json +0 -38
- package/templates/tower-defense/.mcp.json +0 -38
- package/templates/tower-defense/.vscode/mcp.json +0 -43
- package/templates/tower-defense/.zed/settings.json +0 -43
- package/templates/tower-defense/README.md +0 -16
- package/templates/tower-defense/opencode.json +0 -49
- package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
- package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
- package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
- package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
- package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
|
@@ -70,6 +70,20 @@ export async function compileAssets( options: IAssetCompileOptions = { … }
|
|
|
70
70
|
const result = await compileAssets({ source: "assets", output: "public" });
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
+
### `cookTerrainWorld`
|
|
74
|
+
|
|
75
|
+
`function` — Bake evaluated terrain and static species into an instanced GLB and streaming world package.
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
export function cookTerrainWorld( options: IPreparedTerrainWorldOptions, ): Promise< { … }
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- **Use when:** bake a terrain world headlessly into a GLB with instanced trees and rocks · generate a forest world for my game
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
await cookTerrainWorld({ state, species, out: "assets/world" });
|
|
85
|
+
```
|
|
86
|
+
|
|
73
87
|
### `dedupeMaterials`
|
|
74
88
|
|
|
75
89
|
`function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
|
|
@@ -213,8 +227,9 @@ pnpm census:content public/assets
|
|
|
213
227
|
export function modelPass(options: IModelPassOptions = { … }
|
|
214
228
|
```
|
|
215
229
|
|
|
216
|
-
- **Use when:** reduce a model's download and GPU footprint · optimize a GLB before shipping it with a game
|
|
217
|
-
- **Constraints:** the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output
|
|
230
|
+
- **Use when:** reduce a model's download and GPU footprint · optimize a GLB before shipping it with a game · texture bytes too big after the model cook · a KTX2 model texture came out larger than its WebP or JPEG source · choose ETC1S or UASTC for a model's embedded textures · model texture codec ladder · keep smaller source texture · TN_ASSETS_COMPRESSION_SKIPPED
|
|
231
|
+
- **Constraints:** the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output · each colour texture climbs a codec ladder (ETC1S, then UASTC with RDO, then plain UASTC) and keeps the smallest rung that meets the quality floor (SSIM 0.95, ΔE00 3); a data slot such as a normal or metallic-roughness map takes UASTC only, as ETC1S is forbidden there (`TN_ASSETS_TEXTURE_SLOT_CODEC`); a result is kept only when it is smaller than the source, else the source stays and the report says `not-smaller` · a PNG or JPEG source can always be kept; a WebP source can be kept only on a web target, whose runtimes all decode WebP, so on desktop and mobile it always becomes KTX2
|
|
232
|
+
- **Overrides:** `textures: { overrides: [{ slot: "baseColorTexture", codec: "uastc" }] }` forces one glTF slot's codec (`etc1s`, `uastc` or `none`); `textures: { floor }` moves the quality floor; `textures: "none"` keeps every embedded texture as authored
|
|
218
233
|
|
|
219
234
|
```ts
|
|
220
235
|
const pass = modelPass({ simplify: { ratio: 0.5 } });
|
|
@@ -340,6 +355,21 @@ export function texturePass(options: ITexturePassOptions = { … }
|
|
|
340
355
|
const pass = texturePass({ quality: 150 });
|
|
341
356
|
```
|
|
342
357
|
|
|
358
|
+
### `thinFoliageCards`
|
|
359
|
+
|
|
360
|
+
`function` — Build a standalone card-thinned foliage mesh, preserving opaque parts and vertex attributes.
|
|
361
|
+
|
|
362
|
+
```ts
|
|
363
|
+
export function thinFoliageCards(document: Document, keepRatio: number): number { … }
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
- **Use when:** prepare a far foliage mesh by thinning whole cards instead of triangles
|
|
367
|
+
- **Constraints:** mutates the supplied document; rejects unsupported MASK topology and invalid ratios
|
|
368
|
+
|
|
369
|
+
```ts
|
|
370
|
+
thinFoliageCards(document, 0.14);
|
|
371
|
+
```
|
|
372
|
+
|
|
343
373
|
### `totalCensus`
|
|
344
374
|
|
|
345
375
|
`function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
|
|
@@ -434,7 +464,7 @@ addFoliageBackLight(leaf, backIrradiance);
|
|
|
434
464
|
|
|
435
465
|
### `addInSlices`
|
|
436
466
|
|
|
437
|
-
`function` — Attach hundreds of built objects to the scene in slices, presenting a frame between each.
|
|
467
|
+
`function` — Attach hundreds of built objects to the scene in slices with an 8 ms default budget, presenting a frame between each.
|
|
438
468
|
|
|
439
469
|
```ts
|
|
440
470
|
export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }
|
|
@@ -997,9 +1027,9 @@ const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
|
|
|
997
1027
|
export function createAssetLoader(options: IAssetLoaderOptions = { … }
|
|
998
1028
|
```
|
|
999
1029
|
|
|
1000
|
-
- **Use when:** preload models, textures, or audio before a scene enters · keep downloaded web assets on disk between visits · download the next scene before the player gets there · free the disk cache from a settings menu · prefetch assets into the Cache Storage disk cache of a large web game · load assets from a nonstandard base path or a compiled asset manifest
|
|
1001
|
-
- **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches · await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world · web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once
|
|
1002
|
-
- **Overrides:** `assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`
|
|
1030
|
+
- **Use when:** preload models, textures, or audio before a scene enters · keep downloaded web assets on disk between visits · download the next scene before the player gets there · free the disk cache from a settings menu · prefetch assets into the Cache Storage disk cache of a large web game · load assets from a nonstandard base path or a compiled asset manifest · stream a large game: boot on the spawn bytes and prefetch the rest · make the first scene play before the whole game finishes downloading · draw a heavy model's coarsest level first and its full detail when the file lands · draw a model's textures at their resident mips first and the whole files later · coarse first model streaming · streamMeshes and streamTextures: stream the meshes and textures of a model · mip streaming textures · TN_STREAMING_POOL · TN_ASSET_LATE · an asset pops in after the reveal and the game needs to count it · a model texture looks blurry or low resolution right after load, then sharpens · build a collider or navmesh from a streamed model only once its full file landed · compressed texture upload on the owned engine (KTX2 to BC7 or ETC2 on the GPU) · load a model with KHR_texture_basisu or EXT_meshopt_compression on the owned engine · stream a finer mip level into a CompressedTexture that already draws · KTX2Loader on the owned engine · CompressedTexture upload · TN_TEXTURE_TRANSCODE_TARGET · TN_NATIVE_TEXTURE_UNSUPPORTED · webRuntimeDecoders meshopt ktx2
|
|
1031
|
+
- **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches · await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world · a whole-file load requested after the reveal that the game had not `prefetch`ed logs one `TN_ASSET_LATE` line with its bytes, so a pop-in is countable from a playtest · web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once · streaming is engine-owned and on by default: a cooked LOD-chained model loads its `.coarse.<digest>.glb` companion first, then the full file at "soon" priority, and the full geometry replaces the coarse in place (clones and the projection mirror included); a failed coarse load falls back to the whole file and logs `TN_ASSETS_STREAM_FAILED` · texture streaming rides on the coarse parse: each shared `.ktx2` of that model is read by `Range` as its resident mips (the header and the tail), and the whole files replace them when the full model lands; a host without `Range` sends the whole file and keeps it whole. `TN_STREAMING_POOL` reports `files`, `residentBytes`, `fullBytes`, `deferredBytes` and `upgraded` once, two seconds after the last change · the whole texture keeps what the game set on the resident one (`anisotropy`, wrap, filters, offset, repeat, `userData`), so the swap changes the mips and nothing else · every web build cooks meshopt geometry and KTX2 textures for both engines (`webRuntimeDecoders` in create-threenative answers `{ ktx2: true, meshopt: true }`); the owned engine's glTF loader decodes both itself, with no JS decoder · the owned engine transcodes a KTX2 image to BC7 on a device with `texture-compression-bc`, else ETC2, else RGBA8 with an engine mip chain, and prints `TN_TEXTURE_TRANSCODE_TARGET <target>` once; a block format needs a width and height that are multiples of 4, so any other size stays RGBA8 and the same line names it · a three `CompressedTexture` (format plus `mipmaps`) uploads one GPU write per level; a block format the device lacks throws `TN_NATIVE_TEXTURE_UNSUPPORTED` by name instead of drawing garbage · levels are coarse-first: a level whose `mipmaps[i].data` is null is not resident and the texture samples its finest resident level; set `mipmaps[i].data` and `needsUpdate = true` to write that one finer level in place, without re-creating the texture or rewriting the other levels
|
|
1032
|
+
- **Overrides:** `assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache` · `ctx.assets.model(path, { whole: true })` resolves only once the full file has replaced the coarse companion, for a collider or navmesh that copies vertices once · `assets.streamMeshes: false` loads every model whole (reported once as `TN_ASSETS_STREAM_MESHES_OFF`); `assets.streamTextures: false` loads every model texture whole (`TN_ASSETS_STREAM_TEXTURES_OFF`) · `engine: "threejs"` runs three's own `KTX2Loader` and `MeshoptDecoder` in JS instead of the owned engine's decoders
|
|
1003
1033
|
|
|
1004
1034
|
```ts
|
|
1005
1035
|
const assets = createAssetLoader({ basePath: "/assets" });
|
|
@@ -1079,7 +1109,7 @@ ctx.add(daylight);
|
|
|
1079
1109
|
export function debugFlag(name: string): boolean { … }
|
|
1080
1110
|
```
|
|
1081
1111
|
|
|
1082
|
-
- **Use when:** read a debug toggle from the URL
|
|
1112
|
+
- **Use when:** read a debug toggle from the URL, an environment variable or a harness global
|
|
1083
1113
|
- **Constraints:** a name in camelCase becomes UPPER_SNAKE: `debugFlag("freeCam")` reads `?freeCam` or `TN_DEBUG_FREE_CAM` · `0` and `false` are off, so a saved URL cannot turn a switch back on
|
|
1084
1114
|
|
|
1085
1115
|
```ts
|
|
@@ -1132,6 +1162,22 @@ export function describeSceneWarning(warning: ISceneWarning): string { … }
|
|
|
1132
1162
|
defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
1133
1163
|
```
|
|
1134
1164
|
|
|
1165
|
+
### `devGlobal`
|
|
1166
|
+
|
|
1167
|
+
`function` — The one name every dev surface publishes under, and the reader/writer for it.
|
|
1168
|
+
|
|
1169
|
+
```ts
|
|
1170
|
+
export function devGlobal(scope: unknown): DevGlobal | undefined { … }
|
|
1171
|
+
```
|
|
1172
|
+
|
|
1173
|
+
- **Use when:** read or extend the `__THREENATIVE__` object a dev launch publishes
|
|
1174
|
+
- **Constraints:** every dev surface publishes under this key; the worker's typed mirror tuple names it too
|
|
1175
|
+
|
|
1176
|
+
```ts
|
|
1177
|
+
import { DEV_GLOBAL_KEY, devGlobal } from "@threenative/core";
|
|
1178
|
+
const tools = devGlobal(globalThis);
|
|
1179
|
+
```
|
|
1180
|
+
|
|
1135
1181
|
### `directionalTransmittance`
|
|
1136
1182
|
|
|
1137
1183
|
`function` — Approximate direct transmittance for a ray leaving the game surface.
|
|
@@ -1290,6 +1336,21 @@ export function exposureFromEv100(ev100: number): number { … }
|
|
|
1290
1336
|
renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
|
|
1291
1337
|
```
|
|
1292
1338
|
|
|
1339
|
+
### `fetchAsset`
|
|
1340
|
+
|
|
1341
|
+
`function` — Fetch a data file the asset loader serves: each url `assets.resolve(path)` names, in order, until one answers ok. A built game serves the hashed output and a dev server the source path, so taking only the first url 404s on one of them. When none answers it throws `TN_ASSET_NOT_SERVED` naming every url tried and why, so a missing file is never a half-drawn world.
|
|
1342
|
+
|
|
1343
|
+
```ts
|
|
1344
|
+
export async function fetchAsset( assets: Pick<IAssetLoader, "resolve">, path: string, ): Promise<Response> { … }
|
|
1345
|
+
```
|
|
1346
|
+
|
|
1347
|
+
- **Use when:** load a baked JSON or binary file (a heightmap, a placement buffer, a data table) that the loader has no typed method for · a data file loads in dev but 404s in the built game
|
|
1348
|
+
- **Constraints:** reads the response once; call `.json()` or `.arrayBuffer()` on the result
|
|
1349
|
+
|
|
1350
|
+
```ts
|
|
1351
|
+
const heights = new Float32Array(await (await fetchAsset(ctx.assets, "world/forest.bin")).arrayBuffer());
|
|
1352
|
+
```
|
|
1353
|
+
|
|
1293
1354
|
### `FlightModel`
|
|
1294
1355
|
|
|
1295
1356
|
`class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
@@ -1457,11 +1518,12 @@ model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
|
1457
1518
|
export function getPlatform(): Readonly<IPlatformInfo> { … }
|
|
1458
1519
|
```
|
|
1459
1520
|
|
|
1460
|
-
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1521
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1461
1522
|
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1462
1523
|
|
|
1463
1524
|
```ts
|
|
1464
1525
|
if (isMobile()) showTouchControls();
|
|
1526
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1465
1527
|
```
|
|
1466
1528
|
|
|
1467
1529
|
### `GIBudget`
|
|
@@ -1569,8 +1631,9 @@ const snap = new GroundSnap(character, { enabled: true });
|
|
|
1569
1631
|
export class InputMap { … }
|
|
1570
1632
|
```
|
|
1571
1633
|
|
|
1572
|
-
- **Use when:** map WASD keys to a movement axis instead of reading the held key set in the update loop · read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together · read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks
|
|
1573
|
-
- **Constraints:** `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it · scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own
|
|
1634
|
+
- **Use when:** map WASD keys to a movement axis instead of reading the held key set in the update loop · read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together · read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks · support an Xbox pad, a generic XInput clone, an 8BitDo or a Steam Deck controller · the character drifts while the controller stick is idle · the controller does nothing in Firefox on Linux · a second controller or a wheel steals the input from the pad the player holds
|
|
1635
|
+
- **Constraints:** `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it · scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own · gamepad buttons are W3C standard indices on every pad: 0 south (A/Cross), 1 east, 2 west, 3 north, 4/5 shoulders, 6/7 triggers, 8 select, 9 start, 10/11 stick clicks; axes 0..3 are the sticks · both sticks carry a radial dead zone, `0.2` by default, reported per connected pad as `TN_GAMEPAD`; a pad the browser reports unmapped and the table does not know is ignored, never read with raw indices · a pad claims the input when a button goes down or a stick travels past half tilt, and keeps it while idle so its releases read; a stick resting past the dead zone or jittering across it claims nothing, so an idle pad in the first slot cannot steal input
|
|
1636
|
+
- **Overrides:** defineGame({ gamepadDeadZone: 0 }) publishes raw axes
|
|
1574
1637
|
|
|
1575
1638
|
```ts
|
|
1576
1639
|
const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: ["KeyA"], right: ["KeyD"] } }, scenes: { Play } });
|
|
@@ -1641,6 +1704,22 @@ export function invalidateStatic(object: Object3D): number | undefined { … }
|
|
|
1641
1704
|
invalidateStatic(drawbridge);
|
|
1642
1705
|
```
|
|
1643
1706
|
|
|
1707
|
+
### `isConsole`
|
|
1708
|
+
|
|
1709
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
1710
|
+
|
|
1711
|
+
```ts
|
|
1712
|
+
export function isConsole(): boolean { … }
|
|
1713
|
+
```
|
|
1714
|
+
|
|
1715
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1716
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1717
|
+
|
|
1718
|
+
```ts
|
|
1719
|
+
if (isMobile()) showTouchControls();
|
|
1720
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1721
|
+
```
|
|
1722
|
+
|
|
1644
1723
|
### `isMobile`
|
|
1645
1724
|
|
|
1646
1725
|
`function` — Read the host platform without reaching for browser globals.
|
|
@@ -1649,11 +1728,12 @@ invalidateStatic(drawbridge);
|
|
|
1649
1728
|
export function isMobile(): boolean { … }
|
|
1650
1729
|
```
|
|
1651
1730
|
|
|
1652
|
-
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1731
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1653
1732
|
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1654
1733
|
|
|
1655
1734
|
```ts
|
|
1656
1735
|
if (isMobile()) showTouchControls();
|
|
1736
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1657
1737
|
```
|
|
1658
1738
|
|
|
1659
1739
|
### `isNative`
|
|
@@ -1664,11 +1744,28 @@ if (isMobile()) showTouchControls();
|
|
|
1664
1744
|
export function isNative(): boolean { … }
|
|
1665
1745
|
```
|
|
1666
1746
|
|
|
1667
|
-
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1747
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1668
1748
|
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1669
1749
|
|
|
1670
1750
|
```ts
|
|
1671
1751
|
if (isMobile()) showTouchControls();
|
|
1752
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1755
|
+
### `isPs4`
|
|
1756
|
+
|
|
1757
|
+
`function` — Read the host platform without reaching for browser globals.
|
|
1758
|
+
|
|
1759
|
+
```ts
|
|
1760
|
+
export function isPs4(): boolean { … }
|
|
1761
|
+
```
|
|
1762
|
+
|
|
1763
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1764
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1765
|
+
|
|
1766
|
+
```ts
|
|
1767
|
+
if (isMobile()) showTouchControls();
|
|
1768
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1672
1769
|
```
|
|
1673
1770
|
|
|
1674
1771
|
### `isStatic`
|
|
@@ -1686,6 +1783,21 @@ export function isStatic(root: Object3D): boolean { … }
|
|
|
1686
1783
|
invalidateStatic(drawbridge);
|
|
1687
1784
|
```
|
|
1688
1785
|
|
|
1786
|
+
### `isStreamedGeometry`
|
|
1787
|
+
|
|
1788
|
+
`function` — True while a geometry is the coarse companion a streamed model draws first (PRD-860), before its full file replaces it in place. A caller that copies vertices (a trimesh collider, a navmesh bake, a merge) waits with `ctx.assets.model(path, { whole: true })` instead of copying the coarse ones.
|
|
1789
|
+
|
|
1790
|
+
```ts
|
|
1791
|
+
export function isStreamedGeometry(geometry: BufferGeometry): boolean { … }
|
|
1792
|
+
```
|
|
1793
|
+
|
|
1794
|
+
- **Use when:** collider or navmesh built from a model is coarser than what is drawn · wait for the full model before copying its vertices · whole model before collision · TN_COLLIDER_COARSE
|
|
1795
|
+
- **Constraints:** `CollisionShape3D.fromMesh` with "trimesh" or "convexHull" on a streamed geometry warns `TN_COLLIDER_COARSE` naming the mesh and the `{ whole: true }` override, and still builds
|
|
1796
|
+
|
|
1797
|
+
```ts
|
|
1798
|
+
const coarse = isStreamedGeometry(mesh.geometry);
|
|
1799
|
+
```
|
|
1800
|
+
|
|
1689
1801
|
### `isTouchscreenAvailable`
|
|
1690
1802
|
|
|
1691
1803
|
`function` — Read the host platform without reaching for browser globals.
|
|
@@ -1694,11 +1806,12 @@ invalidateStatic(drawbridge);
|
|
|
1694
1806
|
export function isTouchscreenAvailable(): boolean { … }
|
|
1695
1807
|
```
|
|
1696
1808
|
|
|
1697
|
-
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1809
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1698
1810
|
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1699
1811
|
|
|
1700
1812
|
```ts
|
|
1701
1813
|
if (isMobile()) showTouchControls();
|
|
1814
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1702
1815
|
```
|
|
1703
1816
|
|
|
1704
1817
|
### `isWeb`
|
|
@@ -1709,11 +1822,12 @@ if (isMobile()) showTouchControls();
|
|
|
1709
1822
|
export function isWeb(): boolean { … }
|
|
1710
1823
|
```
|
|
1711
1824
|
|
|
1712
|
-
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1825
|
+
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
|
|
1713
1826
|
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1714
1827
|
|
|
1715
1828
|
```ts
|
|
1716
1829
|
if (isMobile()) showTouchControls();
|
|
1830
|
+
if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
|
|
1717
1831
|
```
|
|
1718
1832
|
|
|
1719
1833
|
### `lampPenumbraTangent`
|
|
@@ -1763,6 +1877,21 @@ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TI
|
|
|
1763
1877
|
const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
|
|
1764
1878
|
```
|
|
1765
1879
|
|
|
1880
|
+
### `lodChainOf`
|
|
1881
|
+
|
|
1882
|
+
`function` — The cooked automatic LOD chain (`TN_discrete_lod`) a loaded geometry carries, or `undefined`. Its levels share the base's vertex attributes and differ only in index, and `errors` are each level's world-unit error in the base's own space. A caller that draws one geometry many times (an instanced batch, a streamed world level) reads the reduced shapes here instead of re-cooking.
|
|
1883
|
+
|
|
1884
|
+
```ts
|
|
1885
|
+
export function lodChainOf(geometry: BufferGeometry): ILodChain | undefined { … }
|
|
1886
|
+
```
|
|
1887
|
+
|
|
1888
|
+
- **Use when:** draw a cooked reduced level of a model in an instanced batch or streamed world level
|
|
1889
|
+
- **Constraints:** a geometry the loader built no chain for returns undefined
|
|
1890
|
+
|
|
1891
|
+
```ts
|
|
1892
|
+
const chain = lodChainOf(baseGeometryOf(mesh)); const far = chain?.levels.at(-1);
|
|
1893
|
+
```
|
|
1894
|
+
|
|
1766
1895
|
### `lodPixelScale`
|
|
1767
1896
|
|
|
1768
1897
|
`function` — The screen pixels one world unit covers at `depth` for this camera and viewport. Perspective divides the projected scale by the depth; orthographic has no depth term and uses the frustum height instead. This is the number a level of detail is chosen against: multiply a level's world-space error by it and you have the on-screen error a player can see, which is the comparison `updateModelLods` makes from the baked chain.
|
|
@@ -2016,6 +2145,22 @@ export class ProbeVolume extends Object3D implements IComputeDriven { … }
|
|
|
2016
2145
|
const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
|
|
2017
2146
|
```
|
|
2018
2147
|
|
|
2148
|
+
### `publishDevGlobal`
|
|
2149
|
+
|
|
2150
|
+
`function` — The one name every dev surface publishes under, and the reader/writer for it.
|
|
2151
|
+
|
|
2152
|
+
```ts
|
|
2153
|
+
export function publishDevGlobal(name: string, value: unknown, scope: unknown): void { … }
|
|
2154
|
+
```
|
|
2155
|
+
|
|
2156
|
+
- **Use when:** read or extend the `__THREENATIVE__` object a dev launch publishes
|
|
2157
|
+
- **Constraints:** every dev surface publishes under this key; the worker's typed mirror tuple names it too
|
|
2158
|
+
|
|
2159
|
+
```ts
|
|
2160
|
+
import { DEV_GLOBAL_KEY, devGlobal } from "@threenative/core";
|
|
2161
|
+
const tools = devGlobal(globalThis);
|
|
2162
|
+
```
|
|
2163
|
+
|
|
2019
2164
|
### `qualityPreset`
|
|
2020
2165
|
|
|
2021
2166
|
`function` — The quality tiers of the Unreal 5.8.3 look: what `high` (a desktop, Unreal's Epic), `medium` and `low` (a phone) turn on, how a GPU family picks its start tier, and the global illumination and shadow filter settings per tier named after Unreal's scalability levels. A `WorldEnvironment` with no options starts from `high`. `qualityTiers` holds the tier tables: `resolve` picks a start tier from a GPU class, `gi` and `shadow` read a tier's settings.
|
|
@@ -2032,6 +2177,22 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions { … }
|
|
|
2032
2177
|
const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });
|
|
2033
2178
|
```
|
|
2034
2179
|
|
|
2180
|
+
### `RadianceCache`
|
|
2181
|
+
|
|
2182
|
+
`class` — A probe field of diffuse irradiance that refreshes by tracing the packed scene, with no scene draw: the radiance cache of a dynamic global-illumination pass. Probes in view refresh first, oldest first, within `numProbesToTraceBudget` a frame; a lamp toggled in game code or a sun that steps more than one degree re-traces them while the old values keep lighting the frame.
|
|
2183
|
+
|
|
2184
|
+
```ts
|
|
2185
|
+
export class RadianceCache extends ProbeVolume { … }
|
|
2186
|
+
```
|
|
2187
|
+
|
|
2188
|
+
- **Use when:** light follows a lamp that switches on and off in a room · bounce light that updates when the sun moves, with no baked lightmap · global illumination that refreshes fast enough to read as dynamic
|
|
2189
|
+
- **Constraints:** build a GPUSceneBVH of the static meshes first and pass it as trace.bvh; the cache reads colour and emissive from each material, a texture or a node is counted as ignored · add the cache with ctx.add() so its refresh is measured in the render phase, and read it with sampleNode(position, normal) from a game-owned material · a one-sided material is not seen from behind, as a cube capture would not draw it
|
|
2190
|
+
- **Overrides:** numProbesToTraceBudget (100), probeResolution (8, so 64 rays a probe; 32 for a small emitter), bounds, density, bounces and the sun and sky values are game-owned
|
|
2191
|
+
|
|
2192
|
+
```ts
|
|
2193
|
+
const bvh = new GPUSceneBVH(ctx.scene); ctx.add(bvh); const cache = new RadianceCache({ bounds, density: 0.5, trace: { bvh, sun, sky, camera: ctx.camera } }); ctx.add(cache);
|
|
2194
|
+
```
|
|
2195
|
+
|
|
2035
2196
|
### `readGIMarker`
|
|
2036
2197
|
|
|
2037
2198
|
`function` — Parse a `TN_GI` console line back into its report, or `undefined`.
|
|
@@ -2837,6 +2998,21 @@ export class SurfaceLights { … }
|
|
|
2837
2998
|
const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
|
|
2838
2999
|
```
|
|
2839
3000
|
|
|
3001
|
+
### `thinCards`
|
|
3002
|
+
|
|
3003
|
+
`function` — A far level for a card mesh (needle or leaf quads): keep a share of its cards and grow each kept card about its own centre, so the crown holds its total surface area, as Unreal's Nanite "Preserve Area" foliage does. A simplifier cannot reduce disconnected cards, so the cooked chain leaves them at full count.
|
|
3004
|
+
|
|
3005
|
+
```ts
|
|
3006
|
+
export function thinCards(geometry: BufferGeometry, keep: number): BufferGeometry { … }
|
|
3007
|
+
```
|
|
3008
|
+
|
|
3009
|
+
- **Use when:** far trees draw too many alpha-tested needle or leaf card triangles
|
|
3010
|
+
- **Constraints:** the geometry must be indexed and carry no material groups, else it throws · keep is in (0, 1]; a share that drops nothing returns the same geometry · the choice is deterministic, and the source geometry is left untouched
|
|
3011
|
+
|
|
3012
|
+
```ts
|
|
3013
|
+
const far = thinCards(needles.geometry, 0.4); // 40% of the cards, same area
|
|
3014
|
+
```
|
|
3015
|
+
|
|
2840
3016
|
### `TracedReflections`
|
|
2841
3017
|
|
|
2842
3018
|
`class` — Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material. The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
|
|
@@ -3028,9 +3204,9 @@ tracker.commit(scene);
|
|
|
3028
3204
|
export class VirtualShadowNode extends ShadowBaseNode { … }
|
|
3029
3205
|
```
|
|
3030
3206
|
|
|
3031
|
-
- **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
|
|
3207
|
+
- **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 · shadow edges, tree lighting or level sharpness change while a third-person camera turns around its hero
|
|
3032
3208
|
- **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
|
|
3033
|
-
- **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 · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
|
|
3209
|
+
- **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 · setFocus(point) centres every window on a subject (a third-person hero) instead of the eye, so an orbiting eye moves no shadow; setFocus(undefined) hands them back · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
|
|
3034
3210
|
|
|
3035
3211
|
```ts
|
|
3036
3212
|
const sun = new DirectionalLight(0xffffff, 3);
|
|
@@ -3310,355 +3486,1098 @@ const root = createCssUiRoot();
|
|
|
3310
3486
|
root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
|
|
3311
3487
|
```
|
|
3312
3488
|
|
|
3313
|
-
## `@threenative/core/
|
|
3489
|
+
## `@threenative/core/render/environment`
|
|
3314
3490
|
|
|
3315
|
-
### `
|
|
3491
|
+
### `cachedEnvironmentSample`
|
|
3316
3492
|
|
|
3317
|
-
`function` —
|
|
3493
|
+
`function` — The sample this renderer took of `scene`'s environment, if it is still current.
|
|
3318
3494
|
|
|
3319
3495
|
```ts
|
|
3320
|
-
export function
|
|
3496
|
+
export function cachedEnvironmentSample( renderer: object, scene: Scene, ): IEnvironmentSample | undefined { … }
|
|
3321
3497
|
```
|
|
3322
3498
|
|
|
3323
|
-
- **Use when:**
|
|
3324
|
-
- **Constraints:**
|
|
3499
|
+
- **Use when:** skip a second environment readback in the same frame
|
|
3500
|
+
- **Constraints:** a sample whose source texture or intensity moved is dropped, so a stale one never reaches a material
|
|
3325
3501
|
|
|
3326
3502
|
```ts
|
|
3327
|
-
const
|
|
3503
|
+
const hit = cachedEnvironmentSample(renderer, scene);
|
|
3328
3504
|
```
|
|
3329
3505
|
|
|
3330
|
-
### `
|
|
3506
|
+
### `cacheEnvironmentSample`
|
|
3331
3507
|
|
|
3332
|
-
`function` —
|
|
3508
|
+
`function` — Remembers `sample` as this renderer's reading of `scene`'s environment.
|
|
3333
3509
|
|
|
3334
3510
|
```ts
|
|
3335
|
-
export function
|
|
3511
|
+
export function cacheEnvironmentSample( renderer: object, scene: Scene, sample: IEnvironmentSample, ): void { … }
|
|
3336
3512
|
```
|
|
3337
3513
|
|
|
3338
|
-
- **Use when:**
|
|
3339
|
-
- **Constraints:** prefer game.ui.onIntent, which connects the bridge for you
|
|
3514
|
+
- **Use when:** reuse one environment readback across the materials of a scene
|
|
3340
3515
|
|
|
3341
3516
|
```ts
|
|
3342
|
-
|
|
3517
|
+
cacheEnvironmentSample(renderer, scene, sample);
|
|
3343
3518
|
```
|
|
3344
3519
|
|
|
3345
|
-
### `
|
|
3520
|
+
### `captureEnvironmentSnapshot`
|
|
3346
3521
|
|
|
3347
|
-
`function` —
|
|
3522
|
+
`function` — The provenance of a scene's environment: which texture, at which intensity, in which colour space.
|
|
3348
3523
|
|
|
3349
3524
|
```ts
|
|
3350
|
-
export function
|
|
3525
|
+
export function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot { … }
|
|
3351
3526
|
```
|
|
3352
3527
|
|
|
3353
|
-
- **Use when:**
|
|
3354
|
-
- **Constraints:** mark controls with data-tn-interactive; pointer-events is not the mechanism
|
|
3528
|
+
- **Use when:** reject an environment readback that belongs to a different sky
|
|
3355
3529
|
|
|
3356
3530
|
```ts
|
|
3357
|
-
|
|
3531
|
+
const snapshot = captureEnvironmentSnapshot(scene);
|
|
3358
3532
|
```
|
|
3359
3533
|
|
|
3360
|
-
### `
|
|
3534
|
+
### `environmentSnapshotCurrent`
|
|
3361
3535
|
|
|
3362
|
-
`function` —
|
|
3536
|
+
`function` — Whether the scene's environment still matches the snapshot a sample was taken from.
|
|
3363
3537
|
|
|
3364
3538
|
```ts
|
|
3365
|
-
export function
|
|
3539
|
+
export function environmentSnapshotCurrent( scene: Scene, snapshot: IEnvironmentSourceSnapshot, ): boolean { … }
|
|
3366
3540
|
```
|
|
3367
3541
|
|
|
3368
|
-
- **Use when:**
|
|
3369
|
-
- **Constraints:** publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening
|
|
3542
|
+
- **Use when:** hold a material's fill light to the sky that is on screen now
|
|
3370
3543
|
|
|
3371
3544
|
```ts
|
|
3372
|
-
|
|
3545
|
+
if (environmentSnapshotCurrent(scene, snapshot)) draw(snapshot);
|
|
3373
3546
|
```
|
|
3374
3547
|
|
|
3375
|
-
### `
|
|
3548
|
+
### `isWebGLFallbackRenderer`
|
|
3376
3549
|
|
|
3377
|
-
`function` —
|
|
3550
|
+
`function` — Whether a `WebGPURenderer` wrapper is running three's WebGL backend behind it.
|
|
3378
3551
|
|
|
3379
3552
|
```ts
|
|
3380
|
-
export function
|
|
3553
|
+
export function isWebGLFallbackRenderer(renderer: unknown): boolean { … }
|
|
3381
3554
|
```
|
|
3382
3555
|
|
|
3383
|
-
- **Use when:**
|
|
3384
|
-
- **Constraints:** one-way; the game decides what each name means and may ignore one
|
|
3556
|
+
- **Use when:** refuse a GPU-only lane on a WebGL fallback instead of drawing something wrong
|
|
3385
3557
|
|
|
3386
3558
|
```ts
|
|
3387
|
-
|
|
3559
|
+
if (isWebGLFallbackRenderer(renderer)) skipMaterialLane();
|
|
3388
3560
|
```
|
|
3389
3561
|
|
|
3390
|
-
### `
|
|
3562
|
+
### `materialLightingEnabled`
|
|
3391
3563
|
|
|
3392
|
-
`function` —
|
|
3564
|
+
`function` — Whether `tier` may run the material-lighting lane in `environment`.
|
|
3393
3565
|
|
|
3394
3566
|
```ts
|
|
3395
|
-
export function
|
|
3567
|
+
export function materialLightingEnabled( tier: QualityTier, environment: IMaterialLightingEnvironment, ): boolean { … }
|
|
3396
3568
|
```
|
|
3397
3569
|
|
|
3398
|
-
- **Use when:**
|
|
3399
|
-
- **Constraints:**
|
|
3570
|
+
- **Use when:** decide whether this renderer is the admitted material lane
|
|
3571
|
+
- **Constraints:** high tier, browser, hardware WebGPU, not mobile, not software, not a WebGL fallback
|
|
3400
3572
|
|
|
3401
3573
|
```ts
|
|
3402
|
-
|
|
3574
|
+
if (materialLightingEnabled("high", env)) lightMaterials();
|
|
3403
3575
|
```
|
|
3404
3576
|
|
|
3405
|
-
|
|
3406
|
-
|
|
3407
|
-
### `serveWorkerGame`
|
|
3577
|
+
### `measureEnvironment`
|
|
3408
3578
|
|
|
3409
|
-
`function` —
|
|
3579
|
+
`function` — The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).
|
|
3410
3580
|
|
|
3411
3581
|
```ts
|
|
3412
|
-
export function
|
|
3582
|
+
export function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement { … }
|
|
3413
3583
|
```
|
|
3414
3584
|
|
|
3415
|
-
- **Use when:**
|
|
3585
|
+
- **Use when:** measure what a scene's environment actually contributes · sample the environment on the GPU without stalling the frame · keep an environment readback from reaching a frame it does not belong to
|
|
3416
3586
|
|
|
3417
3587
|
```ts
|
|
3418
|
-
|
|
3588
|
+
const m = measureEnvironment(scene, 2048);
|
|
3419
3589
|
```
|
|
3420
3590
|
|
|
3421
|
-
### `
|
|
3591
|
+
### `reportEnvironmentContribution`
|
|
3422
3592
|
|
|
3423
|
-
`function` —
|
|
3593
|
+
`function` — The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).
|
|
3424
3594
|
|
|
3425
3595
|
```ts
|
|
3426
|
-
export function
|
|
3596
|
+
export function reportEnvironmentContribution( scene: Scene, options: IContributionControls, measurement?: IEnvironmentMeasurement, ) { … }
|
|
3427
3597
|
```
|
|
3428
3598
|
|
|
3429
|
-
- **Use when:**
|
|
3599
|
+
- **Use when:** measure what a scene's environment actually contributes · sample the environment on the GPU without stalling the frame · keep an environment readback from reaching a frame it does not belong to
|
|
3430
3600
|
|
|
3431
3601
|
```ts
|
|
3432
|
-
|
|
3602
|
+
reportEnvironmentContribution(scene, {
|
|
3603
|
+
darkThreshold: 0.02, fillAdmitted: true, fillColor: new Color(1, 1, 1), fillGain: 0.4,
|
|
3604
|
+
maxSourceTexels: 2048, rimGain: 0.6,
|
|
3605
|
+
});
|
|
3433
3606
|
```
|
|
3434
3607
|
|
|
3435
|
-
|
|
3436
|
-
|
|
3437
|
-
### `cellPlacements`
|
|
3608
|
+
### `sampledRadiance`
|
|
3438
3609
|
|
|
3439
|
-
`function` —
|
|
3610
|
+
`function` — The mean radiance and colour of a bounded linear sample, or `unknown` with the reason.
|
|
3440
3611
|
|
|
3441
3612
|
```ts
|
|
3442
|
-
export function
|
|
3613
|
+
export function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement { … }
|
|
3443
3614
|
```
|
|
3444
3615
|
|
|
3445
|
-
- **Use when:**
|
|
3446
|
-
- **Constraints:** the
|
|
3616
|
+
- **Use when:** turn an environment readback into the radiance a material's fill light needs · know why an environment sample could not be measured
|
|
3617
|
+
- **Constraints:** the sample must be the qualified 64x32 float RGBA readback; anything else is refused by name
|
|
3447
3618
|
|
|
3448
3619
|
```ts
|
|
3449
|
-
const
|
|
3620
|
+
const m = sampledRadiance(readback, 1);
|
|
3450
3621
|
```
|
|
3451
3622
|
|
|
3452
|
-
### `
|
|
3623
|
+
### `sampleEnvironment`
|
|
3453
3624
|
|
|
3454
|
-
`function` —
|
|
3625
|
+
`function` — Measures and samples the scene's real environment on the GPU, bounded by a readback deadline.
|
|
3455
3626
|
|
|
3456
3627
|
```ts
|
|
3457
|
-
export function
|
|
3628
|
+
export async function sampleEnvironment( renderer: unknown, scene: Scene, environment: IMaterialLightingEnvironment, ): Promise<IEnvironmentSample> { … }
|
|
3458
3629
|
```
|
|
3459
3630
|
|
|
3460
|
-
- **Use when:**
|
|
3461
|
-
- **Constraints:**
|
|
3462
|
-
- **Overrides:** minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations
|
|
3631
|
+
- **Use when:** measure what a scene's environment actually contributes without stalling the frame · give a material's fill light the environment's own radiance
|
|
3632
|
+
- **Constraints:** off unless the renderer is the admitted high-tier WebGPU lane; every refusal is reported by name · the readback is abandoned after the deadline and the frame keeps the previous answer
|
|
3463
3633
|
|
|
3464
3634
|
```ts
|
|
3465
|
-
const
|
|
3635
|
+
const sample = await sampleEnvironment(renderer, scene, env);
|
|
3466
3636
|
```
|
|
3467
3637
|
|
|
3468
|
-
### `
|
|
3638
|
+
### `samplingSourceSupported`
|
|
3469
3639
|
|
|
3470
|
-
`
|
|
3640
|
+
`function` — Whether an environment texture's mapping and colour space are qualified for the bounded GPU sample.
|
|
3471
3641
|
|
|
3472
3642
|
```ts
|
|
3473
|
-
export
|
|
3643
|
+
export function samplingSourceSupported(source: NonNullable<Scene["environment"]>): boolean { … }
|
|
3474
3644
|
```
|
|
3475
3645
|
|
|
3476
|
-
- **Use when:**
|
|
3477
|
-
- **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
|
|
3478
|
-
- **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
|
|
3646
|
+
- **Use when:** know why an environment was not sampled on the GPU
|
|
3479
3647
|
|
|
3480
3648
|
```ts
|
|
3481
|
-
|
|
3649
|
+
if (samplingSourceSupported(source)) sample(source);
|
|
3482
3650
|
```
|
|
3483
3651
|
|
|
3484
|
-
|
|
3652
|
+
## `@threenative/core/spells`
|
|
3485
3653
|
|
|
3486
|
-
|
|
3654
|
+
### `CastPool`
|
|
3655
|
+
|
|
3656
|
+
`class` — Step a spell's timeline: charge, release, travel, impact, linger, done.
|
|
3487
3657
|
|
|
3488
3658
|
```ts
|
|
3489
|
-
export
|
|
3659
|
+
export class CastPool { … }
|
|
3490
3660
|
```
|
|
3491
3661
|
|
|
3492
|
-
- **Use when:**
|
|
3493
|
-
- **Constraints:** the
|
|
3662
|
+
- **Use when:** a fireball or a lightning bolt that charges, flies, lands and lingers · several spells mid-flight, with no allocation per cast
|
|
3663
|
+
- **Constraints:** the pool is fixed and recycles the cast alive longest; it never grows · a ball that has passed its target lands on the target, however late the frame notices
|
|
3664
|
+
- **Overrides:** timing, shape, speed and radius come from the spell; a cast may override shape and seed
|
|
3494
3665
|
|
|
3495
3666
|
```ts
|
|
3496
|
-
const
|
|
3667
|
+
const casts = new CastPool(world);
|
|
3668
|
+
casts.cast(fireball, target, { from: hand });
|
|
3669
|
+
casts.update(dt);
|
|
3497
3670
|
```
|
|
3498
3671
|
|
|
3499
|
-
### `
|
|
3672
|
+
### `createAegis`
|
|
3500
3673
|
|
|
3501
|
-
`function` —
|
|
3674
|
+
`function` — A ward around the caster: it forms, holds, and breaks outward when it expires.
|
|
3502
3675
|
|
|
3503
3676
|
```ts
|
|
3504
|
-
export
|
|
3677
|
+
export function createAegis(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3505
3678
|
```
|
|
3506
3679
|
|
|
3507
|
-
- **Use when:**
|
|
3508
|
-
- **Constraints:**
|
|
3509
|
-
- **Overrides:**
|
|
3680
|
+
- **Use when:** a shield spell a player casts on themselves · a magic barrier that forms around the caster · make a protective bubble spell · a defensive bubble that flashes when it breaks
|
|
3681
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3682
|
+
- **Overrides:** core, highlight, charge, impact, linger, radius, light · core, highlight, charge, impact, linger, radius, light, shake
|
|
3510
3683
|
|
|
3511
3684
|
```ts
|
|
3512
|
-
const
|
|
3513
|
-
|
|
3685
|
+
const aegis = createAegis(world);
|
|
3686
|
+
casts.cast(aegis, world.focus);
|
|
3514
3687
|
```
|
|
3515
3688
|
|
|
3516
|
-
### `
|
|
3689
|
+
### `createArcaneBarrage`
|
|
3517
3690
|
|
|
3518
|
-
`function` —
|
|
3691
|
+
`function` — A volley of arcane missiles: fast, precise, and each one pops on arrival.
|
|
3519
3692
|
|
|
3520
3693
|
```ts
|
|
3521
|
-
export
|
|
3694
|
+
export function createArcaneBarrage(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3522
3695
|
```
|
|
3523
3696
|
|
|
3524
|
-
- **Use when:**
|
|
3525
|
-
- **Constraints:**
|
|
3697
|
+
- **Use when:** an arcane missile spell that fires projectiles at a target · a magic barrage a mage class spams · a magic missile spell · make an arcane bolt spell · an arcane missile spell that fires several projectiles at a target · a pink energy bolt with a short charge
|
|
3698
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3699
|
+
- **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, light
|
|
3526
3700
|
|
|
3527
3701
|
```ts
|
|
3528
|
-
const
|
|
3702
|
+
const barrage = createArcaneBarrage(world);
|
|
3703
|
+
casts.cast(barrage, target);
|
|
3529
3704
|
```
|
|
3530
3705
|
|
|
3531
|
-
### `
|
|
3706
|
+
### `createFireball`
|
|
3532
3707
|
|
|
3533
|
-
`function` — A
|
|
3708
|
+
`function` — A ball of fire that charges, crosses the room and leaves the floor burning.
|
|
3534
3709
|
|
|
3535
3710
|
```ts
|
|
3536
|
-
export function
|
|
3711
|
+
export function createFireball(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3537
3712
|
```
|
|
3538
3713
|
|
|
3539
|
-
- **Use when:**
|
|
3540
|
-
- **Constraints:**
|
|
3541
|
-
- **Overrides:**
|
|
3714
|
+
- **Use when:** a fireball spell the player casts at an enemy · a burning projectile that explodes and scorches the ground · a wizard's fire attack with a wind-up, a flight and an aftermath · make a fireball · a fireball spell a player casts at an enemy
|
|
3715
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call · the first cast costs what the hundredth does: nothing is built at cast time · the stock look ships as the default, and no override rebuilds a pipeline
|
|
3716
|
+
- **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch
|
|
3542
3717
|
|
|
3543
3718
|
```ts
|
|
3544
|
-
const
|
|
3719
|
+
const fireball = createFireball(world);
|
|
3720
|
+
casts.cast(fireball, target);
|
|
3545
3721
|
```
|
|
3546
3722
|
|
|
3547
|
-
### `
|
|
3723
|
+
### `createGlacialSpike`
|
|
3548
3724
|
|
|
3549
|
-
`
|
|
3725
|
+
`function` — A shard of ice that flies flat and fast, and freezes the ground it breaks on.
|
|
3550
3726
|
|
|
3551
3727
|
```ts
|
|
3552
|
-
export
|
|
3728
|
+
export function createGlacialSpike(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3553
3729
|
```
|
|
3554
3730
|
|
|
3555
|
-
- **Use when:**
|
|
3556
|
-
- **Constraints:**
|
|
3557
|
-
- **
|
|
3558
|
-
- **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
|
|
3731
|
+
- **Use when:** an ice spike spell that flies at a target and shatters · a freezing projectile that leaves frost on the floor · make an ice spell · a cold spell with a charge, a flight and a lingering chill
|
|
3732
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3733
|
+
- **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, trail, light
|
|
3559
3734
|
|
|
3560
3735
|
```ts
|
|
3561
|
-
|
|
3562
|
-
|
|
3563
|
-
const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
|
|
3564
|
-
snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
|
|
3565
|
-
snow.recover(1 / 60, 0.0012, 0.4);
|
|
3736
|
+
const spike = createGlacialSpike(world);
|
|
3737
|
+
casts.cast(spike, target);
|
|
3566
3738
|
```
|
|
3567
3739
|
|
|
3568
|
-
### `
|
|
3740
|
+
### `createInferno`
|
|
3569
3741
|
|
|
3570
|
-
`
|
|
3742
|
+
`function` — A pillar of fire that erupts where it lands and keeps burning.
|
|
3571
3743
|
|
|
3572
3744
|
```ts
|
|
3573
|
-
export
|
|
3745
|
+
export function createInferno(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3574
3746
|
```
|
|
3575
3747
|
|
|
3576
|
-
- **Use when:**
|
|
3577
|
-
- **Constraints:**
|
|
3578
|
-
- **Overrides:**
|
|
3748
|
+
- **Use when:** a fire area spell that erupts at a point and burns there · an inferno column a boss drops on the arena · make a sustained fire area spell · a sustained flame that scorches the ground for seconds
|
|
3749
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3750
|
+
- **Overrides:** core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch
|
|
3579
3751
|
|
|
3580
3752
|
```ts
|
|
3581
|
-
const
|
|
3753
|
+
const inferno = createInferno(world);
|
|
3754
|
+
casts.cast(inferno, target);
|
|
3582
3755
|
```
|
|
3583
3756
|
|
|
3584
|
-
### `
|
|
3757
|
+
### `createSpell`
|
|
3585
3758
|
|
|
3586
|
-
`function` —
|
|
3759
|
+
`function` — Build a spell from a recipe: four beats, a tint, and the numbers between them.
|
|
3587
3760
|
|
|
3588
3761
|
```ts
|
|
3589
|
-
export function
|
|
3762
|
+
export function createSpell(world: SpellWorld, recipe: ISpellRecipe): ISpell { … }
|
|
3590
3763
|
```
|
|
3591
3764
|
|
|
3592
|
-
- **Use when:**
|
|
3593
|
-
- **Constraints:**
|
|
3765
|
+
- **Use when:** author a spell the catalog does not cover, out of the same beats
|
|
3766
|
+
- **Constraints:** read the world through SpellWorld only, so a game can swap the scene and the floor
|
|
3594
3767
|
|
|
3595
3768
|
```ts
|
|
3596
|
-
|
|
3597
|
-
// environment variable, a browser asks with the query string, a test or harness sets the
|
|
3598
|
-
// global. `0` and `false` are off, so a saved URL that enabled it still says "off".
|
|
3599
|
-
const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
|
|
3769
|
+
const spell = createSpell(world, recipe);
|
|
3600
3770
|
```
|
|
3601
3771
|
|
|
3602
|
-
### `
|
|
3772
|
+
### `createThunderstrike`
|
|
3603
3773
|
|
|
3604
|
-
`function` —
|
|
3774
|
+
`function` — A bolt out of the sky: it charges, strikes the point instantly, and the ground remembers it.
|
|
3605
3775
|
|
|
3606
3776
|
```ts
|
|
3607
|
-
export function
|
|
3777
|
+
export function createThunderstrike(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3608
3778
|
```
|
|
3609
3779
|
|
|
3610
|
-
- **Use when:**
|
|
3611
|
-
- **Constraints:**
|
|
3780
|
+
- **Use when:** a lightning strike spell that hits a point immediately · a thunderbolt with a wind-up and a burnt mark where it lands · make a lightning spell · an electrical spell with a column of light from above
|
|
3781
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3782
|
+
- **Overrides:** core, highlight, charge, impact, linger, radius, light, shake, scorch
|
|
3612
3783
|
|
|
3613
3784
|
```ts
|
|
3614
|
-
const
|
|
3785
|
+
const bolt = createThunderstrike(world);
|
|
3786
|
+
casts.cast(bolt, target);
|
|
3615
3787
|
```
|
|
3616
3788
|
|
|
3617
|
-
### `
|
|
3789
|
+
### `ParticleKindTable`
|
|
3618
3790
|
|
|
3619
|
-
`class` —
|
|
3791
|
+
`class` — Tune what a particle kind does, as data rather than a shader.
|
|
3620
3792
|
|
|
3621
3793
|
```ts
|
|
3622
|
-
export class
|
|
3794
|
+
export class ParticleKindTable { … }
|
|
3623
3795
|
```
|
|
3624
3796
|
|
|
3625
|
-
- **Use when:**
|
|
3626
|
-
- **Constraints:**
|
|
3627
|
-
- **Overrides:**
|
|
3797
|
+
- **Use when:** retune a spell's particles at run time from a settings screen · change how long, how fast or how heavy a kind of particle is without a new pipeline
|
|
3798
|
+
- **Constraints:** set writes uniforms; no kernel, material or pipeline is rebuilt · a table knows only the kinds it was asked for, so an unused kind costs nothing
|
|
3799
|
+
- **Overrides:** lifetime, size, speed, cone, gravity, drag, buoyancy, alpha, colour and highlight
|
|
3628
3800
|
|
|
3629
3801
|
```ts
|
|
3630
|
-
const
|
|
3631
|
-
|
|
3632
|
-
world.update();
|
|
3802
|
+
const kinds = new ParticleKindTable(["flame", "smoke"]);
|
|
3803
|
+
kinds.set("flame", { lifetime: [0.3, 0.6], colour: [0.4, 0.8, 1] });
|
|
3633
3804
|
```
|
|
3634
3805
|
|
|
3635
|
-
|
|
3636
|
-
|
|
3637
|
-
### `assertAssetPath`
|
|
3806
|
+
### `ReactionField`
|
|
3638
3807
|
|
|
3639
|
-
`
|
|
3808
|
+
`class` — The marks a spell leaves on the floor: heat, char, wet, frost, crack and glow.
|
|
3640
3809
|
|
|
3641
3810
|
```ts
|
|
3642
|
-
export
|
|
3811
|
+
export class ReactionField { … }
|
|
3643
3812
|
```
|
|
3644
3813
|
|
|
3645
|
-
- **Use when:**
|
|
3646
|
-
- **Constraints:**
|
|
3647
|
-
- **
|
|
3814
|
+
- **Use when:** a fireball impact that leaves a scorch and fades over time · ice that melts where lightning spread, or a lava geyser's crack
|
|
3815
|
+
- **Constraints:** it draws nothing; the game decides what a mark looks like · the patch is finite and every channel decays on its own half-life
|
|
3816
|
+
- **Overrides:** halfLife, resolution and size tune the patch; pattern, radius, seed and angle set each mark
|
|
3648
3817
|
|
|
3649
3818
|
```ts
|
|
3650
|
-
|
|
3819
|
+
field.splat({ heat: 1, char: 0.6, radius: 2.5, x: hit.x, z: hit.z });
|
|
3820
|
+
field.update(dt);
|
|
3651
3821
|
```
|
|
3652
3822
|
|
|
3653
|
-
### `
|
|
3823
|
+
### `SpellLights`
|
|
3654
3824
|
|
|
3655
|
-
`
|
|
3825
|
+
`class` — A fixed pool of spell lights, created once at zero intensity.
|
|
3656
3826
|
|
|
3657
3827
|
```ts
|
|
3658
|
-
|
|
3828
|
+
export class SpellLights { … }
|
|
3659
3829
|
```
|
|
3660
3830
|
|
|
3661
|
-
- **Use when:**
|
|
3831
|
+
- **Use when:** a spell impact that glows without changing the light count · a charge glow or a falling meteor lighting what it passes
|
|
3832
|
+
- **Constraints:** the whole pool exists before the first cast; a cast changes intensity, never the list · flash returns undefined when the pool is busy; a spell carries on without one
|
|
3833
|
+
- **Overrides:** count is the pool size; each flash supplies position, colour, intensity, range and seconds
|
|
3834
|
+
|
|
3835
|
+
```ts
|
|
3836
|
+
lights.flash({ x, y, z, color, intensity: 40, range: 12, seconds: 0.35 });
|
|
3837
|
+
```
|
|
3838
|
+
|
|
3839
|
+
### `SpellWorld`
|
|
3840
|
+
|
|
3841
|
+
`class` — Everything a spell may touch: the scene, the floor, the light pool, the surface field, one shake and one flash limiter.
|
|
3842
|
+
|
|
3843
|
+
```ts
|
|
3844
|
+
export class SpellWorld implements ICastEnvironment { … }
|
|
3845
|
+
```
|
|
3846
|
+
|
|
3847
|
+
- **Use when:** cast an engine spell without passing a scene into every call · honour an accessibility setting that limits flashing
|
|
3848
|
+
- **Constraints:** damage, mana, cooldowns and who the target is stay in the game · with reducedFlashes on, a fourth flash inside one second is refused, never dimmed
|
|
3849
|
+
- **Overrides:** groundAt, castSlots, lightCount, reaction, shake and reducedFlashes are named options
|
|
3850
|
+
|
|
3851
|
+
```ts
|
|
3852
|
+
const world = new SpellWorld({ scene, groundAt });
|
|
3853
|
+
const casts = new CastPool(world);
|
|
3854
|
+
```
|
|
3855
|
+
|
|
3856
|
+
## `@threenative/core/spells/ultra`
|
|
3857
|
+
|
|
3858
|
+
### `bakeNoise`
|
|
3859
|
+
|
|
3860
|
+
`function` — CPU bake of the Ultra Elements 3D noise, curl and blackbody textures that every spell volume samples.
|
|
3861
|
+
|
|
3862
|
+
```ts
|
|
3863
|
+
export function bakeNoise( { … }
|
|
3864
|
+
```
|
|
3865
|
+
|
|
3866
|
+
- **Use when:** the noise and blackbody textures an Ultra Elements spell needs before it first draws
|
|
3867
|
+
- **Constraints:** costs about 0.6 s at 64^3 and about 5 s at 128^3 on the main thread; bake once at load
|
|
3868
|
+
|
|
3869
|
+
```ts
|
|
3870
|
+
bakeNoise({ noiseSize: 64 }); // once at load, before createFx draws
|
|
3871
|
+
```
|
|
3872
|
+
|
|
3873
|
+
### `createFx`
|
|
3874
|
+
|
|
3875
|
+
`function` — The shared Ultra Elements spell world: casts, volumes, spell lights and the per-frame CPU tick. Add `fx.scenes.fx` to the scene, `addSpell` each ported spell, call `renderFrame(dt)` each frame.
|
|
3876
|
+
|
|
3877
|
+
```ts
|
|
3878
|
+
export function createFx(o: IFxOptions) { … }
|
|
3879
|
+
```
|
|
3880
|
+
|
|
3881
|
+
- **Use when:** an Ultra Elements spell such as the raymarched teardrop Fireball cast at a target · a volumetric fire spell drawn through the Three.js TSL node API on WebGPU
|
|
3882
|
+
- **Constraints:** call bakeNoise first: the volume shaders sample its noise, curl and blackbody textures
|
|
3883
|
+
|
|
3884
|
+
```ts
|
|
3885
|
+
const ultra = createFx({ camera, size: () => ({ width: innerWidth, height: innerHeight }), seed: 777 }); const fireball = ultra.addSpell(fire); scene.add(ultra.fx.scenes.fx);
|
|
3886
|
+
```
|
|
3887
|
+
|
|
3888
|
+
### `groundShade`
|
|
3889
|
+
|
|
3890
|
+
`function` — The Ultra Elements arena floor's response to the ground field and spell impacts (scorch, char, wet, glowing hot ground) as nodes for a game's own floor material: `color`, `roughness`, `metalness`, `emissive` from the floor's own surface at a world position.
|
|
3891
|
+
|
|
3892
|
+
```ts
|
|
3893
|
+
export function groundShade(wp: V3, surface: IGroundSurface) { … }
|
|
3894
|
+
```
|
|
3895
|
+
|
|
3896
|
+
- **Use when:** a floor that shows the Fireball's scorch and hot ground cooling over seconds
|
|
3897
|
+
|
|
3898
|
+
```ts
|
|
3899
|
+
const shade = groundShade(positionWorld, { albedo, rough: float(0.85), metal: float(0) }); floor.colorNode = vec4(shade.color, 1);
|
|
3900
|
+
```
|
|
3901
|
+
|
|
3902
|
+
### `Particles`
|
|
3903
|
+
|
|
3904
|
+
`class` — The Ultra Elements GPU particle system behind `fx.particles`: a spell's kinds, emitters and field emitters.
|
|
3905
|
+
|
|
3906
|
+
```ts
|
|
3907
|
+
export class Particles { … }
|
|
3908
|
+
```
|
|
3909
|
+
|
|
3910
|
+
- **Use when:** the flames, embers, sparks, smoke and debris an Ultra Elements spell emits as it charges, flies and hits
|
|
3911
|
+
|
|
3912
|
+
```ts
|
|
3913
|
+
const flames = ultra.fx.particles.emitter("fire.flame"); // ultra from createFx
|
|
3914
|
+
```
|
|
3915
|
+
|
|
3916
|
+
## `@threenative/core/ui-layer`
|
|
3917
|
+
|
|
3918
|
+
### `connectUiBridge`
|
|
3919
|
+
|
|
3920
|
+
`function` — Open the message channel between a game and its UI, whatever host is underneath.
|
|
3921
|
+
|
|
3922
|
+
```ts
|
|
3923
|
+
export function connectUiBridge(options: IConnectOptions): IUiBridge { … }
|
|
3924
|
+
```
|
|
3925
|
+
|
|
3926
|
+
- **Use when:** write a UI that talks to the game on web and on a phone alike · send a message from a HUD rendered over the game surface · connect game code to a platform-owned UI realm · share one UI bridge implementation across web, Android, iOS, and desktop
|
|
3927
|
+
- **Constraints:** the transport is discovered, never configured; no game names the web view
|
|
3928
|
+
|
|
3929
|
+
```ts
|
|
3930
|
+
const bridge = connectUiBridge({ end: "ui" });
|
|
3931
|
+
```
|
|
3932
|
+
|
|
3933
|
+
### `onUiIntent`
|
|
3934
|
+
|
|
3935
|
+
`function` — Handle the actions a UI sends back to the game.
|
|
3936
|
+
|
|
3937
|
+
```ts
|
|
3938
|
+
export function onUiIntent( bridge: IUiBridge, listener: (intent: string, payload: unknown) => void, ): () => void { … }
|
|
3939
|
+
```
|
|
3940
|
+
|
|
3941
|
+
- **Use when:** restart or pause a game from a button in its HUD · handle a HUD button action in game code · route native and web UI commands through one listener
|
|
3942
|
+
- **Constraints:** prefer game.ui.onIntent, which connects the bridge for you
|
|
3943
|
+
|
|
3944
|
+
```ts
|
|
3945
|
+
onUiIntent(bridge, (intent) => { if (intent === "restart") game.goto("Play"); });
|
|
3946
|
+
```
|
|
3947
|
+
|
|
3948
|
+
### `publishHitRegions`
|
|
3949
|
+
|
|
3950
|
+
`function` — Tell the native input host where a UI's touchable controls are.
|
|
3951
|
+
|
|
3952
|
+
```ts
|
|
3953
|
+
export function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry { … }
|
|
3954
|
+
```
|
|
3955
|
+
|
|
3956
|
+
- **Use when:** let a touch on empty HUD space reach the game instead of the UI · make a HUD button receive taps on a phone · give native input hosts the rectangles claimed by UI controls · keep touch hit testing aligned with a moving web or native HUD
|
|
3957
|
+
- **Constraints:** mark controls with data-tn-interactive; pointer-events is not the mechanism
|
|
3958
|
+
|
|
3959
|
+
```ts
|
|
3960
|
+
publishHitRegions({ bridge });
|
|
3961
|
+
```
|
|
3962
|
+
|
|
3963
|
+
### `publishUiState`
|
|
3964
|
+
|
|
3965
|
+
`function` — Publish the game's state so a UI in another process can mirror it.
|
|
3966
|
+
|
|
3967
|
+
```ts
|
|
3968
|
+
export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }
|
|
3969
|
+
```
|
|
3970
|
+
|
|
3971
|
+
- **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same coalesced state stream
|
|
3972
|
+
- **Constraints:** publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening
|
|
3973
|
+
|
|
3974
|
+
```ts
|
|
3975
|
+
publishUiState(bridge, game.state);
|
|
3976
|
+
```
|
|
3977
|
+
|
|
3978
|
+
### `sendUiIntent`
|
|
3979
|
+
|
|
3980
|
+
`function` — Send a player action from the UI back to the game.
|
|
3981
|
+
|
|
3982
|
+
```ts
|
|
3983
|
+
export function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void { … }
|
|
3984
|
+
```
|
|
3985
|
+
|
|
3986
|
+
- **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu drawn over its surface · send a button or menu action from a UI HUD to game code · keep UI input portable across web and native hosts
|
|
3987
|
+
- **Constraints:** one-way; the game decides what each name means and may ignore one
|
|
3988
|
+
|
|
3989
|
+
```ts
|
|
3990
|
+
sendUiIntent(bridge, "restart");
|
|
3991
|
+
```
|
|
3992
|
+
|
|
3993
|
+
### `subscribeUiState`
|
|
3994
|
+
|
|
3995
|
+
`function` — Mirror the game's published state on the UI side.
|
|
3996
|
+
|
|
3997
|
+
```ts
|
|
3998
|
+
export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { … }
|
|
3999
|
+
```
|
|
4000
|
+
|
|
4001
|
+
- **Use when:** read game state from a HUD that runs in the platform's web view · read published game state from a UI HUD · subscribe a web or native UI to the game's mirrored state
|
|
4002
|
+
- **Constraints:** returns undefined until the game publishes its first state
|
|
4003
|
+
|
|
4004
|
+
```ts
|
|
4005
|
+
const mirror = subscribeUiState(bridge);
|
|
4006
|
+
```
|
|
4007
|
+
|
|
4008
|
+
## `@threenative/core/worker`
|
|
4009
|
+
|
|
4010
|
+
### `serveWorkerGame`
|
|
4011
|
+
|
|
4012
|
+
`function` — Runs inside the worker: wire the page's messages to the unchanged portable game. Call it last in the worker entry, after the game module evaluated: it posts the ready message the page waits for before it sends the canvas.
|
|
4013
|
+
|
|
4014
|
+
```ts
|
|
4015
|
+
export function serveWorkerGame( game: { … }
|
|
4016
|
+
```
|
|
4017
|
+
|
|
4018
|
+
- **Use when:** run the game loop in a web worker so a busy page cannot stall its frames
|
|
4019
|
+
|
|
4020
|
+
```ts
|
|
4021
|
+
serveWorkerGame(game);
|
|
4022
|
+
```
|
|
4023
|
+
|
|
4024
|
+
### `startWorkerGame`
|
|
4025
|
+
|
|
4026
|
+
`function` — Runs on the page: own the canvas and the DOM, and feed the worker game. Call it before the UI mounts: the HUD's bridge host globals exist from this call on.
|
|
4027
|
+
|
|
4028
|
+
```ts
|
|
4029
|
+
export function startWorkerGame( worker: Worker, container: HTMLElement, ): { … }
|
|
4030
|
+
```
|
|
4031
|
+
|
|
4032
|
+
- **Use when:** host a worker-run game's canvas, input and HUD on the page
|
|
4033
|
+
|
|
4034
|
+
```ts
|
|
4035
|
+
const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }), root);
|
|
4036
|
+
```
|
|
4037
|
+
|
|
4038
|
+
## `@threenative/core/world`
|
|
4039
|
+
|
|
4040
|
+
### `AdmissionBudget`
|
|
4041
|
+
|
|
4042
|
+
`class` — One frame's admission allowance, shared by every path that puts streamed content on screen. A streaming world has no frame-time ceiling anywhere else: a cell row arriving builds a batch per asset run over every placement in it, a terrain tile builds every LOD level, and the game's `createCollider` runs for every resident tile — all in the one frame that discovers them. That is the 100-330 ms hitch a 60 m/s camera feels every time the ring moves, and it is admission cost, not streaming: the loads never fail. The budget is opened once per `update` and drawn down by the units it admits. A unit always finishes, so a frame spends at most the limit plus the unit that crossed it, and the rest of the backlog waits for the next frame rather than being dropped.
|
|
4043
|
+
|
|
4044
|
+
```ts
|
|
4045
|
+
export class AdmissionBudget implements IAdmissionBudget { … }
|
|
4046
|
+
```
|
|
4047
|
+
|
|
4048
|
+
- **Use when:** streamed terrain tiles or cells hitch the frame that admits them · cap how many milliseconds a frame spends building streamed content
|
|
4049
|
+
- **Constraints:** open a new budget each frame; a unit always finishes, so one unit can cross the limit
|
|
4050
|
+
|
|
4051
|
+
```ts
|
|
4052
|
+
tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));
|
|
4053
|
+
```
|
|
4054
|
+
|
|
4055
|
+
### `applyTerrainSurface`
|
|
4056
|
+
|
|
4057
|
+
`function` — Apply a cooked GLB's package-authored layered surface to its marked terrain meshes. `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.
|
|
4058
|
+
|
|
4059
|
+
```ts
|
|
4060
|
+
export async function applyTerrainSurface( root: Object3D, options: ILoadTerrainSplatOptions, ): Promise<void> { … }
|
|
4061
|
+
```
|
|
4062
|
+
|
|
4063
|
+
- **Use when:** apply the authored layered terrain surface after loading a cooked world GLB
|
|
4064
|
+
- **Constraints:** url names the loaded GLB; tnTerrainSurface extras name a relative world package JSON
|
|
4065
|
+
- **Overrides:** `table` may replace `base`, `breakup`, `macro` and `layers`; baked `splat` and `textures` stay package-owned
|
|
4066
|
+
|
|
4067
|
+
```ts
|
|
4068
|
+
await applyTerrainSurface(world.scene, { assets: ctx.assets, renderer: ctx.renderer, url: "world/world.glb" });
|
|
4069
|
+
```
|
|
4070
|
+
|
|
4071
|
+
### `bakedFractalNoise`
|
|
4072
|
+
|
|
4073
|
+
`function` — Drop-in for `mx_fractal_noise_float(p, octaves, lacunarity, diminish, amplitude)`: one read an octave.
|
|
4074
|
+
|
|
4075
|
+
```ts
|
|
4076
|
+
export function bakedFractalNoise( p: Node<"vec3">, octaves = 3, lacunarity = 2, diminish = 0.5, amplitude: Scalar = 1, ): Node<"float"> { … }
|
|
4077
|
+
```
|
|
4078
|
+
|
|
4079
|
+
- **Use when:** fractal or fbm noise in a material costs too much GPU time per pixel
|
|
4080
|
+
- **Constraints:** octaves is a build-time number; each octave is one filtered volume read
|
|
4081
|
+
|
|
4082
|
+
```ts
|
|
4083
|
+
const macro = bakedFractalNoise(vec3(positionWorld.x, 0, positionWorld.z).mul(0.014), 3);
|
|
4084
|
+
```
|
|
4085
|
+
|
|
4086
|
+
### `bakedNoise`
|
|
4087
|
+
|
|
4088
|
+
`function` — Drop-in for `mx_noise_float(p, amplitude, pivot)` on a vec3 `p`: one filtered read of the baked volume instead of the per-pixel Perlin. Only the 3D form: three's 2D Perlin is another function (0.66 scale), so a vec2 caller keeps `mx_noise_float`. `channel` 1 to 3 are independent fields.
|
|
4089
|
+
|
|
4090
|
+
```ts
|
|
4091
|
+
export function bakedNoise( p: Node<"vec3">, amplitude: Scalar = 1, pivot: Scalar = 0, channel: 0 | 1 | 2 | 3 = 0, ): Node<"float"> { … }
|
|
4092
|
+
```
|
|
4093
|
+
|
|
4094
|
+
- **Use when:** a terrain, foliage or water shader calls mx_noise_float per pixel and the frame is GPU bound · open world ground material with procedural variation that must hold 60 FPS
|
|
4095
|
+
- **Constraints:** the field tiles every NOISE_PERIOD units of p; at p = world metres x 2.6 that is a 3 m repeat · vec3 input only: three's 2D Perlin is another function
|
|
4096
|
+
- **Overrides:** keep mx_noise_float where exact analytic noise matters more than the frame
|
|
4097
|
+
|
|
4098
|
+
```ts
|
|
4099
|
+
const patch = smoothstep(-0.35, 0.35, bakedNoise(positionWorld.mul(0.025)));
|
|
4100
|
+
```
|
|
4101
|
+
|
|
4102
|
+
### `baseRingGap`
|
|
4103
|
+
|
|
4104
|
+
`function` — The highest gap between a wide model's rim and the ground, one sample per angular sector: in each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any burial the game wants) to close it.
|
|
4105
|
+
|
|
4106
|
+
```ts
|
|
4107
|
+
export function baseRingGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options: { … }
|
|
4108
|
+
```
|
|
4109
|
+
|
|
4110
|
+
- **Use when:** a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground
|
|
4111
|
+
- **Constraints:** throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`
|
|
4112
|
+
|
|
4113
|
+
```ts
|
|
4114
|
+
const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;
|
|
4115
|
+
```
|
|
4116
|
+
|
|
4117
|
+
### `cellPlacements`
|
|
4118
|
+
|
|
4119
|
+
`function` — Borrow the run's placement records as a live view over the placement buffer.
|
|
4120
|
+
|
|
4121
|
+
```ts
|
|
4122
|
+
export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }
|
|
4123
|
+
```
|
|
4124
|
+
|
|
4125
|
+
- **Use when:** feed one cell's instance transforms into a batch without copying
|
|
4126
|
+
- **Constraints:** the returned view aliases the caller's buffer; writing to it mutates the source
|
|
4127
|
+
|
|
4128
|
+
```ts
|
|
4129
|
+
const records = cellPlacements(buffer, { asset: "tree", offset: 0, count: 120 });
|
|
4130
|
+
```
|
|
4131
|
+
|
|
4132
|
+
### `footprintGap`
|
|
4133
|
+
|
|
4134
|
+
`function` — How far the flat underside of a static geometry rises above the ground at its highest point. Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.
|
|
4135
|
+
|
|
4136
|
+
```ts
|
|
4137
|
+
export function footprintGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin = 0, ): number { … }
|
|
4138
|
+
```
|
|
4139
|
+
|
|
4140
|
+
- **Use when:** a rock snapped to a slope shows a lip or a gap under its downhill side
|
|
4141
|
+
- **Constraints:** the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer
|
|
4142
|
+
|
|
4143
|
+
```ts
|
|
4144
|
+
matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);
|
|
4145
|
+
```
|
|
4146
|
+
|
|
4147
|
+
### `getWorldCapabilities`
|
|
4148
|
+
|
|
4149
|
+
`function` — Resolve the active world-generation path from host capability facts. The function accepts the adapter facts instead of reaching through a renderer-specific global, so browser and native hosts can report the same object. Missing limits are not treated as infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback. GPU generation remains unavailable until a GPU readback can own the canonical field; a host adapter report therefore never upgrades a CPU fallback into a GPU generation claim.
|
|
4150
|
+
|
|
4151
|
+
```ts
|
|
4152
|
+
export function getWorldCapabilities(options: IWorldCapabilitiesOptions = { … }
|
|
4153
|
+
```
|
|
4154
|
+
|
|
4155
|
+
- **Use when:** decide whether generated terrain can use GPU compute · report why terrain generation is using a reduced CPU fallback
|
|
4156
|
+
- **Constraints:** unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue
|
|
4157
|
+
- **Overrides:** minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations
|
|
4158
|
+
|
|
4159
|
+
```ts
|
|
4160
|
+
const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });
|
|
4161
|
+
```
|
|
4162
|
+
|
|
4163
|
+
### `Heightfield`
|
|
4164
|
+
|
|
4165
|
+
`class` — One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.
|
|
4166
|
+
|
|
4167
|
+
```ts
|
|
4168
|
+
export class Heightfield extends Group implements IComputeDriven { … }
|
|
4169
|
+
```
|
|
4170
|
+
|
|
4171
|
+
- **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`)
|
|
4172
|
+
- **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
|
|
4173
|
+
- **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
|
|
4174
|
+
|
|
4175
|
+
```ts
|
|
4176
|
+
const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
|
|
4177
|
+
```
|
|
4178
|
+
|
|
4179
|
+
### `HeightfieldCollar`
|
|
4180
|
+
|
|
4181
|
+
`class` — A heightfield's far ring: `rings` square rings past its playable square, one vertex per boundary sample, and the index grid that draws them.
|
|
4182
|
+
|
|
4183
|
+
```ts
|
|
4184
|
+
export class HeightfieldCollar { … }
|
|
4185
|
+
```
|
|
4186
|
+
|
|
4187
|
+
- **Use when:** draw the terrain past the playable square without hand-building a ring grid · ground a character past the square, out to the walk band, on drawn triangles
|
|
4188
|
+
- **Constraints:** every ring vertex asks the game's `height` callback; core owns no terrain look · the collar is a ring of triangles, not a field: `heightAt` answers on it and null off it
|
|
4189
|
+
|
|
4190
|
+
```ts
|
|
4191
|
+
const collar = new HeightfieldCollar({ resolution: 129, size: 512, rings: 384, ringDistance: (ring) => (ring / 384) ** 1.65 * 2100, walkBand: 200, height: ({ x, z }) => surveyed.heightAt(x, z) });
|
|
4192
|
+
```
|
|
4193
|
+
|
|
4194
|
+
### `heightSamplerFromHeightmap`
|
|
4195
|
+
|
|
4196
|
+
`function` — Build a game-usable `sampleHeight` from a raw v1 heightmap. The returned function interpolates bilinearly in world units and clamps to the map edges, so it plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
|
|
4197
|
+
|
|
4198
|
+
```ts
|
|
4199
|
+
export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWorldExtent, data: Uint16Array, ): (x: number, z: number) => number { … }
|
|
4200
|
+
```
|
|
4201
|
+
|
|
4202
|
+
- **Use when:** turn an exported raw heightmap into terrain collision and rendering · query ground height from a Blender-authored world package
|
|
4203
|
+
- **Constraints:** the sampler reads the game's data; the framework never selects a terrain shape
|
|
4204
|
+
|
|
4205
|
+
```ts
|
|
4206
|
+
const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
|
|
4207
|
+
```
|
|
4208
|
+
|
|
4209
|
+
### `instanceRandom`
|
|
4210
|
+
|
|
4211
|
+
`function` — A random in [0, 1) that stays with its instance, as UE 5.8.3's PerInstanceRandom: hashed from the instance's world origin, never from its draw slot. WorldCells repacks instances on every refilter, main-pass cull and LOD switch, so `instanceIndex` names another tree from one frame to the next; a wind phase hashed from it re-rolled each crown about every 0.7 s of a walk and snapped its top by a median 0.37 m. Parts of one placement share its translation, so its bark and needles read one value.
|
|
4212
|
+
|
|
4213
|
+
```ts
|
|
4214
|
+
export function instanceRandom(): Node<"float"> { … }
|
|
4215
|
+
```
|
|
4216
|
+
|
|
4217
|
+
- **Use when:** a per-instance random number that stays with each streamed placement as WorldCells repacks · replace instanceIndex in a WorldCells part material, which WorldCells refuses
|
|
4218
|
+
|
|
4219
|
+
```ts
|
|
4220
|
+
const phase = instanceRandom().mul(6.2831);
|
|
4221
|
+
```
|
|
4222
|
+
|
|
4223
|
+
### `lakeReach`
|
|
4224
|
+
|
|
4225
|
+
`function` — How far a lake's water reaches: the waterline its basin measures, `margin` times out, capped. The drawn surface and the swim footprint both size themselves here, so the shore a player sees is the shore they stop at.
|
|
4226
|
+
|
|
4227
|
+
```ts
|
|
4228
|
+
export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }
|
|
4229
|
+
```
|
|
4230
|
+
|
|
4231
|
+
- **Use when:** size a lake's footprint from its basin and the cap its biome row names
|
|
4232
|
+
- **Constraints:** reads the heightfield at every bearing, once per lake, never per frame
|
|
4233
|
+
|
|
4234
|
+
```ts
|
|
4235
|
+
const reach = lakeReach(field, { ...lake, margin: 1.12 });
|
|
4236
|
+
```
|
|
4237
|
+
|
|
4238
|
+
### `lakeSurfaceGeometry`
|
|
4239
|
+
|
|
4240
|
+
`function` — A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with water at a corner get triangles, so the surface does not hover over dry hillside and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.
|
|
4241
|
+
|
|
4242
|
+
```ts
|
|
4243
|
+
export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }
|
|
4244
|
+
```
|
|
4245
|
+
|
|
4246
|
+
- **Use when:** draw a lake's water surface from the baked level and seed · a lake's drawn water and the swimmer's water disagree
|
|
4247
|
+
- **Constraints:** the lake row and field come from the game's bake; the game's material shades the geometry
|
|
4248
|
+
|
|
4249
|
+
```ts
|
|
4250
|
+
const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });
|
|
4251
|
+
```
|
|
4252
|
+
|
|
4253
|
+
### `loadTerrainSplat`
|
|
4254
|
+
|
|
4255
|
+
`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.
|
|
4256
|
+
|
|
4257
|
+
```ts
|
|
4258
|
+
export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }
|
|
4259
|
+
```
|
|
4260
|
+
|
|
4261
|
+
- **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
|
|
4262
|
+
- **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
|
|
4263
|
+
- **Overrides:** `table` may replace `base`, `breakup`, `macro` and `layers` from game source; baked `splat` and `textures` stay package-owned
|
|
4264
|
+
|
|
4265
|
+
```ts
|
|
4266
|
+
const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
|
|
4267
|
+
const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
|
|
4268
|
+
```
|
|
4269
|
+
|
|
4270
|
+
### `loadWorldHeightmap`
|
|
4271
|
+
|
|
4272
|
+
`function` — Fetch a raw little-endian uint16 heightmap and expose it as samples.
|
|
4273
|
+
|
|
4274
|
+
```ts
|
|
4275
|
+
export async function loadWorldHeightmap(url: string): Promise<Uint16Array> { … }
|
|
4276
|
+
```
|
|
4277
|
+
|
|
4278
|
+
- **Use when:** load a world package's heightmap once before building terrain
|
|
4279
|
+
- **Constraints:** a non-OK response throws; bytes are byte-swapped only on a big-endian host
|
|
4280
|
+
|
|
4281
|
+
```ts
|
|
4282
|
+
const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
|
|
4283
|
+
```
|
|
4284
|
+
|
|
4285
|
+
### `meshSections`
|
|
4286
|
+
|
|
4287
|
+
`function` — A mesh's material sections: one per geometry group for a material array, else the whole mesh. Instanced props draw one batch per material, so an imported model splits here first.
|
|
4288
|
+
|
|
4289
|
+
```ts
|
|
4290
|
+
export function meshSections(mesh: Mesh): IMeshSection[] { … }
|
|
4291
|
+
```
|
|
4292
|
+
|
|
4293
|
+
- **Use when:** scatter or instance an imported glTF model that has several materials
|
|
4294
|
+
- **Constraints:** a section's `material` can be `undefined` for a group naming a missing material slot; skip it
|
|
4295
|
+
|
|
4296
|
+
```ts
|
|
4297
|
+
for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));
|
|
4298
|
+
```
|
|
4299
|
+
|
|
4300
|
+
### `noiseVolume`
|
|
4301
|
+
|
|
4302
|
+
`function` — The one volume every material shares: baked on first use, 1 MiB of RGBA8 (it stays in L2).
|
|
4303
|
+
|
|
4304
|
+
```ts
|
|
4305
|
+
export function noiseVolume(): Data3DTexture { … }
|
|
4306
|
+
```
|
|
4307
|
+
|
|
4308
|
+
- **Use when:** a material needs the raw baked noise texture to sample in its own TSL
|
|
4309
|
+
- **Constraints:** baked once per page on the main thread (about 0.15 s); every channel is an independent field
|
|
4310
|
+
|
|
4311
|
+
```ts
|
|
4312
|
+
const volume = noiseVolume();
|
|
4313
|
+
```
|
|
4314
|
+
|
|
4315
|
+
### `repairZeroNormals`
|
|
4316
|
+
|
|
4317
|
+
`function` — Recompute the normals of a geometry whose normals are missing, zero or not finite, and leave authored normals alone. Some exported art ships zero normals and draws black under any light. Run it after any reshape, so the recomputed normals fit the final shape.
|
|
4318
|
+
|
|
4319
|
+
```ts
|
|
4320
|
+
export function repairZeroNormals(geometry: BufferGeometry): boolean { … }
|
|
4321
|
+
```
|
|
4322
|
+
|
|
4323
|
+
- **Use when:** an imported model draws black or unlit because it ships zero normals
|
|
4324
|
+
- **Constraints:** one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad
|
|
4325
|
+
|
|
4326
|
+
```ts
|
|
4327
|
+
geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);
|
|
4328
|
+
```
|
|
4329
|
+
|
|
4330
|
+
### `riverRibbonGeometry`
|
|
4331
|
+
|
|
4332
|
+
`function` — The water surface of every river, as one geometry with one group per river. Each station is a row across the river at its own surface height, out to `reach` widths either side of the centreline, the reach `WaterBodies` floods; one more row a reach past each end stands where `WaterBodies` clamps a segment, so the water a swimmer finds past a river's end is drawn there too (cut at the end station, the surface stopped in a straight edge with its carved bed dry beyond). Quads dry on both rows against `field` are dropped, so the surface ends at the shore. Past an end where the ground falls below the end's bed, the water would run off: that cap is not drawn, and the end stays cut at its last station. Attributes for the game's water material: `flow` (the unit downstream heading), `flowUv` (metres down the centreline, metres across it) and `metres` (water depth over the ground). It decides no colour, ripple or opacity: the game shades it.
|
|
4333
|
+
|
|
4334
|
+
```ts
|
|
4335
|
+
export function riverRibbonGeometry( rivers: readonly { … }
|
|
4336
|
+
```
|
|
4337
|
+
|
|
4338
|
+
- **Use when:** draw a river's water surface from the baked stations · a river's water stops in a straight edge, or a swimmer floats where no water is drawn · share one river shape between the drawn water and the swimmer · river water hangs over dry ground past the river's head or tail
|
|
4339
|
+
- **Constraints:** stations, width and reach come from the game's bake; the game's material shades the geometry
|
|
4340
|
+
|
|
4341
|
+
```ts
|
|
4342
|
+
const geometry = riverRibbonGeometry(rivers, field, { maxDepth: 1.6 });
|
|
4343
|
+
```
|
|
4344
|
+
|
|
4345
|
+
### `sectionGeometry`
|
|
4346
|
+
|
|
4347
|
+
`function` — One section's geometry in model space, standing on y = 0. Every section of a model takes the same base from the whole model's `box`, so a crown keeps its place on its trunk: basing each section on its own bounds detaches them. The mesh's LOD0 geometry is cloned under its world matrix, and a group becomes the clone's draw range.
|
|
4348
|
+
|
|
4349
|
+
```ts
|
|
4350
|
+
export function sectionGeometry( mesh: Mesh, box: Box3, section: IMeshSection, options: { … }
|
|
4351
|
+
```
|
|
4352
|
+
|
|
4353
|
+
- **Use when:** the crown of an instanced tree floats off its trunk, or the parts of a model separate · turn each part of an imported model into a geometry for an instanced prop batch
|
|
4354
|
+
- **Constraints:** `box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first
|
|
4355
|
+
|
|
4356
|
+
```ts
|
|
4357
|
+
const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);
|
|
4358
|
+
```
|
|
4359
|
+
|
|
4360
|
+
### `shoreField`
|
|
4361
|
+
|
|
4362
|
+
`function` — Distance to the shore and open-sea exposure for every node of a square height grid, measured once from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level` (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`, then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out of it. Both feed the game's surf and shore masks; neither decides a colour.
|
|
4363
|
+
|
|
4364
|
+
```ts
|
|
4365
|
+
export function shoreField( heights: ArrayLike<number>, resolution: number, size: number, level: number, options: IShoreFieldOptions = { … }
|
|
4366
|
+
```
|
|
4367
|
+
|
|
4368
|
+
- **Use when:** surf breaks only on water open to the sea, not in a sheltered lagoon · distance from each water cell to the shore, for a foam or depth mask
|
|
4369
|
+
- **Constraints:** heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame
|
|
4370
|
+
|
|
4371
|
+
```ts
|
|
4372
|
+
const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);
|
|
4373
|
+
```
|
|
4374
|
+
|
|
4375
|
+
### `snowDiscFootprint`
|
|
4376
|
+
|
|
4377
|
+
`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.
|
|
4378
|
+
|
|
4379
|
+
```ts
|
|
4380
|
+
export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }
|
|
4381
|
+
```
|
|
4382
|
+
|
|
4383
|
+
- **Use when:** press a ball, wheel or probe into snow · give a sphere a physically sized snow contact instead of a boot shape
|
|
4384
|
+
- **Constraints:** radius is metres; the footprint never grows with load, only deeper
|
|
4385
|
+
- **Overrides:** softness widens the eased edge without changing the contact radius
|
|
4386
|
+
|
|
4387
|
+
```ts
|
|
4388
|
+
const footprint = snowDiscFootprint(0.25);
|
|
4389
|
+
```
|
|
4390
|
+
|
|
4391
|
+
### `SnowField`
|
|
4392
|
+
|
|
4393
|
+
`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.
|
|
4394
|
+
|
|
4395
|
+
```ts
|
|
4396
|
+
export class SnowField { … }
|
|
4397
|
+
```
|
|
4398
|
+
|
|
4399
|
+
- **Use when:** leave footprints, tracks and tyre ruts in snow that persist and fill in over time · let a fresh snowfall slowly fill older tracks back in as the field recovers · 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
|
|
4400
|
+
- **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
|
|
4401
|
+
- **Requires:** @threenative/core/world Heightfield as the canonical terrain and surface
|
|
4402
|
+
- **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
|
|
4403
|
+
|
|
4404
|
+
```ts
|
|
4405
|
+
import { Heightfield } from "@threenative/core/world";
|
|
4406
|
+
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 });
|
|
4407
|
+
const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
|
|
4408
|
+
snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
|
|
4409
|
+
snow.recover(1 / 60, 0.0012, 0.4);
|
|
4410
|
+
```
|
|
4411
|
+
|
|
4412
|
+
### `staticLowestY`
|
|
4413
|
+
|
|
4414
|
+
`function` — Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap` audits against, cheap enough for a load that poses hundreds of thousands of props. An upright pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.
|
|
4415
|
+
|
|
4416
|
+
```ts
|
|
4417
|
+
export function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number { … }
|
|
4418
|
+
```
|
|
4419
|
+
|
|
4420
|
+
- **Use when:** stand a scattered rock, tree or crate on the ground by its lowest point, not its origin · props hover or sink because their pivot is not at their base
|
|
4421
|
+
- **Constraints:** static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions
|
|
4422
|
+
|
|
4423
|
+
```ts
|
|
4424
|
+
placed.position.y += ground - staticLowestY(geometry, matrix);
|
|
4425
|
+
```
|
|
4426
|
+
|
|
4427
|
+
### `surfaceSampler`
|
|
4428
|
+
|
|
4429
|
+
`function` — `Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a player stands on the triangles the eye sees rather than on the bilinear field between them. Answers `null` outside the field and for a transform it does not model (any rotation, or an unequal scale), so the caller keeps its own fallback there.
|
|
4430
|
+
|
|
4431
|
+
```ts
|
|
4432
|
+
export function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler { … }
|
|
4433
|
+
```
|
|
4434
|
+
|
|
4435
|
+
- **Use when:** stand props or a player on the drawn terrain triangles under a moved or scaled mesh · props float or sink where the terrain mesh is drawn under a transform
|
|
4436
|
+
- **Constraints:** the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles
|
|
4437
|
+
|
|
4438
|
+
```ts
|
|
4439
|
+
const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;
|
|
4440
|
+
```
|
|
4441
|
+
|
|
4442
|
+
### `TerrainTiles`
|
|
4443
|
+
|
|
4444
|
+
`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.
|
|
4445
|
+
|
|
4446
|
+
```ts
|
|
4447
|
+
export class TerrainTiles extends Object3D implements IComputeDriven { … }
|
|
4448
|
+
```
|
|
4449
|
+
|
|
4450
|
+
- **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 · a hole or a flicker where streamed terrain tiles are still building (`settledHalf`) · split the ground between streamed tiles and a far mesh around the player (`settledHalf`)
|
|
4451
|
+
- **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
|
|
4452
|
+
- **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets
|
|
4453
|
+
|
|
4454
|
+
```ts
|
|
4455
|
+
const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
|
|
4456
|
+
```
|
|
4457
|
+
|
|
4458
|
+
### `terrainValidationRequested`
|
|
4459
|
+
|
|
4460
|
+
`function` — Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.
|
|
4461
|
+
|
|
4462
|
+
```ts
|
|
4463
|
+
export function terrainValidationRequested(): boolean { … }
|
|
4464
|
+
```
|
|
4465
|
+
|
|
4466
|
+
- **Use when:** turn terrain's per-frame seam, LOD pop and vertex checks on for one run · assert the terrain geometry a game streams before it ships
|
|
4467
|
+
- **Constraints:** off by default: it is the work it checks, every frame
|
|
4468
|
+
|
|
4469
|
+
```ts
|
|
4470
|
+
// Reads its own the way `renderListValidationRequested` does: a native launch sets the
|
|
4471
|
+
// environment variable, a browser asks with the query string, a test or harness sets the
|
|
4472
|
+
// global. `0` and `false` are off, so a saved URL that enabled it still says "off".
|
|
4473
|
+
const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
|
|
4474
|
+
```
|
|
4475
|
+
|
|
4476
|
+
### `validateWorldPackage`
|
|
4477
|
+
|
|
4478
|
+
`function` — Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.
|
|
4479
|
+
|
|
4480
|
+
```ts
|
|
4481
|
+
export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }
|
|
4482
|
+
```
|
|
4483
|
+
|
|
4484
|
+
- **Use when:** check a Blender-exported world package before the runtime attaches anything · report why a world package cannot be streamed
|
|
4485
|
+
- **Constraints:** validation only checks structure and ranges; it never fetches the heightmap or GLBs
|
|
4486
|
+
|
|
4487
|
+
```ts
|
|
4488
|
+
const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
|
|
4489
|
+
```
|
|
4490
|
+
|
|
4491
|
+
### `warmUnculled`
|
|
4492
|
+
|
|
4493
|
+
`function` — Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass), so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only when its water does — builds its pipelines after the reveal and hitches the first frames that see it. Join the promise to the loading curtain to build them behind it. Objects that join `root` while it warms draw unculled too.
|
|
4494
|
+
|
|
4495
|
+
```ts
|
|
4496
|
+
export function warmUnculled( ctx: { … }
|
|
4497
|
+
```
|
|
4498
|
+
|
|
4499
|
+
- **Use when:** the first frames after the loading curtain hitch on pipeline builds for content behind the camera · streamed terrain or a lake compiles its pipelines after the reveal
|
|
4500
|
+
- **Constraints:** `ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold
|
|
4501
|
+
|
|
4502
|
+
```ts
|
|
4503
|
+
const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold("lake", () => warm);
|
|
4504
|
+
```
|
|
4505
|
+
|
|
4506
|
+
### `WaterBodies`
|
|
4507
|
+
|
|
4508
|
+
`class` — One world's water, queried: surface height, current and footprint from the baked arrays. Rendering and physics read the same store, as they do for `Heightfield`, so the surface a player sees and the surface a swimmer rests on cannot disagree. Every station, level, extent and speed comes from the game, and the shading stays in the game's own `src/render/`. A river's segments sit in a uniform grid, so a query tests the few that can reach its cell instead of every station of every river.
|
|
4509
|
+
|
|
4510
|
+
```ts
|
|
4511
|
+
export class WaterBodies { … }
|
|
4512
|
+
```
|
|
4513
|
+
|
|
4514
|
+
- **Use when:** ask how high the water is where a player swims · ask which way a current carries a body · ask which water body covers a point, and how high its surface is · share one water store between rendering and physics
|
|
4515
|
+
- **Constraints:** every station, level, extent and speed comes from the game's own bake; a lake is measured on the field passed in
|
|
4516
|
+
|
|
4517
|
+
```ts
|
|
4518
|
+
const water = new WaterBodies({ ribbons, lakes, field }); const height = water.surfaceAt(x, z);
|
|
4519
|
+
```
|
|
4520
|
+
|
|
4521
|
+
### `waterlineRadius`
|
|
4522
|
+
|
|
4523
|
+
`function` — The furthest a lake's basin reaches on a bearing: where the drawn ground crosses its level. Twenty-four bearings step outwards and stop at the first bank, because binary-searching the whole ray can jump a dry ridge into another pond. Eighteen halvings land inside two centimetres at this scale, well under the ground's own sample spacing.
|
|
4524
|
+
|
|
4525
|
+
```ts
|
|
4526
|
+
export function waterlineRadius( field: Heightfield, centre: readonly number[], level: number, ): number { … }
|
|
4527
|
+
```
|
|
4528
|
+
|
|
4529
|
+
- **Use when:** measure where a lake's water meets the ground it floods · size a lake's drawn surface or the footprint a swimmer may enter
|
|
4530
|
+
- **Constraints:** returns metres on the furthest bearing; the caller applies its own cap
|
|
4531
|
+
|
|
4532
|
+
```ts
|
|
4533
|
+
const reach = waterlineRadius(field, lake.at, lake.level) * 1.12;
|
|
4534
|
+
```
|
|
4535
|
+
|
|
4536
|
+
### `WorldCells`
|
|
4537
|
+
|
|
4538
|
+
`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.
|
|
4539
|
+
|
|
4540
|
+
```ts
|
|
4541
|
+
export class WorldCells extends Group implements IComputeDriven { … }
|
|
4542
|
+
```
|
|
4543
|
+
|
|
4544
|
+
- **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
|
|
4545
|
+
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first · budgets are hard caps that report pressure instead of over-committing · `whenSpawnReady(position, radius, timeoutMs)` snapshots a fixed region and settles from existing updates or disposal; it does not drive streaming, and `prewarmed` remains the separate draw gate · 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 · residency and `placementReach` follow `follow`; levels and `maxDistance` are graded from the render camera, as UE picks instance LODs per view; `lodFrom: "follow"`, `?tnLodFromCamera=0` or `TN_LOD_FROM_CAMERA=0` grade from `follow`, reported as `TN_WORLD_MAIN_CULL lodFrom=` · 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
|
|
4546
|
+
- **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; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
|
|
4547
|
+
|
|
4548
|
+
```ts
|
|
4549
|
+
const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
|
|
4550
|
+
scene.add(world);
|
|
4551
|
+
world.update();
|
|
4552
|
+
```
|
|
4553
|
+
|
|
4554
|
+
## `@threenative/metahuman`
|
|
4555
|
+
|
|
4556
|
+
### `assertAssetPath`
|
|
4557
|
+
|
|
4558
|
+
`function` — Keeps a caller-supplied asset path inside the asset directory.
|
|
4559
|
+
|
|
4560
|
+
```ts
|
|
4561
|
+
export function assertAssetPath(path: string): string { … }
|
|
4562
|
+
```
|
|
4563
|
+
|
|
4564
|
+
- **Use when:** reject a MetaHuman asset path that would read outside the game's asset root
|
|
4565
|
+
- **Constraints:** absolute paths, Windows drive letters, backslashes and any `..` segment throw MetaHumanAssetError with TN_MH_PATH_ESCAPE before the path is joined onto a root
|
|
4566
|
+
- **Requires:** npm i @threenative/metahuman
|
|
4567
|
+
|
|
4568
|
+
```ts
|
|
4569
|
+
assertAssetPath("metahuman/specimen.glb");
|
|
4570
|
+
```
|
|
4571
|
+
|
|
4572
|
+
### `loadMetaHuman`
|
|
4573
|
+
|
|
4574
|
+
`function` — Load a prepared MetaHuman head and drive its expression from the browser's WASM evaluator: declared faceboard controls in, joint deltas and morph weights out, applied to an ordinary Three.js object graph. two characters never write each other's face and nothing is disposed that `ctx.assets` still owns switch re-evaluates the current controls before the replacement mesh is shown `dispose()` throw, each with a stable `code`; nothing is clamped or coerced `diagnostics().backend` reads "native"; the game code does not change
|
|
4575
|
+
|
|
4576
|
+
```ts
|
|
4577
|
+
loadMetaHuman = (options: ILoadMetaHumanOptions): Promise<IMetaHuman> => createMetaHuman( { … }
|
|
4578
|
+
```
|
|
4579
|
+
|
|
4580
|
+
- **Use when:** put a MetaHuman head in a browser game without an Unreal import or a baked clip
|
|
3662
4581
|
- **Constraints:** the model is loaded through the game's own asset loader and cloned per instance, so · the rig's own GUI-to-raw mapping runs; the adapter never re-derives it, and a LOD · an undeclared control, an out-of-domain value, an undeclared LOD and any call after · in a native host that installed the MetaHuman resident the C++ evaluator runs and
|
|
3663
4582
|
- **Requires:** npm i @threenative/metahuman
|
|
3664
4583
|
|
|
@@ -3828,9 +4747,10 @@ const footprint = capsuleFootprint(0.5, 0.2);
|
|
|
3828
4747
|
export class CharacterBody3D { … }
|
|
3829
4748
|
```
|
|
3830
4749
|
|
|
3831
|
-
- **Use when:** move an enemy or player through a level · keep a character from walking through walls
|
|
3832
|
-
- **Constraints:** use moveAndSlide inside the physics update
|
|
4750
|
+
- **Use when:** move an enemy or player through a level · keep a character from walking through walls · swim in a river, lake or sea; float at the surface and wade slower in shallow water · river current carries a swimmer downstream while it floats
|
|
4751
|
+
- **Constraints:** use moveAndSlide inside the physics update · pass `water: (x, z) => surfaceHeight | undefined`; the body reads `swimming`, `immersionDepth` and `waterSurface` each moveAndSlide · pass `waterCurrent: (x, z) => { x, z } | undefined` in m/s to have the water carry the body; it reads `currentVelocity` back
|
|
3833
4752
|
- **Requires:** npm i @threenative/physics
|
|
4753
|
+
- **Overrides:** buoyancy (1.6, floats; Unreal 1.0 sinks), maxSwimSpeed (3 m/s) and fluidFriction (12) tune the Unreal MOVE_Swimming defaults
|
|
3834
4754
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
|
|
3835
4755
|
|
|
3836
4756
|
```ts
|
|
@@ -3911,7 +4831,7 @@ export function rapier(options: IPhysicsOptions = { … }
|
|
|
3911
4831
|
```
|
|
3912
4832
|
|
|
3913
4833
|
- **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
|
|
3914
|
-
- **Constraints:** place rapier() before recast() in the plugin list
|
|
4834
|
+
- **Constraints:** place rapier() before recast() in the plugin list · ctx.physics is set before Scene.enter(), not during load(): Rapier initializes while the scene loads, so create bodies in enter() or later (TN_PHYSICS_NOT_READY)
|
|
3915
4835
|
- **Requires:** npm i @threenative/physics
|
|
3916
4836
|
|
|
3917
4837
|
```ts
|
|
@@ -3926,7 +4846,7 @@ const game = defineGame({ plugins: [rapier()] });
|
|
|
3926
4846
|
export class RigidBody3D { … }
|
|
3927
4847
|
```
|
|
3928
4848
|
|
|
3929
|
-
- **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
|
|
4849
|
+
- **Use when:** give a crate or prop physical motion · a ball rolls across the floor · 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
|
|
3930
4850
|
- **Constraints:** register rapier() in the game plugin list before using bodies
|
|
3931
4851
|
- **Requires:** npm i @threenative/physics
|
|
3932
4852
|
- **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
|
|
@@ -3936,6 +4856,22 @@ export class RigidBody3D { … }
|
|
|
3936
4856
|
const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
|
|
3937
4857
|
```
|
|
3938
4858
|
|
|
4859
|
+
### `ScatterColliders`
|
|
4860
|
+
|
|
4861
|
+
`class` — Make scattered props solid: fixed bodies for rocks and trunks near a followed point, streamed with it.
|
|
4862
|
+
|
|
4863
|
+
```ts
|
|
4864
|
+
export class ScatterColliders { … }
|
|
4865
|
+
```
|
|
4866
|
+
|
|
4867
|
+
- **Use when:** stop the player walking through scattered rocks and trees · give instanced or streamed foliage props collision in an open world
|
|
4868
|
+
- **Constraints:** pass each instance's solid part (stone, bark), not its leaves; shapes are measured: a slender base is a trunk capsule, the rest an 18-DOP hull, and pieces under 0.25 m get none · call update() every frame; it rescans only after the follow point moves a quarter of `radius` (default 40 m) · `collision: "hull" | "trunk" | "none"` on an instance overrides the measured shape
|
|
4869
|
+
- **Requires:** npm i @threenative/physics
|
|
4870
|
+
|
|
4871
|
+
```ts
|
|
4872
|
+
const solids = new ScatterColliders({ physics: ctx.physics, follow: player, collisionLayer: 4, instances: rocks.map((matrix) => ({ geometry: rockGeometry, matrix })) });
|
|
4873
|
+
```
|
|
4874
|
+
|
|
3939
4875
|
### `softBodyCollision`
|
|
3940
4876
|
|
|
3941
4877
|
`function` — Feed existing rigid-body boxes into `SoftBody3D` without inventing a second collider API.
|
|
@@ -4498,6 +5434,23 @@ if (requestedPlaytestClockMode() === "wall-clock") host.pumpDrivesTheSimulation(
|
|
|
4498
5434
|
|
|
4499
5435
|
## `@threenative/playtest/runner`
|
|
4500
5436
|
|
|
5437
|
+
### `absolutesVerdict`
|
|
5438
|
+
|
|
5439
|
+
`function` — The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.
|
|
5440
|
+
|
|
5441
|
+
```ts
|
|
5442
|
+
export function absolutesVerdict(reading: IPerfHostLoadReading): IPerfHostLoad["absolutes"] { … }
|
|
5443
|
+
```
|
|
5444
|
+
|
|
5445
|
+
- **Use when:** mark a benchmark run invalid because the machine was busy
|
|
5446
|
+
- **Constraints:** an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch
|
|
5447
|
+
|
|
5448
|
+
```ts
|
|
5449
|
+
import { absolutesVerdict, readHostLoad } from "@threenative/playtest/runner";
|
|
5450
|
+
const load = readHostLoad();
|
|
5451
|
+
if (absolutesVerdict(load) === "invalid-absolute") ignoreAbsoluteMilliseconds();
|
|
5452
|
+
```
|
|
5453
|
+
|
|
4501
5454
|
### `AdbAndroidDriver`
|
|
4502
5455
|
|
|
4503
5456
|
`class` — Drive and inspect Android playtest transport.
|
|
@@ -5130,6 +6083,23 @@ export function preflightDisplay( config: Pick<IStandalonePlaytestConfig, "headl
|
|
|
5130
6083
|
const report = await runStandalonePlaytest(options);
|
|
5131
6084
|
```
|
|
5132
6085
|
|
|
6086
|
+
### `readHostLoad`
|
|
6087
|
+
|
|
6088
|
+
`function` — The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.
|
|
6089
|
+
|
|
6090
|
+
```ts
|
|
6091
|
+
export function readHostLoad( source: IPerfHostLoadSource = { … }
|
|
6092
|
+
```
|
|
6093
|
+
|
|
6094
|
+
- **Use when:** mark a benchmark run invalid because the machine was busy
|
|
6095
|
+
- **Constraints:** an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch
|
|
6096
|
+
|
|
6097
|
+
```ts
|
|
6098
|
+
import { absolutesVerdict, readHostLoad } from "@threenative/playtest/runner";
|
|
6099
|
+
const load = readHostLoad();
|
|
6100
|
+
if (absolutesVerdict(load) === "invalid-absolute") ignoreAbsoluteMilliseconds();
|
|
6101
|
+
```
|
|
6102
|
+
|
|
5133
6103
|
### `reconcileBrowserPointers`
|
|
5134
6104
|
|
|
5135
6105
|
`function` — Compare pointer snapshots and produce down, move, and up transitions.
|
|
@@ -5269,17 +6239,17 @@ await runDesktopPlaytest(options);
|
|
|
5269
6239
|
|
|
5270
6240
|
### `runDevicePlaytest`
|
|
5271
6241
|
|
|
5272
|
-
`function` — Run a playtest on Android through
|
|
6242
|
+
`function` — Run a playtest on any device lane (Android, desktop or iOS) through its driver and transport.
|
|
5273
6243
|
|
|
5274
6244
|
```ts
|
|
5275
6245
|
export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }
|
|
5276
6246
|
```
|
|
5277
6247
|
|
|
5278
|
-
- **Use when:** execute a scenario on
|
|
5279
|
-
- **Constraints:** the app bundle and
|
|
6248
|
+
- **Use when:** execute a scenario on a device target with a custom driver
|
|
6249
|
+
- **Constraints:** the driver must prepare the app bundle and the transport must answer the handshake
|
|
5280
6250
|
|
|
5281
6251
|
```ts
|
|
5282
|
-
await
|
|
6252
|
+
await runDevicePlaytest(config, { name: "android", driver, transport, processName, mailboxPaths });
|
|
5283
6253
|
```
|
|
5284
6254
|
|
|
5285
6255
|
### `runIosPlaytest`
|
|
@@ -6171,6 +7141,22 @@ export function applyPlacementOverrides(state: ITerrainState, value: unknown): I
|
|
|
6171
7141
|
const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
|
|
6172
7142
|
```
|
|
6173
7143
|
|
|
7144
|
+
### `bakeBiome`
|
|
7145
|
+
|
|
7146
|
+
`function` — Bake one biome: the recipe's evaluated state and the world package it streams. This is the composition `terrain_generate` and a game's build script both call, so the file layout a player streams is decided in one place. The biome is validated first — an inline spec from a request is checked here, not trusted — and the package's own placement runs are checked against the state they came from, so a bake can never ship a cell list that lost instances. An agent does not write this call to get a world: the `threenative-terrain` MCP tool `terrain_generate` takes the request in words ("a pine forest under snowy mountains with a river", "a volcanic island", or `ground: { location }` for a real place) and cooks the world.glb, recipe.json and world.json a game loads with `ctx.assets.model`.
|
|
7147
|
+
|
|
7148
|
+
```ts
|
|
7149
|
+
export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }
|
|
7150
|
+
```
|
|
7151
|
+
|
|
7152
|
+
- **Use when:** bake one biome's world package from an evaluated recipe and a biome file · generate terrain with mountains, hills, a river, a lake or an island from a request in words · generate a landscape or open world map for a game · procedural terrain for a level: a volcanic island, a mountain valley or a coast · make a canyon, a volcano, a fjord, a desert, a tundra or a forest world · cook the real terrain of a place on Earth from its latitude and longitude
|
|
7153
|
+
- **Constraints:** every instance's asset must be in `assets`; every instance must land in exactly one cell run
|
|
7154
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7155
|
+
|
|
7156
|
+
```ts
|
|
7157
|
+
const baked = bakeBiome({ state: terrain.evaluate(), spec: validateBiome(json, "savanna"), assets });
|
|
7158
|
+
```
|
|
7159
|
+
|
|
6174
7160
|
### `bakeMesh`
|
|
6175
7161
|
|
|
6176
7162
|
`function` — Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
|
|
@@ -6207,7 +7193,7 @@ const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCe
|
|
|
6207
7193
|
|
|
6208
7194
|
### `bakeWorldPackage`
|
|
6209
7195
|
|
|
6210
|
-
`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.
|
|
7196
|
+
`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, a placement ID sidecar 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.
|
|
6211
7197
|
|
|
6212
7198
|
```ts
|
|
6213
7199
|
export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }
|
|
@@ -6219,167 +7205,393 @@ export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPacka
|
|
|
6219
7205
|
- **Overrides:** every asset path, bound, LOD distance and cell size comes from the caller's options
|
|
6220
7206
|
|
|
6221
7207
|
```ts
|
|
6222
|
-
const { manifest, files } = bakeWorldPackage(state, { assets });
|
|
7208
|
+
const { manifest, files } = bakeWorldPackage(state, { assets });
|
|
7209
|
+
```
|
|
7210
|
+
|
|
7211
|
+
### `collarSampler`
|
|
7212
|
+
|
|
7213
|
+
`function` — The collar's height at any (x, z), and a way to raise one of its per-vertex attributes at a placement: both read the collar's own quad grid, so a lane that reshapes the collar moves the trees with it.
|
|
7214
|
+
|
|
7215
|
+
```ts
|
|
7216
|
+
export function collarSampler(collar: HeightfieldCollar) { … }
|
|
7217
|
+
```
|
|
7218
|
+
|
|
7219
|
+
- **Use when:** plant a far field on a drawn collar and paint the canopy its crowns cover
|
|
7220
|
+
- **Constraints:** the collar decides where a tree stands; this sampler never resamples the square
|
|
7221
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7222
|
+
|
|
7223
|
+
```ts
|
|
7224
|
+
const sampler = collarSampler(collar); const height = sampler.at(x, z);
|
|
7225
|
+
```
|
|
7226
|
+
|
|
7227
|
+
### `compilePropBuckets`
|
|
7228
|
+
|
|
7229
|
+
`function` — Group placements into their streamed worlds and write each world's cells and records. The order is the streamed one: cells sorted by `x` then `z`, assets sorted by name inside a cell, and records in the order the entries arrived inside a run. Same-cell, same-asset placements keep their input order, so a re-run of a seeded bake reproduces the buffer byte for byte.
|
|
7230
|
+
|
|
7231
|
+
```ts
|
|
7232
|
+
export function compilePropBuckets( entries: readonly IPropBucketEntry[], options: ICompilePropBucketsOptions = { … }
|
|
7233
|
+
```
|
|
7234
|
+
|
|
7235
|
+
- **Use when:** bake the prop worlds a game streams, once, instead of compiling them at load
|
|
7236
|
+
- **Constraints:** headless; the caller decides every placement, its streamed world, its reach and its pose
|
|
7237
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7238
|
+
- **Overrides:** cellSize and the base extent; the bucket, reach and kind of every entry
|
|
7239
|
+
|
|
7240
|
+
```ts
|
|
7241
|
+
const pkg = compilePropBuckets(entries, { bounds });
|
|
7242
|
+
```
|
|
7243
|
+
|
|
7244
|
+
### `createSegmentIndex`
|
|
7245
|
+
|
|
7246
|
+
`function` — Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
|
|
7247
|
+
|
|
7248
|
+
```ts
|
|
7249
|
+
export function createSegmentIndex<T>( segments: readonly IWaterSegment<T>[], cellSize: number, ): ISegmentIndex<T> { … }
|
|
7250
|
+
```
|
|
7251
|
+
|
|
7252
|
+
- **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
|
|
7253
|
+
- **Constraints:** returns candidates only; the caller applies its own exact distance and level test
|
|
7254
|
+
- **Requires:** npm i @threenative/terrain
|
|
7255
|
+
|
|
7256
|
+
```ts
|
|
7257
|
+
const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);
|
|
7258
|
+
```
|
|
7259
|
+
|
|
7260
|
+
### `decodeHeightPNG`
|
|
7261
|
+
|
|
7262
|
+
`function` — CRC-checked bounded non-interlaced grayscale PNG height decoder.
|
|
7263
|
+
|
|
7264
|
+
```ts
|
|
7265
|
+
export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options: IDecodeHeightPngOptions = { … }
|
|
7266
|
+
```
|
|
7267
|
+
|
|
7268
|
+
- **Use when:** import numerical PNG8 or PNG16 terrain elevations
|
|
7269
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7270
|
+
- **Requires:** npm i @threenative/terrain
|
|
7271
|
+
|
|
7272
|
+
```ts
|
|
7273
|
+
const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);
|
|
7274
|
+
```
|
|
7275
|
+
|
|
7276
|
+
### `decodePropBucket`
|
|
7277
|
+
|
|
7278
|
+
`function` — The records of one compiled prop bucket, read back in record order: the inverse of `compilePropBuckets`, so a loader that fetched a bake's files gets each record's ID, model, pose and reach without re-deriving the container layout.
|
|
7279
|
+
|
|
7280
|
+
```ts
|
|
7281
|
+
export function decodePropBucket(bucket: IPropBucketPackage): IPropBucketRecord[] { … }
|
|
7282
|
+
```
|
|
7283
|
+
|
|
7284
|
+
- **Use when:** read a baked prop bucket back into placements to ground them on this machine's terrain
|
|
7285
|
+
- **Constraints:** throws `TN_PROP_BUCKET_INVALID` when the record buffer, the IDs and the runs disagree
|
|
7286
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7287
|
+
|
|
7288
|
+
```ts
|
|
7289
|
+
for (const record of decodePropBucket(bucket)) pose(record.key, record.position, record.quaternion);
|
|
7290
|
+
```
|
|
7291
|
+
|
|
7292
|
+
### `decodeRAW16`
|
|
7293
|
+
|
|
7294
|
+
`function` — Validates dimensions and range before decoding numerical height samples.
|
|
7295
|
+
|
|
7296
|
+
```ts
|
|
7297
|
+
export function decodeRAW16( input: Uint8Array | ArrayBuffer, { … }
|
|
7298
|
+
```
|
|
7299
|
+
|
|
7300
|
+
- **Use when:** import a RAW16 terrain height buffer with explicit dimensions
|
|
7301
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7302
|
+
- **Requires:** npm i @threenative/terrain
|
|
7303
|
+
|
|
7304
|
+
```ts
|
|
7305
|
+
const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });
|
|
7306
|
+
```
|
|
7307
|
+
|
|
7308
|
+
### `encodeGLB`
|
|
7309
|
+
|
|
7310
|
+
`function` — Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.
|
|
7311
|
+
|
|
7312
|
+
```ts
|
|
7313
|
+
export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }
|
|
7314
|
+
```
|
|
7315
|
+
|
|
7316
|
+
- **Use when:** export baked terrain geometry without engine extensions
|
|
7317
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7318
|
+
- **Requires:** npm i @threenative/terrain
|
|
7319
|
+
|
|
7320
|
+
```ts
|
|
7321
|
+
const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
|
|
7322
|
+
```
|
|
7323
|
+
|
|
7324
|
+
### `encodeHeightPNG`
|
|
7325
|
+
|
|
7326
|
+
`function` — Encodes numerical grayscale PNG16 with embedded elevation range.
|
|
7327
|
+
|
|
7328
|
+
```ts
|
|
7329
|
+
export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }
|
|
7330
|
+
```
|
|
7331
|
+
|
|
7332
|
+
- **Use when:** export a terrain heightmap without an eight-bit colour conversion
|
|
7333
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7334
|
+
- **Requires:** npm i @threenative/terrain
|
|
7335
|
+
|
|
7336
|
+
```ts
|
|
7337
|
+
const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());
|
|
7338
|
+
```
|
|
7339
|
+
|
|
7340
|
+
### `encodeRAW16`
|
|
7341
|
+
|
|
7342
|
+
`function` — Encodes finite metre elevations as an explicit-range RAW16 buffer.
|
|
7343
|
+
|
|
7344
|
+
```ts
|
|
7345
|
+
export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }
|
|
7346
|
+
```
|
|
7347
|
+
|
|
7348
|
+
- **Use when:** export terrain heights with a numerical range sidecar
|
|
7349
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7350
|
+
- **Requires:** npm i @threenative/terrain
|
|
7351
|
+
|
|
7352
|
+
```ts
|
|
7353
|
+
const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });
|
|
7354
|
+
```
|
|
7355
|
+
|
|
7356
|
+
### `encodeSplatPNGs`
|
|
7357
|
+
|
|
7358
|
+
`function` — Encodes the eight linear material-weight channels as two RGBA images.
|
|
7359
|
+
|
|
7360
|
+
```ts
|
|
7361
|
+
export async function encodeSplatPNGs(state: ITerrainState) { … }
|
|
7362
|
+
```
|
|
7363
|
+
|
|
7364
|
+
- **Use when:** export terrain splat weights as linear data
|
|
7365
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7366
|
+
- **Requires:** npm i @threenative/terrain
|
|
7367
|
+
|
|
7368
|
+
```ts
|
|
7369
|
+
const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());
|
|
7370
|
+
```
|
|
7371
|
+
|
|
7372
|
+
### `encodeZIP`
|
|
7373
|
+
|
|
7374
|
+
`function` — Deterministic store-method ZIP with safe unique relative filenames.
|
|
7375
|
+
|
|
7376
|
+
```ts
|
|
7377
|
+
export function encodeZIP(files: readonly IExportFile[]) { … }
|
|
7378
|
+
```
|
|
7379
|
+
|
|
7380
|
+
- **Use when:** archive derived terrain files without another dependency
|
|
7381
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7382
|
+
- **Requires:** npm i @threenative/terrain
|
|
7383
|
+
|
|
7384
|
+
```ts
|
|
7385
|
+
const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
|
|
7386
|
+
```
|
|
7387
|
+
|
|
7388
|
+
### `farForestPlacements`
|
|
7389
|
+
|
|
7390
|
+
`function` — Far-field placements on the collar; also paints the collar's `canopy` attribute under each crown.
|
|
7391
|
+
|
|
7392
|
+
```ts
|
|
7393
|
+
export function farForestPlacements(options: IFarFieldOptions): IPlacement[] { … }
|
|
7394
|
+
```
|
|
7395
|
+
|
|
7396
|
+
- **Use when:** plant the stand past a game's playable square, out to the drawn collar
|
|
7397
|
+
- **Constraints:** the row's `far` block decides every density; the caller supplies the collar and layer
|
|
7398
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7399
|
+
|
|
7400
|
+
```ts
|
|
7401
|
+
const trees = farForestPlacements({ size, resolution, collar, treeline, rules, asset, layer });
|
|
7402
|
+
```
|
|
7403
|
+
|
|
7404
|
+
### `fieldWeight`
|
|
7405
|
+
|
|
7406
|
+
`function` — A field's weight at (x, z), clamped to 0..1.
|
|
7407
|
+
|
|
7408
|
+
```ts
|
|
7409
|
+
export function fieldWeight(field: ICoverField, x: number, z: number): number { … }
|
|
7410
|
+
```
|
|
7411
|
+
|
|
7412
|
+
- **Use when:** sample the stand field a biome's trees and cover thin on · measure the drift a biome's blades grow by, or the mat field its cover follows
|
|
7413
|
+
- **Constraints:** the field is a value, so two worlds sample the same formula with their own numbers
|
|
7414
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7415
|
+
|
|
7416
|
+
```ts
|
|
7417
|
+
const stand = fieldWeight(STAND_FIELD, x, z);
|
|
7418
|
+
```
|
|
7419
|
+
|
|
7420
|
+
### `gradientAt`
|
|
7421
|
+
|
|
7422
|
+
`function` — World-space height gradient from the canonical samples.
|
|
7423
|
+
|
|
7424
|
+
```ts
|
|
7425
|
+
export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }
|
|
7426
|
+
```
|
|
7427
|
+
|
|
7428
|
+
- **Use when:** measure an authored terrain gradient in metres
|
|
7429
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
7430
|
+
- **Requires:** npm i @threenative/terrain
|
|
7431
|
+
|
|
7432
|
+
```ts
|
|
7433
|
+
const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
6223
7434
|
```
|
|
6224
7435
|
|
|
6225
|
-
### `
|
|
7436
|
+
### `landform`
|
|
6226
7437
|
|
|
6227
|
-
`function` —
|
|
7438
|
+
`function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
|
|
6228
7439
|
|
|
6229
7440
|
```ts
|
|
6230
|
-
export function
|
|
7441
|
+
export function landform(kind: LandformKind, options: ILandformOptions = { … }
|
|
6231
7442
|
```
|
|
6232
7443
|
|
|
6233
|
-
- **Use when:**
|
|
6234
|
-
- **Constraints:** returns
|
|
7444
|
+
- **Use when:** start an open world, a distant backdrop or a mountain level from a kind of place
|
|
7445
|
+
- **Constraints:** returns an ordinary `Terrain`: add roads, rivers, scatter or more layers, then `evaluate()` in a build script · shape only; materials, colours and textures belong to the game · calibrated at size 5000, resolution 513; other sizes keep the same slopes and scale the relief with `size`
|
|
6235
7446
|
- **Requires:** npm i @threenative/terrain
|
|
7447
|
+
- **Overrides:** `relief` is the highest-minus-lowest height in metres before the finishing passes shave a few percent; `size`, `resolution` and `seed` as in `Terrain`
|
|
6236
7448
|
|
|
6237
7449
|
```ts
|
|
6238
|
-
const
|
|
7450
|
+
const terrain = landform("alpine", { size: 5000, resolution: 513, seed: 4 }); const state = terrain.evaluate();
|
|
6239
7451
|
```
|
|
6240
7452
|
|
|
6241
|
-
### `
|
|
7453
|
+
### `landformBackdrop`
|
|
6242
7454
|
|
|
6243
|
-
`function` —
|
|
7455
|
+
`function` — Distant mountains around a playable area: a landform window with a valley floor at its centre.
|
|
6244
7456
|
|
|
6245
7457
|
```ts
|
|
6246
|
-
export
|
|
7458
|
+
export function landformBackdrop( kind: LandformKind, options: IBackdropOptions = { … }
|
|
6247
7459
|
```
|
|
6248
7460
|
|
|
6249
|
-
- **Use when:**
|
|
6250
|
-
- **Constraints:**
|
|
7461
|
+
- **Use when:** add a mountain backdrop around a playable area that the game's detail terrain covers
|
|
7462
|
+
- **Constraints:** resolution up to 513: the window is cut from a world twice as wide at the same spacing; build script only · shape only; the game places, colours and fades it
|
|
6251
7463
|
- **Requires:** npm i @threenative/terrain
|
|
7464
|
+
- **Overrides:** `relief` and `centerHeight` in metres; `size`, `resolution` and `seed` as in `landform`
|
|
6252
7465
|
|
|
6253
7466
|
```ts
|
|
6254
|
-
const
|
|
7467
|
+
const { size, resolution, heights } = landformBackdrop("temperateMountains", { seed: 7, centerHeight: 13 });
|
|
6255
7468
|
```
|
|
6256
7469
|
|
|
6257
|
-
### `
|
|
7470
|
+
### `liftMassif`
|
|
6258
7471
|
|
|
6259
|
-
`function` —
|
|
7472
|
+
`function` — A tile's mountain above its own foot: the heights minus a smooth surface through its border, so its edge is exactly zero and stands on any ground with no wall or ramp. Signed: a valley inside the mountain cuts below the foot, as it does in the survey.
|
|
6260
7473
|
|
|
6261
7474
|
```ts
|
|
6262
|
-
export function
|
|
7475
|
+
export function liftMassif(tile: IMassifTile): Float32Array { … }
|
|
6263
7476
|
```
|
|
6264
7477
|
|
|
6265
|
-
- **Use when:**
|
|
6266
|
-
- **Constraints:**
|
|
6267
|
-
- **Requires:** npm i @threenative/terrain
|
|
7478
|
+
- **Use when:** measure how tall a surveyed mountain stands above the valley floor around it
|
|
7479
|
+
- **Constraints:** the tile must cover the whole mountain; a summit crop lifts as a cone
|
|
7480
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6268
7481
|
|
|
6269
7482
|
```ts
|
|
6270
|
-
const
|
|
7483
|
+
const lifted = liftMassif({ id: "hill", size: 400, resolution: 3, heights: [0, 0, 0, 0, 90, 0, 0, 0, 0] });
|
|
6271
7484
|
```
|
|
6272
7485
|
|
|
6273
|
-
### `
|
|
7486
|
+
### `makeExport`
|
|
6274
7487
|
|
|
6275
|
-
`function` —
|
|
7488
|
+
`function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
|
|
6276
7489
|
|
|
6277
7490
|
```ts
|
|
6278
|
-
export function
|
|
7491
|
+
export function makeExport( state: ITerrainState | null, recipe: ITerrainDocument, kind: "project", ): Promise<IExportArchive>;
|
|
6279
7492
|
```
|
|
6280
7493
|
|
|
6281
|
-
- **Use when:** export
|
|
7494
|
+
- **Use when:** export a terrain recipe and its numerical runtime data
|
|
6282
7495
|
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
6283
7496
|
- **Requires:** npm i @threenative/terrain
|
|
6284
7497
|
|
|
6285
7498
|
```ts
|
|
6286
|
-
const
|
|
7499
|
+
const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
|
|
6287
7500
|
```
|
|
6288
7501
|
|
|
6289
|
-
### `
|
|
7502
|
+
### `measureBands`
|
|
6290
7503
|
|
|
6291
|
-
`function` —
|
|
7504
|
+
`function` — Resolve a biome's fraction bands against this world's own height samples.
|
|
6292
7505
|
|
|
6293
7506
|
```ts
|
|
6294
|
-
export
|
|
7507
|
+
export function measureBands( layers: readonly ILayerInfo[], heights: ArrayLike<number>, ): IMeasuredBands { … }
|
|
6295
7508
|
```
|
|
6296
7509
|
|
|
6297
|
-
- **Use when:**
|
|
6298
|
-
- **Constraints:**
|
|
6299
|
-
- **Requires:** npm i @threenative/terrain
|
|
7510
|
+
- **Use when:** turn a biome file's height fractions into the metres a world actually measured
|
|
7511
|
+
- **Constraints:** samples are finite and at least one; a flat field resolves every band onto its one height
|
|
7512
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6300
7513
|
|
|
6301
7514
|
```ts
|
|
6302
|
-
const
|
|
7515
|
+
const bands = measureBands(spec.layers, state.height);
|
|
6303
7516
|
```
|
|
6304
7517
|
|
|
6305
|
-
### `
|
|
7518
|
+
### `orderedScatterRules`
|
|
6306
7519
|
|
|
6307
|
-
`function` —
|
|
7520
|
+
`function` — A biome's rows as the ordered generators read them. The rule is short and shared; only these numbers differ between a wood, a barren shoulder, a dune field and a tundra, so the biome file names them rather than the code. A biome whose tree is not one this generator has art for fails here, naming the species, rather than planting nothing.
|
|
6308
7521
|
|
|
6309
7522
|
```ts
|
|
6310
|
-
export function
|
|
7523
|
+
export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules { … }
|
|
6311
7524
|
```
|
|
6312
7525
|
|
|
6313
|
-
- **Use when:**
|
|
6314
|
-
- **Constraints:**
|
|
6315
|
-
- **Requires:** npm i @threenative/terrain
|
|
7526
|
+
- **Use when:** run a biome file's rows through the ordered scatter
|
|
7527
|
+
- **Constraints:** the file carries one foliage row, one grass row and a cover block
|
|
7528
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6316
7529
|
|
|
6317
7530
|
```ts
|
|
6318
|
-
const
|
|
7531
|
+
const rules = orderedScatterRules(spec);
|
|
6319
7532
|
```
|
|
6320
7533
|
|
|
6321
|
-
### `
|
|
7534
|
+
### `placeMassif`
|
|
6322
7535
|
|
|
6323
|
-
`function` —
|
|
7536
|
+
`function` — Stands one surveyed mountain behind a world, chosen and posed by a seed: the tile from a list, a point on a bearing and distance, a turn that faces its steepest wall to the centre within 20 degrees, a mirror and a summit height. It stands on the host's own foot (a smooth surface through the host under its border), replacing the host's hills inside its square, and leaves the centre square untouched. Appends one `heightmap` layer; the placement carries the tile-spacing heights a relief map reads.
|
|
6324
7537
|
|
|
6325
7538
|
```ts
|
|
6326
|
-
export
|
|
7539
|
+
export function placeMassif( terrain: Terrain, options: IPlaceMassifOptions, ): { … }
|
|
6327
7540
|
```
|
|
6328
7541
|
|
|
6329
|
-
- **Use when:**
|
|
6330
|
-
- **Constraints:**
|
|
6331
|
-
- **Requires:** npm i @threenative/terrain
|
|
7542
|
+
- **Use when:** put a real-shaped mountain behind a generated world, a different one per seed
|
|
7543
|
+
- **Constraints:** the tile must be a whole mountain whose border is valley floor; erosion after it carves the survey
|
|
7544
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7545
|
+
- **Overrides:** `at`, `bearing`, `distance`, `height`, `top`, `face` and `keepOut` on the same call
|
|
6332
7546
|
|
|
6333
7547
|
```ts
|
|
6334
|
-
const
|
|
7548
|
+
const { terrain, placement } = placeMassif(new Terrain({ size: 5000, resolution: 129 }), { seed: 3, tile: { id: "cone", size: 2000, resolution: 3, heights: [0, 0, 0, 0, 900, 0, 0, 0, 0] } });
|
|
6335
7549
|
```
|
|
6336
7550
|
|
|
6337
|
-
### `
|
|
7551
|
+
### `propAssetOf`
|
|
6338
7552
|
|
|
6339
|
-
`function` —
|
|
7553
|
+
`function` — The asset a package run names. A prop run names the model it draws, `asset:variant[@shape]`; a container written by `bakeWorldPackage` names the asset alone. Both reduce to the asset here, which is what a count, a material or a placement's own `asset` field holds.
|
|
6340
7554
|
|
|
6341
7555
|
```ts
|
|
6342
|
-
export function
|
|
7556
|
+
export function propAssetOf(modelKey: string): string { … }
|
|
6343
7557
|
```
|
|
6344
7558
|
|
|
6345
|
-
- **Use when:**
|
|
6346
|
-
- **
|
|
6347
|
-
- **Requires:** npm i @threenative/terrain
|
|
7559
|
+
- **Use when:** count one species across a world's prop buckets, or name the asset a run draws
|
|
7560
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6348
7561
|
|
|
6349
7562
|
```ts
|
|
6350
|
-
const
|
|
7563
|
+
const asset = propAssetOf("spruce:2"); // "spruce"
|
|
6351
7564
|
```
|
|
6352
7565
|
|
|
6353
|
-
### `
|
|
7566
|
+
### `propPackageFile`
|
|
6354
7567
|
|
|
6355
|
-
`function` —
|
|
7568
|
+
`function` — A path under `world/` that no bucket name can break: `local:true` becomes `local-true`. The bucket's own name is kept in the manifest, so this rename is only a file-system concern.
|
|
6356
7569
|
|
|
6357
7570
|
```ts
|
|
6358
|
-
export function
|
|
7571
|
+
export function propPackageFile(world: string, bucket: string, suffix: string): string { … }
|
|
6359
7572
|
```
|
|
6360
7573
|
|
|
6361
|
-
- **Use when:**
|
|
6362
|
-
- **
|
|
6363
|
-
- **Requires:** npm i @threenative/terrain
|
|
7574
|
+
- **Use when:** name one of a bucket's three files without a bucket key that breaks a path
|
|
7575
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6364
7576
|
|
|
6365
7577
|
```ts
|
|
6366
|
-
const
|
|
7578
|
+
const file = propPackageFile("forest", "local:true", "props.bin"); // "forest.local-true.props.bin"
|
|
6367
7579
|
```
|
|
6368
7580
|
|
|
6369
|
-
### `
|
|
7581
|
+
### `propPackageFiles`
|
|
6370
7582
|
|
|
6371
|
-
`function` —
|
|
7583
|
+
`function` — Write a compiled package as the manifest the game fetches and one set of files per bucket. The manifest names the files rather than embedding them, so a loader fetches only the buckets its query flags keep (`?farForest=on` keeps the far field, `?meadow=off` drops the vista cover).
|
|
6372
7584
|
|
|
6373
7585
|
```ts
|
|
6374
|
-
export
|
|
7586
|
+
export function propPackageFiles(pkg: IPropPackage, world: string): IPropPackageFiles { … }
|
|
6375
7587
|
```
|
|
6376
7588
|
|
|
6377
|
-
- **Use when:**
|
|
6378
|
-
- **Constraints:**
|
|
6379
|
-
- **Requires:** npm i @threenative/terrain
|
|
7589
|
+
- **Use when:** write a compiled package to disk: one manifest and three files per streamed world
|
|
7590
|
+
- **Constraints:** the manifest names the files; nothing here touches a file system
|
|
7591
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6380
7592
|
|
|
6381
7593
|
```ts
|
|
6382
|
-
const
|
|
7594
|
+
const { manifest, files } = propPackageFiles(pkg, "forest");
|
|
6383
7595
|
```
|
|
6384
7596
|
|
|
6385
7597
|
### `sampleHeight`
|
|
@@ -6398,6 +7610,22 @@ sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid(
|
|
|
6398
7610
|
const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
6399
7611
|
```
|
|
6400
7612
|
|
|
7613
|
+
### `scatterProps`
|
|
7614
|
+
|
|
7615
|
+
`function` — Every placement, for one world, from one seed: the game's own rule set, in its own draw order.
|
|
7616
|
+
|
|
7617
|
+
```ts
|
|
7618
|
+
export function scatterProps( data: IOrderedScatterField, focus: { … }
|
|
7619
|
+
```
|
|
7620
|
+
|
|
7621
|
+
- **Use when:** bake a biome that says `"stream": "ordered"`
|
|
7622
|
+
- **Constraints:** `data.rules` is the biome's rows, and `data.field` the ground they were graded on
|
|
7623
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7624
|
+
|
|
7625
|
+
```ts
|
|
7626
|
+
const { placements, counts } = scatterProps(data, focus, clearings);
|
|
7627
|
+
```
|
|
7628
|
+
|
|
6401
7629
|
### `slopeAtIndex`
|
|
6402
7630
|
|
|
6403
7631
|
`function` — Slope in degrees at a heightfield sample.
|
|
@@ -6454,7 +7682,7 @@ const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
|
|
|
6454
7682
|
export class Terrain { … }
|
|
6455
7683
|
```
|
|
6456
7684
|
|
|
6457
|
-
- **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game
|
|
7685
|
+
- **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game · make realistic mountains, hills, desert, coast, tundra or volcano terrain: start from `landform(kind)`, or add `erode({ method: "fluvial" })` for dendritic valleys
|
|
6458
7686
|
- **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
|
|
6459
7687
|
- **Requires:** npm i @threenative/terrain
|
|
6460
7688
|
- **Overrides:** size, resolution, seed and all layer parameters are caller choices
|
|
@@ -6480,6 +7708,38 @@ export class TerrainEvaluator { … }
|
|
|
6480
7708
|
const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());
|
|
6481
7709
|
```
|
|
6482
7710
|
|
|
7711
|
+
### `terrainStats`
|
|
7712
|
+
|
|
7713
|
+
`function` — Landform statistics used to calibrate generators against real DEMs.
|
|
7714
|
+
|
|
7715
|
+
```ts
|
|
7716
|
+
export function terrainStats(height: ArrayLike<number>, n: number, size: number): ITerrainStats { … }
|
|
7717
|
+
```
|
|
7718
|
+
|
|
7719
|
+
- **Use when:** compare generated terrain with a USGS or SRTM crop on the same footprint
|
|
7720
|
+
- **Constraints:** square grids only; compare crops of equal spacing, because slope and curvature depend on it
|
|
7721
|
+
- **Requires:** npm i @threenative/terrain
|
|
7722
|
+
|
|
7723
|
+
```ts
|
|
7724
|
+
const stats = terrainStats(state.height, state.resolution, state.size);
|
|
7725
|
+
```
|
|
7726
|
+
|
|
7727
|
+
### `validateBiome`
|
|
7728
|
+
|
|
7729
|
+
`function` — One biome file, checked field by field. The file is `biome.data.json`: `biome.json` is Biome's own configuration name, and a data file called that is parsed as a project config and fails the lint.
|
|
7730
|
+
|
|
7731
|
+
```ts
|
|
7732
|
+
export function validateBiome(spec: unknown, name: string): IBiomeSpec { … }
|
|
7733
|
+
```
|
|
7734
|
+
|
|
7735
|
+
- **Use when:** read a biome's rules from `starter/<biome>/biome.data.json` before a game or a cook uses them
|
|
7736
|
+
- **Constraints:** The file carries no appearance; colours, materials and shading stay game source
|
|
7737
|
+
- **Requires:** npm i @threenative/terrain
|
|
7738
|
+
|
|
7739
|
+
```ts
|
|
7740
|
+
const spec = validateBiome(JSON.parse(text), "forest");
|
|
7741
|
+
```
|
|
7742
|
+
|
|
6483
7743
|
### `validateDocument`
|
|
6484
7744
|
|
|
6485
7745
|
`function` — Validates the recovered recipe schema, operation allow-lists and numeric bounds.
|
|
@@ -6532,6 +7792,85 @@ export function checkEnvironmentAssets( environment: IEnvironment, assets: reado
|
|
|
6532
7792
|
checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
|
|
6533
7793
|
```
|
|
6534
7794
|
|
|
7795
|
+
### `createEditorSelection`
|
|
7796
|
+
|
|
7797
|
+
`function` — Gesture and transaction mechanics; the caller owns the controls, proxy and all rendering.
|
|
7798
|
+
|
|
7799
|
+
```ts
|
|
7800
|
+
export function createEditorSelection( { … }
|
|
7801
|
+
```
|
|
7802
|
+
|
|
7803
|
+
- **Use when:** drive terrain-editor selection, gizmo drags, undo and saved transactions
|
|
7804
|
+
- **Constraints:** the caller supplies the TransformControls, proxy, controller and every drawing callback
|
|
7805
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7806
|
+
|
|
7807
|
+
```ts
|
|
7808
|
+
const selection = createEditorSelection({ gizmo, proxy, controller, grounding, surface, defaultFootprintSize, refreshPose, drawFootprint, restorePlacement, previewPlacement, setSaving, selectedChanged, setNavigation, message });
|
|
7809
|
+
```
|
|
7810
|
+
|
|
7811
|
+
### `createTweakBox`
|
|
7812
|
+
|
|
7813
|
+
`function` — A box of range bars and colour pickers over the running game, for tuning numbers by eye. The game names its knobs and applies each change itself; the box owns the page elements, the stored values and the Copy button, whose JSON is what gets pasted back and written into the game's own source. With no `document` (a native launch, a test) it draws nothing and still holds the values, so the game code that reads them is the same on every target.
|
|
7814
|
+
|
|
7815
|
+
```ts
|
|
7816
|
+
export function createTweakBox<K extends string>(options: ITweakBoxOptions<K>): ITweakBox<K> { … }
|
|
7817
|
+
```
|
|
7818
|
+
|
|
7819
|
+
- **Use when:** tune look numbers by eye with live range bars and colour pickers while the game runs
|
|
7820
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7821
|
+
|
|
7822
|
+
```ts
|
|
7823
|
+
const box = createTweakBox({ title: "Fog", knobs: { density: { min: 0, max: 0.1, value: 0.02 } }, onChange: (name, value) => console.info(name, value) });
|
|
7824
|
+
```
|
|
7825
|
+
|
|
7826
|
+
### `editorPlacementCenter`
|
|
7827
|
+
|
|
7828
|
+
`function` — Transform the caller's measured geometry centre into the evaluated placement's world space.
|
|
7829
|
+
|
|
7830
|
+
```ts
|
|
7831
|
+
export function editorPlacementCenter(point: Vector3, pose: IPlacementOverride): Vector3 { … }
|
|
7832
|
+
```
|
|
7833
|
+
|
|
7834
|
+
- **Use when:** find the world-space centre of a placed terrain-editor instance
|
|
7835
|
+
- **Constraints:** the point is multiplied in place; the pose needs finite position, quaternion and scale
|
|
7836
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7837
|
+
|
|
7838
|
+
```ts
|
|
7839
|
+
const centre = editorPlacementCenter(localCentre.clone(), placement);
|
|
7840
|
+
```
|
|
7841
|
+
|
|
7842
|
+
### `editorPointToClient`
|
|
7843
|
+
|
|
7844
|
+
`function` — Project an injected world point to client pixels in the caller's viewport.
|
|
7845
|
+
|
|
7846
|
+
```ts
|
|
7847
|
+
export function editorPointToClient( point: Vector3, camera: Camera, box: { … }
|
|
7848
|
+
```
|
|
7849
|
+
|
|
7850
|
+
- **Use when:** convert a terrain-editor world point to viewport client pixels
|
|
7851
|
+
- **Constraints:** the point is projected in place; pass a clone to keep the original
|
|
7852
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7853
|
+
|
|
7854
|
+
```ts
|
|
7855
|
+
const [x, y] = editorPointToClient(point.clone(), camera, canvas.getBoundingClientRect());
|
|
7856
|
+
```
|
|
7857
|
+
|
|
7858
|
+
### `editorSurfaceHeight`
|
|
7859
|
+
|
|
7860
|
+
`function` — Query the rendered heightfield, including its triangulation rather than an interpolated bake.
|
|
7861
|
+
|
|
7862
|
+
```ts
|
|
7863
|
+
export function editorSurfaceHeight( ctx: { … }
|
|
7864
|
+
```
|
|
7865
|
+
|
|
7866
|
+
- **Use when:** query terrain-editor surface elevation at world X/Z coordinates
|
|
7867
|
+
- **Constraints:** the supplied mesh and raycast determine the surface; missing intersections return undefined
|
|
7868
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7869
|
+
|
|
7870
|
+
```ts
|
|
7871
|
+
const height = editorSurfaceHeight(ctx, terrainMesh, x, z);
|
|
7872
|
+
```
|
|
7873
|
+
|
|
6535
7874
|
### `focusCamera`
|
|
6536
7875
|
|
|
6537
7876
|
`function` — Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera
|
|
@@ -6583,6 +7922,22 @@ export function inspectSpatial( state: ITerrainState, revision: string, query: I
|
|
|
6583
7922
|
const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
|
|
6584
7923
|
```
|
|
6585
7924
|
|
|
7925
|
+
### `landformPose`
|
|
7926
|
+
|
|
7927
|
+
`function` — Recipe footprints are heights over X/Z, never independently transformed solids.
|
|
7928
|
+
|
|
7929
|
+
```ts
|
|
7930
|
+
export function landformPose(layer: Layer, worldSize: number, defaultSize: number) { … }
|
|
7931
|
+
```
|
|
7932
|
+
|
|
7933
|
+
- **Use when:** derive a terrain-editor gizmo pose from a landform layer
|
|
7934
|
+
- **Constraints:** the caller supplies world and default footprint sizes; unsupported layers return undefined
|
|
7935
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7936
|
+
|
|
7937
|
+
```ts
|
|
7938
|
+
const pose = landformPose(layer, terrain.size, footprintSize);
|
|
7939
|
+
```
|
|
7940
|
+
|
|
6586
7941
|
### `mountTerrainEditor`
|
|
6587
7942
|
|
|
6588
7943
|
`function` — Mount recovered terrain controls around the project-owned ThreeNative view.
|
|
@@ -6600,6 +7955,38 @@ export async function mountTerrainEditor(options: { … }
|
|
|
6600
7955
|
await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
|
|
6601
7956
|
```
|
|
6602
7957
|
|
|
7958
|
+
### `pickEditorPlacement`
|
|
7959
|
+
|
|
7960
|
+
`function` — A foreground terrain hit occludes placements; matching uses the evaluated world position.
|
|
7961
|
+
|
|
7962
|
+
```ts
|
|
7963
|
+
export function pickEditorPlacement( ctx: Parameters<typeof pickEditorSurface>[0], terrain: Mesh, meshes: readonly Object3D[], placements: Iterable< { … }
|
|
7964
|
+
```
|
|
7965
|
+
|
|
7966
|
+
- **Use when:** pick a placed instance in the terrain editor from viewport client coordinates
|
|
7967
|
+
- **Constraints:** the caller supplies the raycast context, terrain mesh, instanced meshes and evaluated placements
|
|
7968
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7969
|
+
|
|
7970
|
+
```ts
|
|
7971
|
+
const id = pickEditorPlacement(ctx, terrainMesh, meshes, placements, event.clientX, event.clientY);
|
|
7972
|
+
```
|
|
7973
|
+
|
|
7974
|
+
### `pickEditorSurface`
|
|
7975
|
+
|
|
7976
|
+
`function` — Convert viewport client coordinates once; the installed picker owns ray intersection.
|
|
7977
|
+
|
|
7978
|
+
```ts
|
|
7979
|
+
export function pickEditorSurface( ctx: { … }
|
|
7980
|
+
```
|
|
7981
|
+
|
|
7982
|
+
- **Use when:** pick a terrain-editor surface from viewport client coordinates
|
|
7983
|
+
- **Constraints:** the caller supplies the raycast implementation and ordered targets
|
|
7984
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7985
|
+
|
|
7986
|
+
```ts
|
|
7987
|
+
const hit = pickEditorSurface(ctx, [terrainMesh], event.clientX, event.clientY);
|
|
7988
|
+
```
|
|
7989
|
+
|
|
6603
7990
|
### `probeTerrain`
|
|
6604
7991
|
|
|
6605
7992
|
`function` — Probe the evaluated surface at one world point, separating bilinear from triangle values.
|
|
@@ -6702,6 +8089,22 @@ export class TerrainEditorController { … }
|
|
|
6702
8089
|
const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
|
|
6703
8090
|
```
|
|
6704
8091
|
|
|
8092
|
+
### `transformedLandform`
|
|
8093
|
+
|
|
8094
|
+
`function` — Convert a terrain-editor gizmo pose into a heightfield landform footprint.
|
|
8095
|
+
|
|
8096
|
+
```ts
|
|
8097
|
+
export function transformedLandform( layer: Layer, position: Vector3, quaternion: Quaternion, scale: Vector3, anchor: number, ): Layer { … }
|
|
8098
|
+
```
|
|
8099
|
+
|
|
8100
|
+
- **Use when:** apply a terrain-editor gizmo transform to a landform layer
|
|
8101
|
+
- **Constraints:** finite coordinates and positive scales are required; X/Z rotations that overhang throw
|
|
8102
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8103
|
+
|
|
8104
|
+
```ts
|
|
8105
|
+
const next = transformedLandform(layer, position, quaternion, scale, surfaceHeight);
|
|
8106
|
+
```
|
|
8107
|
+
|
|
6705
8108
|
### `validateAsset`
|
|
6706
8109
|
|
|
6707
8110
|
`function` — Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry
|
|
@@ -6859,21 +8262,104 @@ const document = new TerrainEditorDocument("/project/terrain/world.json"); const
|
|
|
6859
8262
|
|
|
6860
8263
|
## `@threenative/terrain/export`
|
|
6861
8264
|
|
|
6862
|
-
### `
|
|
8265
|
+
### `prepareWorldGLTF`
|
|
8266
|
+
|
|
8267
|
+
`function` — Prepare the game's validated, frozen portable scene; the server cook owns GLB encoding.
|
|
8268
|
+
|
|
8269
|
+
```ts
|
|
8270
|
+
export async function prepareWorldGLTF(input: IWorldGLBInput): Promise< { … }
|
|
8271
|
+
```
|
|
8272
|
+
|
|
8273
|
+
- **Use when:** export the terrain as a glb for another three.js project via the headless cook · prepare the terrain editor's resolved world for headless portable GLB cooking
|
|
8274
|
+
- **Constraints:** browser authoring FileReader/canvas; all appearance and coherent water come from the game
|
|
8275
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8276
|
+
|
|
8277
|
+
```ts
|
|
8278
|
+
const prepared = await prepareWorldGLTF(input);
|
|
8279
|
+
```
|
|
8280
|
+
|
|
8281
|
+
## `@threenative/terrain/kit`
|
|
8282
|
+
|
|
8283
|
+
### `bakeKit`
|
|
8284
|
+
|
|
8285
|
+
`function` — Bake a copied kit, optionally using the caller's installed world cook.
|
|
8286
|
+
|
|
8287
|
+
```ts
|
|
8288
|
+
export async function bakeKit( url: string, { … }
|
|
8289
|
+
```
|
|
8290
|
+
|
|
8291
|
+
- **Use when:** bake a copied terrain starter kit into its offline world package
|
|
8292
|
+
- **Constraints:** Node authoring only; recipes, asset tables and sky paths stay in the game
|
|
8293
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8294
|
+
|
|
8295
|
+
```ts
|
|
8296
|
+
await bakeKit(import.meta.url, { sky: "hdri/game-sky.hdr" });
|
|
8297
|
+
```
|
|
8298
|
+
|
|
8299
|
+
### `starterAssetsDir`
|
|
8300
|
+
|
|
8301
|
+
`function` — Resolve shared starter assets locally, or download the package's pinned archive on demand.
|
|
8302
|
+
|
|
8303
|
+
```ts
|
|
8304
|
+
export async function starterAssetsDir(): Promise<string> { … }
|
|
8305
|
+
```
|
|
8306
|
+
|
|
8307
|
+
- **Use when:** resolve terrain kit models and textures for offline baking
|
|
8308
|
+
- **Constraints:** Node authoring only; verifies archive size and SHA256 before atomic extraction
|
|
8309
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8310
|
+
|
|
8311
|
+
```ts
|
|
8312
|
+
const assets = await starterAssetsDir();
|
|
8313
|
+
```
|
|
8314
|
+
|
|
8315
|
+
## `@threenative/terrain/starter`
|
|
8316
|
+
|
|
8317
|
+
### `addStarterWorld`
|
|
8318
|
+
|
|
8319
|
+
`function` — Load caller-authored starter data with one scene lifetime; all appearance comes from spec.
|
|
8320
|
+
|
|
8321
|
+
```ts
|
|
8322
|
+
export async function addStarterWorld<Extra extends { … }
|
|
8323
|
+
```
|
|
8324
|
+
|
|
8325
|
+
- **Use when:** attach a baked starter world with game-owned surfaces, prop dressing and water
|
|
8326
|
+
- **Constraints:** Runtime subpath; the game supplies every appearance and collision choice
|
|
8327
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8328
|
+
|
|
8329
|
+
```ts
|
|
8330
|
+
await addStarterWorld(ctx, follow, spec);
|
|
8331
|
+
```
|
|
8332
|
+
|
|
8333
|
+
### `editWorldPlacements`
|
|
8334
|
+
|
|
8335
|
+
`function` — Apply deterministic startup edits to the decoded placement data before a world is loaded.
|
|
8336
|
+
|
|
8337
|
+
```ts
|
|
8338
|
+
export function editWorldPlacements( data: { … }
|
|
8339
|
+
```
|
|
8340
|
+
|
|
8341
|
+
- **Use when:** change generated terrain composition from game source without rebaking the world
|
|
8342
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8343
|
+
- **Overrides:** grounding defaults on, while `grounding: false` preserves the authored Y coordinate
|
|
8344
|
+
|
|
8345
|
+
```ts
|
|
8346
|
+
const edited = editWorldPlacements(data, { remove: ["scree:candidate:7:41"] }, (x, z) => field.heightAt(x, z));
|
|
8347
|
+
```
|
|
8348
|
+
|
|
8349
|
+
### `PropColliders`
|
|
6863
8350
|
|
|
6864
|
-
`
|
|
8351
|
+
`class` — Stream caller-specified fixed collision shapes around a moving follow object.
|
|
6865
8352
|
|
|
6866
8353
|
```ts
|
|
6867
|
-
export
|
|
8354
|
+
export class PropColliders extends Object3D implements IComputeDriven { … }
|
|
6868
8355
|
```
|
|
6869
8356
|
|
|
6870
|
-
- **Use when:**
|
|
6871
|
-
- **Constraints:**
|
|
8357
|
+
- **Use when:** attach nearby prop collision bodies from baked placement records
|
|
8358
|
+
- **Constraints:** Shapes and reach are supplied by the game; detach releases every body
|
|
6872
8359
|
- **Requires:** npm i -D @threenative/terrain
|
|
6873
|
-
- **Overrides:** actual static models, final matrices and baked PBR maps are supplied by the game
|
|
6874
8360
|
|
|
6875
8361
|
```ts
|
|
6876
|
-
|
|
8362
|
+
new PropColliders(ctx, follow, manifest, records, shapes, reach, name);
|
|
6877
8363
|
```
|
|
6878
8364
|
|
|
6879
8365
|
## `@threenative/terrain/three`
|