create-threenative 0.2.7 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/agent-docs/references/assertion-reference.md +87 -35
- package/agent-docs/references/auto-exposure.md +57 -0
- package/agent-docs/references/capability-reference.md +1306 -62
- package/agent-docs/references/debug-surface.md +6 -0
- package/agent-docs/references/finding-assets.md +46 -10
- package/agent-docs/references/performance-basics.md +5 -4
- package/agent-docs/references/terrain-authoring.md +140 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
- package/capabilities.json +1505 -79
- package/dist/index.d.ts +28 -3
- package/dist/index.js +402 -167
- package/dist/threenative.js +989 -237
- package/dist/web-engine-buffer-geometry-utils.js +281 -0
- package/dist/web-engine-decal-geometry.js +184 -0
- package/dist/web-engine-gltf-loader.js +196 -0
- package/dist/web-engine-hdr-loader.js +190 -0
- package/dist/web-engine-lut-cube-loader.js +122 -0
- package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
- package/dist/web-engine-mesh-bvh.js +32 -0
- package/dist/web-engine-post-effects.js +168 -0
- package/dist/web-engine-runtime.js +42506 -0
- package/package.json +11 -8
- package/template-assets/autoExposure.ts +225 -0
- package/template-assets/exposure.ts +111 -0
- package/template-assets/exposureGraph.ts +178 -0
- package/template-assets/exposureReadback.ts +79 -0
- package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
- package/template-assets/patches/three@0.185.1.patch +6594 -700
- package/template-assets/patches/vite@8.2.0.patch +422 -0
- package/template-assets/worldEnvironment.ts +433 -30
- package/templates/action-rpg/AGENTS.md +11 -10
- package/templates/action-rpg/CLAUDE.md +11 -10
- package/templates/action-rpg/package.json +11 -9
- package/templates/action-rpg/playtests/performance.playtest.json +7 -1
- package/templates/action-rpg/src/progress.ts +0 -4
- package/templates/action-rpg/src/render/autoExposure.ts +225 -0
- package/templates/action-rpg/src/render/backlightControls.ts +66 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
- package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
- package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
- package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
- package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
- package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
- package/templates/action-rpg/src/render/exposure.ts +111 -0
- package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
- package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
- package/templates/action-rpg/src/render/heightFog.ts +118 -0
- package/templates/action-rpg/src/render/lighting.ts +26 -1
- package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
- package/templates/action-rpg/src/render/materialLighting.ts +155 -0
- package/templates/action-rpg/src/render/postprocessing.ts +17 -2
- package/templates/action-rpg/src/render/quality.ts +61 -2
- package/templates/action-rpg/src/render/sky.ts +21 -1
- package/templates/action-rpg/src/render/vfx.ts +133 -58
- package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
- package/templates/action-rpg/src/scenes/Play.ts +81 -16
- package/templates/action-rpg/threenative.config.ts +3 -0
- package/templates/action-rpg/vite.config.ts +10 -2
- package/templates/minimal/AGENTS.md +9 -10
- package/templates/minimal/CLAUDE.md +9 -10
- package/templates/minimal/package.json +9 -8
- package/templates/minimal/playtests/play.playtest.json +7 -1
- package/templates/minimal/playtests/sky.playtest.json +10 -1
- package/templates/minimal/src/render/autoExposure.ts +225 -0
- package/templates/minimal/src/render/backlightControls.ts +66 -0
- package/templates/minimal/src/render/backlightMaterial.ts +147 -0
- package/templates/minimal/src/render/environmentContribution.ts +188 -0
- package/templates/minimal/src/render/environmentRadiance.ts +36 -0
- package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
- package/templates/minimal/src/render/environmentSampling.ts +193 -0
- package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
- package/templates/minimal/src/render/exposure.ts +111 -0
- package/templates/minimal/src/render/exposureGraph.ts +178 -0
- package/templates/minimal/src/render/exposureReadback.ts +79 -0
- package/templates/minimal/src/render/heightFog.ts +118 -0
- package/templates/minimal/src/render/lighting.ts +25 -1
- package/templates/minimal/src/render/materialAssignments.ts +102 -0
- package/templates/minimal/src/render/materialLighting.ts +146 -0
- package/templates/minimal/src/render/postprocessing.ts +16 -2
- package/templates/minimal/src/render/quality.ts +60 -2
- package/templates/minimal/src/render/sky.ts +21 -1
- package/templates/minimal/src/render/worldEnvironment.ts +433 -30
- package/templates/minimal/src/scenes/Play.ts +50 -1
- package/templates/minimal/vite.config.ts +10 -2
- package/templates/platformer/AGENTS.md +7 -5
- package/templates/platformer/CLAUDE.md +7 -5
- package/templates/platformer/package.json +11 -9
- package/templates/platformer/playtests/performance.playtest.json +7 -1
- package/templates/platformer/src/render/autoExposure.ts +225 -0
- package/templates/platformer/src/render/backlightControls.ts +66 -0
- package/templates/platformer/src/render/backlightMaterial.ts +147 -0
- package/templates/platformer/src/render/environmentContribution.ts +188 -0
- package/templates/platformer/src/render/environmentRadiance.ts +36 -0
- package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
- package/templates/platformer/src/render/environmentSampling.ts +193 -0
- package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
- package/templates/platformer/src/render/exposure.ts +111 -0
- package/templates/platformer/src/render/exposureGraph.ts +178 -0
- package/templates/platformer/src/render/exposureReadback.ts +79 -0
- package/templates/platformer/src/render/heightFog.ts +118 -0
- package/templates/platformer/src/render/lighting.ts +26 -1
- package/templates/platformer/src/render/materialAssignments.ts +160 -0
- package/templates/platformer/src/render/materialLighting.ts +155 -0
- package/templates/platformer/src/render/materials.ts +7 -2
- package/templates/platformer/src/render/palette.ts +3 -3
- package/templates/platformer/src/render/postprocessing.ts +17 -2
- package/templates/platformer/src/render/quality.ts +61 -2
- package/templates/platformer/src/render/sky.ts +72 -23
- package/templates/platformer/src/render/skyEnvironment.ts +50 -0
- package/templates/platformer/src/render/worldEnvironment.ts +433 -30
- package/templates/platformer/src/scenes/Play.ts +70 -6
- package/templates/platformer/vite.config.ts +10 -2
- package/templates/puzzle/AGENTS.md +10 -9
- package/templates/puzzle/CLAUDE.md +10 -9
- package/templates/puzzle/package.json +11 -9
- package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
- package/templates/puzzle/playtests/lit.playtest.json +7 -1
- package/templates/puzzle/playtests/performance.playtest.json +7 -1
- package/templates/puzzle/src/render/autoExposure.ts +225 -0
- package/templates/puzzle/src/render/backlightControls.ts +66 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
- package/templates/puzzle/src/render/environmentContribution.ts +188 -0
- package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
- package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
- package/templates/puzzle/src/render/environmentSampling.ts +193 -0
- package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
- package/templates/puzzle/src/render/exposure.ts +111 -0
- package/templates/puzzle/src/render/exposureGraph.ts +178 -0
- package/templates/puzzle/src/render/exposureReadback.ts +79 -0
- package/templates/puzzle/src/render/heightFog.ts +118 -0
- package/templates/puzzle/src/render/lighting.ts +33 -1
- package/templates/puzzle/src/render/materialAssignments.ts +160 -0
- package/templates/puzzle/src/render/materialLighting.ts +155 -0
- package/templates/puzzle/src/render/materials.ts +1 -1
- package/templates/puzzle/src/render/postprocessing.ts +8 -2
- package/templates/puzzle/src/render/quality.ts +62 -1
- package/templates/puzzle/src/render/sky.ts +20 -1
- package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
- package/templates/puzzle/src/scenes/Play.ts +51 -2
- package/templates/puzzle/vite.config.ts +10 -2
- package/templates/racing/AGENTS.md +8 -7
- package/templates/racing/CLAUDE.md +8 -7
- package/templates/racing/package.json +11 -9
- package/templates/racing/playtests/performance.playtest.json +7 -1
- package/templates/racing/playtests/survives.playtest.json +6 -0
- package/templates/racing/src/render/autoExposure.ts +225 -0
- package/templates/racing/src/render/backlightControls.ts +66 -0
- package/templates/racing/src/render/backlightMaterial.ts +147 -0
- package/templates/racing/src/render/environmentContribution.ts +188 -0
- package/templates/racing/src/render/environmentRadiance.ts +36 -0
- package/templates/racing/src/render/environmentSampleCache.ts +43 -0
- package/templates/racing/src/render/environmentSampling.ts +193 -0
- package/templates/racing/src/render/environmentSnapshot.ts +53 -0
- package/templates/racing/src/render/exposure.ts +111 -0
- package/templates/racing/src/render/exposureGraph.ts +178 -0
- package/templates/racing/src/render/exposureReadback.ts +79 -0
- package/templates/racing/src/render/heightFog.ts +118 -0
- package/templates/racing/src/render/lighting.ts +29 -1
- package/templates/racing/src/render/materialAssignments.ts +160 -0
- package/templates/racing/src/render/materialLighting.ts +155 -0
- package/templates/racing/src/render/palette.ts +1 -10
- package/templates/racing/src/render/postprocessing.ts +17 -2
- package/templates/racing/src/render/quality.ts +61 -2
- package/templates/racing/src/render/shapes.ts +0 -25
- package/templates/racing/src/render/sky.ts +21 -1
- package/templates/racing/src/render/worldEnvironment.ts +433 -30
- package/templates/racing/src/scenes/Race.ts +91 -3
- package/templates/racing/src/track/circuit.ts +0 -9
- package/templates/racing/vite.config.ts +10 -2
- package/templates/rain/.codex/config.toml +19 -0
- package/templates/rain/.cursor/mcp.json +32 -0
- package/templates/rain/.gemini/settings.json +32 -0
- package/templates/rain/.mcp.json +32 -0
- package/templates/rain/.vscode/mcp.json +36 -0
- package/templates/rain/.zed/settings.json +36 -0
- package/templates/rain/AGENTS.md +95 -0
- package/templates/rain/CLAUDE.md +97 -0
- package/templates/rain/assets/rain-loop.wav +0 -0
- package/templates/rain/assets/thunder.wav +0 -0
- package/templates/rain/assets/wind-loop.wav +0 -0
- package/templates/rain/index.html +18 -0
- package/templates/rain/kit.json +7 -0
- package/templates/rain/native-playtests/boot.playtest.json +23 -0
- package/templates/rain/native-playtests/lightning.playtest.json +173 -0
- package/templates/rain/opencode.json +41 -0
- package/templates/rain/package.json +59 -0
- package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
- package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
- package/templates/rain/playtests/automation.playtest.json +133 -0
- package/templates/rain/playtests/cinematic.playtest.json +59 -0
- package/templates/rain/playtests/flash.playtest.json +27 -0
- package/templates/rain/playtests/fly.playtest.json +54 -0
- package/templates/rain/playtests/lightning.playtest.json +220 -0
- package/templates/rain/playtests/loading.playtest.json +57 -0
- package/templates/rain/playtests/paused.playtest.json +59 -0
- package/templates/rain/playtests/performance.playtest.json +32 -0
- package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
- package/templates/rain/playtests/simulation.playtest.json +20 -0
- package/templates/rain/playtests/storm.playtest.json +150 -0
- package/templates/rain/playtests/survives.playtest.json +58 -0
- package/templates/rain/playtests/tiers.playtest.json +194 -0
- package/templates/rain/playtests/weather.playtest.json +77 -0
- package/templates/rain/public/favicon.svg +5 -0
- package/templates/rain/src/audio/storm.ts +314 -0
- package/templates/rain/src/game.ts +81 -0
- package/templates/rain/src/main.ts +15 -0
- package/templates/rain/src/render/autoExposure.ts +225 -0
- package/templates/rain/src/render/bloom-shader.ts +65 -0
- package/templates/rain/src/render/camera.ts +160 -0
- package/templates/rain/src/render/clouds-shader.ts +242 -0
- package/templates/rain/src/render/clouds.ts +142 -0
- package/templates/rain/src/render/exposure.ts +111 -0
- package/templates/rain/src/render/exposureGraph.ts +178 -0
- package/templates/rain/src/render/exposureReadback.ts +79 -0
- package/templates/rain/src/render/lighting.ts +39 -0
- package/templates/rain/src/render/lightning.ts +360 -0
- package/templates/rain/src/render/loading.ts +327 -0
- package/templates/rain/src/render/materials.ts +19 -0
- package/templates/rain/src/render/noise-volume.ts +159 -0
- package/templates/rain/src/render/palette.ts +18 -0
- package/templates/rain/src/render/post-shader.ts +178 -0
- package/templates/rain/src/render/postprocessing.ts +229 -0
- package/templates/rain/src/render/quality.ts +161 -0
- package/templates/rain/src/render/rain.ts +299 -0
- package/templates/rain/src/render/sky.ts +28 -0
- package/templates/rain/src/render/world-shader.ts +680 -0
- package/templates/rain/src/render/world.ts +146 -0
- package/templates/rain/src/render/worldEnvironment.ts +1212 -0
- package/templates/rain/src/scenes/Boot.ts +348 -0
- package/templates/rain/src/state.ts +261 -0
- package/templates/rain/src/style.css +1160 -0
- package/templates/rain/src/ui/App.tsx +29 -0
- package/templates/rain/src/ui/GameUi.tsx +187 -0
- package/templates/rain/src/ui/Hud.tsx +327 -0
- package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
- package/templates/rain/src/ui/Menu.tsx +370 -0
- package/templates/rain/src/ui/automation.ts +60 -0
- package/templates/rain/src/ui/main.tsx +7 -0
- package/templates/rain/src/ui/tempest.ts +149 -0
- package/templates/rain/tailwind.config.ts +2 -0
- package/templates/rain/threenative.config.ts +66 -0
- package/templates/rain/tools/generate-shaders.mjs +656 -0
- package/templates/rain/tools/make-storm-audio.mjs +387 -0
- package/templates/rain/tools/storm-dsp.mjs +177 -0
- package/templates/rain/tools/tempest-bloom.frag +10 -0
- package/templates/rain/tools/tempest-clouds.frag +86 -0
- package/templates/rain/tools/tempest-post.frag +47 -0
- package/templates/rain/tools/tempest-world.frag +210 -0
- package/templates/rain/tools/verify-noise-volume.mjs +61 -0
- package/templates/rain/tsconfig.json +17 -0
- package/templates/rain/vite.config.ts +45 -0
- package/templates/rts/AGENTS.md +10 -11
- package/templates/rts/CLAUDE.md +10 -11
- package/templates/rts/package.json +10 -8
- package/templates/rts/playtests/performance.playtest.json +7 -1
- package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-build.playtest.json +10 -1
- package/templates/rts/playtests/rts-orders.playtest.json +7 -1
- package/templates/rts/playtests/rts-train.playtest.json +10 -1
- package/templates/rts/src/render/army.ts +10 -2
- package/templates/rts/src/render/autoExposure.ts +225 -0
- package/templates/rts/src/render/backlightControls.ts +66 -0
- package/templates/rts/src/render/backlightMaterial.ts +147 -0
- package/templates/rts/src/render/environmentContribution.ts +188 -0
- package/templates/rts/src/render/environmentRadiance.ts +36 -0
- package/templates/rts/src/render/environmentSampleCache.ts +43 -0
- package/templates/rts/src/render/environmentSampling.ts +193 -0
- package/templates/rts/src/render/environmentSnapshot.ts +53 -0
- package/templates/rts/src/render/exposure.ts +111 -0
- package/templates/rts/src/render/exposureGraph.ts +178 -0
- package/templates/rts/src/render/exposureReadback.ts +79 -0
- package/templates/rts/src/render/heightFog.ts +118 -0
- package/templates/rts/src/render/lighting.ts +26 -1
- package/templates/rts/src/render/materialAssignments.ts +160 -0
- package/templates/rts/src/render/materialLighting.ts +155 -0
- package/templates/rts/src/render/postprocessing.ts +8 -2
- package/templates/rts/src/render/quality.ts +61 -2
- package/templates/rts/src/render/sky.ts +21 -1
- package/templates/rts/src/render/worldEnvironment.ts +433 -30
- package/templates/rts/src/scenes/Play.ts +54 -3
- package/templates/rts/src/sim/ai.ts +0 -1
- package/templates/rts/src/sim/terrain.ts +0 -4
- package/templates/rts/vite.config.ts +10 -2
- package/templates/runner/AGENTS.md +10 -8
- package/templates/runner/CLAUDE.md +10 -8
- package/templates/runner/package.json +11 -9
- package/templates/runner/playtests/performance.playtest.json +10 -1
- package/templates/runner/src/physics.ts +0 -1
- package/templates/runner/src/render/autoExposure.ts +225 -0
- package/templates/runner/src/render/backlightControls.ts +66 -0
- package/templates/runner/src/render/backlightMaterial.ts +147 -0
- package/templates/runner/src/render/environmentContribution.ts +188 -0
- package/templates/runner/src/render/environmentRadiance.ts +36 -0
- package/templates/runner/src/render/environmentSampleCache.ts +43 -0
- package/templates/runner/src/render/environmentSampling.ts +193 -0
- package/templates/runner/src/render/environmentSnapshot.ts +53 -0
- package/templates/runner/src/render/exposure.ts +111 -0
- package/templates/runner/src/render/exposureGraph.ts +178 -0
- package/templates/runner/src/render/exposureReadback.ts +79 -0
- package/templates/runner/src/render/heightFog.ts +118 -0
- package/templates/runner/src/render/lighting.ts +26 -1
- package/templates/runner/src/render/materialAssignments.ts +160 -0
- package/templates/runner/src/render/materialLighting.ts +155 -0
- package/templates/runner/src/render/postprocessing.ts +17 -2
- package/templates/runner/src/render/quality.ts +61 -2
- package/templates/runner/src/render/sky.ts +21 -1
- package/templates/runner/src/render/worldEnvironment.ts +433 -30
- package/templates/runner/src/scenes/Run.ts +67 -2
- package/templates/runner/threenative.config.ts +3 -0
- package/templates/runner/vite.config.ts +10 -2
- package/templates/sailing/AGENTS.md +14 -13
- package/templates/sailing/CLAUDE.md +14 -13
- package/templates/sailing/native-playtests/survives.playtest.json +7 -0
- package/templates/sailing/package.json +11 -9
- package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
- package/templates/sailing/src/entities/Ship.ts +38 -18
- package/templates/sailing/src/render/autoExposure.ts +225 -0
- package/templates/sailing/src/render/backlightControls.ts +66 -0
- package/templates/sailing/src/render/backlightMaterial.ts +147 -0
- package/templates/sailing/src/render/camera.ts +12 -4
- package/templates/sailing/src/render/environmentContribution.ts +188 -0
- package/templates/sailing/src/render/environmentRadiance.ts +36 -0
- package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
- package/templates/sailing/src/render/environmentSampling.ts +193 -0
- package/templates/sailing/src/render/environmentSetup.ts +24 -0
- package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
- package/templates/sailing/src/render/exposure.ts +111 -0
- package/templates/sailing/src/render/exposureGraph.ts +178 -0
- package/templates/sailing/src/render/exposureReadback.ts +79 -0
- package/templates/sailing/src/render/heightFog.ts +118 -0
- package/templates/sailing/src/render/lighting.ts +26 -1
- package/templates/sailing/src/render/materialAssignments.ts +160 -0
- package/templates/sailing/src/render/materialLighting.ts +155 -0
- package/templates/sailing/src/render/ocean.ts +71 -53
- package/templates/sailing/src/render/postprocessing.ts +16 -2
- package/templates/sailing/src/render/props.ts +0 -45
- package/templates/sailing/src/render/quality.ts +61 -1
- package/templates/sailing/src/render/sky.ts +21 -1
- package/templates/sailing/src/render/worldEnvironment.ts +433 -30
- package/templates/sailing/src/scenes/Boot.ts +12 -1
- package/templates/sailing/src/scenes/Sailing.ts +87 -2
- package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
- package/templates/sailing/threenative.config.ts +3 -0
- package/templates/sailing/vite.config.ts +10 -2
- package/templates/shooter/AGENTS.md +8 -6
- package/templates/shooter/CLAUDE.md +8 -6
- package/templates/shooter/package.json +11 -9
- package/templates/shooter/playtests/performance.playtest.json +7 -1
- package/templates/shooter/src/entities/Enemy.ts +0 -15
- package/templates/shooter/src/entities/Rifle.ts +38 -1
- package/templates/shooter/src/render/autoExposure.ts +225 -0
- package/templates/shooter/src/render/backlightControls.ts +66 -0
- package/templates/shooter/src/render/backlightMaterial.ts +147 -0
- package/templates/shooter/src/render/camera.ts +1 -12
- package/templates/shooter/src/render/decals.ts +299 -5
- package/templates/shooter/src/render/environmentContribution.ts +188 -0
- package/templates/shooter/src/render/environmentRadiance.ts +36 -0
- package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
- package/templates/shooter/src/render/environmentSampling.ts +193 -0
- package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
- package/templates/shooter/src/render/exposure.ts +111 -0
- package/templates/shooter/src/render/exposureGraph.ts +178 -0
- package/templates/shooter/src/render/exposureReadback.ts +79 -0
- package/templates/shooter/src/render/gunfx.ts +0 -1
- package/templates/shooter/src/render/heightFog.ts +118 -0
- package/templates/shooter/src/render/lighting.ts +26 -1
- package/templates/shooter/src/render/materialAssignments.ts +160 -0
- package/templates/shooter/src/render/materialLighting.ts +155 -0
- package/templates/shooter/src/render/postprocessing.ts +17 -2
- package/templates/shooter/src/render/quality.ts +61 -2
- package/templates/shooter/src/render/scale.ts +2 -93
- package/templates/shooter/src/render/sky.ts +21 -1
- package/templates/shooter/src/render/vehicles.ts +0 -17
- package/templates/shooter/src/render/worldEnvironment.ts +433 -30
- package/templates/shooter/src/scenes/Play.ts +64 -2
- package/templates/shooter/vite.config.ts +10 -2
- package/templates/snow/.codex/config.toml +19 -0
- package/templates/snow/.cursor/mcp.json +32 -0
- package/templates/snow/.gemini/settings.json +32 -0
- package/templates/snow/.mcp.json +32 -0
- package/templates/snow/.vscode/mcp.json +36 -0
- package/templates/snow/.zed/settings.json +36 -0
- package/templates/snow/AGENTS.md +90 -0
- package/templates/snow/CLAUDE.md +92 -0
- package/templates/snow/README.md +26 -0
- package/templates/snow/assets/crunch.wav +0 -0
- package/templates/snow/assets/wind.wav +0 -0
- package/templates/snow/index.html +12 -0
- package/templates/snow/kit.json +7 -0
- package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
- package/templates/snow/native-playtests/survives.playtest.json +47 -0
- package/templates/snow/opencode.json +41 -0
- package/templates/snow/package.json +60 -0
- package/templates/snow/playtests/footsteps.playtest.json +95 -0
- package/templates/snow/playtests/performance.playtest.json +36 -0
- package/templates/snow/playtests/snow-physics.playtest.json +154 -0
- package/templates/snow/playtests/survives.playtest.json +56 -0
- package/templates/snow/playtests/touch-controls.playtest.json +71 -0
- package/templates/snow/playtests/weather.playtest.json +119 -0
- package/templates/snow/public/favicon.svg +5 -0
- package/templates/snow/src/audio.ts +58 -0
- package/templates/snow/src/commands.ts +8 -0
- package/templates/snow/src/entities/Explorer.ts +279 -0
- package/templates/snow/src/game.ts +69 -0
- package/templates/snow/src/main.ts +15 -0
- package/templates/snow/src/render/autoExposure.ts +225 -0
- package/templates/snow/src/render/backlightControls.ts +66 -0
- package/templates/snow/src/render/backlightMaterial.ts +147 -0
- package/templates/snow/src/render/bootPrint.ts +50 -0
- package/templates/snow/src/render/camera.ts +84 -0
- package/templates/snow/src/render/environmentContribution.ts +188 -0
- package/templates/snow/src/render/environmentRadiance.ts +36 -0
- package/templates/snow/src/render/environmentSampleCache.ts +43 -0
- package/templates/snow/src/render/environmentSampling.ts +193 -0
- package/templates/snow/src/render/environmentSnapshot.ts +53 -0
- package/templates/snow/src/render/explorer.ts +321 -0
- package/templates/snow/src/render/exposure.ts +111 -0
- package/templates/snow/src/render/exposureGraph.ts +178 -0
- package/templates/snow/src/render/exposureReadback.ts +79 -0
- package/templates/snow/src/render/heightFog.ts +118 -0
- package/templates/snow/src/render/lighting.ts +82 -0
- package/templates/snow/src/render/loading.ts +325 -0
- package/templates/snow/src/render/materialAssignments.ts +160 -0
- package/templates/snow/src/render/materialLighting.ts +155 -0
- package/templates/snow/src/render/materials.ts +36 -0
- package/templates/snow/src/render/palette.ts +17 -0
- package/templates/snow/src/render/postprocessing.ts +58 -0
- package/templates/snow/src/render/props.ts +42 -0
- package/templates/snow/src/render/quality.ts +193 -0
- package/templates/snow/src/render/scenery.ts +244 -0
- package/templates/snow/src/render/sky.ts +76 -0
- package/templates/snow/src/render/snowSurface.ts +259 -0
- package/templates/snow/src/render/touch-controls.ts +143 -0
- package/templates/snow/src/render/weather.ts +279 -0
- package/templates/snow/src/render/worldEnvironment.ts +1212 -0
- package/templates/snow/src/scenes/Boot.ts +12 -0
- package/templates/snow/src/scenes/Snow.ts +663 -0
- package/templates/snow/src/state.ts +46 -0
- package/templates/snow/src/style.css +143 -0
- package/templates/snow/src/terrain.ts +64 -0
- package/templates/snow/src/ui/App.tsx +15 -0
- package/templates/snow/src/ui/Controls.tsx +322 -0
- package/templates/snow/src/ui/GameUi.tsx +354 -0
- package/templates/snow/src/ui/icons.tsx +54 -0
- package/templates/snow/src/ui/main.tsx +7 -0
- package/templates/snow/tailwind.config.ts +2 -0
- package/templates/snow/threenative.config.ts +54 -0
- package/templates/snow/tsconfig.json +17 -0
- package/templates/snow/vite.config.ts +45 -0
- package/templates/starter/AGENTS.md +11 -16
- package/templates/starter/CLAUDE.md +11 -16
- package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
- package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
- package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
- package/templates/starter/package.json +11 -9
- package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
- package/templates/starter/playtests/movement.playtest.json +192 -0
- package/templates/starter/playtests/play.playtest.json +18 -2
- package/templates/starter/playtests/production-readiness.playtest.json +1 -1
- package/templates/starter/public/grade.cube +735 -0
- package/templates/starter/src/entities/Crate.ts +4 -0
- package/templates/starter/src/entities/Player.ts +79 -18
- package/templates/starter/src/game.ts +1 -0
- package/templates/starter/src/render/adaptiveQuality.ts +28 -41
- package/templates/starter/src/render/autoExposure.ts +225 -0
- package/templates/starter/src/render/backlightControls.ts +66 -0
- package/templates/starter/src/render/backlightMaterial.ts +147 -0
- package/templates/starter/src/render/environmentContribution.ts +188 -0
- package/templates/starter/src/render/environmentRadiance.ts +36 -0
- package/templates/starter/src/render/environmentSampleCache.ts +43 -0
- package/templates/starter/src/render/environmentSampling.ts +193 -0
- package/templates/starter/src/render/environmentSnapshot.ts +53 -0
- package/templates/starter/src/render/exposure.ts +111 -0
- package/templates/starter/src/render/exposureGraph.ts +178 -0
- package/templates/starter/src/render/exposureReadback.ts +79 -0
- package/templates/starter/src/render/grade.ts +157 -0
- package/templates/starter/src/render/heightFog.ts +118 -0
- package/templates/starter/src/render/lighting.ts +26 -1
- package/templates/starter/src/render/materialAssignments.ts +160 -0
- package/templates/starter/src/render/materialLighting.ts +155 -0
- package/templates/starter/src/render/postprocessing.ts +84 -4
- package/templates/starter/src/render/quality.ts +80 -8
- package/templates/starter/src/render/qualityPolicy.ts +54 -0
- package/templates/starter/src/render/rendererGate.ts +36 -0
- package/templates/starter/src/render/sky.ts +23 -1
- package/templates/starter/src/render/temporalAA.ts +197 -0
- package/templates/starter/src/render/temporalAAFrame.ts +179 -0
- package/templates/starter/src/render/temporalAAHooks.ts +101 -0
- package/templates/starter/src/render/temporalAAInput.ts +56 -0
- package/templates/starter/src/render/temporalAAResolve.ts +65 -0
- package/templates/starter/src/render/temporalAAStage.ts +76 -0
- package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
- package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
- package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
- package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
- package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
- package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
- package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
- package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
- package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
- package/templates/starter/src/render/temporalResolve.ts +139 -0
- package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
- package/templates/starter/src/render/temporalResolveMath.ts +196 -0
- package/templates/starter/src/render/volumetricFog.ts +124 -0
- package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
- package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
- package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
- package/templates/starter/src/render/worldEnvironment.ts +433 -30
- package/templates/starter/src/scenes/Play.ts +110 -1
- package/templates/starter/src/state.ts +1 -0
- package/templates/starter/src/ui/Hud.tsx +1 -1
- package/templates/starter/src/ui/Menu.tsx +1 -1
- package/templates/starter/tools/make-grade-lut.mjs +101 -0
- package/templates/starter/vite.config.ts +10 -2
- package/templates/tower-defense/AGENTS.md +10 -9
- package/templates/tower-defense/CLAUDE.md +10 -9
- package/templates/tower-defense/package.json +11 -9
- package/templates/tower-defense/playtests/performance.playtest.json +7 -1
- package/templates/tower-defense/src/render/autoExposure.ts +225 -0
- package/templates/tower-defense/src/render/backlightControls.ts +66 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
- package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
- package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
- package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
- package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
- package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
- package/templates/tower-defense/src/render/exposure.ts +111 -0
- package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
- package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
- package/templates/tower-defense/src/render/lighting.ts +33 -1
- package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
- package/templates/tower-defense/src/render/materialLighting.ts +155 -0
- package/templates/tower-defense/src/render/postprocessing.ts +8 -2
- package/templates/tower-defense/src/render/quality.ts +61 -2
- package/templates/tower-defense/src/render/shapes.ts +0 -3
- package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
- package/templates/tower-defense/src/scenes/Battle.ts +65 -2
- package/templates/tower-defense/vite.config.ts +10 -2
- package/templates/minimal/src/scenes/Boot.ts +0 -5
|
@@ -3,6 +3,7 @@ import {
|
|
|
3
3
|
type IRandom,
|
|
4
4
|
Scene,
|
|
5
5
|
type SceneFrame,
|
|
6
|
+
getPlatform,
|
|
6
7
|
isMobile,
|
|
7
8
|
isTouchscreenAvailable,
|
|
8
9
|
} from "@threenative/core";
|
|
@@ -22,8 +23,10 @@ import { Seal } from "../entities/Seal.js";
|
|
|
22
23
|
import { WARDEN_SPAWN, Warden } from "../entities/Warden.js";
|
|
23
24
|
import { createVaultCamera } from "../render/camera.js";
|
|
24
25
|
import { CRATE_SIZE } from "../render/crateShape.js";
|
|
26
|
+
import { type IEnvironmentSample, sampleEnvironment } from "../render/environmentSampling.js";
|
|
25
27
|
import { setupLighting } from "../render/lighting.js";
|
|
26
28
|
import { createLoadingScreen } from "../render/loading.js";
|
|
29
|
+
import { createMaterialLighting } from "../render/materialLighting.js";
|
|
27
30
|
import {
|
|
28
31
|
crateBraceMaterial,
|
|
29
32
|
crateMaterials,
|
|
@@ -32,6 +35,7 @@ import {
|
|
|
32
35
|
phaseMaterial,
|
|
33
36
|
} from "../render/materials.js";
|
|
34
37
|
import { setupPost } from "../render/postprocessing.js";
|
|
38
|
+
import { isWebGLFallbackRenderer, materialLightingEnabled } from "../render/quality.js";
|
|
35
39
|
import { setupSky } from "../render/sky.js";
|
|
36
40
|
import { TouchControls } from "../render/touch-controls.js";
|
|
37
41
|
import { SEAL, VAULT, createVaultRoom } from "../render/vault.js";
|
|
@@ -109,6 +113,18 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
109
113
|
#banner: Mesh | undefined;
|
|
110
114
|
#statics: RigidBody3D[] = [];
|
|
111
115
|
|
|
116
|
+
#environmentSample: IEnvironmentSample | undefined;
|
|
117
|
+
#materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
|
|
118
|
+
#post: ReturnType<typeof setupPost> | undefined;
|
|
119
|
+
#materialEnvironment(ctx: GameCtx) {
|
|
120
|
+
return {
|
|
121
|
+
web: getPlatform().runtime === "web",
|
|
122
|
+
rendererKind: ctx.renderer.kind,
|
|
123
|
+
webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
|
|
124
|
+
mobile: isMobile(),
|
|
125
|
+
software: ctx.renderer.softwareAdapter !== undefined,
|
|
126
|
+
};
|
|
127
|
+
}
|
|
112
128
|
static override readonly initialState: GameState = {
|
|
113
129
|
blockedTicks: 0,
|
|
114
130
|
crates: 0,
|
|
@@ -184,6 +200,12 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
184
200
|
if (banner === undefined) throw new Error("Proof glTF did not contain a mesh.");
|
|
185
201
|
this.#banner = banner;
|
|
186
202
|
console.info("TN_NATIVE_STARTER_ASSETS_LOADED:texture,glb");
|
|
203
|
+
setupSky(ctx.scene);
|
|
204
|
+
this.#environmentSample = await sampleEnvironment(
|
|
205
|
+
ctx.renderer.raw,
|
|
206
|
+
ctx.scene,
|
|
207
|
+
this.#materialEnvironment(ctx),
|
|
208
|
+
);
|
|
187
209
|
}
|
|
188
210
|
|
|
189
211
|
override enter(ctx: GameCtx): SceneFrame<GameState, IPhysicsContext> {
|
|
@@ -199,10 +221,15 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
199
221
|
);
|
|
200
222
|
// isMobile() arrives as an argument because src/render/ imports no framework package: the
|
|
201
223
|
// platform decision is made here, in portable game code.
|
|
202
|
-
setupPost(ctx.renderer, ctx.scene, ctx.camera, {
|
|
224
|
+
this.#post = setupPost(ctx.renderer, ctx.scene, ctx.camera, {
|
|
203
225
|
godraysLight: sun,
|
|
204
226
|
mobile: isMobile(),
|
|
205
227
|
software: ctx.renderer.softwareAdapter !== undefined,
|
|
228
|
+
gpuClass: ctx.renderer.gpuClass?.class,
|
|
229
|
+
onTierChanged: (tier) =>
|
|
230
|
+
this.#materialLighting?.setEnabled(
|
|
231
|
+
materialLightingEnabled(tier, this.#materialEnvironment(ctx)),
|
|
232
|
+
),
|
|
206
233
|
});
|
|
207
234
|
const loading = createLoadingScreen(ctx);
|
|
208
235
|
const room = createVaultRoom();
|
|
@@ -318,7 +345,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
318
345
|
/** V pressed before the opening drop finished: honoured as soon as it has. */
|
|
319
346
|
let replayRequested = false;
|
|
320
347
|
|
|
321
|
-
|
|
348
|
+
seal.watch({
|
|
322
349
|
isCrate: (body) => crateBodies.has(body),
|
|
323
350
|
onContact: (by) => {
|
|
324
351
|
// The seal is switched off for the duration of the replay, so anything that reaches it
|
|
@@ -400,6 +427,23 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
400
427
|
|
|
401
428
|
const frameState: Partial<GameState> = {};
|
|
402
429
|
|
|
430
|
+
this.#materialLighting = ctx.entities.add(
|
|
431
|
+
"material-lighting",
|
|
432
|
+
createMaterialLighting(ctx.scene, ctx.camera, sun, {
|
|
433
|
+
...this.#materialEnvironment(ctx),
|
|
434
|
+
enabled: materialLightingEnabled(this.#post.tier, this.#materialEnvironment(ctx)),
|
|
435
|
+
}),
|
|
436
|
+
);
|
|
437
|
+
if (this.#environmentSample !== undefined) {
|
|
438
|
+
const { measurement, source, intensity } = this.#environmentSample;
|
|
439
|
+
this.#materialLighting.setEnvironmentMeasurement(
|
|
440
|
+
measurement,
|
|
441
|
+
source,
|
|
442
|
+
intensity,
|
|
443
|
+
this.#environmentSample,
|
|
444
|
+
);
|
|
445
|
+
}
|
|
446
|
+
|
|
403
447
|
// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame is the vault's whole
|
|
404
448
|
// per-tick bookkeeping — the two replay passes, the settle test, the push tally and the state
|
|
405
449
|
// flush — and splitting it would move the wiring between three closures that all share it.
|
|
@@ -550,6 +594,11 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
550
594
|
}
|
|
551
595
|
|
|
552
596
|
override exit(ctx: GameCtx): void {
|
|
597
|
+
this.#materialLighting?.dispose();
|
|
598
|
+
this.#materialLighting = undefined;
|
|
599
|
+
this.#post?.dispose();
|
|
600
|
+
this.#post = undefined;
|
|
601
|
+
|
|
553
602
|
for (const body of this.#statics) body.dispose();
|
|
554
603
|
this.#statics = [];
|
|
555
604
|
super.exit(ctx);
|
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import tailwindcss from "@tailwindcss/vite";
|
|
2
2
|
import { watchAssets } from "@threenative/assets";
|
|
3
3
|
import react from "@vitejs/plugin-react";
|
|
4
|
-
import {
|
|
4
|
+
import {
|
|
5
|
+
createEngineFreshnessPlugin,
|
|
6
|
+
createWebBrandPlugin,
|
|
7
|
+
webRuntimeDecoders,
|
|
8
|
+
} from "create-threenative";
|
|
5
9
|
import { defineConfig } from "vite";
|
|
6
10
|
import type { Plugin } from "vite";
|
|
7
11
|
import config from "./threenative.config.js";
|
|
@@ -15,7 +19,11 @@ function assetsWatchPlugin(): Plugin {
|
|
|
15
19
|
name: "threenative-assets-watch",
|
|
16
20
|
apply: "serve",
|
|
17
21
|
async configureServer(server) {
|
|
18
|
-
const handle = watchAssets({
|
|
22
|
+
const handle = watchAssets({
|
|
23
|
+
config: config.assets,
|
|
24
|
+
cwd: server.config.root,
|
|
25
|
+
runtimeDecoders: webRuntimeDecoders(config),
|
|
26
|
+
});
|
|
19
27
|
server.httpServer?.once("close", () => handle.close());
|
|
20
28
|
// Nothing is served before the first cook settles: until it does, `public/` has no
|
|
21
29
|
// `assets.manifest.json` and every asset answers from its source fallback.
|
|
@@ -3,8 +3,7 @@
|
|
|
3
3
|
Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
|
|
4
4
|
|
|
5
5
|
## Ownership
|
|
6
|
-
|
|
7
|
-
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the car feel, track, race rules, rescue, HUD, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. A bullet that passes through a wall is not a collider bug: `RigidBody3D` defaults to continuous collision, `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
|
|
6
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the car feel, track, race rules, rescue, HUD, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. A bullet that passes through a wall is not a collider bug: `RigidBody3D` defaults to continuous collision, `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
|
|
8
7
|
|
|
9
8
|
## Start every change
|
|
10
9
|
|
|
@@ -34,7 +33,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
|
|
|
34
33
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
35
34
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
36
35
|
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
37
|
-
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
|
|
36
|
+
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind Mesh.computeBoundingSphere yet. The pin keeps upstream Three.js on web and the legacy host on desktop. Android and iOS use the legacy host.
|
|
38
37
|
|
|
39
38
|
## Commands and map
|
|
40
39
|
|
|
@@ -66,12 +65,12 @@ Leave `assets` absent: the cook selects target-decodable passes, with `models.sh
|
|
|
66
65
|
|
|
67
66
|
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
|
|
68
67
|
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable.
|
|
69
|
-
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without
|
|
68
|
+
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `ctx.goto(name)` rebuilds without
|
|
70
69
|
resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
|
|
71
70
|
is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
|
|
72
71
|
state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
73
72
|
|
|
74
|
-
`src/render/quality.ts` owns `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise `high`;
|
|
73
|
+
WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`;
|
|
75
74
|
override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
|
|
76
75
|
the source. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
|
|
77
76
|
|
|
@@ -82,7 +81,7 @@ caught where a bone-direction check reads zero. `clipTrackBindings` names tracks
|
|
|
82
81
|
(the `<bone>.undefined` failure that plays the bind pose instead of the animation),
|
|
83
82
|
`clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
|
|
84
83
|
clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
|
|
85
|
-
supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches
|
|
84
|
+
supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
|
|
86
85
|
|
|
87
86
|
## Budget real time for the look
|
|
88
87
|
|
|
@@ -90,6 +89,8 @@ Reference-driven authoring starts at `node_modules/create-threenative/agent-docs
|
|
|
90
89
|
|
|
91
90
|
Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
92
91
|
|
|
93
|
-
Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
92
|
+
For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
94
93
|
## Optional multiplayer transport
|
|
95
94
|
For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
|
|
95
|
+
Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
|
|
96
|
+
`src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
|
|
@@ -5,8 +5,7 @@
|
|
|
5
5
|
Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
|
|
6
6
|
|
|
7
7
|
## Ownership
|
|
8
|
-
|
|
9
|
-
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the car feel, track, race rules, rescue, HUD, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. A bullet that passes through a wall is not a collider bug: `RigidBody3D` defaults to continuous collision, `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
|
|
8
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the car feel, track, race rules, rescue, HUD, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. A bullet that passes through a wall is not a collider bug: `RigidBody3D` defaults to continuous collision, `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
|
|
10
9
|
|
|
11
10
|
## Start every change
|
|
12
11
|
|
|
@@ -36,7 +35,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
|
|
|
36
35
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
37
36
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
38
37
|
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
39
|
-
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
|
|
38
|
+
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind Mesh.computeBoundingSphere yet. The pin keeps upstream Three.js on web and the legacy host on desktop. Android and iOS use the legacy host.
|
|
40
39
|
|
|
41
40
|
## Commands and map
|
|
42
41
|
|
|
@@ -68,12 +67,12 @@ Leave `assets` absent: the cook selects target-decodable passes, with `models.sh
|
|
|
68
67
|
|
|
69
68
|
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
|
|
70
69
|
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable.
|
|
71
|
-
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without
|
|
70
|
+
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `ctx.goto(name)` rebuilds without
|
|
72
71
|
resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
|
|
73
72
|
is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
|
|
74
73
|
state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
75
74
|
|
|
76
|
-
`src/render/quality.ts` owns `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise `high`;
|
|
75
|
+
WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`;
|
|
77
76
|
override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
|
|
78
77
|
the source. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
|
|
79
78
|
|
|
@@ -84,7 +83,7 @@ caught where a bone-direction check reads zero. `clipTrackBindings` names tracks
|
|
|
84
83
|
(the `<bone>.undefined` failure that plays the bind pose instead of the animation),
|
|
85
84
|
`clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
|
|
86
85
|
clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
|
|
87
|
-
supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches
|
|
86
|
+
supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
|
|
88
87
|
|
|
89
88
|
## Budget real time for the look
|
|
90
89
|
|
|
@@ -92,6 +91,8 @@ Reference-driven authoring starts at `node_modules/create-threenative/agent-docs
|
|
|
92
91
|
|
|
93
92
|
Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
94
93
|
|
|
95
|
-
Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
94
|
+
For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
96
95
|
## Optional multiplayer transport
|
|
97
96
|
For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
|
|
97
|
+
Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
|
|
98
|
+
`src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
|
|
@@ -16,9 +16,9 @@
|
|
|
16
16
|
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
17
17
|
},
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"@threenative/core": "0.3.
|
|
20
|
-
"@threenative/physics": "0.3.
|
|
21
|
-
"@threenative/ui": "0.3.
|
|
19
|
+
"@threenative/core": "0.3.5",
|
|
20
|
+
"@threenative/physics": "0.3.5",
|
|
21
|
+
"@threenative/ui": "0.3.5",
|
|
22
22
|
"react": "19.2.0",
|
|
23
23
|
"react-dom": "19.2.0",
|
|
24
24
|
"three": "0.185.1"
|
|
@@ -26,21 +26,21 @@
|
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@gltf-transform/cli": "4.4.2",
|
|
28
28
|
"@tailwindcss/vite": "4.3.3",
|
|
29
|
-
"@threenative/assets": "0.3.
|
|
30
|
-
"@threenative/playtest": "0.3.
|
|
29
|
+
"@threenative/assets": "0.3.6",
|
|
30
|
+
"@threenative/playtest": "0.3.5",
|
|
31
31
|
"@types/react": "19.2.0",
|
|
32
32
|
"@types/react-dom": "19.2.0",
|
|
33
33
|
"@types/three": "0.185.3",
|
|
34
34
|
"@vitejs/plugin-react": "6.0.5",
|
|
35
|
-
"create-threenative": "0.2.
|
|
35
|
+
"create-threenative": "0.2.9",
|
|
36
36
|
"esbuild": "0.27.0",
|
|
37
37
|
"playwright": "1.62.1",
|
|
38
38
|
"tailwindcss": "4.3.3",
|
|
39
|
-
"typescript": "
|
|
39
|
+
"typescript": "7.0.2",
|
|
40
40
|
"vite": "8.2.0"
|
|
41
41
|
},
|
|
42
42
|
"optionalDependencies": {
|
|
43
|
-
"@threenative/runtime-native": "0.3.
|
|
43
|
+
"@threenative/runtime-native": "0.3.5"
|
|
44
44
|
},
|
|
45
45
|
"overrides": {
|
|
46
46
|
"sharp": ">=0.35.4"
|
|
@@ -51,7 +51,9 @@
|
|
|
51
51
|
},
|
|
52
52
|
"onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
|
|
53
53
|
"patchedDependencies": {
|
|
54
|
-
"three@0.185.1": "patches/three@0.185.1.patch"
|
|
54
|
+
"three@0.185.1": "patches/three@0.185.1.patch",
|
|
55
|
+
"vite@8.2.0": "patches/vite@8.2.0.patch",
|
|
56
|
+
"@tailwindcss/node@4.3.3": "patches/@tailwindcss__node@4.3.3.patch"
|
|
55
57
|
}
|
|
56
58
|
}
|
|
57
59
|
}
|
|
@@ -12,7 +12,13 @@
|
|
|
12
12
|
},
|
|
13
13
|
"renderChain": {
|
|
14
14
|
"tier": "high",
|
|
15
|
-
"perAdapter": {
|
|
15
|
+
"perAdapter": {
|
|
16
|
+
"integrated": { "tier": "medium" },
|
|
17
|
+
"mobile-high": { "tier": "medium" },
|
|
18
|
+
"mobile-low": { "tier": "low" },
|
|
19
|
+
"mobile-mid": { "tier": "low" },
|
|
20
|
+
"software": { "tier": "low" }
|
|
21
|
+
}
|
|
16
22
|
}
|
|
17
23
|
},
|
|
18
24
|
"name": "production-performance",
|
|
@@ -36,6 +36,12 @@
|
|
|
36
36
|
"component": "normaliseFactor",
|
|
37
37
|
"entity": "player",
|
|
38
38
|
"lte": 0.99
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"allowTrivial": "The gap is held near zero by the sun target's world matrix; the target sits at the origin, tens of metres from the car, until a scene traversal refreshes it.",
|
|
42
|
+
"component": "targetGap",
|
|
43
|
+
"entity": "sun",
|
|
44
|
+
"lte": 1.5
|
|
39
45
|
}
|
|
40
46
|
],
|
|
41
47
|
"movement": {
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
// Generated for you: ordinary Three.js GPU metering; exposure.ts owns the game's look.
|
|
2
|
+
import { type RenderTarget, Texture, Vector2 } from "three";
|
|
3
|
+
import { float, ivec2, nodeObject, texture, textureLoad, uniform, vec4 } from "three/tsl";
|
|
4
|
+
import {
|
|
5
|
+
type Node,
|
|
6
|
+
type NodeBuilder,
|
|
7
|
+
type NodeFrame,
|
|
8
|
+
NodeMaterial,
|
|
9
|
+
NodeUpdateType,
|
|
10
|
+
QuadMesh,
|
|
11
|
+
type Renderer,
|
|
12
|
+
RendererUtils,
|
|
13
|
+
TempNode,
|
|
14
|
+
} from "three/webgpu";
|
|
15
|
+
import {
|
|
16
|
+
type IExposureSettings,
|
|
17
|
+
exposureLuminance,
|
|
18
|
+
exposureMeter,
|
|
19
|
+
exposureReductionSizes,
|
|
20
|
+
validateExposureSettings,
|
|
21
|
+
} from "./exposure.js";
|
|
22
|
+
|
|
23
|
+
import {
|
|
24
|
+
type ColourTexture,
|
|
25
|
+
type Decode,
|
|
26
|
+
type Meter,
|
|
27
|
+
adaptExposure,
|
|
28
|
+
exposureBins,
|
|
29
|
+
exposureTarget,
|
|
30
|
+
exposureTiles,
|
|
31
|
+
histogramExposure,
|
|
32
|
+
histogramTiles,
|
|
33
|
+
reduceExposure,
|
|
34
|
+
} from "./exposureGraph.js";
|
|
35
|
+
import { ExposureReadback } from "./exposureReadback.js";
|
|
36
|
+
|
|
37
|
+
/** Scene-referred exposure changes light, never coverage/compositing alpha. */
|
|
38
|
+
export function applyExposure(colour: Node<"vec4">, exposure: Node<"float">): Node<"vec4"> {
|
|
39
|
+
return vec4(colour.rgb.mul(exposure), colour.a);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Owns scratch targets only. Never draws the world or installs another output transform. */
|
|
43
|
+
export class AutoExposureNode extends TempNode<"float"> {
|
|
44
|
+
static get type(): string {
|
|
45
|
+
return "AutoExposureNode";
|
|
46
|
+
}
|
|
47
|
+
readonly input: ColourTexture;
|
|
48
|
+
readonly settings: Readonly<IExposureSettings>;
|
|
49
|
+
readonly #constant: number;
|
|
50
|
+
readonly #size = new Vector2();
|
|
51
|
+
readonly #sourceSize = uniform(new Vector2(1, 1));
|
|
52
|
+
readonly #reduceSize = uniform(new Vector2(1, 1));
|
|
53
|
+
readonly #blockSize = uniform(new Vector2(1, 1));
|
|
54
|
+
readonly #delta = uniform(0);
|
|
55
|
+
readonly #resetMode = uniform(1); // 0 = history, 1 = seed, 2 = next measured target
|
|
56
|
+
readonly #seed = uniform(0);
|
|
57
|
+
readonly #enabled = uniform(false);
|
|
58
|
+
readonly #quad = new QuadMesh();
|
|
59
|
+
readonly #meterMaterial = new NodeMaterial();
|
|
60
|
+
readonly #reduceMaterial = new NodeMaterial();
|
|
61
|
+
readonly #tilesMaterial = new NodeMaterial();
|
|
62
|
+
readonly #histogramMaterial = new NodeMaterial();
|
|
63
|
+
readonly #adaptMaterial = new NodeMaterial();
|
|
64
|
+
readonly #tilesTarget = exposureTarget();
|
|
65
|
+
readonly #histogramTarget = exposureTarget();
|
|
66
|
+
#readTarget = exposureTarget();
|
|
67
|
+
#writeTarget = exposureTarget();
|
|
68
|
+
#levels: RenderTarget[] = [];
|
|
69
|
+
readonly #reduced = texture(new Texture());
|
|
70
|
+
readonly #blocks = texture(new Texture());
|
|
71
|
+
readonly #previous = texture(this.#readTarget.texture);
|
|
72
|
+
readonly #result = texture(this.#writeTarget.texture);
|
|
73
|
+
#disposed = false;
|
|
74
|
+
readonly #observation: ExposureReadback;
|
|
75
|
+
// Three's runtime accepts undefined on first use, but its declaration requires a state.
|
|
76
|
+
#rendererState: Parameters<typeof RendererUtils.resetRendererState>[1] | undefined;
|
|
77
|
+
|
|
78
|
+
constructor(
|
|
79
|
+
input: ColourTexture,
|
|
80
|
+
settings: IExposureSettings,
|
|
81
|
+
constantExposure: number,
|
|
82
|
+
meter: Meter = (colour, uv) => exposureMeter(colour, uv),
|
|
83
|
+
decode: Decode = (mean) => exposureLuminance(mean),
|
|
84
|
+
) {
|
|
85
|
+
super("float");
|
|
86
|
+
validateExposureSettings(settings);
|
|
87
|
+
if (!Number.isFinite(Math.fround(constantExposure)) || Math.fround(constantExposure) <= 0)
|
|
88
|
+
throw new Error("Exposure constant must be finite and positive.");
|
|
89
|
+
this.input = input;
|
|
90
|
+
this.settings = Object.freeze({ ...settings });
|
|
91
|
+
const policy = this.settings;
|
|
92
|
+
this.#constant = constantExposure;
|
|
93
|
+
this.#seed.value = Math.log2(settings.initialExposure);
|
|
94
|
+
this.#enabled.value = settings.enabled;
|
|
95
|
+
this.#observation = new ExposureReadback(constantExposure, () => this.#enabled.value);
|
|
96
|
+
this.updateBeforeType = NodeUpdateType.FRAME;
|
|
97
|
+
this.#meterMaterial.fragmentNode = reduceExposure(input, this.#sourceSize, meter);
|
|
98
|
+
this.#reduceMaterial.fragmentNode = reduceExposure(this.#reduced, this.#reduceSize);
|
|
99
|
+
this.#tilesTarget.setSize(exposureBins, exposureTiles);
|
|
100
|
+
this.#histogramTarget.setSize(exposureBins, 1);
|
|
101
|
+
this.#tilesMaterial.fragmentNode = histogramTiles(this.#blocks, this.#blockSize, policy);
|
|
102
|
+
this.#histogramMaterial.fragmentNode = histogramExposure(texture(this.#tilesTarget.texture));
|
|
103
|
+
this.#adaptMaterial.fragmentNode = adaptExposure(
|
|
104
|
+
texture(this.#histogramTarget.texture),
|
|
105
|
+
this.#previous,
|
|
106
|
+
this.#resetMode,
|
|
107
|
+
this.#seed,
|
|
108
|
+
this.#delta,
|
|
109
|
+
policy,
|
|
110
|
+
decode,
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
override setup(builder: NodeBuilder): Node<"float"> {
|
|
115
|
+
// Force the existing pass dependency even in disabled mode; off never means unmeasured.
|
|
116
|
+
super.setup(builder);
|
|
117
|
+
return this.#enabled.select(
|
|
118
|
+
textureLoad(this.#result, ivec2(0)).r.exp2(),
|
|
119
|
+
float(this.#constant),
|
|
120
|
+
);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
get exposureNode(): Node<"float"> {
|
|
124
|
+
return nodeObject(this);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
reset(exposure?: number): void {
|
|
128
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
129
|
+
if (
|
|
130
|
+
exposure !== undefined &&
|
|
131
|
+
(!Number.isFinite(Math.fround(exposure)) || Math.fround(exposure) <= 0)
|
|
132
|
+
)
|
|
133
|
+
throw new Error("Exposure reset must be finite and positive.");
|
|
134
|
+
this.#resetMode.value = exposure === undefined ? 2 : 1;
|
|
135
|
+
if (exposure !== undefined) this.#seed.value = Math.log2(exposure);
|
|
136
|
+
this.#observation.invalidate();
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
setEnabled(enabled: boolean): void {
|
|
140
|
+
if (typeof enabled !== "boolean") throw new Error("Exposure enabled must be boolean.");
|
|
141
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
142
|
+
this.#enabled.value = enabled;
|
|
143
|
+
this.#observation.invalidate();
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
getObservation(): Record<string, unknown> {
|
|
147
|
+
return this.#observation.get();
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
override updateBefore(frame: NodeFrame): undefined {
|
|
151
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
152
|
+
const renderer = frame.renderer;
|
|
153
|
+
if (renderer === null) throw new Error("Exposure requires a renderer.");
|
|
154
|
+
if (!Number.isFinite(frame.deltaTime) || frame.deltaTime < 0 || !Number.isFinite(frame.time))
|
|
155
|
+
throw new Error("Exposure frame time must be finite and nonnegative.");
|
|
156
|
+
renderer.getDrawingBufferSize(this.#size);
|
|
157
|
+
// Level 0 meters 4x4 pixels, level 1 averages 16x16. The histogram gathers level 1.
|
|
158
|
+
const sizes = exposureReductionSizes(this.#size.x, this.#size.y).slice(0, 2);
|
|
159
|
+
this.#sourceSize.value.copy(this.#size);
|
|
160
|
+
this.#delta.value = Math.min(frame.deltaTime, this.settings.maxDelta);
|
|
161
|
+
while (this.#levels.length > sizes.length) this.#levels.pop()?.dispose();
|
|
162
|
+
for (const [i, [width, height]] of sizes.entries()) {
|
|
163
|
+
const level = this.#levels[i] ?? exposureTarget();
|
|
164
|
+
this.#levels[i] = level;
|
|
165
|
+
level.setSize(width, height);
|
|
166
|
+
}
|
|
167
|
+
this.#rendererState ??= RendererUtils.saveRendererState(renderer);
|
|
168
|
+
this.#rendererState = RendererUtils.resetRendererState(renderer, this.#rendererState);
|
|
169
|
+
try {
|
|
170
|
+
for (const [i, level] of this.#levels.entries()) {
|
|
171
|
+
const previous = this.#levels[i - 1];
|
|
172
|
+
if (previous !== undefined) {
|
|
173
|
+
this.#reduced.value = previous.texture;
|
|
174
|
+
this.#reduceSize.value.set(previous.width, previous.height);
|
|
175
|
+
}
|
|
176
|
+
this.#quad.material = i === 0 ? this.#meterMaterial : this.#reduceMaterial;
|
|
177
|
+
renderer.setRenderTarget(level);
|
|
178
|
+
this.#quad.render(renderer);
|
|
179
|
+
}
|
|
180
|
+
const final = this.#levels.at(-1);
|
|
181
|
+
if (final === undefined) throw new Error("Exposure reduction is empty.");
|
|
182
|
+
this.#blocks.value = final.texture;
|
|
183
|
+
this.#blockSize.value.set(final.width, final.height);
|
|
184
|
+
this.#quad.material = this.#tilesMaterial;
|
|
185
|
+
renderer.setRenderTarget(this.#tilesTarget);
|
|
186
|
+
this.#quad.render(renderer);
|
|
187
|
+
this.#quad.material = this.#histogramMaterial;
|
|
188
|
+
renderer.setRenderTarget(this.#histogramTarget);
|
|
189
|
+
this.#quad.render(renderer);
|
|
190
|
+
const write = this.#writeTarget;
|
|
191
|
+
this.#previous.value = this.#readTarget.texture;
|
|
192
|
+
this.#quad.material = this.#adaptMaterial;
|
|
193
|
+
renderer.setRenderTarget(write);
|
|
194
|
+
this.#quad.render(renderer);
|
|
195
|
+
this.#result.value = write.texture;
|
|
196
|
+
this.#writeTarget = this.#readTarget;
|
|
197
|
+
this.#readTarget = write;
|
|
198
|
+
this.#resetMode.value = 0;
|
|
199
|
+
this.#observation.report(renderer, write, frame.time, this.settings.reportInterval);
|
|
200
|
+
} finally {
|
|
201
|
+
RendererUtils.restoreRendererState(renderer, this.#rendererState);
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
override dispose(): void {
|
|
206
|
+
if (this.#disposed) return;
|
|
207
|
+
this.#disposed = true;
|
|
208
|
+
this.#observation.dispose();
|
|
209
|
+
for (const level of [
|
|
210
|
+
...this.#levels,
|
|
211
|
+
this.#tilesTarget,
|
|
212
|
+
this.#histogramTarget,
|
|
213
|
+
this.#readTarget,
|
|
214
|
+
this.#writeTarget,
|
|
215
|
+
])
|
|
216
|
+
level.dispose();
|
|
217
|
+
this.#levels = [];
|
|
218
|
+
this.#meterMaterial.dispose();
|
|
219
|
+
this.#reduceMaterial.dispose();
|
|
220
|
+
this.#tilesMaterial.dispose();
|
|
221
|
+
this.#histogramMaterial.dispose();
|
|
222
|
+
this.#adaptMaterial.dispose();
|
|
223
|
+
super.dispose();
|
|
224
|
+
}
|
|
225
|
+
}
|