create-threenative 0.2.9 → 0.2.12
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 +109 -3
- package/agent-docs/references/auto-exposure.md +28 -45
- package/agent-docs/references/build-profiles.md +1 -1
- package/agent-docs/references/capability-reference.md +527 -44
- package/agent-docs/references/debug-surface.md +64 -0
- package/agent-docs/references/finding-assets.md +11 -12
- package/agent-docs/references/performance-basics.md +19 -0
- package/agent-docs/references/trace-a-slow-frame.md +21 -0
- package/agent-docs/references/visual-baseline.md +23 -4
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +17 -6
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +87 -23
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +12 -11
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/scripts/reference.mjs +9 -4
- package/capabilities.json +739 -50
- package/dist/index.d.ts +40 -6
- package/dist/index.js +229 -36
- package/dist/quality.d.ts +12 -0
- package/dist/quality.js +166747 -0
- package/dist/threenative.js +60 -44
- package/dist/web-engine-gltf-loader.js +2 -0
- package/dist/web-engine-mesh-bvh-webgpu.js +1 -1
- package/dist/web-engine-mesh-bvh.js +7 -0
- package/dist/web-engine-post-effects.js +645 -19
- package/dist/web-engine-runtime.js +3528 -343
- package/package.json +19 -9
- package/template-assets/assets/bay-PROVENANCE.md +21 -0
- package/template-assets/assets/bay-ground.webp +0 -0
- package/template-assets/assets/bay-metal.webp +0 -0
- package/template-assets/assets/bay-pavement-normal.webp +0 -0
- package/template-assets/assets/bay-pavement.webp +0 -0
- package/template-assets/assets/bay-plaster-normal.webp +0 -0
- package/template-assets/assets/bay-plaster.webp +0 -0
- package/template-assets/assets/bay-wood-normal.webp +0 -0
- package/template-assets/assets/bay-wood.webp +0 -0
- package/template-assets/assets/tex-PROVENANCE.md +25 -0
- package/template-assets/assets/tex-bark-normal.webp +0 -0
- package/template-assets/assets/tex-bark.webp +0 -0
- package/template-assets/assets/tex-birch-bark.webp +0 -0
- package/template-assets/assets/tex-grass.webp +0 -0
- package/template-assets/assets/tex-planks-normal.webp +0 -0
- package/template-assets/assets/tex-planks.webp +0 -0
- package/template-assets/assets/tex-rock-normal.webp +0 -0
- package/template-assets/assets/tex-rock.webp +0 -0
- package/template-assets/assets/tex-roof-tiles-normal.webp +0 -0
- package/template-assets/assets/tex-roof-tiles.webp +0 -0
- package/template-assets/assets/tex-sand-normal.webp +0 -0
- package/template-assets/assets/tex-sand.webp +0 -0
- package/template-assets/assets/tex-stone-wall-normal.webp +0 -0
- package/template-assets/assets/tex-stone-wall.webp +0 -0
- package/template-assets/kitExposure.ts +20 -0
- package/template-assets/patches/three@0.185.1.patch +481 -272
- package/template-assets/quality/biome.json +7 -0
- package/template-assets/quality/eslint.config.js +3 -0
- package/template-assets/realistic-ocean/README.md +113 -0
- package/template-assets/realistic-ocean/install.mjs +56 -0
- package/template-assets/realistic-ocean/src/realisticOcean.ts +151 -0
- package/template-assets/realistic-ocean/src/realisticOceanLifetime.ts +29 -0
- package/template-assets/realistic-ocean/src/render/REALISTIC-OCEAN-LICENSE.txt +25 -0
- package/template-assets/realistic-ocean/src/render/realisticSea.ts +642 -0
- package/template-assets/realistic-ocean/src/render/realisticSeaMaps.ts +311 -0
- package/template-assets/realistic-ocean/src/render/realisticSpectrum.ts +289 -0
- package/templates/AGENTS.md +21 -0
- package/templates/CLAUDE.md +23 -0
- package/templates/action-rpg/.codex/config.toml +6 -2
- package/templates/action-rpg/.cursor/mcp.json +8 -2
- package/templates/action-rpg/.gemini/settings.json +8 -2
- package/templates/action-rpg/.mcp.json +8 -2
- package/templates/action-rpg/.vscode/mcp.json +9 -2
- package/templates/action-rpg/.zed/settings.json +9 -2
- package/templates/action-rpg/AGENTS.md +11 -11
- package/templates/action-rpg/CLAUDE.md +11 -11
- package/templates/action-rpg/opencode.json +10 -2
- package/templates/action-rpg/package.json +17 -11
- package/templates/action-rpg/playtests/combat.playtest.json +6 -0
- package/templates/action-rpg/playtests/inventory.playtest.json +22 -0
- package/templates/action-rpg/playtests/performance.playtest.json +1 -1
- package/templates/action-rpg/playtests/roll.playtest.json +112 -0
- package/templates/action-rpg/playtests/swing.playtest.json +55 -0
- package/templates/action-rpg/playtests/win.playtest.json +4 -4
- package/templates/action-rpg/src/entities/Fighter.ts +44 -4
- package/templates/action-rpg/src/entities/Player.ts +64 -12
- package/templates/action-rpg/src/render/atmosphere.ts +444 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +49 -18
- package/templates/action-rpg/src/render/clouds.ts +605 -0
- package/templates/action-rpg/src/render/dungeon.ts +8 -6
- package/templates/action-rpg/src/render/exposure.ts +11 -109
- package/templates/action-rpg/src/render/gpuSky.ts +752 -0
- package/templates/action-rpg/src/render/lighting.ts +27 -4
- package/templates/action-rpg/src/render/materialLighting.ts +2 -11
- package/templates/action-rpg/src/render/palette.ts +1 -0
- package/templates/action-rpg/src/render/postprocessing.ts +4 -4
- package/templates/action-rpg/src/render/props.ts +10 -8
- package/templates/action-rpg/src/render/quality.ts +56 -108
- package/templates/action-rpg/src/render/sky.ts +74 -1
- package/templates/action-rpg/src/scenes/Play.ts +16 -12
- package/templates/action-rpg/src/ui/CharacterPanel.tsx +7 -2
- package/templates/action-rpg/src/ui/Hud.tsx +5 -7
- package/templates/action-rpg/src/ui/InventoryPanel.tsx +14 -14
- package/templates/action-rpg/threenative.config.ts +3 -0
- package/templates/adventure/.codex/config.toml +23 -0
- package/templates/adventure/.cursor/mcp.json +38 -0
- package/templates/adventure/.gemini/settings.json +38 -0
- package/templates/adventure/.mcp.json +38 -0
- package/templates/adventure/.vscode/mcp.json +43 -0
- package/templates/adventure/.zed/settings.json +43 -0
- package/templates/adventure/AGENTS.md +60 -0
- package/templates/adventure/CLAUDE.md +62 -0
- package/templates/adventure/index.html +14 -0
- package/templates/adventure/kit.json +8 -0
- package/templates/adventure/native-playtests/survives.playtest.json +52 -0
- package/templates/adventure/opencode.json +49 -0
- package/templates/adventure/package.json +65 -0
- package/templates/adventure/playtests/boss.playtest.json +406 -0
- package/templates/adventure/playtests/combat.playtest.json +342 -0
- package/templates/adventure/playtests/controls.playtest.json +142 -0
- package/templates/adventure/playtests/explore.playtest.json +45 -0
- package/templates/adventure/playtests/flicker.playtest.json +206 -0
- package/templates/adventure/playtests/hearts.playtest.json +171 -0
- package/templates/adventure/playtests/lockon.playtest.json +256 -0
- package/templates/adventure/playtests/look.playtest.json +72 -0
- package/templates/adventure/playtests/move-hollow.playtest.json +106 -0
- package/templates/adventure/playtests/move.playtest.json +84 -0
- package/templates/adventure/playtests/performance.playtest.json +55 -0
- package/templates/adventure/playtests/puzzle.playtest.json +250 -0
- package/templates/adventure/playtests/stride.playtest.json +67 -0
- package/templates/adventure/playtests/survives.playtest.json +171 -0
- package/templates/adventure/playtests/thornback.playtest.json +267 -0
- package/templates/adventure/public/favicon.svg +4 -0
- package/templates/adventure/src/entities/Block.ts +114 -0
- package/templates/adventure/src/entities/Chest.ts +69 -0
- package/templates/adventure/src/entities/Door.ts +81 -0
- package/templates/adventure/src/entities/Dummy.ts +69 -0
- package/templates/adventure/src/entities/Flicker.ts +239 -0
- package/templates/adventure/src/entities/Hero.ts +561 -0
- package/templates/adventure/src/entities/LockOn.ts +180 -0
- package/templates/adventure/src/entities/Mossling.ts +249 -0
- package/templates/adventure/src/entities/Switch.ts +49 -0
- package/templates/adventure/src/entities/Thornback.ts +238 -0
- package/templates/adventure/src/entities/Warden.ts +196 -0
- package/templates/adventure/src/game.ts +65 -0
- package/templates/adventure/src/interact.ts +63 -0
- package/templates/adventure/src/level/Hollow.ts +240 -0
- package/templates/adventure/src/level/Vale.ts +383 -0
- package/templates/adventure/src/main.ts +18 -0
- package/templates/adventure/src/render/camera.ts +416 -0
- package/templates/adventure/src/render/creatures.ts +405 -0
- package/templates/adventure/src/render/effects.ts +333 -0
- package/templates/adventure/src/render/foliage.ts +1072 -0
- package/templates/adventure/src/render/hero.ts +1447 -0
- package/templates/adventure/src/render/kitExposure.ts +20 -0
- package/templates/adventure/src/render/lighting.ts +74 -0
- package/templates/adventure/src/render/loading.ts +332 -0
- package/templates/adventure/src/render/materials.ts +179 -0
- package/templates/adventure/src/render/palette.ts +137 -0
- package/templates/adventure/src/render/postprocessing.ts +70 -0
- package/templates/adventure/src/render/props.ts +383 -0
- package/templates/adventure/src/render/quality.ts +46 -0
- package/templates/adventure/src/render/sky.ts +271 -0
- package/templates/adventure/src/render/surface.ts +259 -0
- package/templates/adventure/src/render/touch-controls.ts +137 -0
- package/templates/adventure/src/scenes/Play.ts +959 -0
- package/templates/adventure/src/state.ts +113 -0
- package/templates/adventure/src/style.css +98 -0
- package/templates/adventure/src/ui/App.tsx +22 -0
- package/templates/adventure/src/ui/GameUi.tsx +20 -0
- package/templates/adventure/src/ui/Hud.tsx +70 -0
- package/templates/adventure/src/ui/Menu.tsx +15 -0
- package/templates/adventure/src/ui/main.tsx +14 -0
- package/templates/adventure/tailwind.config.ts +2 -0
- package/templates/adventure/threenative.config.ts +62 -0
- package/templates/adventure/tsconfig.json +17 -0
- package/templates/adventure/vite.config.ts +49 -0
- package/templates/collectathon/.codex/config.toml +23 -0
- package/templates/collectathon/.cursor/mcp.json +38 -0
- package/templates/collectathon/.gemini/settings.json +38 -0
- package/templates/collectathon/.mcp.json +38 -0
- package/templates/collectathon/.vscode/mcp.json +43 -0
- package/templates/collectathon/.zed/settings.json +43 -0
- package/templates/collectathon/AGENTS.md +58 -0
- package/templates/collectathon/CLAUDE.md +60 -0
- package/templates/collectathon/index.html +14 -0
- package/templates/collectathon/kit.json +8 -0
- package/templates/collectathon/native-playtests/survives.playtest.json +52 -0
- package/templates/collectathon/opencode.json +49 -0
- package/templates/collectathon/package.json +65 -0
- package/templates/collectathon/playtests/acrobatics.playtest.json +238 -0
- package/templates/collectathon/playtests/camera.playtest.json +80 -0
- package/templates/collectathon/playtests/clipped-probe.playtest.json +101 -0
- package/templates/collectathon/playtests/collect.playtest.json +196 -0
- package/templates/collectathon/playtests/combat.playtest.json +246 -0
- package/templates/collectathon/playtests/double-tap-air.playtest.json +198 -0
- package/templates/collectathon/playtests/double-tap.playtest.json +136 -0
- package/templates/collectathon/playtests/effects.playtest.json +124 -0
- package/templates/collectathon/playtests/enemies.playtest.json +295 -0
- package/templates/collectathon/playtests/explore.playtest.json +45 -0
- package/templates/collectathon/playtests/hop-reach.playtest.json +117 -0
- package/templates/collectathon/playtests/jump-chain.playtest.json +274 -0
- package/templates/collectathon/playtests/ledge-angle.playtest.json +107 -0
- package/templates/collectathon/playtests/ledge-too-high.playtest.json +115 -0
- package/templates/collectathon/playtests/ledge.playtest.json +100 -0
- package/templates/collectathon/playtests/look.playtest.json +64 -0
- package/templates/collectathon/playtests/performance.playtest.json +55 -0
- package/templates/collectathon/playtests/stride.playtest.json +111 -0
- package/templates/collectathon/playtests/survives.playtest.json +123 -0
- package/templates/collectathon/playtests/telegraphs.playtest.json +132 -0
- package/templates/collectathon/playtests/thornback.playtest.json +157 -0
- package/templates/collectathon/playtests/wall-kick.playtest.json +206 -0
- package/templates/collectathon/playtests/win.playtest.json +166 -0
- package/templates/collectathon/public/favicon.svg +4 -0
- package/templates/collectathon/src/entities/Hero.ts +915 -0
- package/templates/collectathon/src/entities/Pickup.ts +63 -0
- package/templates/collectathon/src/entities/Walker.ts +248 -0
- package/templates/collectathon/src/game.ts +51 -0
- package/templates/collectathon/src/level/Course.ts +590 -0
- package/templates/collectathon/src/level/terrain.ts +144 -0
- package/templates/collectathon/src/main.ts +14 -0
- package/templates/collectathon/src/playtest-events.ts +15 -0
- package/templates/collectathon/src/render/camera.ts +163 -0
- package/templates/collectathon/src/render/castle.ts +408 -0
- package/templates/collectathon/src/render/effects.ts +284 -0
- package/templates/collectathon/src/render/foliage.ts +744 -0
- package/templates/collectathon/src/render/ground.ts +139 -0
- package/templates/collectathon/src/render/hero.ts +452 -0
- package/templates/collectathon/src/render/kitExposure.ts +20 -0
- package/templates/collectathon/src/render/lighting.ts +65 -0
- package/templates/collectathon/src/render/loading.ts +332 -0
- package/templates/collectathon/src/render/materials.ts +196 -0
- package/templates/collectathon/src/render/palette.ts +82 -0
- package/templates/collectathon/src/render/postprocessing.ts +79 -0
- package/templates/collectathon/src/render/props.ts +218 -0
- package/templates/collectathon/src/render/quality.ts +54 -0
- package/templates/collectathon/src/render/sky.ts +262 -0
- package/templates/collectathon/src/render/surface.ts +269 -0
- package/templates/collectathon/src/render/touch-controls.ts +179 -0
- package/templates/collectathon/src/render/touch-layout.ts +48 -0
- package/templates/collectathon/src/render/water.ts +191 -0
- package/templates/collectathon/src/scenes/Play.ts +481 -0
- package/templates/collectathon/src/state.ts +38 -0
- package/templates/collectathon/src/style.css +106 -0
- package/templates/collectathon/src/ui/App.tsx +22 -0
- package/templates/collectathon/src/ui/GameUi.tsx +20 -0
- package/templates/collectathon/src/ui/Hud.tsx +77 -0
- package/templates/collectathon/src/ui/Menu.tsx +13 -0
- package/templates/collectathon/src/ui/main.tsx +14 -0
- package/templates/collectathon/tailwind.config.ts +2 -0
- package/templates/collectathon/threenative.config.ts +62 -0
- package/templates/collectathon/tsconfig.json +17 -0
- package/templates/collectathon/vite.config.ts +49 -0
- package/templates/kart/.codex/config.toml +23 -0
- package/templates/kart/.cursor/mcp.json +38 -0
- package/templates/kart/.gemini/settings.json +38 -0
- package/templates/kart/.mcp.json +38 -0
- package/templates/kart/.vscode/mcp.json +43 -0
- package/templates/kart/.zed/settings.json +43 -0
- package/templates/kart/AGENTS.md +58 -0
- package/templates/kart/CLAUDE.md +60 -0
- package/templates/kart/index.html +14 -0
- package/templates/kart/kit.json +8 -0
- package/templates/kart/native-playtests/survives.playtest.json +65 -0
- package/templates/kart/opencode.json +49 -0
- package/templates/kart/package.json +64 -0
- package/templates/kart/playtests/drift.playtest.json +226 -0
- package/templates/kart/playtests/explore.playtest.json +45 -0
- package/templates/kart/playtests/hit-stays-above-road.playtest.json +92 -0
- package/templates/kart/playtests/item-key.playtest.json +108 -0
- package/templates/kart/playtests/items.playtest.json +143 -0
- package/templates/kart/playtests/lap-times.playtest.json +138 -0
- package/templates/kart/playtests/laps.playtest.json +149 -0
- package/templates/kart/playtests/performance.playtest.json +57 -0
- package/templates/kart/playtests/race.playtest.json +294 -0
- package/templates/kart/playtests/restart.playtest.json +87 -0
- package/templates/kart/playtests/rocket-start.playtest.json +56 -0
- package/templates/kart/playtests/smooth-drive.playtest.json +101 -0
- package/templates/kart/playtests/surfaces.playtest.json +113 -0
- package/templates/kart/playtests/survives.playtest.json +116 -0
- package/templates/kart/playtests/wall.playtest.json +118 -0
- package/templates/kart/public/favicon.svg +4 -0
- package/templates/kart/src/entities/Driver.ts +123 -0
- package/templates/kart/src/entities/Items.ts +194 -0
- package/templates/kart/src/entities/Kart.ts +517 -0
- package/templates/kart/src/game.ts +45 -0
- package/templates/kart/src/main.ts +14 -0
- package/templates/kart/src/playtest-events.ts +15 -0
- package/templates/kart/src/render/camera.ts +83 -0
- package/templates/kart/src/render/course.ts +579 -0
- package/templates/kart/src/render/effects.ts +266 -0
- package/templates/kart/src/render/items.ts +163 -0
- package/templates/kart/src/render/kart.ts +256 -0
- package/templates/kart/src/render/kitExposure.ts +20 -0
- package/templates/kart/src/render/lighting.ts +58 -0
- package/templates/kart/src/render/loading.ts +332 -0
- package/templates/kart/src/render/materials.ts +119 -0
- package/templates/kart/src/render/palette.ts +74 -0
- package/templates/kart/src/render/postprocessing.ts +79 -0
- package/templates/kart/src/render/quality.ts +54 -0
- package/templates/kart/src/render/skids.ts +86 -0
- package/templates/kart/src/render/sky.ts +105 -0
- package/templates/kart/src/render/touch-controls.ts +168 -0
- package/templates/kart/src/render/touch-layout.ts +48 -0
- package/templates/kart/src/scenes/Race.ts +850 -0
- package/templates/kart/src/state.ts +53 -0
- package/templates/kart/src/style.css +106 -0
- package/templates/kart/src/track/Course.ts +276 -0
- package/templates/kart/src/track/Race.ts +133 -0
- package/templates/kart/src/ui/App.tsx +21 -0
- package/templates/kart/src/ui/GameUi.tsx +20 -0
- package/templates/kart/src/ui/Hud.tsx +172 -0
- package/templates/kart/src/ui/Menu.tsx +13 -0
- package/templates/kart/src/ui/main.tsx +14 -0
- package/templates/kart/tailwind.config.ts +2 -0
- package/templates/kart/threenative.config.ts +62 -0
- package/templates/kart/tsconfig.json +17 -0
- package/templates/kart/vite.config.ts +49 -0
- package/templates/minimal/.codex/config.toml +6 -2
- package/templates/minimal/.cursor/mcp.json +8 -2
- package/templates/minimal/.gemini/settings.json +8 -2
- package/templates/minimal/.mcp.json +8 -2
- package/templates/minimal/.vscode/mcp.json +9 -2
- package/templates/minimal/.zed/settings.json +9 -2
- package/templates/minimal/AGENTS.md +11 -13
- package/templates/minimal/CLAUDE.md +11 -13
- package/templates/minimal/opencode.json +10 -2
- package/templates/minimal/package.json +16 -10
- package/templates/minimal/playtests/camera-wall.playtest.json +36 -0
- package/templates/minimal/playtests/jump.playtest.json +45 -0
- package/templates/minimal/playtests/play.playtest.json +1 -1
- package/templates/minimal/src/game.ts +2 -0
- package/templates/minimal/src/render/atmosphere.ts +444 -0
- package/templates/minimal/src/render/backlightMaterial.ts +49 -18
- package/templates/minimal/src/render/camera.ts +35 -4
- package/templates/minimal/src/render/clouds.ts +605 -0
- package/templates/minimal/src/render/exposure.ts +7 -111
- package/templates/minimal/src/render/gpuSky.ts +752 -0
- package/templates/minimal/src/render/lighting.ts +26 -4
- package/templates/minimal/src/render/materialLighting.ts +2 -10
- package/templates/minimal/src/render/postprocessing.ts +4 -4
- package/templates/minimal/src/render/quality.ts +10 -116
- package/templates/minimal/src/render/sky.ts +73 -1
- package/templates/minimal/src/scenes/Play.ts +18 -7
- package/templates/platformer/.codex/config.toml +6 -2
- package/templates/platformer/.cursor/mcp.json +8 -2
- package/templates/platformer/.gemini/settings.json +8 -2
- package/templates/platformer/.mcp.json +8 -2
- package/templates/platformer/.vscode/mcp.json +9 -2
- package/templates/platformer/.zed/settings.json +9 -2
- package/templates/platformer/AGENTS.md +13 -9
- package/templates/platformer/CLAUDE.md +13 -9
- package/templates/platformer/opencode.json +10 -2
- package/templates/platformer/package.json +17 -11
- package/templates/platformer/playtests/dash-jump.playtest.json +34 -0
- package/templates/platformer/playtests/finish.playtest.json +58 -0
- package/templates/platformer/playtests/idle.playtest.json +44 -0
- package/templates/platformer/playtests/performance.playtest.json +1 -1
- package/templates/platformer/src/entities/Fox.ts +19 -6
- package/templates/platformer/src/game.ts +1 -0
- package/templates/platformer/src/level/Stage.ts +4 -1
- package/templates/platformer/src/render/backlightMaterial.ts +49 -18
- package/templates/platformer/src/render/camera.ts +30 -1
- package/templates/platformer/src/render/exposure.ts +6 -111
- package/templates/platformer/src/render/fox.ts +5 -2
- package/templates/platformer/src/render/kitExposure.ts +20 -0
- package/templates/platformer/src/render/materialLighting.ts +2 -11
- package/templates/platformer/src/render/postprocessing.ts +4 -4
- package/templates/platformer/src/render/props.ts +1 -2
- package/templates/platformer/src/render/quality.ts +10 -118
- package/templates/platformer/src/scenes/Play.ts +31 -15
- package/templates/platformer/src/ui/Menu.tsx +1 -1
- package/templates/puzzle/.codex/config.toml +6 -2
- package/templates/puzzle/.cursor/mcp.json +8 -2
- package/templates/puzzle/.gemini/settings.json +8 -2
- package/templates/puzzle/.mcp.json +8 -2
- package/templates/puzzle/.vscode/mcp.json +9 -2
- package/templates/puzzle/.zed/settings.json +9 -2
- package/templates/puzzle/AGENTS.md +14 -17
- package/templates/puzzle/CLAUDE.md +14 -17
- package/templates/puzzle/opencode.json +10 -2
- package/templates/puzzle/package.json +17 -11
- package/templates/puzzle/playtests/performance.playtest.json +1 -1
- package/templates/puzzle/playtests/replay-keeps-progress.playtest.json +78 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +49 -18
- package/templates/puzzle/src/render/exposure.ts +11 -109
- package/templates/puzzle/src/render/lighting.ts +3 -3
- package/templates/puzzle/src/render/materialLighting.ts +2 -11
- package/templates/puzzle/src/render/palette.ts +1 -1
- package/templates/puzzle/src/render/postprocessing.ts +4 -4
- package/templates/puzzle/src/render/quality.ts +44 -153
- package/templates/puzzle/src/render/vault.ts +18 -6
- package/templates/puzzle/src/scenes/Play.ts +6 -1
- package/templates/puzzle/src/ui/Hud.tsx +8 -43
- package/templates/racing/.codex/config.toml +6 -2
- package/templates/racing/.cursor/mcp.json +8 -2
- package/templates/racing/.gemini/settings.json +8 -2
- package/templates/racing/.mcp.json +8 -2
- package/templates/racing/.vscode/mcp.json +9 -2
- package/templates/racing/.zed/settings.json +9 -2
- package/templates/racing/AGENTS.md +10 -12
- package/templates/racing/CLAUDE.md +10 -12
- package/templates/racing/opencode.json +10 -2
- package/templates/racing/package.json +17 -11
- package/templates/racing/playtests/brake.playtest.json +54 -0
- package/templates/racing/playtests/outcome.playtest.json +19 -0
- package/templates/racing/playtests/performance.playtest.json +1 -1
- package/templates/racing/playtests/stopped-car-is-not-rescued.playtest.json +59 -0
- package/templates/racing/src/entities/RacingCar.ts +12 -3
- package/templates/racing/src/entities/Rival.ts +11 -2
- package/templates/racing/src/render/atmosphere.ts +444 -0
- package/templates/racing/src/render/backlightMaterial.ts +49 -18
- package/templates/racing/src/render/clouds.ts +605 -0
- package/templates/racing/src/render/exposure.ts +6 -111
- package/templates/racing/src/render/gpuSky.ts +752 -0
- package/templates/racing/src/render/kitExposure.ts +20 -0
- package/templates/racing/src/render/lighting.ts +26 -4
- package/templates/racing/src/render/materialLighting.ts +2 -11
- package/templates/racing/src/render/materials.ts +2 -1
- package/templates/racing/src/render/postprocessing.ts +4 -4
- package/templates/racing/src/render/quality.ts +27 -115
- package/templates/racing/src/render/sky.ts +76 -5
- package/templates/racing/src/scenes/Race.ts +53 -42
- package/templates/racing/src/track/TrackSector.ts +5 -2
- package/templates/racing/src/ui/Hud.tsx +12 -7
- package/templates/rain/.codex/config.toml +6 -2
- package/templates/rain/.cursor/mcp.json +8 -2
- package/templates/rain/.gemini/settings.json +8 -2
- package/templates/rain/.mcp.json +8 -2
- package/templates/rain/.vscode/mcp.json +9 -2
- package/templates/rain/.zed/settings.json +9 -2
- package/templates/rain/AGENTS.md +12 -12
- package/templates/rain/CLAUDE.md +12 -12
- package/templates/rain/opencode.json +10 -2
- package/templates/rain/package.json +16 -10
- package/templates/rain/playtests/performance.playtest.json +1 -1
- package/templates/rain/src/game.ts +1 -1
- package/templates/rain/src/render/bloom-shader.ts +1 -1
- package/templates/rain/src/render/clouds-shader.ts +2 -2
- package/templates/rain/src/render/clouds.ts +2 -1
- package/templates/rain/src/render/exposure.ts +11 -109
- package/templates/rain/src/render/post-shader.ts +7 -11
- package/templates/rain/src/render/postprocessing.ts +8 -24
- package/templates/rain/src/render/quality.ts +44 -98
- package/templates/rain/src/render/world-shader.ts +281 -97
- package/templates/rain/src/render/world.ts +82 -2
- package/templates/rain/src/style.css +1 -1
- package/templates/rain/src/ui/GameUi.tsx +6 -2
- package/templates/rain/src/ui/Hud.tsx +1 -1
- package/templates/rain/tools/generate-shaders.mjs +2 -2
- package/templates/rain/tools/tempest-post.frag +4 -6
- package/templates/rain/tools/tempest-world.frag +80 -12
- package/templates/rts/.codex/config.toml +6 -2
- package/templates/rts/.cursor/mcp.json +8 -2
- package/templates/rts/.gemini/settings.json +8 -2
- package/templates/rts/.mcp.json +8 -2
- package/templates/rts/.vscode/mcp.json +9 -2
- package/templates/rts/.zed/settings.json +9 -2
- package/templates/rts/AGENTS.md +15 -16
- package/templates/rts/CLAUDE.md +15 -16
- package/templates/rts/opencode.json +10 -2
- package/templates/rts/package.json +16 -10
- package/templates/rts/playtests/performance.playtest.json +1 -1
- package/templates/rts/playtests/rts-attack.playtest.json +5 -0
- package/templates/rts/playtests/rts-build.playtest.json +20 -1
- package/templates/rts/playtests/rts-orders.playtest.json +1 -1
- package/templates/rts/playtests/rts-pause.playtest.json +112 -0
- package/templates/rts/playtests/rts-train.playtest.json +1 -1
- package/templates/rts/playtests/rts-zoom.playtest.json +81 -0
- package/templates/rts/src/game.ts +29 -7
- package/templates/rts/src/render/army.ts +181 -49
- package/templates/rts/src/render/backlightMaterial.ts +49 -18
- package/templates/rts/src/render/environment.ts +276 -0
- package/templates/rts/src/render/exposure.ts +3 -65
- package/templates/rts/src/render/ground.ts +478 -0
- package/templates/rts/src/render/lighting.ts +62 -11
- package/templates/rts/src/render/materialLighting.ts +2 -11
- package/templates/rts/src/render/materials.ts +47 -118
- package/templates/rts/src/render/palette.ts +30 -13
- package/templates/rts/src/render/picking.ts +18 -0
- package/templates/rts/src/render/postprocessing.ts +4 -4
- package/templates/rts/src/render/quality.ts +64 -85
- package/templates/rts/src/render/resources.ts +21 -22
- package/templates/rts/src/render/sky.ts +9 -12
- package/templates/rts/src/render/terrain.ts +36 -11
- package/templates/rts/src/scenes/Play.ts +373 -38
- package/templates/rts/src/sim/ai.ts +0 -11
- package/templates/rts/src/state.ts +46 -0
- package/templates/rts/src/style.css +1543 -0
- package/templates/rts/src/ui/Commands.tsx +204 -107
- package/templates/rts/src/ui/GameUi.tsx +12 -5
- package/templates/rts/src/ui/Hud.tsx +611 -116
- package/templates/rts/src/ui/Minimap.tsx +103 -37
- package/templates/rts/src/ui/icons.tsx +116 -0
- package/templates/rts/src/ui/labels.ts +73 -0
- package/templates/rts/src/ui/minimapPoint.ts +30 -0
- package/templates/rts/threenative.config.ts +1 -1
- package/templates/runner/.codex/config.toml +6 -2
- package/templates/runner/.cursor/mcp.json +8 -2
- package/templates/runner/.gemini/settings.json +8 -2
- package/templates/runner/.mcp.json +8 -2
- package/templates/runner/.vscode/mcp.json +9 -2
- package/templates/runner/.zed/settings.json +9 -2
- package/templates/runner/AGENTS.md +12 -12
- package/templates/runner/CLAUDE.md +12 -12
- package/templates/runner/opencode.json +10 -2
- package/templates/runner/package.json +17 -11
- package/templates/runner/playtests/near-miss.playtest.json +48 -0
- package/templates/runner/playtests/performance.playtest.json +2 -2
- package/templates/runner/playtests/stride.playtest.json +27 -0
- package/templates/runner/playtests/survives.playtest.json +2 -2
- package/templates/runner/src/conventions.ts +3 -1
- package/templates/runner/src/entities/Runner.ts +11 -5
- package/templates/runner/src/render/atmosphere.ts +444 -0
- package/templates/runner/src/render/backlightMaterial.ts +49 -18
- package/templates/runner/src/render/clouds.ts +605 -0
- package/templates/runner/src/render/exposure.ts +6 -111
- package/templates/runner/src/render/gpuSky.ts +752 -0
- package/templates/runner/src/render/kitExposure.ts +20 -0
- package/templates/runner/src/render/lighting.ts +26 -4
- package/templates/runner/src/render/materialLighting.ts +2 -11
- package/templates/runner/src/render/postprocessing.ts +4 -4
- package/templates/runner/src/render/quality.ts +26 -114
- package/templates/runner/src/render/sky.ts +73 -1
- package/templates/runner/src/scenes/Run.ts +19 -15
- package/templates/runner/src/track.ts +12 -3
- package/templates/sailing/.codex/config.toml +6 -2
- package/templates/sailing/.cursor/mcp.json +8 -2
- package/templates/sailing/.gemini/settings.json +8 -2
- package/templates/sailing/.mcp.json +8 -2
- package/templates/sailing/.vscode/mcp.json +9 -2
- package/templates/sailing/.zed/settings.json +9 -2
- package/templates/sailing/AGENTS.md +10 -11
- package/templates/sailing/CLAUDE.md +10 -11
- package/templates/sailing/opencode.json +10 -2
- package/templates/sailing/package.json +17 -11
- package/templates/sailing/playtests/fail.playtest.json +46 -5
- package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +7 -0
- package/templates/sailing/playtests/performance.playtest.json +1 -1
- package/templates/sailing/src/game.ts +1 -0
- package/templates/sailing/src/render/backlightMaterial.ts +49 -18
- package/templates/sailing/src/render/exposure.ts +6 -111
- package/templates/sailing/src/render/kitExposure.ts +20 -0
- package/templates/sailing/src/render/materialLighting.ts +2 -11
- package/templates/sailing/src/render/ocean.ts +0 -1
- package/templates/sailing/src/render/postprocessing.ts +4 -4
- package/templates/sailing/src/render/quality.ts +31 -138
- package/templates/sailing/src/scenes/Sailing.ts +12 -4
- package/templates/sailing/src/ui/Hud.tsx +6 -2
- package/templates/sailing/src/ui/Menu.tsx +1 -1
- package/templates/shooter/.codex/config.toml +6 -2
- package/templates/shooter/.cursor/mcp.json +8 -2
- package/templates/shooter/.gemini/settings.json +8 -2
- package/templates/shooter/.mcp.json +8 -2
- package/templates/shooter/.vscode/mcp.json +9 -2
- package/templates/shooter/.zed/settings.json +9 -2
- package/templates/shooter/AGENTS.md +13 -12
- package/templates/shooter/CLAUDE.md +13 -12
- package/templates/shooter/index.html +1 -1
- package/templates/shooter/main.html +13 -0
- package/templates/shooter/opencode.json +10 -2
- package/templates/shooter/package.json +17 -11
- package/templates/shooter/playtests/breakable-shatters.playtest.json +6 -0
- package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +6 -0
- package/templates/shooter/playtests/hands-authored-rate.playtest.json +54 -0
- package/templates/shooter/playtests/movement-eases.playtest.json +53 -0
- package/templates/shooter/playtests/performance.playtest.json +3 -3
- package/templates/shooter/playtests/stairs-smooth-the-eye.playtest.json +56 -0
- package/templates/shooter/playtests/weapon-sharp-while-turning.playtest.json +206 -0
- package/templates/shooter/src/entities/Breakables.ts +34 -10
- package/templates/shooter/src/entities/Enemy.ts +176 -54
- package/templates/shooter/src/entities/FpsPlayer.ts +55 -16
- package/templates/shooter/src/entities/Rifle.ts +83 -9
- package/templates/shooter/src/entities/movement.ts +96 -0
- package/templates/shooter/src/render/atmosphere.ts +444 -0
- package/templates/shooter/src/render/backlightMaterial.ts +49 -18
- package/templates/shooter/src/render/camera.ts +3 -1
- package/templates/shooter/src/render/clouds.ts +605 -0
- package/templates/shooter/src/render/exposure.ts +10 -109
- package/templates/shooter/src/render/facade.ts +26 -68
- package/templates/shooter/src/render/gpuSky.ts +752 -0
- package/templates/shooter/src/render/lighting.ts +27 -4
- package/templates/shooter/src/render/materialAssignments.ts +9 -1
- package/templates/shooter/src/render/materialLighting.ts +2 -11
- package/templates/shooter/src/render/occlusion.ts +13 -4
- package/templates/shooter/src/render/palette.ts +1 -0
- package/templates/shooter/src/render/postprocessing.ts +4 -4
- package/templates/shooter/src/render/quality.ts +50 -108
- package/templates/shooter/src/render/scale.ts +0 -11
- package/templates/shooter/src/render/sky.ts +103 -2
- package/templates/shooter/src/render/surface.ts +140 -0
- package/templates/shooter/src/render/town.ts +3 -6
- package/templates/shooter/src/render/townMaterials.ts +95 -42
- package/templates/shooter/src/render/vehicles.ts +2 -0
- package/templates/shooter/src/scenes/Play.ts +83 -23
- package/templates/shooter/src/ui/Hud.tsx +268 -193
- package/templates/shooter/src/worker-page.ts +29 -0
- package/templates/shooter/src/worker.ts +5 -0
- package/templates/shooter/threenative.config.ts +3 -0
- package/templates/shooter/vite.config.ts +2 -0
- package/templates/snow/.codex/config.toml +6 -2
- package/templates/snow/.cursor/mcp.json +8 -2
- package/templates/snow/.gemini/settings.json +8 -2
- package/templates/snow/.mcp.json +8 -2
- package/templates/snow/.vscode/mcp.json +9 -2
- package/templates/snow/.zed/settings.json +9 -2
- package/templates/snow/AGENTS.md +12 -10
- package/templates/snow/CLAUDE.md +12 -10
- package/templates/snow/opencode.json +10 -2
- package/templates/snow/package.json +17 -11
- package/templates/snow/playtests/performance.playtest.json +1 -1
- package/templates/snow/src/render/backlightMaterial.ts +49 -18
- package/templates/snow/src/render/exposure.ts +17 -106
- package/templates/snow/src/render/materialLighting.ts +2 -11
- package/templates/snow/src/render/postprocessing.ts +11 -5
- package/templates/snow/src/render/quality.ts +46 -126
- package/templates/snow/src/render/snowSurface.ts +32 -15
- package/templates/snow/src/scenes/Snow.ts +2 -1
- package/templates/starter/.codex/config.toml +6 -2
- package/templates/starter/.cursor/mcp.json +8 -2
- package/templates/starter/.gemini/settings.json +8 -2
- package/templates/starter/.mcp.json +8 -2
- package/templates/starter/.vscode/mcp.json +9 -2
- package/templates/starter/.zed/settings.json +9 -2
- package/templates/starter/AGENTS.md +18 -14
- package/templates/starter/CLAUDE.md +18 -14
- package/templates/starter/index.html +1 -1
- package/templates/starter/main.html +12 -0
- package/templates/starter/native-playtests/react-hud.playtest.json +1 -0
- package/templates/starter/native-playtests/render-chain.playtest.json +34 -21
- package/templates/starter/opencode.json +10 -2
- package/templates/starter/package.json +17 -11
- package/templates/starter/playtests/play.playtest.json +22 -2
- package/templates/starter/playtests/production-readiness.playtest.json +56 -0
- package/templates/starter/src/entities/Crate.ts +19 -1
- package/templates/starter/src/render/arena.ts +2 -2
- package/templates/starter/src/render/atmosphere.ts +444 -0
- package/templates/starter/src/render/backlightMaterial.ts +49 -18
- package/templates/starter/src/render/camera.ts +28 -0
- package/templates/starter/src/render/clouds.ts +605 -0
- package/templates/starter/src/render/contactShadow.ts +50 -0
- package/templates/starter/src/render/exposure.ts +9 -111
- package/templates/starter/src/render/gpuSky.ts +752 -0
- package/templates/starter/src/render/grade.ts +1 -1
- package/templates/starter/src/render/lighting.ts +34 -6
- package/templates/starter/src/render/materialLighting.ts +2 -11
- package/templates/starter/src/render/postprocessing.ts +53 -34
- package/templates/starter/src/render/quality.ts +18 -147
- package/templates/starter/src/render/sky.ts +90 -40
- package/templates/starter/src/render/temporalAA.ts +1 -1
- package/templates/starter/src/render/temporalAAStage.ts +1 -1
- package/templates/starter/src/render/temporalCurrentFootprint.ts +0 -1
- package/templates/starter/src/render/temporalDetailStage.ts +106 -0
- package/templates/starter/src/render/temporalRejectionCounter.ts +2 -2
- package/templates/starter/src/render/volumetricFogCamera.ts +32 -0
- package/templates/starter/src/render/volumetricFogOptions.ts +7 -0
- package/templates/starter/src/render/volumetricFogTransport.ts +27 -19
- package/templates/starter/src/render/volumetricFogVolume.ts +31 -7
- package/templates/starter/src/scenes/Play.ts +11 -8
- package/templates/starter/src/ui/Hud.tsx +1 -1
- package/templates/starter/src/worker-page.ts +29 -0
- package/templates/starter/src/worker.ts +5 -0
- package/templates/starter/vite.config.ts +2 -0
- package/templates/tower-defense/.codex/config.toml +6 -2
- package/templates/tower-defense/.cursor/mcp.json +8 -2
- package/templates/tower-defense/.gemini/settings.json +8 -2
- package/templates/tower-defense/.mcp.json +8 -2
- package/templates/tower-defense/.vscode/mcp.json +9 -2
- package/templates/tower-defense/.zed/settings.json +9 -2
- package/templates/tower-defense/AGENTS.md +10 -12
- package/templates/tower-defense/CLAUDE.md +10 -12
- package/templates/tower-defense/opencode.json +10 -2
- package/templates/tower-defense/package.json +17 -11
- package/templates/tower-defense/playtests/chill-tint.playtest.json +387 -0
- package/templates/tower-defense/playtests/performance.playtest.json +1 -1
- package/templates/tower-defense/src/enemies/Enemy.ts +9 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +49 -18
- package/templates/tower-defense/src/render/exposure.ts +11 -109
- package/templates/tower-defense/src/render/lighting.ts +4 -2
- package/templates/tower-defense/src/render/materialLighting.ts +2 -11
- package/templates/tower-defense/src/render/postprocessing.ts +4 -4
- package/templates/tower-defense/src/render/quality.ts +10 -116
- package/templates/tower-defense/src/render/sky.ts +2 -2
- package/templates/tower-defense/src/scenes/Battle.ts +4 -0
- package/template-assets/autoExposure.ts +0 -225
- package/template-assets/exposureGraph.ts +0 -178
- package/template-assets/exposureReadback.ts +0 -79
- package/template-assets/worldEnvironment.ts +0 -1212
- package/templates/action-rpg/src/render/autoExposure.ts +0 -225
- package/templates/action-rpg/src/render/exposureGraph.ts +0 -178
- package/templates/action-rpg/src/render/exposureReadback.ts +0 -79
- package/templates/action-rpg/src/render/worldEnvironment.ts +0 -1212
- package/templates/minimal/src/render/autoExposure.ts +0 -225
- package/templates/minimal/src/render/exposureGraph.ts +0 -178
- package/templates/minimal/src/render/exposureReadback.ts +0 -79
- package/templates/minimal/src/render/worldEnvironment.ts +0 -1212
- package/templates/platformer/src/render/autoExposure.ts +0 -225
- package/templates/platformer/src/render/exposureGraph.ts +0 -178
- package/templates/platformer/src/render/exposureReadback.ts +0 -79
- package/templates/platformer/src/render/worldEnvironment.ts +0 -1212
- package/templates/puzzle/src/render/autoExposure.ts +0 -225
- package/templates/puzzle/src/render/exposureGraph.ts +0 -178
- package/templates/puzzle/src/render/exposureReadback.ts +0 -79
- package/templates/puzzle/src/render/worldEnvironment.ts +0 -1212
- package/templates/racing/src/render/autoExposure.ts +0 -225
- package/templates/racing/src/render/exposureGraph.ts +0 -178
- package/templates/racing/src/render/exposureReadback.ts +0 -79
- package/templates/racing/src/render/worldEnvironment.ts +0 -1212
- package/templates/rain/src/render/autoExposure.ts +0 -225
- package/templates/rain/src/render/exposureGraph.ts +0 -178
- package/templates/rain/src/render/exposureReadback.ts +0 -79
- package/templates/rain/src/render/worldEnvironment.ts +0 -1212
- package/templates/rts/src/render/autoExposure.ts +0 -225
- package/templates/rts/src/render/exposureGraph.ts +0 -178
- package/templates/rts/src/render/exposureReadback.ts +0 -79
- package/templates/rts/src/render/worldEnvironment.ts +0 -1212
- package/templates/runner/src/render/autoExposure.ts +0 -225
- package/templates/runner/src/render/exposureGraph.ts +0 -178
- package/templates/runner/src/render/exposureReadback.ts +0 -79
- package/templates/runner/src/render/worldEnvironment.ts +0 -1212
- package/templates/sailing/src/render/autoExposure.ts +0 -225
- package/templates/sailing/src/render/exposureGraph.ts +0 -178
- package/templates/sailing/src/render/exposureReadback.ts +0 -79
- package/templates/sailing/src/render/worldEnvironment.ts +0 -1212
- package/templates/shooter/src/render/autoExposure.ts +0 -225
- package/templates/shooter/src/render/exposureGraph.ts +0 -178
- package/templates/shooter/src/render/exposureReadback.ts +0 -79
- package/templates/shooter/src/render/worldEnvironment.ts +0 -1212
- package/templates/snow/src/render/autoExposure.ts +0 -225
- package/templates/snow/src/render/exposureGraph.ts +0 -178
- package/templates/snow/src/render/exposureReadback.ts +0 -79
- package/templates/snow/src/render/worldEnvironment.ts +0 -1212
- package/templates/starter/src/render/autoExposure.ts +0 -225
- package/templates/starter/src/render/exposureGraph.ts +0 -178
- package/templates/starter/src/render/exposureReadback.ts +0 -79
- package/templates/starter/src/render/worldEnvironment.ts +0 -1212
- package/templates/tower-defense/src/render/autoExposure.ts +0 -225
- package/templates/tower-defense/src/render/exposureGraph.ts +0 -178
- package/templates/tower-defense/src/render/exposureReadback.ts +0 -79
- package/templates/tower-defense/src/render/worldEnvironment.ts +0 -1212
|
@@ -417,6 +417,21 @@ if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
|
|
|
417
417
|
|
|
418
418
|
## `@threenative/core`
|
|
419
419
|
|
|
420
|
+
### `addFoliageBackLight`
|
|
421
|
+
|
|
422
|
+
`function` — Adds subsurfaceColor times the far-face irradiance to a Two Sided Foliage leaf's emissive node.
|
|
423
|
+
|
|
424
|
+
```ts
|
|
425
|
+
export function addFoliageBackLight(material: Material, backIrradiance: Node<"vec3">): boolean { … }
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
- **Use when:** add bounce light to the far face of a two sided foliage leaf
|
|
429
|
+
- **Constraints:** the material needs the foliage marker and subsurfaceColor, else nothing is added and false is returned; call once per material · the material needs `twoSidedFoliage = true` and a `subsurfaceColor`, or nothing is added and false is returned; backIrradiance is a vec3 node in the unit of `irradianceNode`; call once per material
|
|
430
|
+
|
|
431
|
+
```ts
|
|
432
|
+
addFoliageBackLight(leaf, backIrradiance);
|
|
433
|
+
```
|
|
434
|
+
|
|
420
435
|
### `addInSlices`
|
|
421
436
|
|
|
422
437
|
`function` — Attach hundreds of built objects to the scene in slices, presenting a frame between each.
|
|
@@ -549,15 +564,15 @@ animation.setWeights([0.5, 0.5]); animation.update(dt);
|
|
|
549
564
|
|
|
550
565
|
### `AnimationPlayer`
|
|
551
566
|
|
|
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.
|
|
567
|
+
`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. A mesh counts at its lowest geometry point, so a boot's origin may sit anywhere; an in-place clip with no foot plant reports `inPlace: true` and `clipGroundSpeed: 0`, and stride sync stays off. Evaluation is automatic by default: `updateRate: "auto"` follows measured camera visibility and projected size. `updateRate: 1` evaluates every frame; another positive safe integer names that frame interval. `updateRateReport` reports the effective rate, whether a named override is active, and whether the latest update evaluated. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"` listener promotes the player to full-rate and observes only loop events after registration, so skipped pre-registration cycles are not replayed; `updateRateReport` reports that effective rate.
|
|
553
568
|
|
|
554
569
|
```ts
|
|
555
570
|
export class AnimationPlayer { … }
|
|
556
571
|
```
|
|
557
572
|
|
|
558
|
-
- **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving · match an in-place walk cycle with no root motion to the body's speed · find out what speed an animation clip was authored for
|
|
559
|
-
- **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only · the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so
|
|
560
|
-
- **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured
|
|
573
|
+
- **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving · match an in-place walk cycle with no root motion to the body's speed · find out what speed an animation clip was authored for · reduce animation CPU for distant characters · inspect the effective animation evaluation rate
|
|
574
|
+
- **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only · a foot mesh is measured at its lowest geometry point (the sole), never its origin; a skinned mesh is measured through its bones · `stride.inPlace: true` with `clipGroundSpeed: 0` means no foot plant was found and stride sync is not active; the playtest `stride` observation carries `inPlace` · the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so
|
|
575
|
+
- **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured · updateRate: "auto" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `"loop"` listener promotes effective evaluation to 1 to preserve event timing
|
|
561
576
|
|
|
562
577
|
```ts
|
|
563
578
|
const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
|
|
@@ -642,6 +657,22 @@ export class AudioBus { … }
|
|
|
642
657
|
const effects = new AudioBus({ camera });
|
|
643
658
|
```
|
|
644
659
|
|
|
660
|
+
### `AutoExposureNode`
|
|
661
|
+
|
|
662
|
+
`class` — Auto exposure with Unreal 5.8.3's metering: a 64-bin histogram of log2 luminance (the darkest and brightest 10% ignored), key 0.18 x 2, -10 to +20 EV100, 3 stops/s brighter and 1 stop/s darker. `AutoExposureNode` meters a colour texture and outputs the adapted exposure; `exposureSettings` holds the defaults.
|
|
663
|
+
|
|
664
|
+
```ts
|
|
665
|
+
export class AutoExposureNode extends TempNode<"float"> { … }
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
- **Use when:** the frame should expose itself the way a fresh Unreal project does as the sun and the view change · a white snowfield or a bright storm should not meter to middle grey, and the compensation changes with the weather
|
|
669
|
+
- **Constraints:** WebGPU renderers only: a renderer without WebGPU keeps the fixed exposure and says so
|
|
670
|
+
- **Overrides:** every `IExposureSettings` field, spread over `exposureSettings` and passed to `AutoExposureNode`, replaces the Unreal default · `setExposureBias(stops)` is Unreal's Exposure Compensation, live: the game changes it per place or weather (`WorldEnvironment.apply` returns the node as `exposure`)
|
|
671
|
+
|
|
672
|
+
```ts
|
|
673
|
+
const slow = { ...exposureSettings, rateDown: 0.5 }; const node = new AutoExposureNode(input, slow, 1);
|
|
674
|
+
```
|
|
675
|
+
|
|
645
676
|
### `baseGeometryOf`
|
|
646
677
|
|
|
647
678
|
`function` — The full-detail geometry of a mesh the loader gave an automatic LOD chain. Selection swaps `mesh.geometry`, so a ray test or a collision body built from the current geometry would change with the camera. Framework picking and gameplay collide against this instead: the authored LOD0, which never changes as the camera moves.
|
|
@@ -766,6 +797,22 @@ import { boneLengths } from "@threenative/core";
|
|
|
766
797
|
const baseline = boneLengths(character);
|
|
767
798
|
```
|
|
768
799
|
|
|
800
|
+
### `BudgetLadder`
|
|
801
|
+
|
|
802
|
+
`class` — A cost ladder for one render stage: the whole GPU frame against the frame period moves it, by Unreal's DynamicRenderScaling rule. A frame over the period for 2 frames in a row steps the level down at once, a frame over the period less 10% headroom steps it down after the 8-frame change period, and a frame with room steps it up. A stage steps only when it could absorb the overage at zero cost, and a level that failed is retried after a growing wait. It decides when to move; the game applies the move.
|
|
803
|
+
|
|
804
|
+
```ts
|
|
805
|
+
export class BudgetLadder<L extends string> { … }
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
- **Use when:** step a render stage down when the GPU frame goes over the frame period · pick a quality level from measured GPU time without oscillating
|
|
809
|
+
- **Constraints:** levels are listed cheapest first, and the frame period is the game's own display target · a frame without a resolved GPU reading never moves the level
|
|
810
|
+
- **Overrides:** explicit: true keeps the level and only reports a frame over the target
|
|
811
|
+
|
|
812
|
+
```ts
|
|
813
|
+
const ladder = new BudgetLadder({ levels: ["low", "high"], framePeriodMs: 1000 / 60, start: "high" }); const window = ladder.observe(stageMs, frameMs);
|
|
814
|
+
```
|
|
815
|
+
|
|
769
816
|
### `bvhIntersectFirstHit`
|
|
770
817
|
|
|
771
818
|
`function` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
|
|
@@ -950,8 +997,9 @@ const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
|
|
|
950
997
|
export function createAssetLoader(options: IAssetLoaderOptions = { … }
|
|
951
998
|
```
|
|
952
999
|
|
|
953
|
-
- **Use when:** preload models, textures, or audio before a scene enters · load assets from a nonstandard base path or a compiled asset manifest
|
|
954
|
-
- **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
|
|
1000
|
+
- **Use when:** preload models, textures, or audio before a scene enters · keep downloaded web assets on disk between visits · download the next scene before the player gets there · free the disk cache from a settings menu · prefetch assets into the Cache Storage disk cache of a large web game · load assets from a nonstandard base path or a compiled asset manifest
|
|
1001
|
+
- **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches · await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world · web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once
|
|
1002
|
+
- **Overrides:** `assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`
|
|
955
1003
|
|
|
956
1004
|
```ts
|
|
957
1005
|
const assets = createAssetLoader({ basePath: "/assets" });
|
|
@@ -1056,7 +1104,7 @@ const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes
|
|
|
1056
1104
|
|
|
1057
1105
|
### `describeSceneShape`
|
|
1058
1106
|
|
|
1059
|
-
`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.
|
|
1107
|
+
`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 in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1060
1108
|
|
|
1061
1109
|
```ts
|
|
1062
1110
|
export function describeSceneShape( window: IFrameBudgetWindow, cull: IRenderCameraCullReport | undefined, ): ISceneShape | undefined { … }
|
|
@@ -1071,7 +1119,7 @@ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
|
1071
1119
|
|
|
1072
1120
|
### `describeSceneWarning`
|
|
1073
1121
|
|
|
1074
|
-
`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.
|
|
1122
|
+
`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 in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1075
1123
|
|
|
1076
1124
|
```ts
|
|
1077
1125
|
export function describeSceneWarning(warning: ISceneWarning): string { … }
|
|
@@ -1116,7 +1164,7 @@ const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
|
|
|
1116
1164
|
|
|
1117
1165
|
### `displayPeriodMs`
|
|
1118
1166
|
|
|
1119
|
-
`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.
|
|
1167
|
+
`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 in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1120
1168
|
|
|
1121
1169
|
```ts
|
|
1122
1170
|
export function displayPeriodMs( declaredTargetFps: number | undefined, ): { … }
|
|
@@ -1165,6 +1213,51 @@ renderer.render(scene, camera);
|
|
|
1165
1213
|
tracker.commit(scene);
|
|
1166
1214
|
```
|
|
1167
1215
|
|
|
1216
|
+
### `ev100FromCamera`
|
|
1217
|
+
|
|
1218
|
+
`function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
|
|
1219
|
+
|
|
1220
|
+
```ts
|
|
1221
|
+
export function ev100FromCamera(aperture: number, shutterSeconds: number, iso: number): number { … }
|
|
1222
|
+
```
|
|
1223
|
+
|
|
1224
|
+
- **Use when:** expose a frame lit in lux and nits with a physical camera exposure value · expose like a camera with an aperture, a shutter time and an ISO
|
|
1225
|
+
- **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · every argument must be finite and greater than zero
|
|
1226
|
+
|
|
1227
|
+
```ts
|
|
1228
|
+
renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
|
|
1229
|
+
```
|
|
1230
|
+
|
|
1231
|
+
### `ev100FromExposure`
|
|
1232
|
+
|
|
1233
|
+
`function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
|
|
1234
|
+
|
|
1235
|
+
```ts
|
|
1236
|
+
export function ev100FromExposure(multiplier: number): number { … }
|
|
1237
|
+
```
|
|
1238
|
+
|
|
1239
|
+
- **Use when:** expose a frame lit in lux and nits with a physical camera exposure value · report a hand-set exposure multiplier as an EV100
|
|
1240
|
+
- **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · multiplier must be finite and greater than zero
|
|
1241
|
+
|
|
1242
|
+
```ts
|
|
1243
|
+
renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
|
|
1244
|
+
```
|
|
1245
|
+
|
|
1246
|
+
### `ev100FromLuminance`
|
|
1247
|
+
|
|
1248
|
+
`function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
|
|
1249
|
+
|
|
1250
|
+
```ts
|
|
1251
|
+
export function ev100FromLuminance(luminance: number): number { … }
|
|
1252
|
+
```
|
|
1253
|
+
|
|
1254
|
+
- **Use when:** expose a frame lit in lux and nits with a physical camera exposure value · meter a frame's average luminance in cd/m² into an exposure value
|
|
1255
|
+
- **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · luminance must be finite and greater than zero
|
|
1256
|
+
|
|
1257
|
+
```ts
|
|
1258
|
+
renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
|
|
1259
|
+
```
|
|
1260
|
+
|
|
1168
1261
|
### `exposeDebug`
|
|
1169
1262
|
|
|
1170
1263
|
`function` — Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
|
|
@@ -1182,6 +1275,21 @@ exposeDebug("player", player);
|
|
|
1182
1275
|
// then from the console: __THREENATIVE__.debug.player
|
|
1183
1276
|
```
|
|
1184
1277
|
|
|
1278
|
+
### `exposureFromEv100`
|
|
1279
|
+
|
|
1280
|
+
`function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
|
|
1281
|
+
|
|
1282
|
+
```ts
|
|
1283
|
+
export function exposureFromEv100(ev100: number): number { … }
|
|
1284
|
+
```
|
|
1285
|
+
|
|
1286
|
+
- **Use when:** expose a frame lit in lux and nits with a physical camera exposure value
|
|
1287
|
+
- **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · ev100 must be finite; a unitless scene keeps its own multiplier instead
|
|
1288
|
+
|
|
1289
|
+
```ts
|
|
1290
|
+
renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
|
|
1291
|
+
```
|
|
1292
|
+
|
|
1185
1293
|
### `FlightModel`
|
|
1186
1294
|
|
|
1187
1295
|
`class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
@@ -1236,7 +1344,7 @@ water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
|
|
|
1236
1344
|
|
|
1237
1345
|
### `formatSceneWarning`
|
|
1238
1346
|
|
|
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.
|
|
1347
|
+
`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 in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
1240
1348
|
|
|
1241
1349
|
```ts
|
|
1242
1350
|
export function formatSceneWarning(warning: ISceneWarning): string { … }
|
|
@@ -1350,12 +1458,45 @@ export function getPlatform(): Readonly<IPlatformInfo> { … }
|
|
|
1350
1458
|
```
|
|
1351
1459
|
|
|
1352
1460
|
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1353
|
-
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
1461
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1354
1462
|
|
|
1355
1463
|
```ts
|
|
1356
1464
|
if (isMobile()) showTouchControls();
|
|
1357
1465
|
```
|
|
1358
1466
|
|
|
1467
|
+
### `GIBudget`
|
|
1468
|
+
|
|
1469
|
+
`class` — Reports what a game's global illumination costs against the frame period: the GI share of the GPU frame and whether the frame fits its period less 10% headroom. The method (`none`, `irradianceField`, `screenProbeGather`) holds its level while the game runs, as Unreal's Lumen does: a frame over its period gets cheaper through the primary resolution scale, and the GI pass follows the lower resolution. The budget is the frame period, never a GI time in milliseconds, because a stage reading moves with the GPU clock.
|
|
1470
|
+
|
|
1471
|
+
```ts
|
|
1472
|
+
export class GIBudget { … }
|
|
1473
|
+
```
|
|
1474
|
+
|
|
1475
|
+
- **Use when:** global illumination costs too much on a weak GPU · see what share of the GPU frame the bounce light takes · quality tier for indirect lighting that follows the hardware
|
|
1476
|
+
- **Constraints:** the method never changes while the game runs: the primary resolution scale is the run-time lever · the GPU time of a pass is read by the scene name three or the game gave it, so name every GI pass in `stages` · timestamp queries are needed: without them every window is unobserved
|
|
1477
|
+
|
|
1478
|
+
```ts
|
|
1479
|
+
const gi = new GIBudget({ method: "screenProbeGather", stages: ["SSGI"], framePeriodMs: 1000 / 60 });
|
|
1480
|
+
ctx.beforeRender(() => gi.observeRenderer(ctx.renderer.raw));
|
|
1481
|
+
```
|
|
1482
|
+
|
|
1483
|
+
### `GIVisualize`
|
|
1484
|
+
|
|
1485
|
+
`class` — Shows the indirect diffuse light of a frame by itself, the counterpart of Unreal's Lumen `Visualize IndirectDiffuse` mode, so a lighting gap against a reference can be told apart from a scene gap. The game's chain builds the term; this class selects it and fails when the term is missing.
|
|
1486
|
+
|
|
1487
|
+
```ts
|
|
1488
|
+
export class GIVisualize { … }
|
|
1489
|
+
```
|
|
1490
|
+
|
|
1491
|
+
- **Use when:** see only the bounce light of a frame · compare indirect lighting alone against Unreal · debug global illumination by looking at the indirect diffuse term
|
|
1492
|
+
- **Constraints:** the game's render chain builds the indirectDiffuse node (gathered and cached light times albedo); this class draws nothing else · a mode whose term the chain did not build throws instead of showing the finished frame
|
|
1493
|
+
- **Overrides:** mode: "off" returns the finished frame unchanged
|
|
1494
|
+
|
|
1495
|
+
```ts
|
|
1496
|
+
const view = new GIVisualize({ mode: "indirectDiffuse", beauty: frame, indirectDiffuse: albedo.mul(bounce) });
|
|
1497
|
+
pipeline.outputNode = view.node;
|
|
1498
|
+
```
|
|
1499
|
+
|
|
1359
1500
|
### `GPUParticles3D`
|
|
1360
1501
|
|
|
1361
1502
|
`class` — Dispatch a game-owned particle surface and process function through a pooled system.
|
|
@@ -1436,6 +1577,22 @@ const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: [
|
|
|
1436
1577
|
// inside the scene, per frame: ctx.input.axis("move") is 0 at rest and 1 at full tilt
|
|
1437
1578
|
```
|
|
1438
1579
|
|
|
1580
|
+
### `installFilmicToneMapping`
|
|
1581
|
+
|
|
1582
|
+
`function` — Unreal 5.8.3's tone curve, the default tone mapping of `createRenderer` and `Game`: a filmic curve in ACEScg (slope 0.88, toe 0.55, shoulder 0.26) after the gamut expansion and blue correction of Unreal's colour LUT. `installFilmicToneMapping` registers it as three's custom tone mapping.
|
|
1583
|
+
|
|
1584
|
+
```ts
|
|
1585
|
+
export function installFilmicToneMapping( raw: unknown, c: IFilmicCurve = FILMIC_CURVE, grade: IColorGrade = COLOR_GRADE, ): number | undefined { … }
|
|
1586
|
+
```
|
|
1587
|
+
|
|
1588
|
+
- **Use when:** the frame should tone map the way a fresh Unreal project does
|
|
1589
|
+
- **Constraints:** WebGPU renderers only: a renderer without a node library keeps ACES and reports `TN_TONEMAP`
|
|
1590
|
+
- **Overrides:** `createRenderer({ toneMapping: "aces" | "agx" | "neutral" | "none" })` or `game.renderer.toneMapping` in the game config; setting `renderer.raw.toneMapping` later wins
|
|
1591
|
+
|
|
1592
|
+
```ts
|
|
1593
|
+
const renderer = await createRenderer({ toneMapping: "aces" }); // the named override
|
|
1594
|
+
```
|
|
1595
|
+
|
|
1439
1596
|
### `installSpanProbes`
|
|
1440
1597
|
|
|
1441
1598
|
`function` — Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's `sort`, the per-draw submission, and the scene-graph walk. Installed for you when `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.
|
|
@@ -1493,7 +1650,7 @@ export function isMobile(): boolean { … }
|
|
|
1493
1650
|
```
|
|
1494
1651
|
|
|
1495
1652
|
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1496
|
-
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
1653
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1497
1654
|
|
|
1498
1655
|
```ts
|
|
1499
1656
|
if (isMobile()) showTouchControls();
|
|
@@ -1508,7 +1665,7 @@ export function isNative(): boolean { … }
|
|
|
1508
1665
|
```
|
|
1509
1666
|
|
|
1510
1667
|
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1511
|
-
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
1668
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1512
1669
|
|
|
1513
1670
|
```ts
|
|
1514
1671
|
if (isMobile()) showTouchControls();
|
|
@@ -1538,7 +1695,7 @@ export function isTouchscreenAvailable(): boolean { … }
|
|
|
1538
1695
|
```
|
|
1539
1696
|
|
|
1540
1697
|
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1541
|
-
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
1698
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1542
1699
|
|
|
1543
1700
|
```ts
|
|
1544
1701
|
if (isMobile()) showTouchControls();
|
|
@@ -1553,12 +1710,43 @@ export function isWeb(): boolean { … }
|
|
|
1553
1710
|
```
|
|
1554
1711
|
|
|
1555
1712
|
- **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
|
|
1556
|
-
- **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
|
|
1713
|
+
- **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
|
|
1557
1714
|
|
|
1558
1715
|
```ts
|
|
1559
1716
|
if (isMobile()) showTouchControls();
|
|
1560
1717
|
```
|
|
1561
1718
|
|
|
1719
|
+
### `lampPenumbraTangent`
|
|
1720
|
+
|
|
1721
|
+
`function` — A lamp's penumbra radius in tangent units at a receiver, from the lamp's source radius and the blocker and receiver distances.
|
|
1722
|
+
|
|
1723
|
+
```ts
|
|
1724
|
+
export function lampPenumbraTangent( sourceRadius: number, blockerDistance: number, receiverDistance: number, ): number { … }
|
|
1725
|
+
```
|
|
1726
|
+
|
|
1727
|
+
- **Use when:** measure a lamp shadow's penumbra width without a GPU
|
|
1728
|
+
- **Constraints:** sourceRadius is 0 or more; both distances are positive metres; the result is the geometric tangent, before penumbraScale
|
|
1729
|
+
|
|
1730
|
+
```ts
|
|
1731
|
+
const tangent = lampPenumbraTangent(0.05, 2, 3);
|
|
1732
|
+
```
|
|
1733
|
+
|
|
1734
|
+
### `lampShadowMarker`
|
|
1735
|
+
|
|
1736
|
+
`function` — The `TN_LAMP_SHADOW` line for the renderer's last frame, or `undefined` on a renderer that keeps no lamp counters (three's own).
|
|
1737
|
+
|
|
1738
|
+
```ts
|
|
1739
|
+
export function lampShadowMarker( renderer: { … }
|
|
1740
|
+
```
|
|
1741
|
+
|
|
1742
|
+
- **Use when:** log lamp shadow redraws and GPU time apart from the sun's on the owned engine
|
|
1743
|
+
- **Constraints:** counters that do not add up to the frame's shadow draws throw TN_LAMP_SHADOW_INVALID
|
|
1744
|
+
|
|
1745
|
+
```ts
|
|
1746
|
+
const line = lampShadowMarker(renderer, frame);
|
|
1747
|
+
if (line !== undefined) console.info(line);
|
|
1748
|
+
```
|
|
1749
|
+
|
|
1562
1750
|
### `loadAll`
|
|
1563
1751
|
|
|
1564
1752
|
`function` — Load a list with bounded concurrency, returning results in the input's order.
|
|
@@ -1734,6 +1922,21 @@ export class PathFollow3D { … }
|
|
|
1734
1922
|
const follower = new PathFollow3D({ points: patrolPoints, loop: true, speed: 3 });
|
|
1735
1923
|
```
|
|
1736
1924
|
|
|
1925
|
+
### `penumbraUv`
|
|
1926
|
+
|
|
1927
|
+
`function` — Convert world-space caster gap to a shadow UV radius, floored at one texel.
|
|
1928
|
+
|
|
1929
|
+
```ts
|
|
1930
|
+
export function penumbraUv( gapMetres: number, sourceAngleRad: number, frustumWidthMetres: number, mapSize: number, ): number { … }
|
|
1931
|
+
```
|
|
1932
|
+
|
|
1933
|
+
- **Use when:** measure a source-angle shadow's filter radius without a GPU
|
|
1934
|
+
- **Constraints:** inputs must be finite and non-negative; sizes must be positive and angle < PI/2 radians
|
|
1935
|
+
|
|
1936
|
+
```ts
|
|
1937
|
+
const radius = penumbraUv(10, angle, 40, 2048);
|
|
1938
|
+
```
|
|
1939
|
+
|
|
1737
1940
|
### `PipelineCensus`
|
|
1738
1941
|
|
|
1739
1942
|
`class` — Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.
|
|
@@ -1805,14 +2008,61 @@ prewarm(tracerPool);
|
|
|
1805
2008
|
export class ProbeVolume extends Object3D implements IComputeDriven { … }
|
|
1806
2009
|
```
|
|
1807
2010
|
|
|
1808
|
-
- **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
|
|
1809
|
-
- **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
|
|
2011
|
+
- **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter · glass or fog inside a room takes the room's bounce light
|
|
2012
|
+
- **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour · a translucent material or a fog sample has no side that faces the light: it reads sampleNonDirectional(position), one atlas fetch, the same in every direction (divide by pi for a radiance)
|
|
1810
2013
|
- **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
|
|
1811
2014
|
|
|
1812
2015
|
```ts
|
|
1813
2016
|
const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
|
|
1814
2017
|
```
|
|
1815
2018
|
|
|
2019
|
+
### `qualityPreset`
|
|
2020
|
+
|
|
2021
|
+
`function` — The quality tiers of the Unreal 5.8.3 look: what `high` (a desktop, Unreal's Epic), `medium` and `low` (a phone) turn on, how a GPU family picks its start tier, and the global illumination and shadow filter settings per tier named after Unreal's scalability levels. A `WorldEnvironment` with no options starts from `high`. `qualityTiers` holds the tier tables: `resolve` picks a start tier from a GPU class, `gi` and `shadow` read a tier's settings.
|
|
2022
|
+
|
|
2023
|
+
```ts
|
|
2024
|
+
export function qualityPreset(tier: string): IWorldEnvironmentOptions { … }
|
|
2025
|
+
```
|
|
2026
|
+
|
|
2027
|
+
- **Use when:** pick a start tier for the GPU class and read what that tier costs the look · build a `WorldEnvironment` for a weaker device from a named tier
|
|
2028
|
+
- **Constraints:** an unknown tier name throws with the names it expected
|
|
2029
|
+
- **Overrides:** pass any `IWorldEnvironmentOptions` field after `qualityPreset(tier)`, or an explicit `tier` to `qualityTiers.resolve`
|
|
2030
|
+
|
|
2031
|
+
```ts
|
|
2032
|
+
const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });
|
|
2033
|
+
```
|
|
2034
|
+
|
|
2035
|
+
### `readGIMarker`
|
|
2036
|
+
|
|
2037
|
+
`function` — Parse a `TN_GI` console line back into its report, or `undefined`.
|
|
2038
|
+
|
|
2039
|
+
```ts
|
|
2040
|
+
export function readGIMarker(line: string): IGIBudgetReport | undefined { … }
|
|
2041
|
+
```
|
|
2042
|
+
|
|
2043
|
+
- **Use when:** inspect which global illumination method ran and what the frame cost
|
|
2044
|
+
- **Constraints:** non-marker lines and malformed markers return `undefined`
|
|
2045
|
+
|
|
2046
|
+
```ts
|
|
2047
|
+
const report = readGIMarker(line); if (report?.verdict === "over") console.log(report.reason);
|
|
2048
|
+
```
|
|
2049
|
+
|
|
2050
|
+
### `readLampShadowMarker`
|
|
2051
|
+
|
|
2052
|
+
`function` — Parse a `TN_LAMP_SHADOW` line back into its stats, or `undefined`.
|
|
2053
|
+
|
|
2054
|
+
```ts
|
|
2055
|
+
export function readLampShadowMarker(line: string): ILampShadowStats | undefined { … }
|
|
2056
|
+
```
|
|
2057
|
+
|
|
2058
|
+
- **Use when:** count lamp shadow redraws from a renderer log, for example a moving-caster run
|
|
2059
|
+
- **Constraints:** non-marker lines and markers whose sun and lamp draws do not add up return `undefined`
|
|
2060
|
+
|
|
2061
|
+
```ts
|
|
2062
|
+
const stats = readLampShadowMarker(line);
|
|
2063
|
+
if (stats !== undefined) console.log(stats.lamps.redraws);
|
|
2064
|
+
```
|
|
2065
|
+
|
|
1816
2066
|
### `readProbeVolumeObservation`
|
|
1817
2067
|
|
|
1818
2068
|
`function` — Read the most recent observation from a probe volume.
|
|
@@ -1858,6 +2108,21 @@ export function readRenderChainReport(renderer: unknown): IRenderChainMarker | u
|
|
|
1858
2108
|
const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
|
|
1859
2109
|
```
|
|
1860
2110
|
|
|
2111
|
+
### `readShadowTierMarker`
|
|
2112
|
+
|
|
2113
|
+
`function` — Parse a `TN_SHADOW_TIER` console line back into its report, or `undefined`.
|
|
2114
|
+
|
|
2115
|
+
```ts
|
|
2116
|
+
export function readShadowTierMarker(line: string): IShadowFilterReport | undefined { … }
|
|
2117
|
+
```
|
|
2118
|
+
|
|
2119
|
+
- **Use when:** inspect which shadow filter tier ran and why it stepped
|
|
2120
|
+
- **Constraints:** non-marker lines and malformed markers return `undefined`
|
|
2121
|
+
|
|
2122
|
+
```ts
|
|
2123
|
+
const report = readShadowTierMarker(line); if (report?.stepped) console.log(report.reason);
|
|
2124
|
+
```
|
|
2125
|
+
|
|
1861
2126
|
### `readVelocityPreviousBoneMatrices`
|
|
1862
2127
|
|
|
1863
2128
|
`function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
|
|
@@ -2169,10 +2434,10 @@ const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer:
|
|
|
2169
2434
|
|
|
2170
2435
|
### `sceneWarning`
|
|
2171
2436
|
|
|
2172
|
-
`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.
|
|
2437
|
+
`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 in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
2173
2438
|
|
|
2174
2439
|
```ts
|
|
2175
|
-
export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, ): ISceneWarning | undefined { … }
|
|
2440
|
+
export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, gpuClass?: string, ): ISceneWarning | undefined { … }
|
|
2176
2441
|
```
|
|
2177
2442
|
|
|
2178
2443
|
- **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
|
|
@@ -2229,17 +2494,34 @@ export function setSpanRecorder(next: SpanRecorder | undefined): void { … }
|
|
|
2229
2494
|
if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
2230
2495
|
```
|
|
2231
2496
|
|
|
2497
|
+
### `ShadowFilterBudget`
|
|
2498
|
+
|
|
2499
|
+
`class` — Steps a game's soft-shadow tier down (`low`, `medium`, `high`) when the whole GPU frame stays over the frame period, and back up when the frame has room, by the settings of Unreal's virtual shadow map budget (a linear model, 5% headroom). A frame that is slow for another reason keeps its shadows: the tier steps only when the shadow passes could absorb the overage. The game owns the sample counts of each tier and rebuilds its filter on each step; the tiers follow Unreal's `sg.ShadowQuality` Low, Medium and Epic.
|
|
2500
|
+
|
|
2501
|
+
```ts
|
|
2502
|
+
export class ShadowFilterBudget { … }
|
|
2503
|
+
```
|
|
2504
|
+
|
|
2505
|
+
- **Use when:** soft shadow filter costs too much on a weak GPU · step the shadow quality tier when the GPU frame goes over the frame period · shadow quality tier that follows the hardware
|
|
2506
|
+
- **Constraints:** the game rebuilds its filter with the tier's sample counts on each step; this class draws nothing · timestamp queries are needed: without them every window is unobserved and the tier holds · the rule reads the whole GPU frame and the `Shadow` stage, which the receiver filter inside the colour pass is not part of
|
|
2507
|
+
- **Overrides:** explicit: true keeps the game's own sample counts and reports an over-budget frame
|
|
2508
|
+
|
|
2509
|
+
```ts
|
|
2510
|
+
const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60, onStep: (tier) => { light.shadow.filterNode = filterFor(tier); } });
|
|
2511
|
+
ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
|
|
2512
|
+
```
|
|
2513
|
+
|
|
2232
2514
|
### `SkeletalMesh3D`
|
|
2233
2515
|
|
|
2234
|
-
`class` — Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting.
|
|
2516
|
+
`class` — Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting. Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: "auto"` default; `updateRate: 1` evaluates every frame, another positive safe integer requests that interval, and `updateRateReport` exposes the effective rate, override status and latest result. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"` listener promotes effective evaluation to 1 and observes only loop events after registration, so skipped pre-registration cycles are not replayed.
|
|
2235
2517
|
|
|
2236
2518
|
```ts
|
|
2237
2519
|
export class SkeletalMesh3D extends AnimationPlayer { … }
|
|
2238
2520
|
```
|
|
2239
2521
|
|
|
2240
|
-
- **Use when:** put an animated character in the scene · my imported character renders deformed · instance an imported rigged character · validate animation clips on a character rig at load time · prepare a skinned character with safe skeleton cloning and stride sync
|
|
2522
|
+
- **Use when:** put an animated character in the scene · my imported character renders deformed · instance an imported rigged character · validate animation clips on a character rig at load time · prepare a skinned character with safe skeleton cloning and stride sync · reduce animation CPU for a crowd of imported rigs · inspect an imported rig's effective animation evaluation rate
|
|
2241
2523
|
- **Constraints:** use strideRoot to name the body moved by game code when the rig is parented under it · requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
|
|
2242
|
-
- **Overrides:** strideSync controls whether locomotion playback rate matches ground covered · size normalises the instance to real-world metres with skin-aware measurement
|
|
2524
|
+
- **Overrides:** strideSync controls whether locomotion playback rate matches ground covered · size normalises the instance to real-world metres with skin-aware measurement · updateRate: "auto" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `"loop"` listener promotes effective evaluation to 1 to preserve event timing
|
|
2243
2525
|
|
|
2244
2526
|
```ts
|
|
2245
2527
|
import { SkeletalMesh3D } from "@threenative/core";
|
|
@@ -2266,6 +2548,36 @@ import { skeletonBones } from "@threenative/core";
|
|
|
2266
2548
|
const bones = skeletonBones(character);
|
|
2267
2549
|
```
|
|
2268
2550
|
|
|
2551
|
+
### `SkyCapture`
|
|
2552
|
+
|
|
2553
|
+
`class` — Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.
|
|
2554
|
+
|
|
2555
|
+
```ts
|
|
2556
|
+
export class SkyCapture { … }
|
|
2557
|
+
```
|
|
2558
|
+
|
|
2559
|
+
- **Use when:** light a scene from a procedural sky when its sun moves
|
|
2560
|
+
- **Constraints:** use an initialized WebGPURenderer; the game supplies the sky and assigns the texture · call update once per frame on an initialized WebGPURenderer; assign texture after it returns true · sky nodes use a world-space view direction; keep supplied sky resources alive until dispose
|
|
2561
|
+
|
|
2562
|
+
```ts
|
|
2563
|
+
const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;
|
|
2564
|
+
```
|
|
2565
|
+
|
|
2566
|
+
### `SkyCaptureSchedule`
|
|
2567
|
+
|
|
2568
|
+
`class` — Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.
|
|
2569
|
+
|
|
2570
|
+
```ts
|
|
2571
|
+
export class SkyCaptureSchedule { … }
|
|
2572
|
+
```
|
|
2573
|
+
|
|
2574
|
+
- **Use when:** light a scene from a procedural sky when its sun moves
|
|
2575
|
+
- **Constraints:** use an initialized WebGPURenderer; the game supplies the sky and assigns the texture
|
|
2576
|
+
|
|
2577
|
+
```ts
|
|
2578
|
+
const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;
|
|
2579
|
+
```
|
|
2580
|
+
|
|
2269
2581
|
### `snapRefreshRate`
|
|
2270
2582
|
|
|
2271
2583
|
`function` — Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.
|
|
@@ -2342,6 +2654,37 @@ export function solarPositionAt( date: Date | string, latitude: number, longitud
|
|
|
2342
2654
|
const sun = solarPositionAt(new Date(), 49.28, -123.12);
|
|
2343
2655
|
```
|
|
2344
2656
|
|
|
2657
|
+
### `sourceAngleShadowFilter`
|
|
2658
|
+
|
|
2659
|
+
`function` — Source-angle blocker search and variable-radius PCF on three's shadow map.
|
|
2660
|
+
|
|
2661
|
+
```ts
|
|
2662
|
+
export function sourceAngleShadowFilter( { … }
|
|
2663
|
+
```
|
|
2664
|
+
|
|
2665
|
+
- **Use when:** soften a directional shadow as the caster-receiver gap grows
|
|
2666
|
+
- **Constraints:** sourceAngleRad is required, in radians in [0, PI/2); orthographic depth shadows only, not VSM
|
|
2667
|
+
|
|
2668
|
+
```ts
|
|
2669
|
+
sun.shadow.filterNode = sourceAngleShadowFilter({ sourceAngleRad: angle });
|
|
2670
|
+
```
|
|
2671
|
+
|
|
2672
|
+
### `sourceRadiusShadowFilter`
|
|
2673
|
+
|
|
2674
|
+
`function` — Source-radius blocker search and variable-radius PCF on a spot or point light's shadow map.
|
|
2675
|
+
|
|
2676
|
+
```ts
|
|
2677
|
+
export function sourceRadiusShadowFilter( { … }
|
|
2678
|
+
```
|
|
2679
|
+
|
|
2680
|
+
- **Use when:** soften a lamp's shadow by the lamp's size, as Unreal's SourceRadius does
|
|
2681
|
+
- **Constraints:** sourceRadius is required, in metres, 0 or more (0 is one hard tap); penumbraScale, the share of the geometric penumbra kept, is in (0, 4] and defaults to 0.6, the width Unreal's lamp ray test resolves; forward-depth maps only
|
|
2682
|
+
- **Overrides:** penumbraScale: 1 gives the geometric penumbra of a disk lamp
|
|
2683
|
+
|
|
2684
|
+
```ts
|
|
2685
|
+
lamp.shadow.filterNode = sourceRadiusShadowFilter({ sourceRadius: 0.05 });
|
|
2686
|
+
```
|
|
2687
|
+
|
|
2345
2688
|
### `spanNow`
|
|
2346
2689
|
|
|
2347
2690
|
`function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
|
|
@@ -2432,6 +2775,21 @@ export class SpriteAnimator3D { … }
|
|
|
2432
2775
|
const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
|
|
2433
2776
|
```
|
|
2434
2777
|
|
|
2778
|
+
### `stageGpuReading`
|
|
2779
|
+
|
|
2780
|
+
`function` — Read the GPU milliseconds of each named render pass of the newest resolved frame, such as `SSGI` or `AO`, with the whole frame's total.
|
|
2781
|
+
|
|
2782
|
+
```ts
|
|
2783
|
+
export function stageGpuReading(renderer: unknown): IStageGpuReading | undefined { … }
|
|
2784
|
+
```
|
|
2785
|
+
|
|
2786
|
+
- **Use when:** read the GPU cost of one post-processing stage · tell which render pass takes the GPU time
|
|
2787
|
+
- **Constraints:** absent before a whole frame resolves and on an adapter without timestamp queries; the frame number counts each reading once
|
|
2788
|
+
|
|
2789
|
+
```ts
|
|
2790
|
+
const reading = stageGpuReading(renderer); const ssgiMs = reading?.stages.SSGI;
|
|
2791
|
+
```
|
|
2792
|
+
|
|
2435
2793
|
### `staticTransformCensus`
|
|
2436
2794
|
|
|
2437
2795
|
`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.
|
|
@@ -2447,6 +2805,54 @@ export function staticTransformCensus(): IStaticTransformCensus { … }
|
|
|
2447
2805
|
invalidateStatic(drawbridge);
|
|
2448
2806
|
```
|
|
2449
2807
|
|
|
2808
|
+
### `SurfaceCache`
|
|
2809
|
+
|
|
2810
|
+
`class` — The Surface Cache: what a traced global-illumination ray reads where it hits a surface. A material atlas (base colour and emissive maps reduced to small tiles) answers the albedo and the glow at the hit UV; a flat material keeps its colour. `SurfaceLights` adds the scene's point and spot lamps at the hit, the brightest eight.
|
|
2811
|
+
|
|
2812
|
+
```ts
|
|
2813
|
+
export class SurfaceCache { … }
|
|
2814
|
+
```
|
|
2815
|
+
|
|
2816
|
+
- **Use when:** give a traced bounce ray the texture colour and glow of the surface it hits
|
|
2817
|
+
- **Constraints:** the materials are fixed when the cache is built; build a new one when a material or a map changes · a map whose image the runtime does not show to JavaScript (the owned engine's glTF maps) returns the flat colour and is listed in `report.fallbacks`; the `images` option hands over its pixels · the cache owns no colour, texture or light; the game's materials and lamps are the only source
|
|
2818
|
+
- **Overrides:** atlasSize and cardTexelDensityScale size the atlas; images supplies the pixels of a map the runtime hides
|
|
2819
|
+
|
|
2820
|
+
```ts
|
|
2821
|
+
const cache = SurfaceCache.from(materials); cache.albedo(slot, hit.uv.x, hit.uv.y, out);
|
|
2822
|
+
```
|
|
2823
|
+
|
|
2824
|
+
### `SurfaceLights`
|
|
2825
|
+
|
|
2826
|
+
`class` — The local lamps at the hit of a traced ray: the point and spot lights whose range reaches it, the brightest eight, one shadow ray each. The Surface Cache gives the hit its colour; this gives it the lamps.
|
|
2827
|
+
|
|
2828
|
+
```ts
|
|
2829
|
+
export class SurfaceLights { … }
|
|
2830
|
+
```
|
|
2831
|
+
|
|
2832
|
+
- **Use when:** light the hit of a traced ray with the scene's point and spot lamps
|
|
2833
|
+
- **Constraints:** the cap skips the ninth-brightest lamp and every one after it, and counts them in `skipped` · the caller answers each shadow ray; the class owns no scene
|
|
2834
|
+
- **Overrides:** maxLights caps the lamps evaluated at one hit
|
|
2835
|
+
|
|
2836
|
+
```ts
|
|
2837
|
+
const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
|
|
2838
|
+
```
|
|
2839
|
+
|
|
2840
|
+
### `TracedReflections`
|
|
2841
|
+
|
|
2842
|
+
`class` — Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material. The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
|
|
2843
|
+
|
|
2844
|
+
```ts
|
|
2845
|
+
export class TracedReflections { … }
|
|
2846
|
+
```
|
|
2847
|
+
|
|
2848
|
+
- **Use when:** reflect what is behind the camera in a mirror or a chrome sphere · make a glossy or wet floor reflect objects that are off screen · trace a shadow ray from a reflected surface toward the sun · split a surface's specular by roughness into traced, radiance-cache and diffuse-GI shares
|
|
2849
|
+
- **Constraints:** the pack is a snapshot of the static triangles taken when the object is built: build a new one after geometry moves · instanced, skinned, batched and morphing meshes are not in the pack; report.skippedMoving counts them · trace only pixels at or below maxRoughnessToTrace (0.4, Unreal's cut-off): each ray walks the tree · a ray visits at most maxSteps tree nodes, then reports a miss; hit light, the miss colour and the blend with the frame stay in the game's src/render/ · the pack needs a device with float32-filterable
|
|
2850
|
+
- **Overrides:** maxRoughnessToTrace, roughnessFadeLength, maxRoughnessToEvaluateRoughSpecular, roughSpecularFadeLength and maxSteps are game-owned choices
|
|
2851
|
+
|
|
2852
|
+
```ts
|
|
2853
|
+
const traced = new TracedReflections(ctx.scene); const hit = traced.trace({ origin, direction, far: 30 }); // light hit.albedo at hit.position in the stage
|
|
2854
|
+
```
|
|
2855
|
+
|
|
2450
2856
|
### `TracerPool3D`
|
|
2451
2857
|
|
|
2452
2858
|
`class` — Pool travelling bullet-streak meshes for hitscan shots.
|
|
@@ -2541,6 +2947,22 @@ const hull = await ctx.assets.model("hull.glb");
|
|
|
2541
2947
|
ctx.scene.add(hull.scene);
|
|
2542
2948
|
```
|
|
2543
2949
|
|
|
2950
|
+
### `useRoughDiffuse`
|
|
2951
|
+
|
|
2952
|
+
`function` — Unreal's Substrate rough diffuse (EON) on standard and physical materials, so direct sun and lamp light meets a rough surface the way Unreal shades it. The same `roughDiffuse` flag works on three's WebGPU renderer and on the owned engine.
|
|
2953
|
+
|
|
2954
|
+
```ts
|
|
2955
|
+
export function useRoughDiffuse(root: Object3D, enabled = true): number { … }
|
|
2956
|
+
```
|
|
2957
|
+
|
|
2958
|
+
- **Use when:** shade rough surfaces under a sun or a lamp the way Unreal's Substrate does, not as flat Lambert
|
|
2959
|
+
- **Constraints:** direct light only, indirect light stays Lambert; standard and physical materials; a lamp's `sourceRadius` in metres fades the effect to Lambert at 20 cm; a material changed after its first draw needs `needsUpdate`
|
|
2960
|
+
- **Overrides:** material.roughDiffuse = false, or useRoughDiffuse(root, false), puts Lambert back
|
|
2961
|
+
|
|
2962
|
+
```ts
|
|
2963
|
+
useRoughDiffuse(scene);
|
|
2964
|
+
```
|
|
2965
|
+
|
|
2544
2966
|
### `validateWorldMatrices`
|
|
2545
2967
|
|
|
2546
2968
|
`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.
|
|
@@ -2608,7 +3030,7 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
|
|
|
2608
3030
|
|
|
2609
3031
|
- **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
|
|
2610
3032
|
- **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
|
|
3033
|
+
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
|
|
2612
3034
|
|
|
2613
3035
|
```ts
|
|
2614
3036
|
const sun = new DirectionalLight(0xffffff, 3);
|
|
@@ -2685,6 +3107,22 @@ renderer.render(scene, camera);
|
|
|
2685
3107
|
tracker.commit(scene);
|
|
2686
3108
|
```
|
|
2687
3109
|
|
|
3110
|
+
### `WorldEnvironment`
|
|
3111
|
+
|
|
3112
|
+
`class` — The node that says which lighting effects a scene runs and how strong they are, with a fresh Unreal 5.8.3 project's defaults: the filmic tone curve, Unreal-metered auto exposure, screen-space GI and ambient occlusion, SMAA, Unreal's bloom and local exposure. It builds the post chain through `renderer.createRenderChain()` and prints `TN_RENDER_CHAIN` naming every stage as applied or refused with a reason. Property names are Godot's `Environment` where it has one.
|
|
3113
|
+
|
|
3114
|
+
```ts
|
|
3115
|
+
export class WorldEnvironment { … }
|
|
3116
|
+
```
|
|
3117
|
+
|
|
3118
|
+
- **Use when:** a scene should light and tone map like a fresh Unreal level without wiring each post stage by hand · turn one lighting effect off, or pick a cheaper tier, for a weak GPU or a stylised look
|
|
3119
|
+
- **Constraints:** post stages run on WebGPU only: a renderer without it keeps the fixed exposure and reports `TN_AUTO_EXPOSURE_REFUSED`, and a missing node library keeps ACES and reports `TN_TONEMAP` · an unknown option value throws instead of becoming the default
|
|
3120
|
+
- **Overrides:** every option on `IWorldEnvironmentOptions`: `tonemapMode: "aces" | "agx" | "neutral"`, `autoExposureEnabled: false` with a fixed `exposure`, `bloomEnabled`, `gtaoEnabled`, `ssgiEnabled`, `screenSpaceAA`
|
|
3121
|
+
|
|
3122
|
+
```ts
|
|
3123
|
+
const world = new WorldEnvironment({ tonemapMode: "aces", autoExposureEnabled: false, exposure: 0.8 }); world.apply(renderer, scene, view);
|
|
3124
|
+
```
|
|
3125
|
+
|
|
2688
3126
|
### `zenithTransmittance`
|
|
2689
3127
|
|
|
2690
3128
|
`function` — Return direct vertical transmittance for the supplied atmosphere.
|
|
@@ -2964,6 +3402,36 @@ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { …
|
|
|
2964
3402
|
const mirror = subscribeUiState(bridge);
|
|
2965
3403
|
```
|
|
2966
3404
|
|
|
3405
|
+
## `@threenative/core/worker`
|
|
3406
|
+
|
|
3407
|
+
### `serveWorkerGame`
|
|
3408
|
+
|
|
3409
|
+
`function` — Runs inside the worker: wire the page's messages to the unchanged portable game. Call it last in the worker entry, after the game module evaluated: it posts the ready message the page waits for before it sends the canvas.
|
|
3410
|
+
|
|
3411
|
+
```ts
|
|
3412
|
+
export function serveWorkerGame( game: { … }
|
|
3413
|
+
```
|
|
3414
|
+
|
|
3415
|
+
- **Use when:** run the game loop in a web worker so a busy page cannot stall its frames
|
|
3416
|
+
|
|
3417
|
+
```ts
|
|
3418
|
+
serveWorkerGame(game);
|
|
3419
|
+
```
|
|
3420
|
+
|
|
3421
|
+
### `startWorkerGame`
|
|
3422
|
+
|
|
3423
|
+
`function` — Runs on the page: own the canvas and the DOM, and feed the worker game. Call it before the UI mounts: the HUD's bridge host globals exist from this call on.
|
|
3424
|
+
|
|
3425
|
+
```ts
|
|
3426
|
+
export function startWorkerGame( worker: Worker, container: HTMLElement, ): { … }
|
|
3427
|
+
```
|
|
3428
|
+
|
|
3429
|
+
- **Use when:** host a worker-run game's canvas, input and HUD on the page
|
|
3430
|
+
|
|
3431
|
+
```ts
|
|
3432
|
+
const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }), root);
|
|
3433
|
+
```
|
|
3434
|
+
|
|
2967
3435
|
## `@threenative/core/world`
|
|
2968
3436
|
|
|
2969
3437
|
### `cellPlacements`
|
|
@@ -3155,7 +3623,7 @@ export class WorldCells extends Group implements IComputeDriven { … }
|
|
|
3155
3623
|
```
|
|
3156
3624
|
|
|
3157
3625
|
- **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
|
|
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
|
|
3626
|
+
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first · budgets are hard caps that report pressure instead of over-committing · 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
3627
|
- **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
|
|
3160
3628
|
|
|
3161
3629
|
```ts
|
|
@@ -3426,8 +3894,9 @@ export class PhysicsDirectSpaceState3D { … }
|
|
|
3426
3894
|
```
|
|
3427
3895
|
|
|
3428
3896
|
- **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
|
|
3429
|
-
- **Constraints:** query results are bounded by the configured result limit
|
|
3897
|
+
- **Constraints:** query results are bounded by the configured result limit · intersectRay ignores a solid that contains the ray origin and returns the next real hit or none, like Godot hit_from_inside false
|
|
3430
3898
|
- **Requires:** npm i @threenative/physics
|
|
3899
|
+
- **Overrides:** hitFromInside: true returns the solid around the ray origin as a distance 0 hit with a zero normal
|
|
3431
3900
|
|
|
3432
3901
|
```ts
|
|
3433
3902
|
const space = new PhysicsDirectSpaceState3D(context);
|
|
@@ -4049,7 +4518,7 @@ const adb = discoverAdb(process.env);
|
|
|
4049
4518
|
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
4050
4519
|
|
|
4051
4520
|
```ts
|
|
4052
|
-
export async function advanceFixedStep( page: Page, bridge:
|
|
4521
|
+
export async function advanceFixedStep( page: Page, bridge: { … }
|
|
4053
4522
|
```
|
|
4054
4523
|
|
|
4055
4524
|
- **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
|
|
@@ -5026,6 +5495,21 @@ const config = parseStandalonePlaytestArgs(["--scenario", "playtests/smoke.playt
|
|
|
5026
5495
|
await withBrowserCapture(config, async (session) => session.screenshot("ready"));
|
|
5027
5496
|
```
|
|
5028
5497
|
|
|
5498
|
+
### `withScenarioClock`
|
|
5499
|
+
|
|
5500
|
+
`function` — Parse standalone playtest runner configuration.
|
|
5501
|
+
|
|
5502
|
+
```ts
|
|
5503
|
+
export function withScenarioClock<T extends { … }
|
|
5504
|
+
```
|
|
5505
|
+
|
|
5506
|
+
- **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
|
|
5507
|
+
- **Constraints:** invalid flags throw a named usage error
|
|
5508
|
+
|
|
5509
|
+
```ts
|
|
5510
|
+
const config = parseStandalonePlaytestArgs(argv);
|
|
5511
|
+
```
|
|
5512
|
+
|
|
5029
5513
|
### `writeCaptureProvenance`
|
|
5030
5514
|
|
|
5031
5515
|
`function` — Execute scenario steps, assertions, and evidence capture.
|
|
@@ -6600,13 +7084,29 @@ export function useUiState<TState extends object>(): TState | undefined;
|
|
|
6600
7084
|
```
|
|
6601
7085
|
|
|
6602
7086
|
- **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
|
|
6603
|
-
- **Constraints:** returns undefined until the game publishes its first state
|
|
7087
|
+
- **Constraints:** returns undefined until the game publishes its first state and while the loading cover is up
|
|
6604
7088
|
- **Requires:** npm i @threenative/ui
|
|
6605
7089
|
|
|
6606
7090
|
```ts
|
|
6607
7091
|
const score = useUiState<GameState, number>((state) => state.score);
|
|
6608
7092
|
```
|
|
6609
7093
|
|
|
7094
|
+
### `useUiStateDuringStartup`
|
|
7095
|
+
|
|
7096
|
+
`function` — Read the game's published state while the loading cover is still up, for a UI that draws its own loading screen.
|
|
7097
|
+
|
|
7098
|
+
```ts
|
|
7099
|
+
export function useUiStateDuringStartup<TState extends object>(options: { … }
|
|
7100
|
+
```
|
|
7101
|
+
|
|
7102
|
+
- **Use when:** draw a staged loading overlay from the startup progress the game publishes
|
|
7103
|
+
- **Constraints:** needs a non-empty reason, reported once as TN_UI_STARTUP_OVERRIDE; every other HUD uses useUiState
|
|
7104
|
+
- **Requires:** npm i @threenative/ui
|
|
7105
|
+
|
|
7106
|
+
```ts
|
|
7107
|
+
const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);
|
|
7108
|
+
```
|
|
7109
|
+
|
|
6610
7110
|
## `src/audio/storm.ts`
|
|
6611
7111
|
|
|
6612
7112
|
### `createStormAudio`
|
|
@@ -6742,23 +7242,6 @@ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
|
|
|
6742
7242
|
src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
|
|
6743
7243
|
```
|
|
6744
7244
|
|
|
6745
|
-
## `src/render/worldEnvironment.ts`
|
|
6746
|
-
|
|
6747
|
-
### `WorldEnvironment`
|
|
6748
|
-
|
|
6749
|
-
`class` — The generated file that composes every lighting stage and prints TN_RENDER_CHAIN naming each one as applied or refused with a reason. It is the game's source, not the framework's — edit it.
|
|
6750
|
-
|
|
6751
|
-
```ts
|
|
6752
|
-
class WorldEnvironment
|
|
6753
|
-
```
|
|
6754
|
-
|
|
6755
|
-
- **Use when:** turn a lighting or post-processing effect on or off · find out why an effect you enabled is not visible · change how the scene is lit, graded, or tonemapped · match a reference image's lighting
|
|
6756
|
-
- **Constraints:** Read the TN_RENDER_CHAIN line before assuming a stage ran: it names every stage as applied or dropped, with the reason it was dropped. · A stage reported `applied` can still be invisible if its own inputs are wrong — the chain reports whether it built, not whether you can see it. · Appearance belongs here, in generated game source. Nothing in packages/ decides how the scene looks.
|
|
6757
|
-
|
|
6758
|
-
```ts
|
|
6759
|
-
src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment
|
|
6760
|
-
```
|
|
6761
|
-
|
|
6762
7245
|
## `three/addons/tsl/display/BloomNode.js`
|
|
6763
7246
|
|
|
6764
7247
|
### `bloom`
|