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
|
@@ -4,6 +4,7 @@ import {
|
|
|
4
4
|
Scene,
|
|
5
5
|
type SceneFrame,
|
|
6
6
|
TracerPool3D,
|
|
7
|
+
getPlatform,
|
|
7
8
|
isMobile,
|
|
8
9
|
} from "@threenative/core";
|
|
9
10
|
import { CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
|
|
@@ -27,12 +28,19 @@ import { Target } from "../entities/Target.js";
|
|
|
27
28
|
import { TouchControls } from "../entities/TouchControls.js";
|
|
28
29
|
import { onAfterPhysics } from "../postPhysics.js";
|
|
29
30
|
import { DecalField, bulletHoleTexture } from "../render/decals.js";
|
|
31
|
+
import { type IEnvironmentSample, sampleEnvironment } from "../render/environmentSampling.js";
|
|
30
32
|
import { ImpactBursts, MuzzleFlash, MuzzleFlashPool, softCircleTexture } from "../render/gunfx.js";
|
|
31
33
|
import { setupLighting } from "../render/lighting.js";
|
|
32
34
|
import { createLoadingScreen } from "../render/loading.js";
|
|
35
|
+
import { createMaterialLighting } from "../render/materialLighting.js";
|
|
33
36
|
import { BoxOccluders } from "../render/occlusion.js";
|
|
34
37
|
import { PooledBillboards } from "../render/pooled-billboards.js";
|
|
35
38
|
import { setupPost } from "../render/postprocessing.js";
|
|
39
|
+
import {
|
|
40
|
+
type QualityTier,
|
|
41
|
+
isWebGLFallbackRenderer,
|
|
42
|
+
materialLightingEnabled,
|
|
43
|
+
} from "../render/quality.js";
|
|
36
44
|
import { scale } from "../render/scale.js";
|
|
37
45
|
import { setupSky } from "../render/sky.js";
|
|
38
46
|
import { TOWN_HALF, type Town, buildTown } from "../render/town.js";
|
|
@@ -101,6 +109,10 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
101
109
|
}
|
|
102
110
|
| undefined;
|
|
103
111
|
|
|
112
|
+
#post: ReturnType<typeof setupPost> | undefined;
|
|
113
|
+
#environmentSample: IEnvironmentSample | undefined;
|
|
114
|
+
#materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
|
|
115
|
+
|
|
104
116
|
override async load(ctx: GameCtx): Promise<void> {
|
|
105
117
|
// Three files, and one of them is the whole town: the geometry is procedural
|
|
106
118
|
// (`render/town.ts`), so the only downloads are two rigs and one photograph.
|
|
@@ -119,9 +131,23 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
119
131
|
ctx.assets.texture("sky.jpg"),
|
|
120
132
|
]);
|
|
121
133
|
this.#assets = { enemy, viewmodel, sky };
|
|
134
|
+
setupSky(ctx.scene, this.#assets.sky);
|
|
135
|
+
this.#environmentSample = await sampleEnvironment(ctx.renderer.raw, ctx.scene, {
|
|
136
|
+
web: getPlatform().runtime === "web",
|
|
137
|
+
rendererKind: ctx.renderer.kind,
|
|
138
|
+
webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
|
|
139
|
+
mobile: isMobile(),
|
|
140
|
+
software: ctx.renderer.softwareAdapter !== undefined,
|
|
141
|
+
});
|
|
122
142
|
}
|
|
123
143
|
|
|
124
144
|
override exit(): void {
|
|
145
|
+
this.#materialLighting?.dispose();
|
|
146
|
+
this.#materialLighting = undefined;
|
|
147
|
+
this.#post?.dispose();
|
|
148
|
+
this.#post = undefined;
|
|
149
|
+
this.#environmentSample = undefined;
|
|
150
|
+
|
|
125
151
|
// The hook closes over this scene's player. Leaving it registered means a restart keeps
|
|
126
152
|
// syncing the camera to the torn-down body until `enter` happens to overwrite it.
|
|
127
153
|
onAfterPhysics(undefined);
|
|
@@ -145,10 +171,23 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
145
171
|
TOWN_HALF,
|
|
146
172
|
mobile,
|
|
147
173
|
);
|
|
148
|
-
|
|
174
|
+
const materialEnvironment = {
|
|
175
|
+
web: getPlatform().runtime === "web",
|
|
176
|
+
rendererKind: ctx.renderer.kind,
|
|
177
|
+
webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
|
|
178
|
+
mobile: isMobile(),
|
|
179
|
+
software: ctx.renderer.softwareAdapter !== undefined,
|
|
180
|
+
};
|
|
181
|
+
let materialTier: QualityTier = "low";
|
|
182
|
+
this.#post = setupPost(ctx.renderer, ctx.scene, camera, {
|
|
183
|
+
onTierChanged: (tier) => {
|
|
184
|
+
materialTier = tier;
|
|
185
|
+
this.#materialLighting?.setEnabled(materialLightingEnabled(tier, materialEnvironment));
|
|
186
|
+
},
|
|
149
187
|
godraysLight: key,
|
|
150
188
|
mobile,
|
|
151
189
|
software: ctx.renderer.softwareAdapter !== undefined,
|
|
190
|
+
gpuClass: ctx.renderer.gpuClass?.class,
|
|
152
191
|
});
|
|
153
192
|
ctx.add(camera);
|
|
154
193
|
|
|
@@ -392,9 +431,10 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
392
431
|
// Bullet holes. They stay put: a mark that fades tells the player their rounds went nowhere.
|
|
393
432
|
// What colour the crushed rim comes out is per material — steel burns bare and cold, plaster
|
|
394
433
|
// and stone go pale, wood darkens. See `decals.ts` for why the pool is shaped this way.
|
|
434
|
+
const decalTexture = bulletHoleTexture();
|
|
395
435
|
const decals = new DecalField(ctx.scene, {
|
|
396
436
|
countPerVariant: 56,
|
|
397
|
-
map:
|
|
437
|
+
map: decalTexture,
|
|
398
438
|
size: 0.13,
|
|
399
439
|
tints: {
|
|
400
440
|
plaster: 0xf3ead8,
|
|
@@ -404,7 +444,11 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
404
444
|
},
|
|
405
445
|
});
|
|
406
446
|
ctx.entities.remove("decals");
|
|
447
|
+
ctx.entities.remove("decal-texture");
|
|
407
448
|
ctx.entities.add("decals", decals);
|
|
449
|
+
// The field borrows its map. Register the scene-owned texture after its borrowers so
|
|
450
|
+
// registry teardown releases their materials first, then the texture, exactly once.
|
|
451
|
+
ctx.entities.add("decal-texture", decalTexture);
|
|
408
452
|
// `hit.face.normal` is object-local; transform it into world space before any
|
|
409
453
|
// spawn math, or rotated meshes send their bursts into the wall.
|
|
410
454
|
const impactNormal = new Vector3();
|
|
@@ -680,6 +724,24 @@ export class Play extends Scene<GameState, IPhysicsContext> {
|
|
|
680
724
|
};
|
|
681
725
|
ctx.entities.remove("render");
|
|
682
726
|
ctx.entities.add("render", { debug: renderInfo });
|
|
727
|
+
// Collect only after the loaded character and scene receivers are attached.
|
|
728
|
+
this.#materialLighting = ctx.entities.add(
|
|
729
|
+
"material-lighting",
|
|
730
|
+
createMaterialLighting(ctx.scene, ctx.camera, key, {
|
|
731
|
+
...materialEnvironment,
|
|
732
|
+
enabled: materialLightingEnabled(materialTier, materialEnvironment),
|
|
733
|
+
}),
|
|
734
|
+
);
|
|
735
|
+
if (this.#environmentSample !== undefined) {
|
|
736
|
+
const sample = this.#environmentSample;
|
|
737
|
+
this.#materialLighting.setEnvironmentMeasurement(
|
|
738
|
+
sample.measurement,
|
|
739
|
+
sample.source,
|
|
740
|
+
sample.intensity,
|
|
741
|
+
sample,
|
|
742
|
+
);
|
|
743
|
+
}
|
|
744
|
+
|
|
683
745
|
return (frameCtx, dt) => {
|
|
684
746
|
loading.update();
|
|
685
747
|
// The totals of the frame that just finished, read before this frame's
|
|
@@ -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.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
[mcp_servers.threenative-assets]
|
|
2
|
+
command = "node"
|
|
3
|
+
args = ["./node_modules/@threenative/core/mcp/assets.mjs"]
|
|
4
|
+
|
|
5
|
+
[mcp_servers.threenative-assets.env]
|
|
6
|
+
ASSET_DOWNLOAD_DIR = "./public/assets"
|
|
7
|
+
AUDIO_DOWNLOAD_DIR = "./public/audio"
|
|
8
|
+
|
|
9
|
+
[mcp_servers.threenative-sculpt]
|
|
10
|
+
command = "node"
|
|
11
|
+
args = ["./node_modules/@threenative/core/mcp/sculpt.mjs"]
|
|
12
|
+
|
|
13
|
+
[mcp_servers.threenative-engine]
|
|
14
|
+
command = "node"
|
|
15
|
+
args = ["./node_modules/@threenative/core/mcp/engine.mjs"]
|
|
16
|
+
|
|
17
|
+
[mcp_servers.threenative-blender]
|
|
18
|
+
command = "node"
|
|
19
|
+
args = ["./node_modules/@threenative/core/mcp/blender.mjs"]
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"threenative-assets": {
|
|
4
|
+
"command": "node",
|
|
5
|
+
"args": [
|
|
6
|
+
"./node_modules/@threenative/core/mcp/assets.mjs"
|
|
7
|
+
],
|
|
8
|
+
"env": {
|
|
9
|
+
"ASSET_DOWNLOAD_DIR": "./public/assets",
|
|
10
|
+
"AUDIO_DOWNLOAD_DIR": "./public/audio"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"threenative-sculpt": {
|
|
14
|
+
"command": "node",
|
|
15
|
+
"args": [
|
|
16
|
+
"./node_modules/@threenative/core/mcp/sculpt.mjs"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
"threenative-engine": {
|
|
20
|
+
"command": "node",
|
|
21
|
+
"args": [
|
|
22
|
+
"./node_modules/@threenative/core/mcp/engine.mjs"
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"threenative-blender": {
|
|
26
|
+
"command": "node",
|
|
27
|
+
"args": [
|
|
28
|
+
"./node_modules/@threenative/core/mcp/blender.mjs"
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"threenative-assets": {
|
|
4
|
+
"command": "node",
|
|
5
|
+
"args": [
|
|
6
|
+
"./node_modules/@threenative/core/mcp/assets.mjs"
|
|
7
|
+
],
|
|
8
|
+
"env": {
|
|
9
|
+
"ASSET_DOWNLOAD_DIR": "./public/assets",
|
|
10
|
+
"AUDIO_DOWNLOAD_DIR": "./public/audio"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"threenative-sculpt": {
|
|
14
|
+
"command": "node",
|
|
15
|
+
"args": [
|
|
16
|
+
"./node_modules/@threenative/core/mcp/sculpt.mjs"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
"threenative-engine": {
|
|
20
|
+
"command": "node",
|
|
21
|
+
"args": [
|
|
22
|
+
"./node_modules/@threenative/core/mcp/engine.mjs"
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"threenative-blender": {
|
|
26
|
+
"command": "node",
|
|
27
|
+
"args": [
|
|
28
|
+
"./node_modules/@threenative/core/mcp/blender.mjs"
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"threenative-assets": {
|
|
4
|
+
"command": "node",
|
|
5
|
+
"args": [
|
|
6
|
+
"./node_modules/@threenative/core/mcp/assets.mjs"
|
|
7
|
+
],
|
|
8
|
+
"env": {
|
|
9
|
+
"ASSET_DOWNLOAD_DIR": "./public/assets",
|
|
10
|
+
"AUDIO_DOWNLOAD_DIR": "./public/audio"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"threenative-sculpt": {
|
|
14
|
+
"command": "node",
|
|
15
|
+
"args": [
|
|
16
|
+
"./node_modules/@threenative/core/mcp/sculpt.mjs"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
"threenative-engine": {
|
|
20
|
+
"command": "node",
|
|
21
|
+
"args": [
|
|
22
|
+
"./node_modules/@threenative/core/mcp/engine.mjs"
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"threenative-blender": {
|
|
26
|
+
"command": "node",
|
|
27
|
+
"args": [
|
|
28
|
+
"./node_modules/@threenative/core/mcp/blender.mjs"
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"servers": {
|
|
3
|
+
"threenative-assets": {
|
|
4
|
+
"type": "stdio",
|
|
5
|
+
"command": "node",
|
|
6
|
+
"args": [
|
|
7
|
+
"./node_modules/@threenative/core/mcp/assets.mjs"
|
|
8
|
+
],
|
|
9
|
+
"env": {
|
|
10
|
+
"ASSET_DOWNLOAD_DIR": "./public/assets",
|
|
11
|
+
"AUDIO_DOWNLOAD_DIR": "./public/audio"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"threenative-sculpt": {
|
|
15
|
+
"type": "stdio",
|
|
16
|
+
"command": "node",
|
|
17
|
+
"args": [
|
|
18
|
+
"./node_modules/@threenative/core/mcp/sculpt.mjs"
|
|
19
|
+
]
|
|
20
|
+
},
|
|
21
|
+
"threenative-engine": {
|
|
22
|
+
"type": "stdio",
|
|
23
|
+
"command": "node",
|
|
24
|
+
"args": [
|
|
25
|
+
"./node_modules/@threenative/core/mcp/engine.mjs"
|
|
26
|
+
]
|
|
27
|
+
},
|
|
28
|
+
"threenative-blender": {
|
|
29
|
+
"type": "stdio",
|
|
30
|
+
"command": "node",
|
|
31
|
+
"args": [
|
|
32
|
+
"./node_modules/@threenative/core/mcp/blender.mjs"
|
|
33
|
+
]
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"context_servers": {
|
|
3
|
+
"threenative-assets": {
|
|
4
|
+
"source": "custom",
|
|
5
|
+
"command": "node",
|
|
6
|
+
"args": [
|
|
7
|
+
"./node_modules/@threenative/core/mcp/assets.mjs"
|
|
8
|
+
],
|
|
9
|
+
"env": {
|
|
10
|
+
"ASSET_DOWNLOAD_DIR": "./public/assets",
|
|
11
|
+
"AUDIO_DOWNLOAD_DIR": "./public/audio"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"threenative-sculpt": {
|
|
15
|
+
"source": "custom",
|
|
16
|
+
"command": "node",
|
|
17
|
+
"args": [
|
|
18
|
+
"./node_modules/@threenative/core/mcp/sculpt.mjs"
|
|
19
|
+
]
|
|
20
|
+
},
|
|
21
|
+
"threenative-engine": {
|
|
22
|
+
"source": "custom",
|
|
23
|
+
"command": "node",
|
|
24
|
+
"args": [
|
|
25
|
+
"./node_modules/@threenative/core/mcp/engine.mjs"
|
|
26
|
+
]
|
|
27
|
+
},
|
|
28
|
+
"threenative-blender": {
|
|
29
|
+
"source": "custom",
|
|
30
|
+
"command": "node",
|
|
31
|
+
"args": [
|
|
32
|
+
"./node_modules/@threenative/core/mcp/blender.mjs"
|
|
33
|
+
]
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# AGENTS.md — __PROJECT_NAME__ snow
|
|
2
|
+
|
|
3
|
+
Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
|
|
4
|
+
|
|
5
|
+
## Ownership
|
|
6
|
+
|
|
7
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the explorer, the boot print, the glade, the weather, the HUD and the
|
|
8
|
+
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. 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
|
+
|
|
10
|
+
## Start every change
|
|
11
|
+
|
|
12
|
+
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
|
|
13
|
+
`engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
|
|
14
|
+
matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
|
|
15
|
+
2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
|
|
16
|
+
direct the user to review it, and wait for explicit approval plus an instruction to implement it.
|
|
17
|
+
3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
|
|
18
|
+
on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
|
|
19
|
+
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
|
|
20
|
+
`npx @threenative/playtest doctor`; missing observations are not zero.
|
|
21
|
+
For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
|
|
22
|
+
|
|
23
|
+
## When the framework blocks you, write plain Three.js
|
|
24
|
+
|
|
25
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
26
|
+
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
27
|
+
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
28
|
+
(API, expectation, result, replacement); never stall the game.
|
|
29
|
+
|
|
30
|
+
## Workflow skills
|
|
31
|
+
|
|
32
|
+
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
33
|
+
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
|
|
34
|
+
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
35
|
+
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
36
|
+
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
37
|
+
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
38
|
+
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
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. 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
|
+
|
|
42
|
+
## Commands and map
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
pnpm dev
|
|
46
|
+
pnpm build
|
|
47
|
+
pnpm test
|
|
48
|
+
pnpm test:native
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The snow is one `SnowField` (`@threenative/core/world`) over one `Heightfield` built in `src/terrain.ts`: indentation, bank, compaction and disturbance composed into the canonical surface that queries, the drawn mesh and the collider all read. Never keep a second height grid.
|
|
52
|
+
`attachSnowPhysics` (`@threenative/physics`) owns the snow collider: each fixed step it reads the solver's contacts for the ball, crate and log, presses each body's own shape with its solved load, and installs the changed surface before the next step. Call `step` from `afterPhysics`, once; `observe()` reports `colliderError` and `loadProvenance` (load is a solver estimate). A kinematic `CharacterBody3D` makes no contact load, so `src/entities/Explorer.ts` plants `src/render/bootPrint.ts` itself with `snow.stamp`, only while `grounded`. Its capsule stands on a coarse walk surface (`walkSurface` in `src/terrain.ts`), not the 6 cm snow collider: Rapier sweeps a character against every triangle under it, which cost ~0.9 ms a step there.
|
|
53
|
+
|
|
54
|
+
Look lives in `src/render/`: `snowSurface.ts` (TSL material, compaction view, redraws `takeDirtyRegion`), `weather.ts` (`GPUParticles3D` snowfall and powder), `explorer.ts`, `scenery.ts`, `props.ts`. Tune response with `depth`/`hardness` and the refill in `src/scenes/Snow.ts`. The React HUD reads `GameState` and sends intents; `src/commands.ts` routes panel verbs into the same functions as the keys. Keep `playtests/survives.playtest.json` as smoke proof and `playtests/snow-physics.playtest.json` honest: it proves drop, settle and rolling track.
|
|
55
|
+
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left movement stick; keyboard is the desktop fallback.
|
|
56
|
+
|
|
57
|
+
## Portable authoring contracts
|
|
58
|
+
|
|
59
|
+
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
|
|
60
|
+
|
|
61
|
+
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.
|
|
62
|
+
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. The fixed step is the snow's clock: deposition, footsteps and contacts never read the frame rate.
|
|
63
|
+
`input.vector("move").y` is +up and means forward; `Snow.ts` turns it into a camera-relative direction.
|
|
64
|
+
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 resetting game
|
|
65
|
+
state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
|
|
66
|
+
is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
|
|
67
|
+
state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
68
|
+
|
|
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. `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 and `TN_QUALITY_TIER` reports
|
|
70
|
+
the source. The bridge flushes about 100 ms; keep readouts in state and frame feedback in Three.js.
|
|
71
|
+
|
|
72
|
+
When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
|
|
73
|
+
retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
|
|
74
|
+
own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
|
|
75
|
+
caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
|
|
76
|
+
(the `<bone>.undefined` failure that plays the bind pose instead of the animation),
|
|
77
|
+
`clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
|
|
78
|
+
clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
|
|
79
|
+
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.
|
|
80
|
+
## Budget real time for the look
|
|
81
|
+
|
|
82
|
+
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
|
|
83
|
+
|
|
84
|
+
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 beside the frame rate; `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.
|
|
85
|
+
|
|
86
|
+
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`.
|
|
87
|
+
## Optional multiplayer transport
|
|
88
|
+
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`.
|
|
89
|
+
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.
|
|
90
|
+
`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.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
<!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
|
|
2
|
+
|
|
3
|
+
# AGENTS.md — __PROJECT_NAME__ snow
|
|
4
|
+
|
|
5
|
+
Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
|
|
6
|
+
|
|
7
|
+
## Ownership
|
|
8
|
+
|
|
9
|
+
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the explorer, the boot print, the glade, the weather, the HUD and the
|
|
10
|
+
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. 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
|
+
|
|
12
|
+
## Start every change
|
|
13
|
+
|
|
14
|
+
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
|
|
15
|
+
`engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
|
|
16
|
+
matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
|
|
17
|
+
2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
|
|
18
|
+
direct the user to review it, and wait for explicit approval plus an instruction to implement it.
|
|
19
|
+
3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
|
|
20
|
+
on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
|
|
21
|
+
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
|
|
22
|
+
`npx @threenative/playtest doctor`; missing observations are not zero.
|
|
23
|
+
For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
|
|
24
|
+
|
|
25
|
+
## When the framework blocks you, write plain Three.js
|
|
26
|
+
|
|
27
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
28
|
+
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
29
|
+
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
30
|
+
(API, expectation, result, replacement); never stall the game.
|
|
31
|
+
|
|
32
|
+
## Workflow skills
|
|
33
|
+
|
|
34
|
+
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
35
|
+
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
|
|
36
|
+
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
37
|
+
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
38
|
+
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
39
|
+
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
40
|
+
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
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. 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
|
+
|
|
44
|
+
## Commands and map
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
pnpm dev
|
|
48
|
+
pnpm build
|
|
49
|
+
pnpm test
|
|
50
|
+
pnpm test:native
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The snow is one `SnowField` (`@threenative/core/world`) over one `Heightfield` built in `src/terrain.ts`: indentation, bank, compaction and disturbance composed into the canonical surface that queries, the drawn mesh and the collider all read. Never keep a second height grid.
|
|
54
|
+
`attachSnowPhysics` (`@threenative/physics`) owns the snow collider: each fixed step it reads the solver's contacts for the ball, crate and log, presses each body's own shape with its solved load, and installs the changed surface before the next step. Call `step` from `afterPhysics`, once; `observe()` reports `colliderError` and `loadProvenance` (load is a solver estimate). A kinematic `CharacterBody3D` makes no contact load, so `src/entities/Explorer.ts` plants `src/render/bootPrint.ts` itself with `snow.stamp`, only while `grounded`. Its capsule stands on a coarse walk surface (`walkSurface` in `src/terrain.ts`), not the 6 cm snow collider: Rapier sweeps a character against every triangle under it, which cost ~0.9 ms a step there.
|
|
55
|
+
|
|
56
|
+
Look lives in `src/render/`: `snowSurface.ts` (TSL material, compaction view, redraws `takeDirtyRegion`), `weather.ts` (`GPUParticles3D` snowfall and powder), `explorer.ts`, `scenery.ts`, `props.ts`. Tune response with `depth`/`hardness` and the refill in `src/scenes/Snow.ts`. The React HUD reads `GameState` and sends intents; `src/commands.ts` routes panel verbs into the same functions as the keys. Keep `playtests/survives.playtest.json` as smoke proof and `playtests/snow-physics.playtest.json` honest: it proves drop, settle and rolling track.
|
|
57
|
+
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left movement stick; keyboard is the desktop fallback.
|
|
58
|
+
|
|
59
|
+
## Portable authoring contracts
|
|
60
|
+
|
|
61
|
+
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
|
|
62
|
+
|
|
63
|
+
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.
|
|
64
|
+
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. The fixed step is the snow's clock: deposition, footsteps and contacts never read the frame rate.
|
|
65
|
+
`input.vector("move").y` is +up and means forward; `Snow.ts` turns it into a camera-relative direction.
|
|
66
|
+
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 resetting game
|
|
67
|
+
state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
|
|
68
|
+
is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
|
|
69
|
+
state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
70
|
+
|
|
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. `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 and `TN_QUALITY_TIER` reports
|
|
72
|
+
the source. The bridge flushes about 100 ms; keep readouts in state and frame feedback in Three.js.
|
|
73
|
+
|
|
74
|
+
When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
|
|
75
|
+
retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
|
|
76
|
+
own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
|
|
77
|
+
caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
|
|
78
|
+
(the `<bone>.undefined` failure that plays the bind pose instead of the animation),
|
|
79
|
+
`clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
|
|
80
|
+
clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
|
|
81
|
+
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.
|
|
82
|
+
## Budget real time for the look
|
|
83
|
+
|
|
84
|
+
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
|
|
85
|
+
|
|
86
|
+
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 beside the frame rate; `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.
|
|
87
|
+
|
|
88
|
+
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`.
|
|
89
|
+
## Optional multiplayer transport
|
|
90
|
+
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`.
|
|
91
|
+
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.
|
|
92
|
+
`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.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Snow glade starter
|
|
2
|
+
|
|
3
|
+
A small winter glade where the snow remembers. The explorer leaves boot prints that sink with
|
|
4
|
+
their weight; a ball dropped into the powder settles into the crater it makes, and pushed, it rolls
|
|
5
|
+
and carves a connected track. A crate and a fallen log press their own shapes. Switch on the
|
|
6
|
+
blizzard and fresh snow slowly fills every track.
|
|
7
|
+
|
|
8
|
+
`SnowField` stores the deformation and `attachSnowPhysics` connects it to real Rapier contacts, so
|
|
9
|
+
the ball rests on the same surface you see. Everything that decides how it looks — the snow
|
|
10
|
+
material, the boot, the explorer, the forest, the flakes — is ordinary source in `src/render/`.
|
|
11
|
+
|
|
12
|
+
Controls: WASD or the arrow keys to walk (Shift to run), drag to orbit and scroll to zoom; `F` drops
|
|
13
|
+
the ball and `G` pushes it; `B` blizzard, `C` camera view, `V` compaction view, `P` auto-explore,
|
|
14
|
+
`R` clears every footprint, `M` sound. On a touch screen, drag the left stick.
|
|
15
|
+
|
|
16
|
+
The crunch and wind clips in `assets/` are generated noise; replace either with a recording.
|
|
17
|
+
|
|
18
|
+
## Commands
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
pnpm dev
|
|
22
|
+
pnpm build
|
|
23
|
+
pnpm typecheck
|
|
24
|
+
pnpm test
|
|
25
|
+
pnpm test:native
|
|
26
|
+
```
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
6
|
+
<title>__PROJECT_NAME__</title>
|
|
7
|
+
</head>
|
|
8
|
+
<body>
|
|
9
|
+
<div id="root"></div>
|
|
10
|
+
<script type="module" src="/src/main.ts"></script>
|
|
11
|
+
</body>
|
|
12
|
+
</html>
|