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
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
import { Scene } from "@threenative/core";
|
|
1
|
+
import { Scene, getPlatform, isMobile } from "@threenative/core";
|
|
2
2
|
import type { IPhysicsContext } from "@threenative/physics";
|
|
3
3
|
import type { Texture } from "three";
|
|
4
|
+
import { prepareEnvironmentSample } from "../render/environmentSetup.js";
|
|
4
5
|
import { loadShipModel } from "../render/props.js";
|
|
6
|
+
import { isWebGLFallbackRenderer } from "../render/quality.js";
|
|
5
7
|
import { loadSky } from "../render/sky.js";
|
|
6
8
|
import type { GameState } from "../state.js";
|
|
7
9
|
import { Sailing } from "./Sailing.js";
|
|
@@ -19,12 +21,21 @@ export class Boot extends Scene<GameState, IPhysicsContext> {
|
|
|
19
21
|
// is read the instant `Boot.enter()` returns — not once `Sailing.enter()` eventually does. See
|
|
20
22
|
// `loadSky` and `loadShipModel`.
|
|
21
23
|
override async load(ctx: {
|
|
24
|
+
readonly renderer?: Parameters<Sailing["enter"]>[0]["renderer"];
|
|
22
25
|
readonly assets: {
|
|
23
26
|
model<T>(path: string): Promise<T>;
|
|
24
27
|
texture(path: string): Promise<Texture>;
|
|
25
28
|
};
|
|
26
29
|
}): Promise<void> {
|
|
27
30
|
await Promise.all([loadSky(ctx.assets), loadShipModel(ctx.assets)]);
|
|
31
|
+
if (ctx.renderer !== undefined)
|
|
32
|
+
await prepareEnvironmentSample(ctx.renderer.raw, {
|
|
33
|
+
web: getPlatform().runtime === "web",
|
|
34
|
+
rendererKind: ctx.renderer.kind,
|
|
35
|
+
webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
|
|
36
|
+
mobile: isMobile(),
|
|
37
|
+
software: ctx.renderer.softwareAdapter !== undefined,
|
|
38
|
+
});
|
|
28
39
|
}
|
|
29
40
|
|
|
30
41
|
override enter(ctx: Parameters<Sailing["enter"]>[0]): void {
|
|
@@ -3,15 +3,18 @@ import {
|
|
|
3
3
|
Scene,
|
|
4
4
|
type SceneFrame,
|
|
5
5
|
WaterSurface3D,
|
|
6
|
+
getPlatform,
|
|
6
7
|
isMobile,
|
|
7
8
|
isTouchscreenAvailable,
|
|
8
9
|
} from "@threenative/core";
|
|
9
10
|
import type { IPhysicsContext } from "@threenative/physics";
|
|
10
|
-
import type
|
|
11
|
+
import { type Group, type PerspectiveCamera, type Texture, Vector3 } from "three";
|
|
11
12
|
import { Ship } from "../entities/Ship.js";
|
|
12
13
|
import { followShip, setupCamera } from "../render/camera.js";
|
|
14
|
+
import { loadedEnvironmentSample } from "../render/environmentSetup.js";
|
|
13
15
|
import { followSun, setupLighting } from "../render/lighting.js";
|
|
14
16
|
import { createLoadingScreen } from "../render/loading.js";
|
|
17
|
+
import { createMaterialLighting } from "../render/materialLighting.js";
|
|
15
18
|
import { createMaterials } from "../render/materials.js";
|
|
16
19
|
import {
|
|
17
20
|
SEA_MIRROR,
|
|
@@ -22,9 +25,11 @@ import {
|
|
|
22
25
|
} from "../render/ocean.js";
|
|
23
26
|
import { setupPost } from "../render/postprocessing.js";
|
|
24
27
|
import { createBuoy, createIsland, getShipModel } from "../render/props.js";
|
|
28
|
+
import { isWebGLFallbackRenderer, materialLightingEnabled } from "../render/quality.js";
|
|
25
29
|
import { setupSky } from "../render/sky.js";
|
|
26
30
|
import { TouchControls } from "../render/touch-controls.js";
|
|
27
31
|
import type { GameState } from "../state.js";
|
|
32
|
+
import { holdOceanHeight } from "./ocean-readiness.js";
|
|
28
33
|
|
|
29
34
|
export type GameCtx = ICtx<GameState, IPhysicsContext>;
|
|
30
35
|
|
|
@@ -63,6 +68,9 @@ const MAX_WAKE_SPEED = 4.6;
|
|
|
63
68
|
const WIND_DURATION = 120;
|
|
64
69
|
|
|
65
70
|
export class Sailing extends Scene<GameState, IPhysicsContext> {
|
|
71
|
+
#observeRender: ((ctx: GameCtx) => void) | undefined;
|
|
72
|
+
#materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
|
|
73
|
+
#post: ReturnType<typeof setupPost> | undefined;
|
|
66
74
|
static override readonly initialState: GameState = {
|
|
67
75
|
buoysRounded: 0,
|
|
68
76
|
elapsed: 0,
|
|
@@ -78,6 +86,7 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
|
|
|
78
86
|
};
|
|
79
87
|
|
|
80
88
|
#sea: ReturnType<typeof createWaterMesh> | undefined;
|
|
89
|
+
#stopOceanReadiness: (() => void) | undefined;
|
|
81
90
|
|
|
82
91
|
// No `load()` here: `ship.glb` is fetched in `Boot.load()`, alongside the sky, so this scene's
|
|
83
92
|
// `enter()` stays synchronous — a playtest runner reads the registry the instant it returns, and
|
|
@@ -89,10 +98,20 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
|
|
|
89
98
|
const software = ctx.renderer.softwareAdapter !== undefined;
|
|
90
99
|
setupSky(ctx.scene, { software });
|
|
91
100
|
const sun = setupLighting(ctx.scene, ctx.renderer.raw as Parameters<typeof setupLighting>[1]);
|
|
92
|
-
|
|
101
|
+
const materialEnvironment = {
|
|
102
|
+
web: getPlatform().runtime === "web",
|
|
103
|
+
rendererKind: ctx.renderer.kind,
|
|
104
|
+
webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
|
|
105
|
+
mobile: isMobile(),
|
|
106
|
+
software: ctx.renderer.softwareAdapter !== undefined,
|
|
107
|
+
};
|
|
108
|
+
this.#post = setupPost(ctx.renderer, ctx.scene, ctx.camera, {
|
|
109
|
+
onTierChanged: (tier) =>
|
|
110
|
+
this.#materialLighting?.setEnabled(materialLightingEnabled(tier, materialEnvironment)),
|
|
93
111
|
godraysLight: sun,
|
|
94
112
|
mobile: isMobile(),
|
|
95
113
|
software,
|
|
114
|
+
gpuClass: ctx.renderer.gpuClass?.class,
|
|
96
115
|
});
|
|
97
116
|
const loading = createLoadingScreen(ctx);
|
|
98
117
|
const camera = ctx.camera as PerspectiveCamera;
|
|
@@ -107,6 +126,7 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
|
|
|
107
126
|
// passes in the warmup set. It draws nothing — the mesh and its material are this game's, and
|
|
108
127
|
// both live in `src/render/ocean.ts`.
|
|
109
128
|
const ocean = ctx.add(createOcean());
|
|
129
|
+
this.#stopOceanReadiness = holdOceanHeight(ctx, ocean);
|
|
110
130
|
// The mirror is constructed here and handed to the material: `src/render/` reaches the engine
|
|
111
131
|
// for the wave field it draws and nothing else, so the pass that draws the world a second time
|
|
112
132
|
// is built in game code from the options that file authored.
|
|
@@ -126,12 +146,66 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
|
|
|
126
146
|
buoy.position.set(mark.x, 0, mark.z);
|
|
127
147
|
marks.push(buoy);
|
|
128
148
|
markReflected(ctx.add(buoy));
|
|
149
|
+
ctx.interpolate(buoy);
|
|
129
150
|
}
|
|
130
151
|
|
|
131
152
|
const ship = new Ship(ctx, ocean, shipModel);
|
|
132
153
|
// The ship is deliberately not in the sea's mirror: it is a second draw of the hull *and its
|
|
133
154
|
// keel*, which the mirror sees from below as a black blot smeared under the stern.
|
|
134
155
|
ctx.entities.add("player", ship);
|
|
156
|
+
const projected = new Vector3();
|
|
157
|
+
let previous: { time: number; x: number; y: number; vx?: number; vy?: number } | undefined;
|
|
158
|
+
let sampleFrame = -1;
|
|
159
|
+
let lowestY = Number.POSITIVE_INFINITY;
|
|
160
|
+
let highestY = Number.NEGATIVE_INFINITY;
|
|
161
|
+
this.#observeRender = (renderCtx) => {
|
|
162
|
+
if (renderCtx.startup.phase !== "ready") return;
|
|
163
|
+
projected.copy(ship.visual.position).project(camera);
|
|
164
|
+
if (Math.abs(projected.x) > 1 || Math.abs(projected.y) > 1 || projected.z > 1) {
|
|
165
|
+
previous = undefined;
|
|
166
|
+
return;
|
|
167
|
+
}
|
|
168
|
+
const motion = ship.renderMotion;
|
|
169
|
+
lowestY = Math.min(lowestY, ship.visual.position.y);
|
|
170
|
+
highestY = Math.max(highestY, ship.visual.position.y);
|
|
171
|
+
motion.verticalRange = highestY - lowestY;
|
|
172
|
+
motion.frames += 1;
|
|
173
|
+
motion.fractionalFrames += Number(renderCtx.alpha > 0 && renderCtx.alpha < 1);
|
|
174
|
+
const sample = ocean.sampleHeight(ship.visual.position.x, ship.visual.position.z);
|
|
175
|
+
const frame = sample === undefined ? -1 : ocean.steps - sample.staleFrames;
|
|
176
|
+
motion.readbacks += Number(frame >= 0 && frame !== sampleFrame);
|
|
177
|
+
sampleFrame = frame;
|
|
178
|
+
const time = renderCtx.frameTime / 1_000;
|
|
179
|
+
const x = (projected.x * renderCtx.viewport.size.width) / 2;
|
|
180
|
+
const y = (projected.y * renderCtx.viewport.size.height) / 2;
|
|
181
|
+
const delta = time - (previous?.time ?? time);
|
|
182
|
+
if (previous === undefined || delta <= 0) {
|
|
183
|
+
previous = { time, x, y };
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
const vx = (x - previous.x) / delta;
|
|
187
|
+
const vy = (y - previous.y) / delta;
|
|
188
|
+
motion.maxJitterPixels = Math.max(
|
|
189
|
+
motion.maxJitterPixels,
|
|
190
|
+
Math.hypot(vx - (previous.vx ?? vx), vy - (previous.vy ?? vy)) / 60,
|
|
191
|
+
);
|
|
192
|
+
previous = { time, x, y, vx, vy };
|
|
193
|
+
};
|
|
194
|
+
this.#materialLighting = ctx.entities.add(
|
|
195
|
+
"material-lighting",
|
|
196
|
+
createMaterialLighting(ctx.scene, ctx.camera, sun, {
|
|
197
|
+
...materialEnvironment,
|
|
198
|
+
enabled: materialLightingEnabled(this.#post.tier, materialEnvironment),
|
|
199
|
+
}),
|
|
200
|
+
);
|
|
201
|
+
const sample = loadedEnvironmentSample();
|
|
202
|
+
if (sample !== undefined)
|
|
203
|
+
this.#materialLighting.setEnvironmentMeasurement(
|
|
204
|
+
sample.measurement,
|
|
205
|
+
sample.source,
|
|
206
|
+
sample.intensity,
|
|
207
|
+
sample,
|
|
208
|
+
);
|
|
135
209
|
let elapsed = 0;
|
|
136
210
|
let buoysRounded = 0;
|
|
137
211
|
let markBearing = 0;
|
|
@@ -257,7 +331,18 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
|
|
|
257
331
|
};
|
|
258
332
|
}
|
|
259
333
|
|
|
334
|
+
override render(ctx: GameCtx): void {
|
|
335
|
+
this.#observeRender?.(ctx);
|
|
336
|
+
}
|
|
337
|
+
|
|
260
338
|
override exit(ctx: GameCtx): void {
|
|
339
|
+
this.#observeRender = undefined;
|
|
340
|
+
this.#materialLighting?.dispose();
|
|
341
|
+
this.#materialLighting = undefined;
|
|
342
|
+
this.#post?.dispose();
|
|
343
|
+
this.#post = undefined;
|
|
344
|
+
this.#stopOceanReadiness?.();
|
|
345
|
+
this.#stopOceanReadiness = undefined;
|
|
261
346
|
// The mirror owns a render target and a pass. Nothing in the frame releases it, so a restart
|
|
262
347
|
// — which is `goto("sailing")`, and this scene is entered again — would leak one every time.
|
|
263
348
|
this.#sea?.dispose();
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { ICtx, SpectralOcean } from "@threenative/core";
|
|
2
|
+
|
|
3
|
+
// Match the existing startup hold deadline; the contract test guards this against core drift.
|
|
4
|
+
const HEIGHT_READBACK_BUDGET_MS = 45_000;
|
|
5
|
+
let nextHold = 0;
|
|
6
|
+
|
|
7
|
+
/** Keep the initial loading curtain up until the sea has an authoritative CPU height. */
|
|
8
|
+
export function holdOceanHeight(
|
|
9
|
+
ctx: Pick<ICtx, "beforeRender" | "startup">,
|
|
10
|
+
ocean: Pick<SpectralOcean, "process" | "sampleHeight">,
|
|
11
|
+
): () => void {
|
|
12
|
+
// Startup is a one-time gate. A later scene restart uses the ordinary compute lifecycle.
|
|
13
|
+
if (ctx.startup.phase === "ready") return () => undefined;
|
|
14
|
+
let active = true;
|
|
15
|
+
let dispatched = false;
|
|
16
|
+
let removeObserver: () => void = () => undefined;
|
|
17
|
+
let finishWork: () => void = () => undefined;
|
|
18
|
+
const work = new Promise<void>((resolve) => {
|
|
19
|
+
finishWork = resolve;
|
|
20
|
+
});
|
|
21
|
+
const stop = (): void => {
|
|
22
|
+
if (!active) return;
|
|
23
|
+
active = false;
|
|
24
|
+
clearTimeout(timer);
|
|
25
|
+
removeObserver();
|
|
26
|
+
finishWork();
|
|
27
|
+
};
|
|
28
|
+
const fail = (reason: unknown): void => {
|
|
29
|
+
if (!active) return;
|
|
30
|
+
console.error(
|
|
31
|
+
"TN_SAILING_HEIGHT_READBACK_FAILED",
|
|
32
|
+
reason instanceof Error ? reason.message : String(reason),
|
|
33
|
+
);
|
|
34
|
+
stop();
|
|
35
|
+
};
|
|
36
|
+
// Register this timer before hold(): a failed sample must be reported before the gate fails open.
|
|
37
|
+
const timer = setTimeout(
|
|
38
|
+
() => fail("No finite ocean height sample arrived within the startup budget."),
|
|
39
|
+
HEIGHT_READBACK_BUDGET_MS,
|
|
40
|
+
);
|
|
41
|
+
removeObserver = ctx.beforeRender(() => {
|
|
42
|
+
if (!active || !dispatched) return;
|
|
43
|
+
try {
|
|
44
|
+
const sample = ocean.sampleHeight(0, 0);
|
|
45
|
+
if (sample !== undefined && Number.isFinite(sample.height)) stop();
|
|
46
|
+
} catch (error) {
|
|
47
|
+
fail(error);
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
try {
|
|
51
|
+
ctx.startup.hold(`sailing-ocean-height-${++nextHold}`, work);
|
|
52
|
+
} catch (error) {
|
|
53
|
+
stop();
|
|
54
|
+
throw error;
|
|
55
|
+
}
|
|
56
|
+
// Waiting on whenReady() here would make the hold wait on itself. Compilation and the frame
|
|
57
|
+
// window finish independently; one dispatch then primes the copy without advancing game time.
|
|
58
|
+
void ctx.startup.whenFrameworkReady().then(() => {
|
|
59
|
+
if (!active) return;
|
|
60
|
+
try {
|
|
61
|
+
dispatched = true;
|
|
62
|
+
ocean.process();
|
|
63
|
+
} catch (error) {
|
|
64
|
+
fail(error);
|
|
65
|
+
}
|
|
66
|
+
}, fail);
|
|
67
|
+
return stop;
|
|
68
|
+
}
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import type { IThreeNativeConfig } from "@threenative/core";
|
|
2
2
|
|
|
3
3
|
const config: IThreeNativeConfig = {
|
|
4
|
+
// Pinned to the legacy engine: the native engine does not bind three/tsl vertexIndex yet (PRD-573 slice 8).
|
|
5
|
+
// Delete this line when `pnpm build --target desktop` passes without it, and the game runs on the native engine.
|
|
6
|
+
engine: "threejs",
|
|
4
7
|
app: {
|
|
5
8
|
id: "com.threenative.__PROJECT_ID__",
|
|
6
9
|
name: "__PROJECT_NAME__",
|
|
@@ -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";
|
|
@@ -11,7 +15,11 @@ function assetsWatchPlugin(): Plugin {
|
|
|
11
15
|
name: "threenative-assets-watch",
|
|
12
16
|
apply: "serve",
|
|
13
17
|
async configureServer(server) {
|
|
14
|
-
const handle = watchAssets({
|
|
18
|
+
const handle = watchAssets({
|
|
19
|
+
config: config.assets,
|
|
20
|
+
cwd: server.config.root,
|
|
21
|
+
runtimeDecoders: webRuntimeDecoders(config),
|
|
22
|
+
});
|
|
15
23
|
server.httpServer?.once("close", () => handle.close());
|
|
16
24
|
// Nothing is served before the first cook settles: until it does, `public/` has no
|
|
17
25
|
// `assets.manifest.json` and every asset answers from its source fallback.
|
|
@@ -5,7 +5,7 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
|
|
|
5
5
|
## Ownership
|
|
6
6
|
|
|
7
7
|
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the town, the soldiers, the rifle, the HUD and the look; `src/game.ts` is
|
|
8
|
-
portable, `src/main.ts` is the web-only React mount. 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.
|
|
8
|
+
portable, `src/main.ts` is the web-only React mount. 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. 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).
|
|
9
9
|
|
|
10
10
|
## Start every change
|
|
11
11
|
|
|
@@ -37,7 +37,7 @@ result, replacement); never stall the game.
|
|
|
37
37
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
38
38
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
39
39
|
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
40
|
-
- 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.
|
|
40
|
+
- 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 some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
|
|
41
41
|
|
|
42
42
|
## Commands and map
|
|
43
43
|
|
|
@@ -66,16 +66,18 @@ Leave `assets` absent: the cook selects target-decodable passes, and `models.com
|
|
|
66
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.
|
|
67
67
|
First person, four rules: place the camera in the plugin hook after the physics step, never at the end of the frame function, or the eye sits one step behind the body and shots land in the floor on the deck stairs; start every shot at `player.aimRay()`, where the crosshair is, and let `Rifle.converge` lean the weapon to meet it; the trigger takes `pressed` and `justPressed`, because the cooldown makes the cadence and the edge catches a click the harness delivers no other way; `src/render/scale.ts` is the only size table.
|
|
68
68
|
|
|
69
|
-
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, size it with `normaliseToMetres` at a named joint, drive `AnimationPlayer` beside its entity, and reach a held prop with `attachToBone`. `input.vector("move").y` is +up, so forward uses one explicit `-move.y`. `ctx.goto(name)` rebuilds without resetting game state (from a frame function, `goto` then `return`); `ctx.state.set({ … })` is a partial patch; `game.goto()` rebuilds and resets. Seeded randomness needs `defineGame({ seed })`.
|
|
70
|
-
`src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) background, environment light and fog colour (re-aim `SUN_DIRECTION` when you swap it); `src/render/quality.ts` owns `low`, `medium`, `high`; `isMobile()`
|
|
69
|
+
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. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, size it with `normaliseToMetres` at a named joint, drive `AnimationPlayer` beside its entity, and reach a held prop with `attachToBone`. `input.vector("move").y` is +up, so forward uses one explicit `-move.y`. `ctx.goto(name)` rebuilds without resetting game state (from a frame function, `goto` then `return`); `ctx.state.set({ … })` is a partial patch; `game.goto()` rebuilds and resets. Seeded randomness needs `defineGame({ seed })`.
|
|
70
|
+
`src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) background, environment light and fog colour (re-aim `SUN_DIRECTION` when you swap it); `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`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw, `TN_QUALITY_TIER` reports the source, and the bridge flushes about 100 ms — keep score/phase in state, feedback in Three.js. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — 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.
|
|
71
71
|
|
|
72
72
|
When an animation looks wrong, measure it before rewriting it: `clipPoseError` scores a retargeted clip per bone in degrees relative to each rig's own bind pose, `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose), `clipBoneCoverage` names bones the clip does not drive, and `boneContact` reports whether a bone reaches its prop. A soldier reads as a soldier only when every AI state picks a clip that names the action — patrol and chase `Rifle_Walk`, standing aim `Rifle_Idle`, firing `Rifle_Shoot`, crouch `Rifle_Crouch_To_Idle`/`Rifle_Crouch_Walk` (the six `Rifle_*` clips are Mixamo rifle clips retargeted onto the mannequin, and `RIFLE_HOLD` in `Enemy.ts` turns the rifle to each; the soldier's `rightHandContact`/`leftHandContact` are `boneContact` metres, held under 0.05), hit `Rifle_Hit`, dead `Death01` — crossfaded, feet snapped to the floor, body turned into the direction of travel or aim, and tinted so he does not vanish into the white first-person hands.
|
|
73
|
-
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
|
|
73
|
+
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.
|
|
74
74
|
|
|
75
75
|
## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
|
|
76
76
|
|
|
77
77
|
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; `TN_FRAME_SPANS=1` adds the render phase's own span tree. 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.
|
|
78
78
|
|
|
79
|
-
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`. On a touch-primary device, `src/entities/TouchControls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints.
|
|
79
|
+
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`. On a touch-primary device, `src/entities/TouchControls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints.
|
|
80
80
|
## Optional multiplayer transport
|
|
81
81
|
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`.
|
|
82
|
+
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.
|
|
83
|
+
`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.
|
|
@@ -7,7 +7,7 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
|
|
|
7
7
|
## Ownership
|
|
8
8
|
|
|
9
9
|
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the town, the soldiers, the rifle, the HUD and the look; `src/game.ts` is
|
|
10
|
-
portable, `src/main.ts` is the web-only React mount. 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.
|
|
10
|
+
portable, `src/main.ts` is the web-only React mount. 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. 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).
|
|
11
11
|
|
|
12
12
|
## Start every change
|
|
13
13
|
|
|
@@ -39,7 +39,7 @@ result, replacement); never stall the game.
|
|
|
39
39
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
40
40
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
41
41
|
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
42
|
-
- 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.
|
|
42
|
+
- 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 some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
|
|
43
43
|
|
|
44
44
|
## Commands and map
|
|
45
45
|
|
|
@@ -68,16 +68,18 @@ Leave `assets` absent: the cook selects target-decodable passes, and `models.com
|
|
|
68
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.
|
|
69
69
|
First person, four rules: place the camera in the plugin hook after the physics step, never at the end of the frame function, or the eye sits one step behind the body and shots land in the floor on the deck stairs; start every shot at `player.aimRay()`, where the crosshair is, and let `Rifle.converge` lean the weapon to meet it; the trigger takes `pressed` and `justPressed`, because the cooldown makes the cadence and the edge catches a click the harness delivers no other way; `src/render/scale.ts` is the only size table.
|
|
70
70
|
|
|
71
|
-
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, size it with `normaliseToMetres` at a named joint, drive `AnimationPlayer` beside its entity, and reach a held prop with `attachToBone`. `input.vector("move").y` is +up, so forward uses one explicit `-move.y`. `ctx.goto(name)` rebuilds without resetting game state (from a frame function, `goto` then `return`); `ctx.state.set({ … })` is a partial patch; `game.goto()` rebuilds and resets. Seeded randomness needs `defineGame({ seed })`.
|
|
72
|
-
`src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) background, environment light and fog colour (re-aim `SUN_DIRECTION` when you swap it); `src/render/quality.ts` owns `low`, `medium`, `high`; `isMobile()`
|
|
71
|
+
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. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, size it with `normaliseToMetres` at a named joint, drive `AnimationPlayer` beside its entity, and reach a held prop with `attachToBone`. `input.vector("move").y` is +up, so forward uses one explicit `-move.y`. `ctx.goto(name)` rebuilds without resetting game state (from a frame function, `goto` then `return`); `ctx.state.set({ … })` is a partial patch; `game.goto()` rebuilds and resets. Seeded randomness needs `defineGame({ seed })`.
|
|
72
|
+
`src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) background, environment light and fog colour (re-aim `SUN_DIRECTION` when you swap it); `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`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw, `TN_QUALITY_TIER` reports the source, and the bridge flushes about 100 ms — keep score/phase in state, feedback in Three.js. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — 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.
|
|
73
73
|
|
|
74
74
|
When an animation looks wrong, measure it before rewriting it: `clipPoseError` scores a retargeted clip per bone in degrees relative to each rig's own bind pose, `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose), `clipBoneCoverage` names bones the clip does not drive, and `boneContact` reports whether a bone reaches its prop. A soldier reads as a soldier only when every AI state picks a clip that names the action — patrol and chase `Rifle_Walk`, standing aim `Rifle_Idle`, firing `Rifle_Shoot`, crouch `Rifle_Crouch_To_Idle`/`Rifle_Crouch_Walk` (the six `Rifle_*` clips are Mixamo rifle clips retargeted onto the mannequin, and `RIFLE_HOLD` in `Enemy.ts` turns the rifle to each; the soldier's `rightHandContact`/`leftHandContact` are `boneContact` metres, held under 0.05), hit `Rifle_Hit`, dead `Death01` — crossfaded, feet snapped to the floor, body turned into the direction of travel or aim, and tinted so he does not vanish into the white first-person hands.
|
|
75
|
-
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
|
|
75
|
+
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.
|
|
76
76
|
|
|
77
77
|
## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
|
|
78
78
|
|
|
79
79
|
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; `TN_FRAME_SPANS=1` adds the render phase's own span tree. 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.
|
|
80
80
|
|
|
81
|
-
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`. On a touch-primary device, `src/entities/TouchControls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints.
|
|
81
|
+
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`. On a touch-primary device, `src/entities/TouchControls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints.
|
|
82
82
|
## Optional multiplayer transport
|
|
83
83
|
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`.
|
|
84
|
+
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.
|
|
85
|
+
`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"
|
|
@@ -27,20 +27,20 @@
|
|
|
27
27
|
"@tailwindcss/vite": "4.3.3",
|
|
28
28
|
"@types/three": "0.185.3",
|
|
29
29
|
"@vitejs/plugin-react": "6.0.5",
|
|
30
|
-
"@threenative/assets": "0.3.
|
|
31
|
-
"@threenative/playtest": "0.3.
|
|
30
|
+
"@threenative/assets": "0.3.6",
|
|
31
|
+
"@threenative/playtest": "0.3.5",
|
|
32
32
|
"@types/react": "19.2.0",
|
|
33
33
|
"@types/react-dom": "19.2.0",
|
|
34
34
|
"playwright": "1.62.1",
|
|
35
|
-
"create-threenative": "0.2.
|
|
35
|
+
"create-threenative": "0.2.9",
|
|
36
36
|
"esbuild": "0.27.0",
|
|
37
37
|
"tailwindcss": "4.3.3",
|
|
38
|
-
"typescript": "
|
|
38
|
+
"typescript": "7.0.2",
|
|
39
39
|
"vite": "8.2.0",
|
|
40
40
|
"@gltf-transform/cli": "4.4.2"
|
|
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
|
}
|
|
@@ -52,7 +52,13 @@
|
|
|
52
52
|
},
|
|
53
53
|
"renderChain": {
|
|
54
54
|
"tier": "high",
|
|
55
|
-
"perAdapter": {
|
|
55
|
+
"perAdapter": {
|
|
56
|
+
"integrated": { "tier": "medium" },
|
|
57
|
+
"mobile-high": { "tier": "medium" },
|
|
58
|
+
"mobile-low": { "tier": "low" },
|
|
59
|
+
"mobile-mid": { "tier": "low" },
|
|
60
|
+
"software": { "tier": "low" }
|
|
61
|
+
}
|
|
56
62
|
},
|
|
57
63
|
"performance": {
|
|
58
64
|
"maxDrawCalls": 1300,
|
|
@@ -223,18 +223,6 @@ const ROUTE_START = ROUTE[0] ?? new Vector3();
|
|
|
223
223
|
* anyone can act on. Peaks are per frame and reset by `beginSquadFrame`, so what comes out is
|
|
224
224
|
* the worst single frame each stage has ever cost across all five soldiers together.
|
|
225
225
|
*/
|
|
226
|
-
/**
|
|
227
|
-
* Seconds between line-of-sight raycasts for one soldier.
|
|
228
|
-
*
|
|
229
|
-
* The cheap half of `#canSee` — range and view cone — still runs every frame, so a soldier turning
|
|
230
|
-
* away or stepping out of range loses sight instantly. Only the raycast is rationed, because it is
|
|
231
|
-
* a `raycastAll` against every solid in the town and five soldiers doing that at 60 Hz measured at
|
|
232
|
-
* 15.9 ms of a 16.3 ms frame: the entire mid-round hitch, in one call.
|
|
233
|
-
*
|
|
234
|
-
* A tenth of a second of staleness on "can he see me" is invisible next to `REACTION_SECONDS`,
|
|
235
|
-
* which already holds fire for far longer than this after a soldier first spots the player.
|
|
236
|
-
*/
|
|
237
|
-
const LOS_INTERVAL_SECONDS = 0;
|
|
238
226
|
/**
|
|
239
227
|
* Shortest gap between two grid searches for one soldier when only the goal has drifted.
|
|
240
228
|
*
|
|
@@ -250,9 +238,6 @@ const LOS_INTERVAL_SECONDS = 0;
|
|
|
250
238
|
* per-frame cost.
|
|
251
239
|
*/
|
|
252
240
|
const GOAL_REPLAN_SECONDS = 0.15;
|
|
253
|
-
/** Spreads the squad's raycasts across frames, so five soldiers never all test on the same one. */
|
|
254
|
-
const losStagger = 0;
|
|
255
|
-
|
|
256
241
|
/** Blocked-cell bitmaps per collider set, so the squad pays for the nav grid once. */
|
|
257
242
|
const NAV_GRIDS = new WeakMap<object, Map<string, Uint8Array>>();
|
|
258
243
|
|
|
@@ -9,8 +9,10 @@ import {
|
|
|
9
9
|
AdditiveBlending,
|
|
10
10
|
type AnimationClip,
|
|
11
11
|
Box3,
|
|
12
|
+
CircleGeometry,
|
|
12
13
|
ConeGeometry,
|
|
13
14
|
Group,
|
|
15
|
+
type Material,
|
|
14
16
|
MathUtils,
|
|
15
17
|
Mesh,
|
|
16
18
|
MeshBasicMaterial,
|
|
@@ -22,6 +24,7 @@ import {
|
|
|
22
24
|
type Scene as ThreeScene,
|
|
23
25
|
Vector3,
|
|
24
26
|
} from "three";
|
|
27
|
+
import { FIRST_PERSON } from "../render/camera.js";
|
|
25
28
|
import { PooledBillboards } from "../render/pooled-billboards.js";
|
|
26
29
|
import { scale } from "../render/scale.js";
|
|
27
30
|
import type { GameState } from "../state.js";
|
|
@@ -45,6 +48,8 @@ const CYCLIC_SECONDS = 0.1;
|
|
|
45
48
|
* the forearm as a sleeve filling the screen, whatever this pose says.
|
|
46
49
|
*/
|
|
47
50
|
const HIP = { x: 0.22, y: -0.29, z: -0.15, pitch: -0.03, yaw: 0.12, roll: 0.04 };
|
|
51
|
+
/** Measured on the shipped viewmodel's ADS capture: scope body spans 190..455 px, window center at ~265 px down from top. */
|
|
52
|
+
const SIGHT_WINDOW_FROM_TOP = 0.28;
|
|
48
53
|
const AIM_Z = -0.16;
|
|
49
54
|
const ZERO_DISTANCE = 25;
|
|
50
55
|
const MAX_CONVERGENCE_DEGREES = 8;
|
|
@@ -63,6 +68,7 @@ export class Rifle {
|
|
|
63
68
|
onMagIn: (() => void) | undefined;
|
|
64
69
|
readonly group = new Group();
|
|
65
70
|
#flash: Mesh;
|
|
71
|
+
#reticle: Mesh;
|
|
66
72
|
#flashLife = 0;
|
|
67
73
|
#light: PointLight;
|
|
68
74
|
#smokeMaterial: MeshBasicMaterial;
|
|
@@ -108,6 +114,15 @@ export class Rifle {
|
|
|
108
114
|
// The viewmodel is drawn over the world, so nothing in the yard can clip it.
|
|
109
115
|
const mesh = object as Mesh;
|
|
110
116
|
if (mesh.isMesh === true) mesh.renderOrder = 20;
|
|
117
|
+
// The scope glass is 58% opaque dark navy. It makes the view center black while aiming.
|
|
118
|
+
// Alpha test keeps only the opaque frame, so the window stays clear.
|
|
119
|
+
const material = mesh.material as Material | undefined;
|
|
120
|
+
if (material?.name === "Scope") {
|
|
121
|
+
material.alphaTest = 0.9;
|
|
122
|
+
material.transparent = false;
|
|
123
|
+
material.depthWrite = true;
|
|
124
|
+
material.needsUpdate = true;
|
|
125
|
+
}
|
|
111
126
|
});
|
|
112
127
|
// The fixed half-turn is the authored asset correction; the barrel axis and tip below are
|
|
113
128
|
// measured after this transform, so no caller has to guess where the suppressor ends.
|
|
@@ -149,6 +164,24 @@ export class Rifle {
|
|
|
149
164
|
this.#light = new PointLight(0xffc46a, 0, 6, 2);
|
|
150
165
|
this.#light.position.copy(this.#barrelTipLocal);
|
|
151
166
|
this.group.add(this.#light);
|
|
167
|
+
// The dot radius is 1.75 px at 1280x720 with the aim FOV. At the optic distance d, the view
|
|
168
|
+
// is 2 d tan(FOV / 2) meters tall. It spans 720 px, so one pixel is that height divided by 720.
|
|
169
|
+
const opticDistance = -(AIM_Z + this.#opticLocal.z);
|
|
170
|
+
const halfFov = MathUtils.degToRad(FIRST_PERSON.aimFov) / 2;
|
|
171
|
+
const metresPerPixel = (2 * opticDistance * Math.tan(halfFov)) / 720;
|
|
172
|
+
this.#reticle = new Mesh(
|
|
173
|
+
new CircleGeometry(1.75 * metresPerPixel, 16),
|
|
174
|
+
new MeshBasicMaterial({
|
|
175
|
+
color: 0xff2a2a,
|
|
176
|
+
depthTest: false,
|
|
177
|
+
opacity: 0,
|
|
178
|
+
toneMapped: false,
|
|
179
|
+
transparent: true,
|
|
180
|
+
}),
|
|
181
|
+
);
|
|
182
|
+
this.#reticle.position.copy(this.#opticLocal);
|
|
183
|
+
this.#reticle.renderOrder = 31;
|
|
184
|
+
this.group.add(this.#reticle);
|
|
152
185
|
// Smoke lives in world space, not on the camera, so it stays where it was made when you
|
|
153
186
|
// turn — smoke welded to the viewmodel slides with the view and reads as a bug. The
|
|
154
187
|
// shared billboard pool keeps every puff present at zero opacity from the first frame.
|
|
@@ -233,7 +266,9 @@ export class Rifle {
|
|
|
233
266
|
}
|
|
234
267
|
});
|
|
235
268
|
if (bestScore < Number.POSITIVE_INFINITY) {
|
|
236
|
-
|
|
269
|
+
const center = candidate.getCenter(new Vector3());
|
|
270
|
+
center.y = candidate.max.y - (candidate.max.y - candidate.min.y) * SIGHT_WINDOW_FROM_TOP;
|
|
271
|
+
this.#opticLocal.copy(center).applyMatrix4(fit.matrix);
|
|
237
272
|
} else {
|
|
238
273
|
this.#opticLocal
|
|
239
274
|
.set(
|
|
@@ -396,6 +431,8 @@ export class Rifle {
|
|
|
396
431
|
HIP.yaw * (1 - t),
|
|
397
432
|
HIP.roll * (1 - t) + this.#lowered * 0.18,
|
|
398
433
|
);
|
|
434
|
+
// The red dot shows only at full aim. Opacity keeps it in the render list, as the flash does.
|
|
435
|
+
(this.#reticle.material as MeshBasicMaterial).opacity = this.#blend > 0.9 ? 1 : 0;
|
|
399
436
|
if (!this.#hasAimRay) return;
|
|
400
437
|
|
|
401
438
|
const target = this.#aimOrigin.clone().addScaledVector(this.#aimDirection, ZERO_DISTANCE);
|