create-threenative 0.2.8 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-docs/references/assertion-reference.md +87 -35
- package/agent-docs/references/auto-exposure.md +57 -0
- package/agent-docs/references/capability-reference.md +1097 -23
- package/agent-docs/references/debug-surface.md +6 -0
- package/agent-docs/references/finding-assets.md +46 -10
- package/agent-docs/references/performance-basics.md +5 -4
- package/agent-docs/references/terrain-authoring.md +140 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
- package/capabilities.json +1210 -27
- package/dist/index.d.ts +28 -3
- package/dist/index.js +396 -166
- package/dist/threenative.js +986 -235
- package/dist/web-engine-buffer-geometry-utils.js +281 -0
- package/dist/web-engine-decal-geometry.js +184 -0
- package/dist/web-engine-gltf-loader.js +196 -0
- package/dist/web-engine-hdr-loader.js +190 -0
- package/dist/web-engine-lut-cube-loader.js +122 -0
- package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
- package/dist/web-engine-mesh-bvh.js +32 -0
- package/dist/web-engine-post-effects.js +168 -0
- package/dist/web-engine-runtime.js +42506 -0
- package/package.json +11 -8
- package/template-assets/autoExposure.ts +225 -0
- package/template-assets/exposure.ts +111 -0
- package/template-assets/exposureGraph.ts +178 -0
- package/template-assets/exposureReadback.ts +79 -0
- package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
- package/template-assets/patches/three@0.185.1.patch +6594 -700
- package/template-assets/patches/vite@8.2.0.patch +422 -0
- package/template-assets/worldEnvironment.ts +433 -30
- package/templates/action-rpg/AGENTS.md +11 -10
- package/templates/action-rpg/CLAUDE.md +11 -10
- package/templates/action-rpg/package.json +11 -9
- package/templates/action-rpg/playtests/performance.playtest.json +7 -1
- package/templates/action-rpg/src/progress.ts +0 -4
- package/templates/action-rpg/src/render/autoExposure.ts +225 -0
- package/templates/action-rpg/src/render/backlightControls.ts +66 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
- package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
- package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
- package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
- package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
- package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
- package/templates/action-rpg/src/render/exposure.ts +111 -0
- package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
- package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
- package/templates/action-rpg/src/render/heightFog.ts +118 -0
- package/templates/action-rpg/src/render/lighting.ts +26 -1
- package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
- package/templates/action-rpg/src/render/materialLighting.ts +155 -0
- package/templates/action-rpg/src/render/postprocessing.ts +17 -2
- package/templates/action-rpg/src/render/quality.ts +61 -2
- package/templates/action-rpg/src/render/sky.ts +21 -1
- package/templates/action-rpg/src/render/vfx.ts +133 -58
- package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
- package/templates/action-rpg/src/scenes/Play.ts +81 -16
- package/templates/action-rpg/threenative.config.ts +3 -0
- package/templates/action-rpg/vite.config.ts +10 -2
- package/templates/minimal/AGENTS.md +9 -10
- package/templates/minimal/CLAUDE.md +9 -10
- package/templates/minimal/package.json +9 -8
- package/templates/minimal/playtests/play.playtest.json +7 -1
- package/templates/minimal/playtests/sky.playtest.json +10 -1
- package/templates/minimal/src/render/autoExposure.ts +225 -0
- package/templates/minimal/src/render/backlightControls.ts +66 -0
- package/templates/minimal/src/render/backlightMaterial.ts +147 -0
- package/templates/minimal/src/render/environmentContribution.ts +188 -0
- package/templates/minimal/src/render/environmentRadiance.ts +36 -0
- package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
- package/templates/minimal/src/render/environmentSampling.ts +193 -0
- package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
- package/templates/minimal/src/render/exposure.ts +111 -0
- package/templates/minimal/src/render/exposureGraph.ts +178 -0
- package/templates/minimal/src/render/exposureReadback.ts +79 -0
- package/templates/minimal/src/render/heightFog.ts +118 -0
- package/templates/minimal/src/render/lighting.ts +25 -1
- package/templates/minimal/src/render/materialAssignments.ts +102 -0
- package/templates/minimal/src/render/materialLighting.ts +146 -0
- package/templates/minimal/src/render/postprocessing.ts +16 -2
- package/templates/minimal/src/render/quality.ts +60 -2
- package/templates/minimal/src/render/sky.ts +21 -1
- package/templates/minimal/src/render/worldEnvironment.ts +433 -30
- package/templates/minimal/src/scenes/Play.ts +50 -1
- package/templates/minimal/vite.config.ts +10 -2
- package/templates/platformer/AGENTS.md +7 -5
- package/templates/platformer/CLAUDE.md +7 -5
- package/templates/platformer/package.json +11 -9
- package/templates/platformer/playtests/performance.playtest.json +7 -1
- package/templates/platformer/src/render/autoExposure.ts +225 -0
- package/templates/platformer/src/render/backlightControls.ts +66 -0
- package/templates/platformer/src/render/backlightMaterial.ts +147 -0
- package/templates/platformer/src/render/environmentContribution.ts +188 -0
- package/templates/platformer/src/render/environmentRadiance.ts +36 -0
- package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
- package/templates/platformer/src/render/environmentSampling.ts +193 -0
- package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
- package/templates/platformer/src/render/exposure.ts +111 -0
- package/templates/platformer/src/render/exposureGraph.ts +178 -0
- package/templates/platformer/src/render/exposureReadback.ts +79 -0
- package/templates/platformer/src/render/heightFog.ts +118 -0
- package/templates/platformer/src/render/lighting.ts +26 -1
- package/templates/platformer/src/render/materialAssignments.ts +160 -0
- package/templates/platformer/src/render/materialLighting.ts +155 -0
- package/templates/platformer/src/render/materials.ts +7 -2
- package/templates/platformer/src/render/palette.ts +3 -3
- package/templates/platformer/src/render/postprocessing.ts +17 -2
- package/templates/platformer/src/render/quality.ts +61 -2
- package/templates/platformer/src/render/sky.ts +72 -23
- package/templates/platformer/src/render/skyEnvironment.ts +50 -0
- package/templates/platformer/src/render/worldEnvironment.ts +433 -30
- package/templates/platformer/src/scenes/Play.ts +70 -6
- package/templates/platformer/vite.config.ts +10 -2
- package/templates/puzzle/AGENTS.md +10 -9
- package/templates/puzzle/CLAUDE.md +10 -9
- package/templates/puzzle/package.json +11 -9
- package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
- package/templates/puzzle/playtests/lit.playtest.json +7 -1
- package/templates/puzzle/playtests/performance.playtest.json +7 -1
- package/templates/puzzle/src/render/autoExposure.ts +225 -0
- package/templates/puzzle/src/render/backlightControls.ts +66 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
- package/templates/puzzle/src/render/environmentContribution.ts +188 -0
- package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
- package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
- package/templates/puzzle/src/render/environmentSampling.ts +193 -0
- package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
- package/templates/puzzle/src/render/exposure.ts +111 -0
- package/templates/puzzle/src/render/exposureGraph.ts +178 -0
- package/templates/puzzle/src/render/exposureReadback.ts +79 -0
- package/templates/puzzle/src/render/heightFog.ts +118 -0
- package/templates/puzzle/src/render/lighting.ts +33 -1
- package/templates/puzzle/src/render/materialAssignments.ts +160 -0
- package/templates/puzzle/src/render/materialLighting.ts +155 -0
- package/templates/puzzle/src/render/materials.ts +1 -1
- package/templates/puzzle/src/render/postprocessing.ts +8 -2
- package/templates/puzzle/src/render/quality.ts +62 -1
- package/templates/puzzle/src/render/sky.ts +20 -1
- package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
- package/templates/puzzle/src/scenes/Play.ts +51 -2
- package/templates/puzzle/vite.config.ts +10 -2
- package/templates/racing/AGENTS.md +8 -7
- package/templates/racing/CLAUDE.md +8 -7
- package/templates/racing/package.json +11 -9
- package/templates/racing/playtests/performance.playtest.json +7 -1
- package/templates/racing/playtests/survives.playtest.json +6 -0
- package/templates/racing/src/render/autoExposure.ts +225 -0
- package/templates/racing/src/render/backlightControls.ts +66 -0
- package/templates/racing/src/render/backlightMaterial.ts +147 -0
- package/templates/racing/src/render/environmentContribution.ts +188 -0
- package/templates/racing/src/render/environmentRadiance.ts +36 -0
- package/templates/racing/src/render/environmentSampleCache.ts +43 -0
- package/templates/racing/src/render/environmentSampling.ts +193 -0
- package/templates/racing/src/render/environmentSnapshot.ts +53 -0
- package/templates/racing/src/render/exposure.ts +111 -0
- package/templates/racing/src/render/exposureGraph.ts +178 -0
- package/templates/racing/src/render/exposureReadback.ts +79 -0
- package/templates/racing/src/render/heightFog.ts +118 -0
- package/templates/racing/src/render/lighting.ts +29 -1
- package/templates/racing/src/render/materialAssignments.ts +160 -0
- package/templates/racing/src/render/materialLighting.ts +155 -0
- package/templates/racing/src/render/palette.ts +1 -10
- package/templates/racing/src/render/postprocessing.ts +17 -2
- package/templates/racing/src/render/quality.ts +61 -2
- package/templates/racing/src/render/shapes.ts +0 -25
- package/templates/racing/src/render/sky.ts +21 -1
- package/templates/racing/src/render/worldEnvironment.ts +433 -30
- package/templates/racing/src/scenes/Race.ts +91 -3
- package/templates/racing/src/track/circuit.ts +0 -9
- package/templates/racing/vite.config.ts +10 -2
- package/templates/rain/AGENTS.md +8 -9
- package/templates/rain/CLAUDE.md +8 -9
- package/templates/rain/native-playtests/boot.playtest.json +11 -1
- package/templates/rain/package.json +12 -9
- package/templates/rain/playtests/automation.playtest.json +1 -1
- package/templates/rain/playtests/performance.playtest.json +11 -1
- package/templates/rain/playtests/tiers.playtest.json +15 -0
- package/templates/rain/playtests/weather.playtest.json +1 -1
- package/templates/rain/src/game.ts +1 -34
- package/templates/rain/src/render/autoExposure.ts +225 -0
- package/templates/rain/src/render/exposure.ts +111 -0
- package/templates/rain/src/render/exposureGraph.ts +178 -0
- package/templates/rain/src/render/exposureReadback.ts +79 -0
- package/templates/rain/src/render/postprocessing.ts +3 -0
- package/templates/rain/src/render/quality.ts +27 -1
- package/templates/rain/src/render/worldEnvironment.ts +433 -30
- package/templates/rain/src/scenes/Boot.ts +14 -0
- package/templates/rain/src/state.ts +5 -1
- package/templates/rain/src/ui/GameUi.tsx +6 -6
- package/templates/rain/tools/generate-shaders.mjs +1 -1
- package/templates/rain/vite.config.ts +10 -2
- package/templates/rts/AGENTS.md +10 -11
- package/templates/rts/CLAUDE.md +10 -11
- package/templates/rts/package.json +10 -8
- package/templates/rts/playtests/performance.playtest.json +7 -1
- package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-build.playtest.json +10 -1
- package/templates/rts/playtests/rts-orders.playtest.json +7 -1
- package/templates/rts/playtests/rts-train.playtest.json +10 -1
- package/templates/rts/src/render/army.ts +10 -2
- package/templates/rts/src/render/autoExposure.ts +225 -0
- package/templates/rts/src/render/backlightControls.ts +66 -0
- package/templates/rts/src/render/backlightMaterial.ts +147 -0
- package/templates/rts/src/render/environmentContribution.ts +188 -0
- package/templates/rts/src/render/environmentRadiance.ts +36 -0
- package/templates/rts/src/render/environmentSampleCache.ts +43 -0
- package/templates/rts/src/render/environmentSampling.ts +193 -0
- package/templates/rts/src/render/environmentSnapshot.ts +53 -0
- package/templates/rts/src/render/exposure.ts +111 -0
- package/templates/rts/src/render/exposureGraph.ts +178 -0
- package/templates/rts/src/render/exposureReadback.ts +79 -0
- package/templates/rts/src/render/heightFog.ts +118 -0
- package/templates/rts/src/render/lighting.ts +26 -1
- package/templates/rts/src/render/materialAssignments.ts +160 -0
- package/templates/rts/src/render/materialLighting.ts +155 -0
- package/templates/rts/src/render/postprocessing.ts +8 -2
- package/templates/rts/src/render/quality.ts +61 -2
- package/templates/rts/src/render/sky.ts +21 -1
- package/templates/rts/src/render/worldEnvironment.ts +433 -30
- package/templates/rts/src/scenes/Play.ts +54 -3
- package/templates/rts/src/sim/ai.ts +0 -1
- package/templates/rts/src/sim/terrain.ts +0 -4
- package/templates/rts/vite.config.ts +10 -2
- package/templates/runner/AGENTS.md +10 -8
- package/templates/runner/CLAUDE.md +10 -8
- package/templates/runner/package.json +11 -9
- package/templates/runner/playtests/performance.playtest.json +10 -1
- package/templates/runner/src/physics.ts +0 -1
- package/templates/runner/src/render/autoExposure.ts +225 -0
- package/templates/runner/src/render/backlightControls.ts +66 -0
- package/templates/runner/src/render/backlightMaterial.ts +147 -0
- package/templates/runner/src/render/environmentContribution.ts +188 -0
- package/templates/runner/src/render/environmentRadiance.ts +36 -0
- package/templates/runner/src/render/environmentSampleCache.ts +43 -0
- package/templates/runner/src/render/environmentSampling.ts +193 -0
- package/templates/runner/src/render/environmentSnapshot.ts +53 -0
- package/templates/runner/src/render/exposure.ts +111 -0
- package/templates/runner/src/render/exposureGraph.ts +178 -0
- package/templates/runner/src/render/exposureReadback.ts +79 -0
- package/templates/runner/src/render/heightFog.ts +118 -0
- package/templates/runner/src/render/lighting.ts +26 -1
- package/templates/runner/src/render/materialAssignments.ts +160 -0
- package/templates/runner/src/render/materialLighting.ts +155 -0
- package/templates/runner/src/render/postprocessing.ts +17 -2
- package/templates/runner/src/render/quality.ts +61 -2
- package/templates/runner/src/render/sky.ts +21 -1
- package/templates/runner/src/render/worldEnvironment.ts +433 -30
- package/templates/runner/src/scenes/Run.ts +67 -2
- package/templates/runner/threenative.config.ts +3 -0
- package/templates/runner/vite.config.ts +10 -2
- package/templates/sailing/AGENTS.md +14 -13
- package/templates/sailing/CLAUDE.md +14 -13
- package/templates/sailing/native-playtests/survives.playtest.json +7 -0
- package/templates/sailing/package.json +11 -9
- package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
- package/templates/sailing/src/entities/Ship.ts +38 -18
- package/templates/sailing/src/render/autoExposure.ts +225 -0
- package/templates/sailing/src/render/backlightControls.ts +66 -0
- package/templates/sailing/src/render/backlightMaterial.ts +147 -0
- package/templates/sailing/src/render/camera.ts +12 -4
- package/templates/sailing/src/render/environmentContribution.ts +188 -0
- package/templates/sailing/src/render/environmentRadiance.ts +36 -0
- package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
- package/templates/sailing/src/render/environmentSampling.ts +193 -0
- package/templates/sailing/src/render/environmentSetup.ts +24 -0
- package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
- package/templates/sailing/src/render/exposure.ts +111 -0
- package/templates/sailing/src/render/exposureGraph.ts +178 -0
- package/templates/sailing/src/render/exposureReadback.ts +79 -0
- package/templates/sailing/src/render/heightFog.ts +118 -0
- package/templates/sailing/src/render/lighting.ts +26 -1
- package/templates/sailing/src/render/materialAssignments.ts +160 -0
- package/templates/sailing/src/render/materialLighting.ts +155 -0
- package/templates/sailing/src/render/ocean.ts +71 -53
- package/templates/sailing/src/render/postprocessing.ts +16 -2
- package/templates/sailing/src/render/props.ts +0 -45
- package/templates/sailing/src/render/quality.ts +61 -1
- package/templates/sailing/src/render/sky.ts +21 -1
- package/templates/sailing/src/render/worldEnvironment.ts +433 -30
- package/templates/sailing/src/scenes/Boot.ts +12 -1
- package/templates/sailing/src/scenes/Sailing.ts +87 -2
- package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
- package/templates/sailing/threenative.config.ts +3 -0
- package/templates/sailing/vite.config.ts +10 -2
- package/templates/shooter/AGENTS.md +8 -6
- package/templates/shooter/CLAUDE.md +8 -6
- package/templates/shooter/package.json +11 -9
- package/templates/shooter/playtests/performance.playtest.json +7 -1
- package/templates/shooter/src/entities/Enemy.ts +0 -15
- package/templates/shooter/src/entities/Rifle.ts +38 -1
- package/templates/shooter/src/render/autoExposure.ts +225 -0
- package/templates/shooter/src/render/backlightControls.ts +66 -0
- package/templates/shooter/src/render/backlightMaterial.ts +147 -0
- package/templates/shooter/src/render/camera.ts +1 -12
- package/templates/shooter/src/render/decals.ts +299 -5
- package/templates/shooter/src/render/environmentContribution.ts +188 -0
- package/templates/shooter/src/render/environmentRadiance.ts +36 -0
- package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
- package/templates/shooter/src/render/environmentSampling.ts +193 -0
- package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
- package/templates/shooter/src/render/exposure.ts +111 -0
- package/templates/shooter/src/render/exposureGraph.ts +178 -0
- package/templates/shooter/src/render/exposureReadback.ts +79 -0
- package/templates/shooter/src/render/gunfx.ts +0 -1
- package/templates/shooter/src/render/heightFog.ts +118 -0
- package/templates/shooter/src/render/lighting.ts +26 -1
- package/templates/shooter/src/render/materialAssignments.ts +160 -0
- package/templates/shooter/src/render/materialLighting.ts +155 -0
- package/templates/shooter/src/render/postprocessing.ts +17 -2
- package/templates/shooter/src/render/quality.ts +61 -2
- package/templates/shooter/src/render/scale.ts +2 -93
- package/templates/shooter/src/render/sky.ts +21 -1
- package/templates/shooter/src/render/vehicles.ts +0 -17
- package/templates/shooter/src/render/worldEnvironment.ts +433 -30
- package/templates/shooter/src/scenes/Play.ts +64 -2
- package/templates/shooter/vite.config.ts +10 -2
- package/templates/snow/AGENTS.md +8 -6
- package/templates/snow/CLAUDE.md +8 -6
- package/templates/snow/package.json +11 -9
- package/templates/snow/src/render/autoExposure.ts +225 -0
- package/templates/snow/src/render/backlightControls.ts +66 -0
- package/templates/snow/src/render/backlightMaterial.ts +147 -0
- package/templates/snow/src/render/environmentContribution.ts +188 -0
- package/templates/snow/src/render/environmentRadiance.ts +36 -0
- package/templates/snow/src/render/environmentSampleCache.ts +43 -0
- package/templates/snow/src/render/environmentSampling.ts +193 -0
- package/templates/snow/src/render/environmentSnapshot.ts +53 -0
- package/templates/snow/src/render/exposure.ts +111 -0
- package/templates/snow/src/render/exposureGraph.ts +178 -0
- package/templates/snow/src/render/exposureReadback.ts +79 -0
- package/templates/snow/src/render/heightFog.ts +118 -0
- package/templates/snow/src/render/lighting.ts +33 -1
- package/templates/snow/src/render/materialAssignments.ts +160 -0
- package/templates/snow/src/render/materialLighting.ts +155 -0
- package/templates/snow/src/render/postprocessing.ts +16 -2
- package/templates/snow/src/render/quality.ts +59 -1
- package/templates/snow/src/render/sky.ts +21 -2
- package/templates/snow/src/render/worldEnvironment.ts +433 -30
- package/templates/snow/src/scenes/Snow.ts +29 -1
- package/templates/snow/threenative.config.ts +3 -0
- package/templates/snow/vite.config.ts +10 -2
- package/templates/starter/AGENTS.md +11 -16
- package/templates/starter/CLAUDE.md +11 -16
- package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
- package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
- package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
- package/templates/starter/package.json +11 -9
- package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
- package/templates/starter/playtests/movement.playtest.json +192 -0
- package/templates/starter/playtests/play.playtest.json +18 -2
- package/templates/starter/playtests/production-readiness.playtest.json +1 -1
- package/templates/starter/public/grade.cube +735 -0
- package/templates/starter/src/entities/Crate.ts +4 -0
- package/templates/starter/src/entities/Player.ts +79 -18
- package/templates/starter/src/game.ts +1 -0
- package/templates/starter/src/render/adaptiveQuality.ts +28 -41
- package/templates/starter/src/render/autoExposure.ts +225 -0
- package/templates/starter/src/render/backlightControls.ts +66 -0
- package/templates/starter/src/render/backlightMaterial.ts +147 -0
- package/templates/starter/src/render/environmentContribution.ts +188 -0
- package/templates/starter/src/render/environmentRadiance.ts +36 -0
- package/templates/starter/src/render/environmentSampleCache.ts +43 -0
- package/templates/starter/src/render/environmentSampling.ts +193 -0
- package/templates/starter/src/render/environmentSnapshot.ts +53 -0
- package/templates/starter/src/render/exposure.ts +111 -0
- package/templates/starter/src/render/exposureGraph.ts +178 -0
- package/templates/starter/src/render/exposureReadback.ts +79 -0
- package/templates/starter/src/render/grade.ts +157 -0
- package/templates/starter/src/render/heightFog.ts +118 -0
- package/templates/starter/src/render/lighting.ts +26 -1
- package/templates/starter/src/render/materialAssignments.ts +160 -0
- package/templates/starter/src/render/materialLighting.ts +155 -0
- package/templates/starter/src/render/postprocessing.ts +84 -4
- package/templates/starter/src/render/quality.ts +80 -8
- package/templates/starter/src/render/qualityPolicy.ts +54 -0
- package/templates/starter/src/render/rendererGate.ts +36 -0
- package/templates/starter/src/render/sky.ts +23 -1
- package/templates/starter/src/render/temporalAA.ts +197 -0
- package/templates/starter/src/render/temporalAAFrame.ts +179 -0
- package/templates/starter/src/render/temporalAAHooks.ts +101 -0
- package/templates/starter/src/render/temporalAAInput.ts +56 -0
- package/templates/starter/src/render/temporalAAResolve.ts +65 -0
- package/templates/starter/src/render/temporalAAStage.ts +76 -0
- package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
- package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
- package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
- package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
- package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
- package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
- package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
- package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
- package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
- package/templates/starter/src/render/temporalResolve.ts +139 -0
- package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
- package/templates/starter/src/render/temporalResolveMath.ts +196 -0
- package/templates/starter/src/render/volumetricFog.ts +124 -0
- package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
- package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
- package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
- package/templates/starter/src/render/worldEnvironment.ts +433 -30
- package/templates/starter/src/scenes/Play.ts +110 -1
- package/templates/starter/src/state.ts +1 -0
- package/templates/starter/src/ui/Hud.tsx +1 -1
- package/templates/starter/src/ui/Menu.tsx +1 -1
- package/templates/starter/tools/make-grade-lut.mjs +101 -0
- package/templates/starter/vite.config.ts +10 -2
- package/templates/tower-defense/AGENTS.md +10 -9
- package/templates/tower-defense/CLAUDE.md +10 -9
- package/templates/tower-defense/package.json +11 -9
- package/templates/tower-defense/playtests/performance.playtest.json +7 -1
- package/templates/tower-defense/src/render/autoExposure.ts +225 -0
- package/templates/tower-defense/src/render/backlightControls.ts +66 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
- package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
- package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
- package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
- package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
- package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
- package/templates/tower-defense/src/render/exposure.ts +111 -0
- package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
- package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
- package/templates/tower-defense/src/render/lighting.ts +33 -1
- package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
- package/templates/tower-defense/src/render/materialLighting.ts +155 -0
- package/templates/tower-defense/src/render/postprocessing.ts +8 -2
- package/templates/tower-defense/src/render/quality.ts +61 -2
- package/templates/tower-defense/src/render/shapes.ts +0 -3
- package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
- package/templates/tower-defense/src/scenes/Battle.ts +65 -2
- package/templates/tower-defense/vite.config.ts +10 -2
- package/templates/minimal/src/scenes/Boot.ts +0 -5
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# Capability reference
|
|
5
5
|
|
|
6
|
-
Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
|
|
6
|
+
Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
|
|
7
7
|
generated from the doc tags the engine itself compiles, so this page cannot disagree with
|
|
8
8
|
the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
|
|
9
9
|
MCP server is available.
|
|
@@ -427,7 +427,7 @@ export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, ind
|
|
|
427
427
|
|
|
428
428
|
- **Use when:** add hundreds of built objects to the scene without one multi-second frame · stream a detail tier in behind a loading curtain without the page looking hung
|
|
429
429
|
- **Constraints:** the objects, and where each one goes, stay the game's; this decides only when each joins the graph · input order is the attach order and cannot be changed · a false `while` stops the run and is reported as `stopped`, never thrown
|
|
430
|
-
- **Overrides:** sliceSize
|
|
430
|
+
- **Overrides:** a slice ends on an 8 ms budget unless the game gives `sliceSize`, and the reported sliceSize is then the measured average; `marker: false` silences the TN_ADD_SLICES line, not the report
|
|
431
431
|
|
|
432
432
|
```ts
|
|
433
433
|
const report = await addInSlices(objects, (object) => ctx.add(object), {
|
|
@@ -531,6 +531,22 @@ import { alwaysRender } from "@threenative/core";
|
|
|
531
531
|
alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
|
|
532
532
|
```
|
|
533
533
|
|
|
534
|
+
### `AnimationComposer`
|
|
535
|
+
|
|
536
|
+
`class` — Compose game-authored locomotion and masked actions on one Three.js mixer.
|
|
537
|
+
|
|
538
|
+
```ts
|
|
539
|
+
export class AnimationComposer { … }
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
- **Use when:** synchronize walk/run/strafe clips with different durations · reload with the upper body while locomotion continues · apply an additive recoil clip with an explicit reference pose · route root motion through collision-aware character movement
|
|
543
|
+
- **Constraints:** one base phase, one masked override, at most two additive layers and eight actions · root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK · root motion excludes velocity-driven stride sync; unsupported parent transforms throw · source clips remain immutable; dispose at scene exit
|
|
544
|
+
|
|
545
|
+
```ts
|
|
546
|
+
const animation = new AnimationComposer({ root: rig, clips, samples: ["walk", "run"] });
|
|
547
|
+
animation.setWeights([0.5, 0.5]); animation.update(dt);
|
|
548
|
+
```
|
|
549
|
+
|
|
534
550
|
### `AnimationPlayer`
|
|
535
551
|
|
|
536
552
|
`class` — Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
|
|
@@ -671,6 +687,36 @@ const billboard = new Billboard3D(label, { camera });
|
|
|
671
687
|
billboard.update();
|
|
672
688
|
```
|
|
673
689
|
|
|
690
|
+
### `BlendSpace1D`
|
|
691
|
+
|
|
692
|
+
`class` — Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
|
|
693
|
+
|
|
694
|
+
```ts
|
|
695
|
+
export class BlendSpace1D { … }
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
- **Use when:** calculate 1D walk/run blend weights from speed · calculate 2D locomotion weights from forward and strafe intent
|
|
699
|
+
- **Constraints:** duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization · outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
|
|
700
|
+
|
|
701
|
+
```ts
|
|
702
|
+
const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
### `BlendSpace2D`
|
|
706
|
+
|
|
707
|
+
`class` — Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
|
|
708
|
+
|
|
709
|
+
```ts
|
|
710
|
+
export class BlendSpace2D { … }
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
- **Use when:** calculate 1D walk/run blend weights from speed · calculate 2D locomotion weights from forward and strafe intent
|
|
714
|
+
- **Constraints:** duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization · outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
|
|
715
|
+
|
|
716
|
+
```ts
|
|
717
|
+
const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
|
|
718
|
+
```
|
|
719
|
+
|
|
674
720
|
### `boneContact`
|
|
675
721
|
|
|
676
722
|
`function` — Measure whether a named bone reaches the object it is supposed to be touching, in metres.
|
|
@@ -1170,6 +1216,24 @@ ctx.add(field);
|
|
|
1170
1216
|
field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
|
|
1171
1217
|
```
|
|
1172
1218
|
|
|
1219
|
+
### `FluidParticles3D`
|
|
1220
|
+
|
|
1221
|
+
`class` — Simulate liquid as GPU particles (pour, splash, dam break, waterfall) and expose positions, a density volume and a surface height while the game owns every look.
|
|
1222
|
+
|
|
1223
|
+
```ts
|
|
1224
|
+
export class FluidParticles3D extends Group { … }
|
|
1225
|
+
```
|
|
1226
|
+
|
|
1227
|
+
- **Use when:** pour, splash, or dam-break water that fills a container and flows around obstacles · simulate water or another liquid as particles in a fluid simulation · drop a ball or box into liquid and let it displace and float on the water · emit a stream or waterfall of particle fluid and drain it somewhere else · sample particle-fluid density or surface height in a game-owned render node
|
|
1228
|
+
- **Constraints:** add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic · a renderer without WebGPU compute throws a named error at attach; it never draws nothing · `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity · `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
|
|
1229
|
+
- **Overrides:** iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
|
|
1230
|
+
|
|
1231
|
+
```ts
|
|
1232
|
+
const water = new FluidParticles3D({ capacity: 6000 });
|
|
1233
|
+
ctx.add(water);
|
|
1234
|
+
water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
|
|
1235
|
+
```
|
|
1236
|
+
|
|
1173
1237
|
### `formatSceneWarning`
|
|
1174
1238
|
|
|
1175
1239
|
`function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
@@ -1200,6 +1264,22 @@ export function formatSpansWindow(window: ISpanWindow): string { … }
|
|
|
1200
1264
|
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
1201
1265
|
```
|
|
1202
1266
|
|
|
1267
|
+
### `formatUnlitFoliageWarning`
|
|
1268
|
+
|
|
1269
|
+
`function` — Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.
|
|
1270
|
+
|
|
1271
|
+
```ts
|
|
1272
|
+
export function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string { … }
|
|
1273
|
+
```
|
|
1274
|
+
|
|
1275
|
+
- **Use when:** catch the "why does my forest look like cardboard" question before a human plays it · audit a scene a game built from imported GLB foliage
|
|
1276
|
+
- **Constraints:** derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material · it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
|
|
1277
|
+
- **Overrides:** `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
|
|
1278
|
+
|
|
1279
|
+
```ts
|
|
1280
|
+
defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
|
|
1281
|
+
```
|
|
1282
|
+
|
|
1203
1283
|
### `formatValidationReport`
|
|
1204
1284
|
|
|
1205
1285
|
`function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
|
|
@@ -1223,8 +1303,8 @@ if (renderListValidationRequested()) console.log(formatValidationReport(report))
|
|
|
1223
1303
|
export class FrameBudget { … }
|
|
1224
1304
|
```
|
|
1225
1305
|
|
|
1226
|
-
- **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass
|
|
1227
|
-
- **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
|
|
1306
|
+
- **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass · retain every asynchronous GPU render frame for a complete paired benchmark
|
|
1307
|
+
- **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero · `ctx.renderer.observeGpuFrames({ maxFrames, maxQueries })` is opt-in, bounded and fail-closed; `take()` delivers immutable complete render-query groups once, while `status()` reports pending/undrained/queued membership and losses · observation preserves ordinary sampling; a complete benchmark explicitly requests `renderer.gpuTimestampFrameInterval: 1` and joins Three query IDs to actual world renders, including separate overlay IDs · `stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement
|
|
1228
1308
|
|
|
1229
1309
|
```ts
|
|
1230
1310
|
defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
|
|
@@ -1284,11 +1364,13 @@ if (isMobile()) showTouchControls();
|
|
|
1284
1364
|
export class GPUParticles3D extends Sprite implements IComputeDriven { … }
|
|
1285
1365
|
```
|
|
1286
1366
|
|
|
1287
|
-
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles · falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard · kick up a spray of powder snow or dust where a foot or a ball lands
|
|
1288
|
-
- **Constraints:** geometry, color, and timing remain supplied by the game
|
|
1367
|
+
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles · splash spray droplets with lifetime and gravity · spawn water droplets, mist, or foam bubbles above a fluid surface · falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard · kick up a spray of powder snow or dust where a foot or a ball lands · a hit, impact or explosion burst that starts at the point and moment it is asked for, and a second hit that must not move the first hit's live particles · emitParticle a burst of GPU particles at a world position with its own free slots
|
|
1368
|
+
- **Constraints:** geometry, color, and timing remain supplied by the game · a `spawn` kernel makes bursts requests: `emitParticle({ count, origin })` reserves ring slots, the engine stamps `buffers.births` and `process` reads age as `runtime.time - births[i]`; there is no readback · a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent · requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option · the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view · a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view · when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget
|
|
1369
|
+
- **Overrides:** localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring · onCull: "clear" restarts a returning effect, the default "pause" resumes it with buffers intact · bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence · graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling
|
|
1289
1370
|
|
|
1290
1371
|
```ts
|
|
1291
1372
|
const particles = new GPUParticles3D(particleOptions);
|
|
1373
|
+
particles.emitParticle({ count: 220, origin: hit.position });
|
|
1292
1374
|
```
|
|
1293
1375
|
|
|
1294
1376
|
### `GPUReadback`
|
|
@@ -1377,9 +1459,9 @@ const uninstall = installSpanProbes(renderer.raw, scene);
|
|
|
1377
1459
|
export class InstancedBatch { … }
|
|
1378
1460
|
```
|
|
1379
1461
|
|
|
1380
|
-
- **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
|
|
1381
|
-
- **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed
|
|
1382
|
-
- **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
|
|
1462
|
+
- **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · automatically select instanced prop detail from projected screen error using baked AutoLOD chains · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
|
|
1463
|
+
- **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed · baked AutoLOD chains survive geometry clone/transform preparation and partition instances automatically into spatially bounded draws in the engine frame loop at 4 px projected error; public instance slots remain stable · unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE
|
|
1464
|
+
- **Overrides:** autoLod: false leaves selection to the game; autoLod.maxPixelError and hysteresis override the measured-camera budget; lods supplies authored distance/geometry levels and wins over the baked chain · castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
|
|
1383
1465
|
|
|
1384
1466
|
```ts
|
|
1385
1467
|
const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
|
|
@@ -1931,6 +2013,21 @@ export class RenderListValidator { … }
|
|
|
1931
2013
|
if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
1932
2014
|
```
|
|
1933
2015
|
|
|
2016
|
+
### `renderTrapAudit`
|
|
2017
|
+
|
|
2018
|
+
`function` — Catch scene state that silently loses environment fill or ignores authored opacity. After `enter()` the game first applies the opacity convention: a drawn material with `opacity < 1` turns transparent and one `TN_OPACITY_TRANSPARENT` console warning names it (override: `alphaHash: true`, or `opacity: 1`). It then prints `TN_ENVIRONMENT_TOO_SMALL` as a console error with the fix, so playtest `noConsoleErrors` rejects it.
|
|
2019
|
+
|
|
2020
|
+
```ts
|
|
2021
|
+
export function renderTrapAudit(scene: Object3D & { … }
|
|
2022
|
+
```
|
|
2023
|
+
|
|
2024
|
+
- **Use when:** audit an equirectangular sky too narrow for three's WebGPU PMREM · find visible opaque materials whose authored opacity is ignored
|
|
2025
|
+
- **Constraints:** structural scene reads only, one visible-tree walk per entry, at most five material examples · the audit itself changes no scene state; the game loop's opacity convention is the only writer
|
|
2026
|
+
|
|
2027
|
+
```ts
|
|
2028
|
+
renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array
|
|
2029
|
+
```
|
|
2030
|
+
|
|
1934
2031
|
### `replay`
|
|
1935
2032
|
|
|
1936
2033
|
`function` — Record or replay deterministic game input and state.
|
|
@@ -2366,6 +2463,22 @@ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
|
|
|
2366
2463
|
tracers.spawn(muzzle, shotDirection, hit.distance);
|
|
2367
2464
|
```
|
|
2368
2465
|
|
|
2466
|
+
### `unlitFoliageWarning`
|
|
2467
|
+
|
|
2468
|
+
`function` — Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.
|
|
2469
|
+
|
|
2470
|
+
```ts
|
|
2471
|
+
export function unlitFoliageWarning( scene: Object3D & { … }
|
|
2472
|
+
```
|
|
2473
|
+
|
|
2474
|
+
- **Use when:** catch the "why does my forest look like cardboard" question before a human plays it · audit a scene a game built from imported GLB foliage
|
|
2475
|
+
- **Constraints:** derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material · it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
|
|
2476
|
+
- **Overrides:** `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
|
|
2477
|
+
|
|
2478
|
+
```ts
|
|
2479
|
+
defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
|
|
2480
|
+
```
|
|
2481
|
+
|
|
2369
2482
|
### `unmarkStatic`
|
|
2370
2483
|
|
|
2371
2484
|
`function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
|
|
@@ -2494,8 +2607,8 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
|
|
|
2494
2607
|
```
|
|
2495
2608
|
|
|
2496
2609
|
- **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
|
|
2497
|
-
- **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing ·
|
|
2498
|
-
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
|
|
2610
|
+
- **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left · `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region · call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
|
|
2611
|
+
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
|
|
2499
2612
|
|
|
2500
2613
|
```ts
|
|
2501
2614
|
const sun = new DirectionalLight(0xffffff, 3);
|
|
@@ -2525,12 +2638,12 @@ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) })
|
|
|
2525
2638
|
export class WaterSurface3D { … }
|
|
2526
2639
|
```
|
|
2527
2640
|
|
|
2528
|
-
- **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame
|
|
2529
|
-
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only ·
|
|
2641
|
+
- **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame · automatically reflect terrain and large casters without redrawing instanced small props
|
|
2642
|
+
- **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only · omitted reflection.layers automatically reflects terrain-sized surfaces and large non-instanced casters, excluding instanced/skinned props; TN_WATER_REFLECTION_DEFAULT reports the set once · reflection.refreshInterval is in presented frames; 1 is every frame, and the default · the mirror plane is level, from level alone; do not parent target to a scaled mesh
|
|
2643
|
+
- **Overrides:** reflection.layers is an explicit Three Layers mask and wins over automatic filtering, including layer-0 mask 1; reflection.minSize overrides the default 10 metre minimum extent
|
|
2530
2644
|
|
|
2531
2645
|
```ts
|
|
2532
|
-
const
|
|
2533
|
-
const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });
|
|
2646
|
+
const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
|
|
2534
2647
|
material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
|
|
2535
2648
|
```
|
|
2536
2649
|
|
|
@@ -2741,6 +2854,24 @@ export function View(props: IViewProps): ReactNode { … }
|
|
|
2741
2854
|
<View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>
|
|
2742
2855
|
```
|
|
2743
2856
|
|
|
2857
|
+
## `@threenative/core/react-css`
|
|
2858
|
+
|
|
2859
|
+
### `createCssUiRoot`
|
|
2860
|
+
|
|
2861
|
+
`function` — Mount React into a native CSS engine.
|
|
2862
|
+
|
|
2863
|
+
```ts
|
|
2864
|
+
export function createCssUiRoot(options: ICssUiRootOptions = { … }
|
|
2865
|
+
```
|
|
2866
|
+
|
|
2867
|
+
- **Use when:** mount a React HUD on the desktop host with no DOM in the runtime · write one React component and run it on the web and on the desktop host
|
|
2868
|
+
- **Constraints:** desktop only, and the game host must be built with the CSS backend (`TN_ENABLE_CSS_UI=1`); Android, iOS and web phones render a React HUD in a web overlay instead · import `react`, never `react-dom`, from a native entry · styling is CSS resolved by the native engine; JS only mirrors the element tree
|
|
2869
|
+
|
|
2870
|
+
```ts
|
|
2871
|
+
const root = createCssUiRoot();
|
|
2872
|
+
root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
|
|
2873
|
+
```
|
|
2874
|
+
|
|
2744
2875
|
## `@threenative/core/ui-layer`
|
|
2745
2876
|
|
|
2746
2877
|
### `connectUiBridge`
|
|
@@ -2899,18 +3030,18 @@ const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorld
|
|
|
2899
3030
|
|
|
2900
3031
|
### `loadTerrainSplat`
|
|
2901
3032
|
|
|
2902
|
-
`function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Nothing here is a look choice: textures, tiles, tints, thresholds and noise scales all come from the package's table, which the game authors once and its DCC shares.
|
|
3033
|
+
`function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.
|
|
2903
3034
|
|
|
2904
3035
|
```ts
|
|
2905
3036
|
export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }
|
|
2906
3037
|
```
|
|
2907
3038
|
|
|
2908
3039
|
- **Use when:** terrain textured by splat masks exported from Blender with the world package · the game's terrain should match the DCC's terrain material without a second copy
|
|
2909
|
-
- **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `
|
|
3040
|
+
- **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe · WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
|
|
2910
3041
|
- **Overrides:** every value comes from the package's table; the returned material is the game's to adjust
|
|
2911
3042
|
|
|
2912
3043
|
```ts
|
|
2913
|
-
const surface = await loadTerrainSplat({ assets: ctx.assets, url: "world/world.json" });
|
|
3044
|
+
const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
|
|
2914
3045
|
const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
|
|
2915
3046
|
```
|
|
2916
3047
|
|
|
@@ -2976,7 +3107,7 @@ export class TerrainTiles extends Object3D implements IComputeDriven { … }
|
|
|
2976
3107
|
|
|
2977
3108
|
- **Use when:** stream terrain without cracks · keep generated terrain resident around a moving player · put a generated terrain tile into a game-owned physics world
|
|
2978
3109
|
- **Constraints:** sampleHeight and surface are required game choices; no landform or surface preset is installed · residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws · seam gap, LOD pop and the rendered-vertex finiteness scan are measurements that are off by default; TN_TERRAIN_VALIDATE=1, ?tnTerrainValidate=1 or validate: true runs them, and maxSeamGap, maxVisualSeamGap and maxLodPop report undefined while they are off
|
|
2979
|
-
- **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets
|
|
3110
|
+
- **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets
|
|
2980
3111
|
|
|
2981
3112
|
```ts
|
|
2982
3113
|
const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
|
|
@@ -3017,15 +3148,15 @@ const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer
|
|
|
3017
3148
|
|
|
3018
3149
|
### `WorldCells`
|
|
3019
3150
|
|
|
3020
|
-
`class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, per-asset `maxDistance` filtering, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset
|
|
3151
|
+
`class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.
|
|
3021
3152
|
|
|
3022
3153
|
```ts
|
|
3023
3154
|
export class WorldCells extends Group implements IComputeDriven { … }
|
|
3024
3155
|
```
|
|
3025
3156
|
|
|
3026
3157
|
- **Use when:** stream a large Blender-authored world by cell instead of one huge GLB · keep scattered props and hand-placed chunks resident around a moving player · honour per-asset draw distances and hard streaming budgets without a mid-frame throw
|
|
3027
|
-
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with authored `lods` never consults it · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
|
|
3028
|
-
- **Overrides:** ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
|
|
3158
|
+
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts · eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
|
|
3159
|
+
- **Overrides:** `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
|
|
3029
3160
|
|
|
3030
3161
|
```ts
|
|
3031
3162
|
const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
|
|
@@ -3131,6 +3262,7 @@ export class Area3D { … }
|
|
|
3131
3262
|
|
|
3132
3263
|
- **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
|
|
3133
3264
|
- **Constraints:** add the area to the physics context before stepping the world
|
|
3265
|
+
- **Requires:** npm i @threenative/physics
|
|
3134
3266
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated.
|
|
3135
3267
|
|
|
3136
3268
|
```ts
|
|
@@ -3165,6 +3297,7 @@ export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootpri
|
|
|
3165
3297
|
|
|
3166
3298
|
- **Use when:** let a crate, platform or plank press a rectangular pit into snow · imprint a box's own footprint rather than a circle around it
|
|
3167
3299
|
- **Constraints:** halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint
|
|
3300
|
+
- **Requires:** npm i @threenative/physics
|
|
3168
3301
|
|
|
3169
3302
|
```ts
|
|
3170
3303
|
const footprint = boxFootprint(0.4, 0.25);
|
|
@@ -3180,6 +3313,7 @@ export function buildStaticColliders( context: IStaticColliderContext, root: Obj
|
|
|
3180
3313
|
|
|
3181
3314
|
- **Use when:** make the level I built stop the player · turn a cathedral or map scene into static collision
|
|
3182
3315
|
- **Constraints:** supply the game-owned predicate for decorative meshes; the helper throws when it selects nothing · generated bodies use trimesh geometry and world-space instance transforms
|
|
3316
|
+
- **Requires:** npm i @threenative/physics
|
|
3183
3317
|
|
|
3184
3318
|
```ts
|
|
3185
3319
|
const colliders = buildStaticColliders(ctx, level, { predicate: (object) => object.name.startsWith("wall") });
|
|
@@ -3195,6 +3329,7 @@ export class Buoyancy3D { … }
|
|
|
3195
3329
|
|
|
3196
3330
|
- **Use when:** float a boat on waves · keep a hull above a moving water surface
|
|
3197
3331
|
- **Constraints:** supply hull points, density, drag, and the height source
|
|
3332
|
+
- **Requires:** npm i @threenative/physics
|
|
3198
3333
|
- **Overrides:** buoyancy disables force application while submergedFraction remains measured
|
|
3199
3334
|
|
|
3200
3335
|
```ts
|
|
@@ -3211,6 +3346,7 @@ export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootp
|
|
|
3211
3346
|
|
|
3212
3347
|
- **Use when:** let a fallen capsule, limb or barrel leave a linear imprint in snow · give a capsule a shape-appropriate snow contact instead of a sphere's dot
|
|
3213
3348
|
- **Constraints:** radius and halfHeight are metres and never grow with load
|
|
3349
|
+
- **Requires:** npm i @threenative/physics
|
|
3214
3350
|
|
|
3215
3351
|
```ts
|
|
3216
3352
|
const footprint = capsuleFootprint(0.5, 0.2);
|
|
@@ -3226,6 +3362,7 @@ export class CharacterBody3D { … }
|
|
|
3226
3362
|
|
|
3227
3363
|
- **Use when:** move an enemy or player through a level · keep a character from walking through walls
|
|
3228
3364
|
- **Constraints:** use moveAndSlide inside the physics update
|
|
3365
|
+
- **Requires:** npm i @threenative/physics
|
|
3229
3366
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
|
|
3230
3367
|
|
|
3231
3368
|
```ts
|
|
@@ -3242,6 +3379,7 @@ export class CollisionShape3D { … }
|
|
|
3242
3379
|
|
|
3243
3380
|
- **Use when:** add a capsule or box collider to a character · configure the shape used by a rigid body
|
|
3244
3381
|
- **Constraints:** create shapes through the owning physics context
|
|
3382
|
+
- **Requires:** npm i @threenative/physics
|
|
3245
3383
|
|
|
3246
3384
|
```ts
|
|
3247
3385
|
const shape = CollisionShape3D.capsule(0.5, 0.35);
|
|
@@ -3256,6 +3394,7 @@ export function interactionGroups(layer: number, mask: number): number { … }
|
|
|
3256
3394
|
```
|
|
3257
3395
|
|
|
3258
3396
|
- **Use when:** make an enemy collide with the world but not pickups · configure which physics layers interact
|
|
3397
|
+
- **Requires:** npm i @threenative/physics
|
|
3259
3398
|
|
|
3260
3399
|
```ts
|
|
3261
3400
|
const groups = interactionGroups(1, 3);
|
|
@@ -3271,6 +3410,7 @@ export class Joint3D { … }
|
|
|
3271
3410
|
|
|
3272
3411
|
- **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism · swing a pendulum, wrecking ball, or hinged door on a joint
|
|
3273
3412
|
- **Constraints:** both bodies must belong to the same physics context
|
|
3413
|
+
- **Requires:** npm i @threenative/physics
|
|
3274
3414
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated.
|
|
3275
3415
|
|
|
3276
3416
|
```ts
|
|
@@ -3287,6 +3427,7 @@ export class PhysicsDirectSpaceState3D { … }
|
|
|
3287
3427
|
|
|
3288
3428
|
- **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
|
|
3289
3429
|
- **Constraints:** query results are bounded by the configured result limit
|
|
3430
|
+
- **Requires:** npm i @threenative/physics
|
|
3290
3431
|
|
|
3291
3432
|
```ts
|
|
3292
3433
|
const space = new PhysicsDirectSpaceState3D(context);
|
|
@@ -3302,6 +3443,7 @@ export function rapier(options: IPhysicsOptions = { … }
|
|
|
3302
3443
|
|
|
3303
3444
|
- **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
|
|
3304
3445
|
- **Constraints:** place rapier() before recast() in the plugin list
|
|
3446
|
+
- **Requires:** npm i @threenative/physics
|
|
3305
3447
|
|
|
3306
3448
|
```ts
|
|
3307
3449
|
const game = defineGame({ plugins: [rapier()] });
|
|
@@ -3317,6 +3459,7 @@ export class RigidBody3D { … }
|
|
|
3317
3459
|
|
|
3318
3460
|
- **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
|
|
3319
3461
|
- **Constraints:** register rapier() in the game plugin list before using bodies
|
|
3462
|
+
- **Requires:** npm i @threenative/physics
|
|
3320
3463
|
- **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
|
|
3321
3464
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated.
|
|
3322
3465
|
|
|
@@ -3334,6 +3477,7 @@ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyC
|
|
|
3334
3477
|
|
|
3335
3478
|
- **Use when:** stop a cloth flag, cape, or curtain at an existing physics wall · collide SoftBody3D with fixed box bodies
|
|
3336
3479
|
- **Constraints:** every body must use CollisionShape3D.box and retain its Three.js object transform · rotated boxes become conservative cloth-local axis-aligned bounds
|
|
3480
|
+
- **Requires:** npm i @threenative/physics
|
|
3337
3481
|
|
|
3338
3482
|
```ts
|
|
3339
3483
|
const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
|
|
@@ -3349,6 +3493,7 @@ export class VehicleBody3D extends RigidBody3D { … }
|
|
|
3349
3493
|
|
|
3350
3494
|
- **Use when:** drive a car, truck or bike around a track · make a vehicle roll over kerbs, brake into a corner or stop at a wall
|
|
3351
3495
|
- **Constraints:** write engineForce, brake and steering every physics update; a car with no input does not move · suspensionStiffness is a frequency squared, not newtons per metre; 100 is a road car and 20 bottoms out
|
|
3496
|
+
- **Requires:** npm i @threenative/physics
|
|
3352
3497
|
- **Overrides:** a wheel ray never hits the chassis it hangs from, and it honours the chassis collision mask · continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall
|
|
3353
3498
|
|
|
3354
3499
|
```ts
|
|
@@ -3367,6 +3512,7 @@ export class NavigationAgent3D { … }
|
|
|
3367
3512
|
|
|
3368
3513
|
- **Use when:** enemy walks around a wall · enemy patrols a level and chases the player · enemy walks around a patrol path and chases the player when it sees them · enemy patrols and chases while avoiding obstacles · enemy chases the player with line of sight and obstacle avoidance · NPC walks to a destination · move crew around a ship deck
|
|
3369
3514
|
- **Constraints:** import NavigationAgent3D from exactly `@threenative/physics/navigation`; `@threenative/physics` is not a valid import for this symbol; use this capability instead of hand-written A*; requires recast() after rapier(), plus a baked NavigationRegion3D
|
|
3515
|
+
- **Requires:** npm i @threenative/physics
|
|
3370
3516
|
|
|
3371
3517
|
```ts
|
|
3372
3518
|
import { NavigationAgent3D } from "@threenative/physics/navigation";
|
|
@@ -3387,6 +3533,7 @@ export class NavigationObstacle3D { … }
|
|
|
3387
3533
|
|
|
3388
3534
|
- **Use when:** keep navigation agents away from a blocking prop · make a stationary character affect crowd avoidance
|
|
3389
3535
|
- **Constraints:** create it after recast() and dispose it with the scene
|
|
3536
|
+
- **Requires:** npm i @threenative/physics
|
|
3390
3537
|
|
|
3391
3538
|
```ts
|
|
3392
3539
|
const obstacle = new NavigationObstacle3D({ navigation, object });
|
|
@@ -3402,6 +3549,7 @@ export class NavigationRegion3D { … }
|
|
|
3402
3549
|
|
|
3403
3550
|
- **Use when:** let enemies walk around level geometry · create the baked navmesh required by NavigationAgent3D
|
|
3404
3551
|
- **Constraints:** bake before creating agents or obstacles
|
|
3552
|
+
- **Requires:** npm i @threenative/physics
|
|
3405
3553
|
|
|
3406
3554
|
```ts
|
|
3407
3555
|
const region = new NavigationRegion3D({ navigation, meshes: [floor] });
|
|
@@ -3417,6 +3565,7 @@ export function recast(): NavigationPlugin { … }
|
|
|
3417
3565
|
|
|
3418
3566
|
- **Use when:** enemy walks around a wall · NPC patrols a level and chases a player
|
|
3419
3567
|
- **Constraints:** requires rapier() earlier in the plugins array
|
|
3568
|
+
- **Requires:** npm i @threenative/physics
|
|
3420
3569
|
|
|
3421
3570
|
```ts
|
|
3422
3571
|
const game = defineGame({ plugins: [rapier(), recast()] });
|
|
@@ -3759,6 +3908,21 @@ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrame
|
|
|
3759
3908
|
assertCaptureNotBlank(png, "first frame");
|
|
3760
3909
|
```
|
|
3761
3910
|
|
|
3911
|
+
### `assertDesktopCaptureNotBlank`
|
|
3912
|
+
|
|
3913
|
+
`function` — Fail closed when a desktop-host frame shows no rendered content. A native desktop frame has no HTML overlay, so the browser bright-pixel floor does not apply.
|
|
3914
|
+
|
|
3915
|
+
```ts
|
|
3916
|
+
export function assertDesktopCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }
|
|
3917
|
+
```
|
|
3918
|
+
|
|
3919
|
+
- **Use when:** guard a native desktop capture of a 3D scene
|
|
3920
|
+
- **Constraints:** keeps the uniform-frame checks and replaces only the bright-pixel floor
|
|
3921
|
+
|
|
3922
|
+
```ts
|
|
3923
|
+
assertDesktopCaptureNotBlank(png, "panned-culled.png");
|
|
3924
|
+
```
|
|
3925
|
+
|
|
3762
3926
|
### `assertFrameShowsSomething`
|
|
3763
3927
|
|
|
3764
3928
|
`function` — Fail closed when a screenshot is blank or uniform.
|
|
@@ -3788,6 +3952,21 @@ export class CaptureGuardError extends Error { … }
|
|
|
3788
3952
|
throw new CaptureGuardError("menu", "no bright pixels");
|
|
3789
3953
|
```
|
|
3790
3954
|
|
|
3955
|
+
### `collectRegionalTone`
|
|
3956
|
+
|
|
3957
|
+
`function` — Collect opt-in regional tone observations from the same acquired PNG.
|
|
3958
|
+
|
|
3959
|
+
```ts
|
|
3960
|
+
export function collectRegionalTone( png: Buffer, assertions: readonly IPlaytestToneAssertion[], label: string, atStep?: string, ): IPlaytestRegionalToneObservation[] { … }
|
|
3961
|
+
```
|
|
3962
|
+
|
|
3963
|
+
- **Use when:** measure a specified pixel crop in a captured playtest frame
|
|
3964
|
+
- **Constraints:** does not acquire another screenshot or alter frame timing
|
|
3965
|
+
|
|
3966
|
+
```ts
|
|
3967
|
+
collectRegionalTone(png, assertions, "character", "posed");
|
|
3968
|
+
```
|
|
3969
|
+
|
|
3791
3970
|
### `inspectFrame`
|
|
3792
3971
|
|
|
3793
3972
|
`function` — Inspect a PNG frame for visible pixels and luminance variation.
|
|
@@ -3833,6 +4012,21 @@ export function jsonByteLength(value: JsonValue): number { … }
|
|
|
3833
4012
|
const bytes = jsonByteLength(observation);
|
|
3834
4013
|
```
|
|
3835
4014
|
|
|
4015
|
+
### `requestedPlaytestClockMode`
|
|
4016
|
+
|
|
4017
|
+
`function` — The clock the host asked for, or `undefined` for the default deterministic run. `wall-clock` is the production profile's opt-in and the only one this protocol has. An unrecognised value throws instead of falling back, because a misspelling that quietly left the loop frozen would publish a frame rate for a game that was not playing. Read at the moment it is needed rather than once at install: a request that arrives after the producer was installed is still a request, and a producer that missed it would judge a live frame pump by a count it never asked for.
|
|
4018
|
+
|
|
4019
|
+
```ts
|
|
4020
|
+
export function requestedPlaytestClockMode(): PlaytestClockMode | undefined { … }
|
|
4021
|
+
```
|
|
4022
|
+
|
|
4023
|
+
- **Use when:** report which clock a playtest producer is really running on, before judging its ticks
|
|
4024
|
+
- **Constraints:** throws on an unrecognised value instead of falling back to a fixed-step run
|
|
4025
|
+
|
|
4026
|
+
```ts
|
|
4027
|
+
if (requestedPlaytestClockMode() === "wall-clock") host.pumpDrivesTheSimulation();
|
|
4028
|
+
```
|
|
4029
|
+
|
|
3836
4030
|
## `@threenative/playtest/runner`
|
|
3837
4031
|
|
|
3838
4032
|
### `AdbAndroidDriver`
|
|
@@ -3855,7 +4049,7 @@ const adb = discoverAdb(process.env);
|
|
|
3855
4049
|
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
3856
4050
|
|
|
3857
4051
|
```ts
|
|
3858
|
-
export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, ): Promise<void> { … }
|
|
4052
|
+
export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, render = false, ): Promise<void> { … }
|
|
3859
4053
|
```
|
|
3860
4054
|
|
|
3861
4055
|
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
@@ -4032,6 +4226,21 @@ const lane = decideDisplayStrategy({ env: process.env, platform: "linux" });
|
|
|
4032
4226
|
if (lane.kind === "private-xvfb") throw new Error("refuse to judge this frame rate");
|
|
4033
4227
|
```
|
|
4034
4228
|
|
|
4229
|
+
### `desktopConsoleType`
|
|
4230
|
+
|
|
4231
|
+
`function` — Drive a local desktop playtest mailbox.
|
|
4232
|
+
|
|
4233
|
+
```ts
|
|
4234
|
+
export function desktopConsoleType(stream: "stderr" | "stdout", line: string): string { … }
|
|
4235
|
+
```
|
|
4236
|
+
|
|
4237
|
+
- **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
|
|
4238
|
+
- **Constraints:** the mailbox lifecycle must be disposed after the run
|
|
4239
|
+
|
|
4240
|
+
```ts
|
|
4241
|
+
const driver = new DesktopPlaytestDriver(options);
|
|
4242
|
+
```
|
|
4243
|
+
|
|
4035
4244
|
### `DesktopPlaytestDriver`
|
|
4036
4245
|
|
|
4037
4246
|
`class` — Drive a local desktop playtest mailbox.
|
|
@@ -4954,6 +5163,122 @@ export class ThreePlaytestPhysicsRecorder { … }
|
|
|
4954
5163
|
const physics = new ThreePlaytestPhysicsRecorder(worldPhysics);
|
|
4955
5164
|
```
|
|
4956
5165
|
|
|
5166
|
+
## `@threenative/procedural-animals`
|
|
5167
|
+
|
|
5168
|
+
### `createAnimalActor`
|
|
5169
|
+
|
|
5170
|
+
`function` — Own one actor's pose/lifetime, accepting the completed physics state as its only root writer.
|
|
5171
|
+
|
|
5172
|
+
```ts
|
|
5173
|
+
export function createAnimalActor(bake: IAnimalBake, options: IAnimalActorOptions) { … }
|
|
5174
|
+
```
|
|
5175
|
+
|
|
5176
|
+
- **Use when:** follow a baked animal from accepted fixed-step Rapier state
|
|
5177
|
+
- **Constraints:** identity parent required; material and motion are editable game source; no move/Mixer/composer writer exists
|
|
5178
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5179
|
+
|
|
5180
|
+
```ts
|
|
5181
|
+
const wolf = createAnimalActor(bake, { motion, material, ground });
|
|
5182
|
+
```
|
|
5183
|
+
|
|
5184
|
+
### `createAnimalGeometry`
|
|
5185
|
+
|
|
5186
|
+
`function` — Validates all bytes before constructing geometry with the bake's skin and rig attributes.
|
|
5187
|
+
|
|
5188
|
+
```ts
|
|
5189
|
+
export function createAnimalGeometry(buffer: ArrayBuffer): { … }
|
|
5190
|
+
```
|
|
5191
|
+
|
|
5192
|
+
- **Use when:** construct a Three.js geometry from a validated procedural wolf bake
|
|
5193
|
+
- **Constraints:** this creates bind geometry only; game-owned DQS material and animated bounds remain required
|
|
5194
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5195
|
+
|
|
5196
|
+
```ts
|
|
5197
|
+
const { bake, geometry } = createAnimalGeometry(bytes);
|
|
5198
|
+
```
|
|
5199
|
+
|
|
5200
|
+
### `loadAnimalBake`
|
|
5201
|
+
|
|
5202
|
+
`function` — Resolves and loads a prebuilt wolf through the game's ordinary asset resolver.
|
|
5203
|
+
|
|
5204
|
+
```ts
|
|
5205
|
+
export async function loadAnimalBake( assets: IAnimalAssetResolver, logicalPath: string, options: { … }
|
|
5206
|
+
```
|
|
5207
|
+
|
|
5208
|
+
- **Use when:** load a cooked animal from ctx.assets without runtime generation
|
|
5209
|
+
- **Constraints:** a corrupt served bake rejects rather than falling back to a different file
|
|
5210
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5211
|
+
|
|
5212
|
+
```ts
|
|
5213
|
+
const bake = await loadAnimalBake(ctx.assets, "wolf.animal");
|
|
5214
|
+
```
|
|
5215
|
+
|
|
5216
|
+
### `parseAnimalBake`
|
|
5217
|
+
|
|
5218
|
+
`function` — Validates a pinned wolf PANM bake before constructing any renderer resource.
|
|
5219
|
+
|
|
5220
|
+
```ts
|
|
5221
|
+
export function parseAnimalBake(buffer: ArrayBuffer): IAnimalBake { … }
|
|
5222
|
+
```
|
|
5223
|
+
|
|
5224
|
+
- **Use when:** validate a baked procedural animal before allocating geometry
|
|
5225
|
+
- **Constraints:** unknown revisions, malformed sections, indices and skin weights throw by name
|
|
5226
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5227
|
+
|
|
5228
|
+
```ts
|
|
5229
|
+
const bake = parseAnimalBake(bytes);
|
|
5230
|
+
```
|
|
5231
|
+
|
|
5232
|
+
## `@threenative/procedural-animals/build`
|
|
5233
|
+
|
|
5234
|
+
### `animalBakePass`
|
|
5235
|
+
|
|
5236
|
+
`function` — Validate staged PANM sources inside the existing asset compiler; it owns the hashed manifest.
|
|
5237
|
+
|
|
5238
|
+
```ts
|
|
5239
|
+
export function animalBakePass() { … }
|
|
5240
|
+
```
|
|
5241
|
+
|
|
5242
|
+
- **Use when:** cook staged animal bakes through the ordinary asset pipeline
|
|
5243
|
+
- **Constraints:** only .animal inputs are interpreted; corruption fails the cook, without regeneration
|
|
5244
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5245
|
+
|
|
5246
|
+
```ts
|
|
5247
|
+
await compileAssets({ passes: [animalBakePass()] });
|
|
5248
|
+
```
|
|
5249
|
+
|
|
5250
|
+
### `bakeWolf`
|
|
5251
|
+
|
|
5252
|
+
`function` — Bake the pinned wolf on the build machine, never on the portable runtime path.
|
|
5253
|
+
|
|
5254
|
+
```ts
|
|
5255
|
+
export async function bakeWolf(options: IWolfBakeOptions): Promise<ArrayBuffer> { … }
|
|
5256
|
+
```
|
|
5257
|
+
|
|
5258
|
+
- **Use when:** bake high and crowd wolf geometry before the ordinary asset cook
|
|
5259
|
+
- **Constraints:** exact pinned Node runtime, donor revision, options and generated bytes are validated; no worker is created
|
|
5260
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5261
|
+
|
|
5262
|
+
```ts
|
|
5263
|
+
const bytes = await bakeWolf({ seed: 7, tier: "crowd" });
|
|
5264
|
+
```
|
|
5265
|
+
|
|
5266
|
+
### `bakeWolfToFile`
|
|
5267
|
+
|
|
5268
|
+
`function` — Stage a validated source bake with a same-directory atomic rename, then use compileAssets.
|
|
5269
|
+
|
|
5270
|
+
```ts
|
|
5271
|
+
export async function bakeWolfToFile( options: IWolfBakeOptions, destination: string, ): Promise<string> { … }
|
|
5272
|
+
```
|
|
5273
|
+
|
|
5274
|
+
- **Use when:** publish a generated wolf without replacing the last valid bake on interruption
|
|
5275
|
+
- **Constraints:** validation and generation complete before the destination is touched; temporary files are removed on failure
|
|
5276
|
+
- **Requires:** npm i @threenative/procedural-animals
|
|
5277
|
+
|
|
5278
|
+
```ts
|
|
5279
|
+
await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
|
|
5280
|
+
```
|
|
5281
|
+
|
|
4957
5282
|
## `@threenative/raw-unreal`
|
|
4958
5283
|
|
|
4959
5284
|
### `createThreeGeometry`
|
|
@@ -5343,6 +5668,749 @@ function sparkle
|
|
|
5343
5668
|
sparkle(...)
|
|
5344
5669
|
```
|
|
5345
5670
|
|
|
5671
|
+
## `@threenative/terrain`
|
|
5672
|
+
|
|
5673
|
+
### `applyPlacementOverrides`
|
|
5674
|
+
|
|
5675
|
+
`function` — Attach manual transforms to raw evaluated candidates and report orphan keys.
|
|
5676
|
+
|
|
5677
|
+
```ts
|
|
5678
|
+
export function applyPlacementOverrides(state: ITerrainState, value: unknown): ITerrainState { … }
|
|
5679
|
+
```
|
|
5680
|
+
|
|
5681
|
+
- **Use when:** retain manual prop transforms across terrain scatter re-evaluation
|
|
5682
|
+
- **Constraints:** headless authoring; game applies transforms against its model bounds and actual terrain surface
|
|
5683
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
5684
|
+
- **Overrides:** transform.grounding=false preserves requested Y while the game still measures clearance
|
|
5685
|
+
|
|
5686
|
+
```ts
|
|
5687
|
+
const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
|
|
5688
|
+
```
|
|
5689
|
+
|
|
5690
|
+
### `bakeMesh`
|
|
5691
|
+
|
|
5692
|
+
`function` — Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
|
|
5693
|
+
|
|
5694
|
+
```ts
|
|
5695
|
+
export function bakeMesh( state: ITerrainState, { … }
|
|
5696
|
+
```
|
|
5697
|
+
|
|
5698
|
+
- **Use when:** bake an authored terrain into portable indexed mesh arrays
|
|
5699
|
+
- **Constraints:** no material is chosen; vertex colours exist only with a caller-supplied palette
|
|
5700
|
+
- **Requires:** npm i @threenative/terrain
|
|
5701
|
+
- **Overrides:** step, chunk bounds, skirtDepth and palette belong to the caller
|
|
5702
|
+
|
|
5703
|
+
```ts
|
|
5704
|
+
const mesh = bakeMesh(new Terrain({ resolution: 17 }).evaluate());
|
|
5705
|
+
```
|
|
5706
|
+
|
|
5707
|
+
### `bakeTerrain`
|
|
5708
|
+
|
|
5709
|
+
`function` — Bakes finite LOD chunks, the same collision samples and resolved placements.
|
|
5710
|
+
|
|
5711
|
+
```ts
|
|
5712
|
+
export function bakeTerrain( state: ITerrainState, { … }
|
|
5713
|
+
```
|
|
5714
|
+
|
|
5715
|
+
- **Use when:** prepare terrain arrays and collision before a game starts
|
|
5716
|
+
- **Constraints:** collision origin is the southwest corner; engine Heightfield origin is its centre
|
|
5717
|
+
- **Requires:** npm i @threenative/terrain
|
|
5718
|
+
- **Overrides:** chunkCells, lodSteps, skirtDepth and palette are explicit authoring choices
|
|
5719
|
+
|
|
5720
|
+
```ts
|
|
5721
|
+
const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCells: 64 });
|
|
5722
|
+
```
|
|
5723
|
+
|
|
5724
|
+
### `bakeWorldPackage`
|
|
5725
|
+
|
|
5726
|
+
`function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
|
|
5727
|
+
|
|
5728
|
+
```ts
|
|
5729
|
+
export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }
|
|
5730
|
+
```
|
|
5731
|
+
|
|
5732
|
+
- **Use when:** hand an evaluated Strata terrain to a game without a Blender round trip
|
|
5733
|
+
- **Constraints:** headless authoring; no three, no DOM, and nothing here decides how the world looks
|
|
5734
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
5735
|
+
- **Overrides:** every asset path, bound, LOD distance and cell size comes from the caller's options
|
|
5736
|
+
|
|
5737
|
+
```ts
|
|
5738
|
+
const { manifest, files } = bakeWorldPackage(state, { assets });
|
|
5739
|
+
```
|
|
5740
|
+
|
|
5741
|
+
### `createSegmentIndex`
|
|
5742
|
+
|
|
5743
|
+
`function` — Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
|
|
5744
|
+
|
|
5745
|
+
```ts
|
|
5746
|
+
export function createSegmentIndex<T>( segments: readonly IWaterSegment<T>[], cellSize: number, ): ISegmentIndex<T> { … }
|
|
5747
|
+
```
|
|
5748
|
+
|
|
5749
|
+
- **Use when:** test scatter candidates or terrain vertices against rivers and lakes without scanning every segment · find which river stations can reach a heightfield vertex when baking a wet margin
|
|
5750
|
+
- **Constraints:** returns candidates only; the caller applies its own exact distance and level test
|
|
5751
|
+
- **Requires:** npm i @threenative/terrain
|
|
5752
|
+
|
|
5753
|
+
```ts
|
|
5754
|
+
const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);
|
|
5755
|
+
```
|
|
5756
|
+
|
|
5757
|
+
### `decodeHeightPNG`
|
|
5758
|
+
|
|
5759
|
+
`function` — CRC-checked bounded non-interlaced grayscale PNG height decoder.
|
|
5760
|
+
|
|
5761
|
+
```ts
|
|
5762
|
+
export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options: IDecodeHeightPngOptions = { … }
|
|
5763
|
+
```
|
|
5764
|
+
|
|
5765
|
+
- **Use when:** import numerical PNG8 or PNG16 terrain elevations
|
|
5766
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5767
|
+
- **Requires:** npm i @threenative/terrain
|
|
5768
|
+
|
|
5769
|
+
```ts
|
|
5770
|
+
const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);
|
|
5771
|
+
```
|
|
5772
|
+
|
|
5773
|
+
### `decodeRAW16`
|
|
5774
|
+
|
|
5775
|
+
`function` — Validates dimensions and range before decoding numerical height samples.
|
|
5776
|
+
|
|
5777
|
+
```ts
|
|
5778
|
+
export function decodeRAW16( input: Uint8Array | ArrayBuffer, { … }
|
|
5779
|
+
```
|
|
5780
|
+
|
|
5781
|
+
- **Use when:** import a RAW16 terrain height buffer with explicit dimensions
|
|
5782
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5783
|
+
- **Requires:** npm i @threenative/terrain
|
|
5784
|
+
|
|
5785
|
+
```ts
|
|
5786
|
+
const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });
|
|
5787
|
+
```
|
|
5788
|
+
|
|
5789
|
+
### `encodeGLB`
|
|
5790
|
+
|
|
5791
|
+
`function` — Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.
|
|
5792
|
+
|
|
5793
|
+
```ts
|
|
5794
|
+
export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }
|
|
5795
|
+
```
|
|
5796
|
+
|
|
5797
|
+
- **Use when:** export baked terrain geometry without engine extensions
|
|
5798
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5799
|
+
- **Requires:** npm i @threenative/terrain
|
|
5800
|
+
|
|
5801
|
+
```ts
|
|
5802
|
+
const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
|
|
5803
|
+
```
|
|
5804
|
+
|
|
5805
|
+
### `encodeHeightPNG`
|
|
5806
|
+
|
|
5807
|
+
`function` — Encodes numerical grayscale PNG16 with embedded elevation range.
|
|
5808
|
+
|
|
5809
|
+
```ts
|
|
5810
|
+
export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }
|
|
5811
|
+
```
|
|
5812
|
+
|
|
5813
|
+
- **Use when:** export a terrain heightmap without an eight-bit colour conversion
|
|
5814
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5815
|
+
- **Requires:** npm i @threenative/terrain
|
|
5816
|
+
|
|
5817
|
+
```ts
|
|
5818
|
+
const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());
|
|
5819
|
+
```
|
|
5820
|
+
|
|
5821
|
+
### `encodeRAW16`
|
|
5822
|
+
|
|
5823
|
+
`function` — Encodes finite metre elevations as an explicit-range RAW16 buffer.
|
|
5824
|
+
|
|
5825
|
+
```ts
|
|
5826
|
+
export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }
|
|
5827
|
+
```
|
|
5828
|
+
|
|
5829
|
+
- **Use when:** export terrain heights with a numerical range sidecar
|
|
5830
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5831
|
+
- **Requires:** npm i @threenative/terrain
|
|
5832
|
+
|
|
5833
|
+
```ts
|
|
5834
|
+
const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });
|
|
5835
|
+
```
|
|
5836
|
+
|
|
5837
|
+
### `encodeSplatPNGs`
|
|
5838
|
+
|
|
5839
|
+
`function` — Encodes the eight linear material-weight channels as two RGBA images.
|
|
5840
|
+
|
|
5841
|
+
```ts
|
|
5842
|
+
export async function encodeSplatPNGs(state: ITerrainState) { … }
|
|
5843
|
+
```
|
|
5844
|
+
|
|
5845
|
+
- **Use when:** export terrain splat weights as linear data
|
|
5846
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5847
|
+
- **Requires:** npm i @threenative/terrain
|
|
5848
|
+
|
|
5849
|
+
```ts
|
|
5850
|
+
const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());
|
|
5851
|
+
```
|
|
5852
|
+
|
|
5853
|
+
### `encodeZIP`
|
|
5854
|
+
|
|
5855
|
+
`function` — Deterministic store-method ZIP with safe unique relative filenames.
|
|
5856
|
+
|
|
5857
|
+
```ts
|
|
5858
|
+
export function encodeZIP(files: readonly IExportFile[]) { … }
|
|
5859
|
+
```
|
|
5860
|
+
|
|
5861
|
+
- **Use when:** archive derived terrain files without another dependency
|
|
5862
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5863
|
+
- **Requires:** npm i @threenative/terrain
|
|
5864
|
+
|
|
5865
|
+
```ts
|
|
5866
|
+
const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
|
|
5867
|
+
```
|
|
5868
|
+
|
|
5869
|
+
### `gradientAt`
|
|
5870
|
+
|
|
5871
|
+
`function` — World-space height gradient from the canonical samples.
|
|
5872
|
+
|
|
5873
|
+
```ts
|
|
5874
|
+
export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }
|
|
5875
|
+
```
|
|
5876
|
+
|
|
5877
|
+
- **Use when:** measure an authored terrain gradient in metres
|
|
5878
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5879
|
+
- **Requires:** npm i @threenative/terrain
|
|
5880
|
+
|
|
5881
|
+
```ts
|
|
5882
|
+
const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
5883
|
+
```
|
|
5884
|
+
|
|
5885
|
+
### `makeExport`
|
|
5886
|
+
|
|
5887
|
+
`function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
|
|
5888
|
+
|
|
5889
|
+
```ts
|
|
5890
|
+
export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }
|
|
5891
|
+
```
|
|
5892
|
+
|
|
5893
|
+
- **Use when:** export a terrain recipe and its numerical runtime data
|
|
5894
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5895
|
+
- **Requires:** npm i @threenative/terrain
|
|
5896
|
+
|
|
5897
|
+
```ts
|
|
5898
|
+
const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
|
|
5899
|
+
```
|
|
5900
|
+
|
|
5901
|
+
### `sampleHeight`
|
|
5902
|
+
|
|
5903
|
+
`function` — Bilinear query of canonical height samples; triangle sampling is a separate contract.
|
|
5904
|
+
|
|
5905
|
+
```ts
|
|
5906
|
+
sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid( grid.height, grid.resolution, grid.resolution, x / grid.size + 0.5, z / grid.size + 0.5, )
|
|
5907
|
+
```
|
|
5908
|
+
|
|
5909
|
+
- **Use when:** query an authored heightfield at world coordinates
|
|
5910
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5911
|
+
- **Requires:** npm i @threenative/terrain
|
|
5912
|
+
|
|
5913
|
+
```ts
|
|
5914
|
+
const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
5915
|
+
```
|
|
5916
|
+
|
|
5917
|
+
### `slopeAtIndex`
|
|
5918
|
+
|
|
5919
|
+
`function` — Slope in degrees at a heightfield sample.
|
|
5920
|
+
|
|
5921
|
+
```ts
|
|
5922
|
+
export function slopeAtIndex(grid: ISampledGrid, i: number): number { … }
|
|
5923
|
+
```
|
|
5924
|
+
|
|
5925
|
+
- **Use when:** measure terrain slope for authoring diagnostics
|
|
5926
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5927
|
+
- **Requires:** npm i @threenative/terrain
|
|
5928
|
+
|
|
5929
|
+
```ts
|
|
5930
|
+
const slope = slopeAtIndex(new Terrain({ resolution: 17 }).evaluate(), 0);
|
|
5931
|
+
```
|
|
5932
|
+
|
|
5933
|
+
### `slopeQuantile`
|
|
5934
|
+
|
|
5935
|
+
`function` — A slope, in degrees, that the given share of this terrain's interior vertices lie at or below. Placement rules keyed to fixed degrees break when a world is rebaked smoother or rougher: an outcrop rule of "over 30 degrees" placed nothing on a forest whose 98th percentile is 22. Asking the terrain for its own steepest share keeps the rule meaning the same thing on every world.
|
|
5936
|
+
|
|
5937
|
+
```ts
|
|
5938
|
+
export function slopeQuantile(grid: ISampledGrid, quantile: number): number { … }
|
|
5939
|
+
```
|
|
5940
|
+
|
|
5941
|
+
- **Use when:** place rocks or cliffs on a terrain's own steepest ground instead of a fixed slope in degrees
|
|
5942
|
+
- **Constraints:** interior vertices only (edges have one-sided differences); quantile must be in [0, 1]
|
|
5943
|
+
- **Requires:** npm i @threenative/terrain
|
|
5944
|
+
|
|
5945
|
+
```ts
|
|
5946
|
+
const steep = slopeQuantile(grid, 0.98); if (slopeAt(x, z) > Math.min(30, steep)) placeRock(x, z);
|
|
5947
|
+
```
|
|
5948
|
+
|
|
5949
|
+
### `splinePoints`
|
|
5950
|
+
|
|
5951
|
+
`function` — Recovered horizontal Catmull–Rom and vertically linear profile sampler.
|
|
5952
|
+
|
|
5953
|
+
```ts
|
|
5954
|
+
export function splinePoints( points: readonly (readonly [number, number, number])[], step = 3, smooth = true, ): [number, number, number][] { … }
|
|
5955
|
+
```
|
|
5956
|
+
|
|
5957
|
+
- **Use when:** sample a road or river profile without vertical overshoot
|
|
5958
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
5959
|
+
- **Requires:** npm i @threenative/terrain
|
|
5960
|
+
|
|
5961
|
+
```ts
|
|
5962
|
+
const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
|
|
5963
|
+
```
|
|
5964
|
+
|
|
5965
|
+
### `Terrain`
|
|
5966
|
+
|
|
5967
|
+
`class` — Ordered, stable-ID terrain authoring with synchronous atomic transactions.
|
|
5968
|
+
|
|
5969
|
+
```ts
|
|
5970
|
+
export class Terrain { … }
|
|
5971
|
+
```
|
|
5972
|
+
|
|
5973
|
+
- **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game
|
|
5974
|
+
- **Constraints:** authoring stays outside the game's steady-play graph; no renderer or physics is created · units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin · `resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025 · `seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays · `evaluate()` is synchronous on the calling thread: run it in a build script, never per frame · no art is chosen or shipped: materials, models and texture paths belong to the game
|
|
5975
|
+
- **Requires:** npm i @threenative/terrain
|
|
5976
|
+
- **Overrides:** size, resolution, seed and all layer parameters are caller choices
|
|
5977
|
+
|
|
5978
|
+
```ts
|
|
5979
|
+
const terrain = new Terrain({ size: 512, resolution: 257, seed: 73 }).noise({ id: "hills", amplitude: 35 });
|
|
5980
|
+
```
|
|
5981
|
+
|
|
5982
|
+
### `TerrainEvaluator`
|
|
5983
|
+
|
|
5984
|
+
`class` — Recovered prefix-caching authoring evaluator. Returned buffers belong to the caller.
|
|
5985
|
+
|
|
5986
|
+
```ts
|
|
5987
|
+
export class TerrainEvaluator { … }
|
|
5988
|
+
```
|
|
5989
|
+
|
|
5990
|
+
- **Use when:** reuse terrain evaluation prefixes while authoring a finite heightfield
|
|
5991
|
+
- **Constraints:** evaluates authoring documents only; games consume pre-baked arrays
|
|
5992
|
+
- **Requires:** npm i @threenative/terrain
|
|
5993
|
+
- **Overrides:** cacheMB bounds retained prefix data
|
|
5994
|
+
|
|
5995
|
+
```ts
|
|
5996
|
+
const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());
|
|
5997
|
+
```
|
|
5998
|
+
|
|
5999
|
+
### `validateDocument`
|
|
6000
|
+
|
|
6001
|
+
`function` — Validates the recovered recipe schema, operation allow-lists and numeric bounds.
|
|
6002
|
+
|
|
6003
|
+
```ts
|
|
6004
|
+
export function validateDocument(doc: ITerrainDocument): void { … }
|
|
6005
|
+
```
|
|
6006
|
+
|
|
6007
|
+
- **Use when:** validate a terrain document before accepting an authoring write
|
|
6008
|
+
- **Constraints:** authoring data only; the game owns appearance, physics and rendering
|
|
6009
|
+
- **Requires:** npm i @threenative/terrain
|
|
6010
|
+
|
|
6011
|
+
```ts
|
|
6012
|
+
validateDocument(new Terrain({ resolution: 17 }).toJSON());
|
|
6013
|
+
```
|
|
6014
|
+
|
|
6015
|
+
### `validatePlacementOverrides`
|
|
6016
|
+
|
|
6017
|
+
`function` — Validate and clone stable-key placement transforms before saving or previewing them.
|
|
6018
|
+
|
|
6019
|
+
```ts
|
|
6020
|
+
export function validatePlacementOverrides( value: unknown = { … }
|
|
6021
|
+
```
|
|
6022
|
+
|
|
6023
|
+
- **Use when:** validate finite positive manual prop transforms before a terrain authoring transaction
|
|
6024
|
+
- **Constraints:** grounding defaults on only when omitted; position and scale have three components and quaternion is unit length
|
|
6025
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6026
|
+
- **Overrides:** grounding=false preserves authored Y and keeps clearance observable
|
|
6027
|
+
|
|
6028
|
+
```ts
|
|
6029
|
+
const transforms = validatePlacementOverrides(document.placementOverrides);
|
|
6030
|
+
```
|
|
6031
|
+
|
|
6032
|
+
## `@threenative/terrain/editor`
|
|
6033
|
+
|
|
6034
|
+
### `checkEnvironmentAssets`
|
|
6035
|
+
|
|
6036
|
+
`function` — Check that the images an environment names are registered environment or image assets. @summary Validate the assets a preview environment refers to
|
|
6037
|
+
|
|
6038
|
+
```ts
|
|
6039
|
+
export function checkEnvironmentAssets( environment: IEnvironment, assets: readonly { … }
|
|
6040
|
+
```
|
|
6041
|
+
|
|
6042
|
+
- **Use when:** refuse a saved environment whose sky or lighting image is not a registered file
|
|
6043
|
+
- **Constraints:** throws by name; HDR/EXR environment files and ordinary images are accepted, models are not
|
|
6044
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6045
|
+
- **Overrides:** the project owns which images it registers
|
|
6046
|
+
|
|
6047
|
+
```ts
|
|
6048
|
+
checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
|
|
6049
|
+
```
|
|
6050
|
+
|
|
6051
|
+
### `focusCamera`
|
|
6052
|
+
|
|
6053
|
+
`function` — Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera
|
|
6054
|
+
|
|
6055
|
+
```ts
|
|
6056
|
+
export function focusCamera( camera: ISavedCamera, request: IFocusRequest, resolve: IFocusResolver, ): IFocusOutcome { … }
|
|
6057
|
+
```
|
|
6058
|
+
|
|
6059
|
+
- **Use when:** frame one selected prop, a registered landmark, a terrain region or a local point
|
|
6060
|
+
- **Constraints:** framing only; an unknown target returns a named diagnostic and no camera
|
|
6061
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6062
|
+
- **Overrides:** the view supplies target bounds, the live aspect and the camera to keep
|
|
6063
|
+
|
|
6064
|
+
```ts
|
|
6065
|
+
const outcome = focusCamera(camera, { target: { kind: "prop", id: "pine-3" }, aspect: 16 / 9 }, resolve);
|
|
6066
|
+
```
|
|
6067
|
+
|
|
6068
|
+
### `inspectImage`
|
|
6069
|
+
|
|
6070
|
+
`function` — Validate a PNG, JPEG, WebP, Radiance HDR or OpenEXR container and read its pixel size. @summary Inspect an image file's container and pixel size without decoding it
|
|
6071
|
+
|
|
6072
|
+
```ts
|
|
6073
|
+
export function inspectImage( bytes: Uint8Array, format: string, limits: { … }
|
|
6074
|
+
```
|
|
6075
|
+
|
|
6076
|
+
- **Use when:** check an imported surface or environment image for damage and for the project's size limit
|
|
6077
|
+
- **Constraints:** headers and checksums only; throws by name for a damaged, truncated or oversize file
|
|
6078
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6079
|
+
- **Overrides:** the project sets the dimension limit
|
|
6080
|
+
|
|
6081
|
+
```ts
|
|
6082
|
+
const report = inspectImage(bytes, "png", { maxDimension: 8192 });
|
|
6083
|
+
```
|
|
6084
|
+
|
|
6085
|
+
### `inspectSpatial`
|
|
6086
|
+
|
|
6087
|
+
`function` — Read-only spatial inspection of one evaluated terrain revision.
|
|
6088
|
+
|
|
6089
|
+
```ts
|
|
6090
|
+
export function inspectSpatial( state: ITerrainState, revision: string, query: ISpatialQuery, ): ISpatialObservation { … }
|
|
6091
|
+
```
|
|
6092
|
+
|
|
6093
|
+
- **Use when:** measure a point, profile a transect or score a saved reference against the world
|
|
6094
|
+
- **Constraints:** authoring data only; queries outside the extent or without observations throw
|
|
6095
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6096
|
+
- **Overrides:** the caller owns the revision identity and the evaluated state being inspected
|
|
6097
|
+
|
|
6098
|
+
```ts
|
|
6099
|
+
const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
|
|
6100
|
+
```
|
|
6101
|
+
|
|
6102
|
+
### `mountTerrainEditor`
|
|
6103
|
+
|
|
6104
|
+
`function` — Mount recovered terrain controls around the project-owned ThreeNative view.
|
|
6105
|
+
|
|
6106
|
+
```ts
|
|
6107
|
+
export async function mountTerrainEditor(options: { … }
|
|
6108
|
+
```
|
|
6109
|
+
|
|
6110
|
+
- **Use when:** open the terrain brush and layer GUI around game-owned rendering
|
|
6111
|
+
- **Constraints:** browser authoring only; createView and materialColours are required game choices
|
|
6112
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6113
|
+
- **Overrides:** createView owns the renderer scene, materials, lighting and camera
|
|
6114
|
+
|
|
6115
|
+
```ts
|
|
6116
|
+
await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
|
|
6117
|
+
```
|
|
6118
|
+
|
|
6119
|
+
### `probeTerrain`
|
|
6120
|
+
|
|
6121
|
+
`function` — Probe the evaluated surface at one world point, separating bilinear from triangle values.
|
|
6122
|
+
|
|
6123
|
+
```ts
|
|
6124
|
+
export function probeTerrain( state: ITerrainState, revision: string, at: readonly number[], ): IPointObservation { … }
|
|
6125
|
+
```
|
|
6126
|
+
|
|
6127
|
+
- **Use when:** measure an authored terrain point with provenance and a revision identity
|
|
6128
|
+
- **Constraints:** authoring data only; non-finite, malformed and out-of-extent queries throw
|
|
6129
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6130
|
+
- **Overrides:** the caller owns the revision identity and the evaluated state being inspected
|
|
6131
|
+
|
|
6132
|
+
```ts
|
|
6133
|
+
const probe = probeTerrain(state, revision, [12, -4]);
|
|
6134
|
+
```
|
|
6135
|
+
|
|
6136
|
+
### `runCameraOperation`
|
|
6137
|
+
|
|
6138
|
+
`function` — Run one create / get / list / update / delete / activate operation over saved cameras. @summary Apply an editor camera operation to a saved camera set
|
|
6139
|
+
|
|
6140
|
+
```ts
|
|
6141
|
+
export function runCameraOperation(set: ICameraSet, operation: unknown): ICameraResult { … }
|
|
6142
|
+
```
|
|
6143
|
+
|
|
6144
|
+
- **Use when:** drive the terrain editor camera list from an agent or the GUI through one shared dispatch
|
|
6145
|
+
- **Constraints:** pure: the input set is never mutated, an unknown id throws, and deleting the live camera falls back
|
|
6146
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6147
|
+
- **Overrides:** the caller persists the returned set against its own revision
|
|
6148
|
+
|
|
6149
|
+
```ts
|
|
6150
|
+
const next = runCameraOperation(set, { op: "activate", id: "survey" });
|
|
6151
|
+
```
|
|
6152
|
+
|
|
6153
|
+
### `runEnvironmentOperation`
|
|
6154
|
+
|
|
6155
|
+
`function` — Apply one get / patch / reset against the saved environment overrides; the caller commits it. @summary Run one preview-environment operation
|
|
6156
|
+
|
|
6157
|
+
```ts
|
|
6158
|
+
export function runEnvironmentOperation( current: IEnvironment, operation: unknown, ): IEnvironmentResult { … }
|
|
6159
|
+
```
|
|
6160
|
+
|
|
6161
|
+
- **Use when:** patch sun, haze, exposure or sea overrides from a controller or the editor GUI
|
|
6162
|
+
- **Constraints:** authoring metadata only; a null field returns to the project's own value
|
|
6163
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6164
|
+
- **Overrides:** the project's render source decides what each value does
|
|
6165
|
+
|
|
6166
|
+
```ts
|
|
6167
|
+
const result = runEnvironmentOperation({}, { op: "patch", values: { sun: { elevation: 25 } } });
|
|
6168
|
+
```
|
|
6169
|
+
|
|
6170
|
+
### `sniff`
|
|
6171
|
+
|
|
6172
|
+
`function` — The kind and format a file's own bytes declare, whatever its name says. @summary Identify a GLB, PNG, JPEG, WebP, HDR or EXR file by its header
|
|
6173
|
+
|
|
6174
|
+
```ts
|
|
6175
|
+
export function sniff( bytes: Uint8Array, ): { … }
|
|
6176
|
+
```
|
|
6177
|
+
|
|
6178
|
+
- **Use when:** decide whether a dropped or downloaded file is a model, surface image or environment image
|
|
6179
|
+
- **Constraints:** reads only the first bytes; a file it cannot name returns undefined and must be refused
|
|
6180
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6181
|
+
- **Overrides:** the caller decides what to do with an unknown file
|
|
6182
|
+
|
|
6183
|
+
```ts
|
|
6184
|
+
const kind = sniff(new Uint8Array(await file.arrayBuffer()))?.kind;
|
|
6185
|
+
```
|
|
6186
|
+
|
|
6187
|
+
### `surfaceSpace`
|
|
6188
|
+
|
|
6189
|
+
`function` — The colour space an input's pixels are read in, from the channel its name ends with. @summary Resolve a surface input name to sRGB or linear
|
|
6190
|
+
|
|
6191
|
+
```ts
|
|
6192
|
+
export function surfaceSpace(input: string): "srgb" | "linear" { … }
|
|
6193
|
+
```
|
|
6194
|
+
|
|
6195
|
+
- **Use when:** decide how an imported image bound to a named surface input must be sampled
|
|
6196
|
+
- **Constraints:** throws by name for an input that is not <surface>.<channel> with a known channel
|
|
6197
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6198
|
+
- **Overrides:** the project owns which surface inputs exist
|
|
6199
|
+
|
|
6200
|
+
```ts
|
|
6201
|
+
const space = surfaceSpace("bark.normal");
|
|
6202
|
+
```
|
|
6203
|
+
|
|
6204
|
+
### `TerrainEditorController`
|
|
6205
|
+
|
|
6206
|
+
`class` — HTTP controller for the project-local terrain editor.
|
|
6207
|
+
|
|
6208
|
+
```ts
|
|
6209
|
+
export class TerrainEditorController { … }
|
|
6210
|
+
```
|
|
6211
|
+
|
|
6212
|
+
- **Use when:** inspect and atomically edit the terrain editor from an agent
|
|
6213
|
+
- **Constraints:** optional tooling; only subscribe/mount touches DOM; stale revisions fail explicitly
|
|
6214
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6215
|
+
- **Overrides:** editorUrl is the activation-returned project URL
|
|
6216
|
+
|
|
6217
|
+
```ts
|
|
6218
|
+
const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
|
|
6219
|
+
```
|
|
6220
|
+
|
|
6221
|
+
### `validateAsset`
|
|
6222
|
+
|
|
6223
|
+
`function` — Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry
|
|
6224
|
+
|
|
6225
|
+
```ts
|
|
6226
|
+
export function validateAsset(input: unknown): IProjectAsset { … }
|
|
6227
|
+
```
|
|
6228
|
+
|
|
6229
|
+
- **Use when:** check a model, image or environment asset entry before saving it in the authoring document
|
|
6230
|
+
- **Constraints:** authoring metadata only; ids, content-hashed paths, bounds and unit adjustments are checked, files are not read
|
|
6231
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6232
|
+
- **Overrides:** the project owns its asset directory and which entries it keeps
|
|
6233
|
+
|
|
6234
|
+
```ts
|
|
6235
|
+
const asset = validateAsset({ id: "oak", kind: "model", name: "oak.glb", path: "models/0123456789ab-oak.glb", sha256: "0123456789ab".padEnd(64, "0"), bytes: 2180, status: "ready" });
|
|
6236
|
+
```
|
|
6237
|
+
|
|
6238
|
+
### `validateAssets`
|
|
6239
|
+
|
|
6240
|
+
`function` — Validate the whole asset list of an authoring document. @summary Validate the registered terrain-editor assets
|
|
6241
|
+
|
|
6242
|
+
```ts
|
|
6243
|
+
export function validateAssets(input: unknown): IProjectAsset[] { … }
|
|
6244
|
+
```
|
|
6245
|
+
|
|
6246
|
+
- **Use when:** check every registered model, image and environment entry together, with unique ids
|
|
6247
|
+
- **Constraints:** at most 64 entries; unique ids; each entry as validateAsset
|
|
6248
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6249
|
+
- **Overrides:** the project owns its asset directory and which entries it keeps
|
|
6250
|
+
|
|
6251
|
+
```ts
|
|
6252
|
+
const assets = validateAssets(document.assets ?? []);
|
|
6253
|
+
```
|
|
6254
|
+
|
|
6255
|
+
### `validateCamera`
|
|
6256
|
+
|
|
6257
|
+
`function` — Normalise and validate one saved camera, exactly as a document commit would store it. @summary Validate an editor observation camera bookmark
|
|
6258
|
+
|
|
6259
|
+
```ts
|
|
6260
|
+
export function validateCamera( input: unknown, existing: readonly ISavedCamera[] = [], ): ISavedCamera { … }
|
|
6261
|
+
```
|
|
6262
|
+
|
|
6263
|
+
- **Use when:** create or update a named terrain-editor camera in the shared authoring document
|
|
6264
|
+
- **Constraints:** authoring metadata only; finite noncoincident poses, usable up, valid projection, ordered planes
|
|
6265
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6266
|
+
- **Overrides:** the caller owns the document revision and the live viewport aspect
|
|
6267
|
+
|
|
6268
|
+
```ts
|
|
6269
|
+
const camera = validateCamera({ id: "survey", name: "Survey", position: [40, 60, 40], target: [0, 12, 0], up: [0, 1, 0], projection: "perspective", fov: 50, near: 0.5, far: 900 });
|
|
6270
|
+
```
|
|
6271
|
+
|
|
6272
|
+
### `validateCameras`
|
|
6273
|
+
|
|
6274
|
+
`function` — Validate a document's saved camera list, keeping ids unique across it. @summary Validate the saved editor camera list of an authoring document
|
|
6275
|
+
|
|
6276
|
+
```ts
|
|
6277
|
+
export function validateCameras(input: unknown): ISavedCamera[] { … }
|
|
6278
|
+
```
|
|
6279
|
+
|
|
6280
|
+
- **Use when:** reject a disk document whose saved cameras are malformed or duplicated
|
|
6281
|
+
- **Constraints:** authoring metadata only; the same validation the camera operations apply
|
|
6282
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6283
|
+
- **Overrides:** the document owns how many cameras it keeps; the list bound is the editor's own
|
|
6284
|
+
|
|
6285
|
+
```ts
|
|
6286
|
+
const cameras = validateCameras(JSON.parse(saved).cameras ?? []);
|
|
6287
|
+
```
|
|
6288
|
+
|
|
6289
|
+
### `validateEnvironment`
|
|
6290
|
+
|
|
6291
|
+
`function` — Validate a complete overrides object exactly as a document commit stores it. @summary Validate preview environment overrides
|
|
6292
|
+
|
|
6293
|
+
```ts
|
|
6294
|
+
export function validateEnvironment(input: unknown): IEnvironment { … }
|
|
6295
|
+
```
|
|
6296
|
+
|
|
6297
|
+
- **Use when:** save sun, sky, haze, exposure or ocean overrides in the shared authoring document
|
|
6298
|
+
- **Constraints:** authoring metadata only; unknown fields and unsupported fog modes are refused by name
|
|
6299
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6300
|
+
- **Overrides:** the project's render source defines what each value does; absent fields keep its own
|
|
6301
|
+
|
|
6302
|
+
```ts
|
|
6303
|
+
const environment = validateEnvironment({ sun: { elevation: 25, intensity: 3 } });
|
|
6304
|
+
```
|
|
6305
|
+
|
|
6306
|
+
### `validateSpatialReference`
|
|
6307
|
+
|
|
6308
|
+
`function` — Normalise and validate one saved reference, exactly as a document commit would store it.
|
|
6309
|
+
|
|
6310
|
+
```ts
|
|
6311
|
+
export function validateSpatialReference(input: unknown): ISavedSpatialReference { … }
|
|
6312
|
+
```
|
|
6313
|
+
|
|
6314
|
+
- **Use when:** accept a bounded local reference image registration into the shared document
|
|
6315
|
+
- **Constraints:** authoring metadata only; rejects unknown fields, malformed points and unknown scale
|
|
6316
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6317
|
+
- **Overrides:** a project owns the image file; only its hash and provenance travel in the document
|
|
6318
|
+
|
|
6319
|
+
```ts
|
|
6320
|
+
const reference = validateSpatialReference(JSON.parse(saved));
|
|
6321
|
+
```
|
|
6322
|
+
|
|
6323
|
+
### `validateSurfaces`
|
|
6324
|
+
|
|
6325
|
+
`function` — Validate surface mappings against the registered images they name. @summary Validate terrain-editor surface image mappings
|
|
6326
|
+
|
|
6327
|
+
```ts
|
|
6328
|
+
export function validateSurfaces( input: unknown, assets: readonly IProjectAsset[], ): ISurfaceMappings { … }
|
|
6329
|
+
```
|
|
6330
|
+
|
|
6331
|
+
- **Use when:** save which imported PBR image replaces which named surface input of the project's render source
|
|
6332
|
+
- **Constraints:** authoring metadata only; each input is <surface>.<channel>; every asset must be a registered image
|
|
6333
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6334
|
+
- **Overrides:** the project's render source defines which surface inputs exist and what they draw
|
|
6335
|
+
|
|
6336
|
+
```ts
|
|
6337
|
+
const surfaces = validateSurfaces({ "bark.normal": { asset: "my-normal" } }, document.assets ?? []);
|
|
6338
|
+
```
|
|
6339
|
+
|
|
6340
|
+
## `@threenative/terrain/editor/server`
|
|
6341
|
+
|
|
6342
|
+
### `terrainEditor`
|
|
6343
|
+
|
|
6344
|
+
`function` — Mount the optional terrain document API on an existing loopback Vite server.
|
|
6345
|
+
|
|
6346
|
+
```ts
|
|
6347
|
+
export function terrainEditor(options: { … }
|
|
6348
|
+
```
|
|
6349
|
+
|
|
6350
|
+
- **Use when:** share terrain recipe edits between an agent and the live terrain editor
|
|
6351
|
+
- **Constraints:** dev tooling only; serve a project-owned /terrain-editor/index.html; no runtime import
|
|
6352
|
+
- **Requires:** npm i -D @threenative/terrain vite
|
|
6353
|
+
- **Overrides:** documentPath and optional configured viewerUrl belong to the project
|
|
6354
|
+
|
|
6355
|
+
```ts
|
|
6356
|
+
const editor = terrainEditor({ documentPath: resolve("terrain/world.json") });
|
|
6357
|
+
```
|
|
6358
|
+
|
|
6359
|
+
### `TerrainEditorDocument`
|
|
6360
|
+
|
|
6361
|
+
`class` — Project-local terrain document authority; no renderer or game dependency.
|
|
6362
|
+
|
|
6363
|
+
```ts
|
|
6364
|
+
export class TerrainEditorDocument { … }
|
|
6365
|
+
```
|
|
6366
|
+
|
|
6367
|
+
- **Use when:** validate atomic revision-based project-local terrain document edits
|
|
6368
|
+
- **Constraints:** Node authoring only; documentPath is a configured absolute regular file; input is bounded to 64 MiB
|
|
6369
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6370
|
+
- **Overrides:** the project chooses its document path; revisions come from validated content
|
|
6371
|
+
|
|
6372
|
+
```ts
|
|
6373
|
+
const document = new TerrainEditorDocument("/project/terrain/world.json"); const snapshot = document.snapshot();
|
|
6374
|
+
```
|
|
6375
|
+
|
|
6376
|
+
## `@threenative/terrain/export`
|
|
6377
|
+
|
|
6378
|
+
### `exportWorldGLB`
|
|
6379
|
+
|
|
6380
|
+
`function` — Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.
|
|
6381
|
+
|
|
6382
|
+
```ts
|
|
6383
|
+
export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }
|
|
6384
|
+
```
|
|
6385
|
+
|
|
6386
|
+
- **Use when:** export terrain, resolved models and final manual placement transforms as a portable GLB · export the whole terrain world as one glb for another three.js project
|
|
6387
|
+
- **Constraints:** browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless
|
|
6388
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6389
|
+
- **Overrides:** actual static models, final matrices and baked PBR maps are supplied by the game
|
|
6390
|
+
|
|
6391
|
+
```ts
|
|
6392
|
+
const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });
|
|
6393
|
+
```
|
|
6394
|
+
|
|
6395
|
+
## `@threenative/terrain/three`
|
|
6396
|
+
|
|
6397
|
+
### `toGeometry`
|
|
6398
|
+
|
|
6399
|
+
`function` — Converts baked arrays to ordinary geometry using the consumer's installed Three.js.
|
|
6400
|
+
|
|
6401
|
+
```ts
|
|
6402
|
+
export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }
|
|
6403
|
+
```
|
|
6404
|
+
|
|
6405
|
+
- **Use when:** put an authored terrain mesh in a game-owned Three.js scene
|
|
6406
|
+
- **Constraints:** creates only geometry; the caller owns its material, scene and disposal
|
|
6407
|
+
- **Requires:** npm i @threenative/terrain
|
|
6408
|
+
- **Overrides:** every surface choice remains in game source
|
|
6409
|
+
|
|
6410
|
+
```ts
|
|
6411
|
+
const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));
|
|
6412
|
+
```
|
|
6413
|
+
|
|
5346
6414
|
## `@threenative/ueformat`
|
|
5347
6415
|
|
|
5348
6416
|
### `createThreeGeometry`
|
|
@@ -5453,6 +6521,7 @@ export function DebugOverlay() { … }
|
|
|
5453
6521
|
|
|
5454
6522
|
- **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene · find out which scene object is submitting the frame's triangles · tell a cheap foreground character from an expensive distant prop
|
|
5455
6523
|
- **Constraints:** the Geometry tab captures only on an explicit press; nothing is collected while idle · per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden
|
|
6524
|
+
- **Requires:** npm i @threenative/ui
|
|
5456
6525
|
|
|
5457
6526
|
```ts
|
|
5458
6527
|
<DebugOverlay />
|
|
@@ -5468,6 +6537,7 @@ export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( {
|
|
|
5468
6537
|
|
|
5469
6538
|
- **Use when:** add a game viewport to a React application · connect a game canvas to the web UI shell
|
|
5470
6539
|
- **Constraints:** keep the portable game entry free of React DOM code
|
|
6540
|
+
- **Requires:** npm i @threenative/ui
|
|
5471
6541
|
|
|
5472
6542
|
```ts
|
|
5473
6543
|
<GameCanvas game={game} />
|
|
@@ -5483,6 +6553,7 @@ export function UiLayer( { … }
|
|
|
5483
6553
|
|
|
5484
6554
|
- **Use when:** write one HUD that looks the same on the web build and on a phone · mount a React UI over the game surface on Android or iOS
|
|
5485
6555
|
- **Constraints:** mark every control the player touches with data-tn-interactive
|
|
6556
|
+
- **Requires:** npm i @threenative/ui
|
|
5486
6557
|
|
|
5487
6558
|
```ts
|
|
5488
6559
|
<UiLayer><Hud /></UiLayer>
|
|
@@ -5498,6 +6569,7 @@ export function useGameState<TState extends Record<string, unknown>, TPhysics, T
|
|
|
5498
6569
|
|
|
5499
6570
|
- **Use when:** bind a HUD component to game state · select a slice of state for a React panel
|
|
5500
6571
|
- **Constraints:** use this hook only from the web UI entry
|
|
6572
|
+
- **Requires:** npm i @threenative/ui
|
|
5501
6573
|
|
|
5502
6574
|
```ts
|
|
5503
6575
|
const score = useGameState(game, (state) => state.score);
|
|
@@ -5513,6 +6585,7 @@ export function useUiIntent(): (intent: string, payload?: unknown) => void { …
|
|
|
5513
6585
|
|
|
5514
6586
|
- **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu rendered over its surface
|
|
5515
6587
|
- **Constraints:** the game decides what each intent name means; it may ignore one
|
|
6588
|
+
- **Requires:** npm i @threenative/ui
|
|
5516
6589
|
|
|
5517
6590
|
```ts
|
|
5518
6591
|
const send = useUiIntent(); send("restart");
|
|
@@ -5528,6 +6601,7 @@ export function useUiState<TState extends object>(): TState | undefined;
|
|
|
5528
6601
|
|
|
5529
6602
|
- **Use when:** bind a HUD to game state on web and native alike · show score or health in a UI rendered over the game surface
|
|
5530
6603
|
- **Constraints:** returns undefined until the game publishes its first state
|
|
6604
|
+
- **Requires:** npm i @threenative/ui
|
|
5531
6605
|
|
|
5532
6606
|
```ts
|
|
5533
6607
|
const score = useUiState<GameState, number>((state) => state.score);
|