create-threenative 0.2.15 → 0.2.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-docs/kit-mcp.md +10 -0
- package/agent-docs/kit-router.md +14 -0
- package/agent-docs/kit-stuck.md +7 -0
- package/agent-docs/references/assertion-reference.md +54 -110
- package/agent-docs/references/capability-reference.md +1740 -254
- package/agent-docs/references/conventions.md +299 -0
- package/agent-docs/references/kit-action-rpg.md +40 -0
- package/agent-docs/references/kit-adventure.md +40 -0
- package/agent-docs/references/kit-collectathon.md +38 -0
- package/agent-docs/references/kit-kart.md +31 -0
- package/agent-docs/references/kit-minimal.md +29 -0
- package/agent-docs/references/kit-platformer.md +34 -0
- package/agent-docs/references/kit-puzzle.md +22 -0
- package/agent-docs/references/kit-racing.md +26 -0
- package/agent-docs/references/kit-rain.md +31 -0
- package/agent-docs/references/kit-rts.md +34 -0
- package/agent-docs/references/kit-runner.md +32 -0
- package/agent-docs/references/kit-sailing.md +41 -0
- package/agent-docs/references/kit-shooter.md +33 -0
- package/agent-docs/references/kit-snow.md +33 -0
- package/agent-docs/references/kit-starter.md +55 -0
- package/agent-docs/references/kit-tower-defense.md +27 -0
- package/agent-docs/references/performance-basics.md +8 -4
- package/agent-docs/references/terrain-authoring.md +2 -1
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +84 -59
- package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/.claude/settings.json +25 -0
- package/agent-files/.codex/hooks.json +18 -1
- package/dist/index.d.ts +97 -6
- package/dist/index.js +899 -271
- package/dist/terrain-kit.d.ts +7 -0
- package/dist/terrain-kit.js +82 -0
- package/dist/threenative.js +114 -16
- package/dist/web-engine-ccd-ik-solver.js +127 -0
- package/dist/web-engine-gltf-loader.js +71 -20
- package/dist/web-engine-post-effects.js +39 -14
- package/dist/web-engine-runtime.js +10011 -4101
- package/package.json +15 -9
- package/template-assets/clearwater/README.md +1 -1
- package/template-assets/patches/manifest.json +18 -0
- package/template-assets/patches/three@0.187.0.patch +2004 -407
- package/template-assets/terrain/alpine/assets.json +12 -0
- package/template-assets/terrain/alpine/bake.mjs +6 -0
- package/template-assets/terrain/alpine/credits.json +164 -0
- package/template-assets/terrain/alpine/heightmap.r16 +0 -0
- package/template-assets/terrain/alpine/recipe.json +119 -0
- package/template-assets/terrain/alpine/surface.json +53 -0
- package/template-assets/terrain/coastal/assets.json +11 -0
- package/template-assets/terrain/coastal/bake.mjs +6 -0
- package/template-assets/terrain/coastal/credits.json +117 -0
- package/template-assets/terrain/coastal/heightmap.r16 +0 -0
- package/template-assets/terrain/coastal/recipe.json +113 -0
- package/template-assets/terrain/coastal/surface.json +41 -0
- package/template-assets/terrain/desert/assets.json +12 -0
- package/template-assets/terrain/desert/bake.mjs +6 -0
- package/template-assets/terrain/desert/credits.json +164 -0
- package/template-assets/terrain/desert/heightmap.r16 +0 -0
- package/template-assets/terrain/desert/recipe.json +108 -0
- package/template-assets/terrain/desert/surface.json +54 -0
- package/template-assets/terrain/forest/assets.json +65 -0
- package/template-assets/terrain/forest/bake.mjs +8 -0
- package/template-assets/terrain/forest/credits.json +225 -0
- package/template-assets/terrain/forest/heightmap.r16 +0 -0
- package/template-assets/terrain/forest/recipe.json +350 -0
- package/template-assets/terrain/forest/surface.json +79 -0
- package/template-assets/terrain/tundra/assets.json +12 -0
- package/template-assets/terrain/tundra/bake.mjs +6 -0
- package/template-assets/terrain/tundra/credits.json +164 -0
- package/template-assets/terrain/tundra/heightmap.r16 +0 -0
- package/template-assets/terrain/tundra/recipe.json +277 -0
- package/template-assets/terrain/tundra/surface.json +54 -0
- package/templates/action-rpg/AGENTS.md +103 -84
- package/templates/action-rpg/CLAUDE.md +103 -84
- package/templates/action-rpg/kit.json +1 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/spells.playtest.json +20 -0
- package/templates/action-rpg/src/game.ts +2 -1
- package/templates/action-rpg/src/render/atmosphere.ts +11 -16
- package/templates/action-rpg/src/render/backlightControls.ts +10 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
- package/templates/action-rpg/src/render/clouds.ts +13 -0
- package/templates/action-rpg/src/render/gpuSky.ts +4 -7
- package/templates/action-rpg/src/render/materialLighting.ts +5 -5
- package/templates/action-rpg/src/render/quality.ts +10 -33
- package/templates/action-rpg/src/scenes/Play.ts +30 -1
- package/templates/action-rpg/src/style.css +4 -0
- package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
- package/templates/action-rpg/threenative.config.ts +0 -3
- package/templates/action-rpg/vite.config.ts +2 -0
- package/templates/adventure/AGENTS.md +92 -44
- package/templates/adventure/CLAUDE.md +92 -44
- package/templates/adventure/kit.json +5 -1
- package/templates/adventure/package.json +7 -7
- package/templates/adventure/src/game.ts +1 -1
- package/templates/adventure/src/style.css +4 -0
- package/templates/adventure/tsconfig.json +1 -1
- package/templates/adventure/vite.config.ts +2 -0
- package/templates/collectathon/AGENTS.md +93 -42
- package/templates/collectathon/CLAUDE.md +93 -42
- package/templates/collectathon/package.json +7 -7
- package/templates/collectathon/src/game.ts +1 -1
- package/templates/collectathon/src/level/Course.ts +55 -9
- package/templates/collectathon/src/level/terrain.ts +27 -6
- package/templates/collectathon/src/main.ts +1 -0
- package/templates/collectathon/src/render/foliage.ts +359 -98
- package/templates/collectathon/src/render/sky.ts +76 -12
- package/templates/collectathon/src/render/water.ts +32 -10
- package/templates/collectathon/src/scenes/Play.ts +18 -5
- package/templates/collectathon/src/style.css +4 -0
- package/templates/collectathon/tsconfig.json +1 -1
- package/templates/collectathon/vite.config.ts +2 -0
- package/templates/kart/AGENTS.md +87 -42
- package/templates/kart/CLAUDE.md +87 -42
- package/templates/kart/package.json +6 -6
- package/templates/kart/src/game.ts +1 -1
- package/templates/kart/src/main.ts +1 -0
- package/templates/kart/src/style.css +4 -0
- package/templates/kart/tsconfig.json +1 -1
- package/templates/kart/vite.config.ts +2 -0
- package/templates/minimal/AGENTS.md +105 -84
- package/templates/minimal/CLAUDE.md +105 -84
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/playtests/stands-still.playtest.json +30 -0
- package/templates/minimal/src/game.ts +1 -1
- package/templates/minimal/src/render/atmosphere.ts +11 -16
- package/templates/minimal/src/render/backlightControls.ts +10 -0
- package/templates/minimal/src/render/backlightMaterial.ts +4 -4
- package/templates/minimal/src/render/camera.ts +13 -2
- package/templates/minimal/src/render/clouds.ts +13 -0
- package/templates/minimal/src/render/gpuSky.ts +4 -7
- package/templates/minimal/src/render/lighting.ts +4 -2
- package/templates/minimal/src/render/materialLighting.ts +5 -5
- package/templates/minimal/src/render/materials.ts +10 -0
- package/templates/minimal/src/render/quality.ts +7 -32
- package/templates/minimal/src/scenes/Play.ts +4 -1
- package/templates/minimal/vite.config.ts +7 -1
- package/templates/platformer/AGENTS.md +95 -46
- package/templates/platformer/CLAUDE.md +95 -46
- package/templates/platformer/index.html +1 -1
- package/templates/platformer/main.html +12 -0
- package/templates/platformer/package.json +7 -7
- package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
- package/templates/platformer/playtests/gamepad.playtest.json +30 -0
- package/templates/platformer/src/entities/Fox.ts +21 -6
- package/templates/platformer/src/game.ts +1 -1
- package/templates/platformer/src/main.ts +1 -0
- package/templates/platformer/src/render/backlightControls.ts +10 -0
- package/templates/platformer/src/render/backlightMaterial.ts +4 -4
- package/templates/platformer/src/render/materialLighting.ts +5 -5
- package/templates/platformer/src/render/quality.ts +7 -32
- package/templates/platformer/src/scenes/Play.ts +2 -1
- package/templates/platformer/src/style.css +4 -0
- package/templates/platformer/src/worker-page.ts +29 -0
- package/templates/platformer/src/worker.ts +5 -0
- package/templates/platformer/tsconfig.json +1 -1
- package/templates/platformer/vite.config.ts +4 -0
- package/templates/puzzle/AGENTS.md +97 -80
- package/templates/puzzle/CLAUDE.md +97 -80
- package/templates/puzzle/package.json +7 -7
- package/templates/puzzle/src/game.ts +1 -1
- package/templates/puzzle/src/render/backlightControls.ts +10 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
- package/templates/puzzle/src/render/materialLighting.ts +5 -5
- package/templates/puzzle/src/render/quality.ts +7 -32
- package/templates/puzzle/src/scenes/Play.ts +1 -1
- package/templates/puzzle/src/style.css +4 -0
- package/templates/puzzle/tsconfig.json +1 -1
- package/templates/puzzle/vite.config.ts +2 -0
- package/templates/racing/AGENTS.md +100 -82
- package/templates/racing/CLAUDE.md +100 -82
- package/templates/racing/package.json +7 -7
- package/templates/racing/src/game.ts +1 -1
- package/templates/racing/src/render/atmosphere.ts +11 -16
- package/templates/racing/src/render/backlightControls.ts +10 -0
- package/templates/racing/src/render/backlightMaterial.ts +4 -4
- package/templates/racing/src/render/clouds.ts +13 -0
- package/templates/racing/src/render/gpuSky.ts +4 -7
- package/templates/racing/src/render/materialLighting.ts +5 -5
- package/templates/racing/src/render/quality.ts +7 -32
- package/templates/racing/src/scenes/Race.ts +4 -1
- package/templates/racing/src/style.css +4 -0
- package/templates/racing/tsconfig.json +1 -1
- package/templates/racing/vite.config.ts +2 -0
- package/templates/rain/AGENTS.md +96 -84
- package/templates/rain/CLAUDE.md +96 -84
- package/templates/rain/native-playtests/lightning.playtest.json +85 -10
- package/templates/rain/package.json +6 -6
- package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
- package/templates/rain/src/game.ts +1 -1
- package/templates/rain/src/scenes/Boot.ts +1 -0
- package/templates/rain/src/state.ts +7 -0
- package/templates/rain/src/ui/GameUi.tsx +7 -1
- package/templates/rain/vite.config.ts +6 -0
- package/templates/rts/AGENTS.md +100 -85
- package/templates/rts/CLAUDE.md +100 -85
- package/templates/rts/package.json +6 -6
- package/templates/rts/src/game.ts +1 -1
- package/templates/rts/src/render/backlightControls.ts +10 -0
- package/templates/rts/src/render/backlightMaterial.ts +4 -4
- package/templates/rts/src/render/materialLighting.ts +5 -5
- package/templates/rts/src/render/quality.ts +7 -31
- package/templates/rts/src/scenes/Play.ts +1 -1
- package/templates/rts/src/style.css +4 -0
- package/templates/rts/vite.config.ts +2 -0
- package/templates/runner/AGENTS.md +97 -80
- package/templates/runner/CLAUDE.md +97 -80
- package/templates/runner/package.json +7 -7
- package/templates/runner/playtests/performance.playtest.json +1 -1
- package/templates/runner/src/game.ts +1 -1
- package/templates/runner/src/render/atmosphere.ts +11 -16
- package/templates/runner/src/render/backlightControls.ts +10 -0
- package/templates/runner/src/render/backlightMaterial.ts +4 -4
- package/templates/runner/src/render/clouds.ts +13 -0
- package/templates/runner/src/render/gpuSky.ts +4 -7
- package/templates/runner/src/render/lighting.ts +53 -11
- package/templates/runner/src/render/materialLighting.ts +5 -5
- package/templates/runner/src/render/quality.ts +7 -32
- package/templates/runner/src/scenes/Run.ts +8 -4
- package/templates/runner/src/style.css +4 -0
- package/templates/runner/threenative.config.ts +0 -3
- package/templates/runner/tsconfig.json +1 -1
- package/templates/runner/vite.config.ts +2 -0
- package/templates/sailing/AGENTS.md +96 -79
- package/templates/sailing/CLAUDE.md +96 -79
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/playtests/sails.playtest.json +1 -0
- package/templates/sailing/src/game.ts +1 -1
- package/templates/sailing/src/render/backlightControls.ts +10 -0
- package/templates/sailing/src/render/backlightMaterial.ts +4 -4
- package/templates/sailing/src/render/environmentSetup.ts +1 -1
- package/templates/sailing/src/render/materialLighting.ts +5 -5
- package/templates/sailing/src/render/quality.ts +7 -32
- package/templates/sailing/src/render/sky.ts +4 -0
- package/templates/sailing/src/style.css +5 -0
- package/templates/sailing/threenative.config.ts +0 -3
- package/templates/sailing/vite.config.ts +6 -0
- package/templates/shooter/AGENTS.md +97 -68
- package/templates/shooter/CLAUDE.md +97 -68
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/game.ts +3 -2
- package/templates/shooter/src/render/atmosphere.ts +11 -16
- package/templates/shooter/src/render/backlightControls.ts +10 -0
- package/templates/shooter/src/render/backlightMaterial.ts +4 -4
- package/templates/shooter/src/render/clouds.ts +13 -0
- package/templates/shooter/src/render/gpuSky.ts +4 -7
- package/templates/shooter/src/render/materialLighting.ts +5 -5
- package/templates/shooter/src/render/quality.ts +10 -33
- package/templates/shooter/src/scenes/Play.ts +4 -1
- package/templates/shooter/src/style.css +4 -0
- package/templates/shooter/vite.config.ts +2 -0
- package/templates/snow/AGENTS.md +95 -76
- package/templates/snow/CLAUDE.md +95 -76
- package/templates/snow/package.json +7 -7
- package/templates/snow/src/game.ts +1 -1
- package/templates/snow/src/render/backlightControls.ts +10 -0
- package/templates/snow/src/render/backlightMaterial.ts +4 -4
- package/templates/snow/src/render/materialLighting.ts +5 -5
- package/templates/snow/src/render/quality.ts +7 -32
- package/templates/snow/src/style.css +5 -0
- package/templates/snow/threenative.config.ts +0 -3
- package/templates/snow/vite.config.ts +6 -0
- package/templates/starter/AGENTS.md +109 -88
- package/templates/starter/CLAUDE.md +109 -88
- package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
- package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Crate.ts +5 -2
- package/templates/starter/src/entities/Player.ts +10 -22
- package/templates/starter/src/game.ts +4 -3
- package/templates/starter/src/render/adaptiveQuality.ts +17 -0
- package/templates/starter/src/render/atmosphere.ts +11 -16
- package/templates/starter/src/render/backlightControls.ts +10 -0
- package/templates/starter/src/render/backlightMaterial.ts +4 -4
- package/templates/starter/src/render/clouds.ts +13 -0
- package/templates/starter/src/render/contactShadow.ts +1 -1
- package/templates/starter/src/render/gpuSky.ts +4 -7
- package/templates/starter/src/render/lighting.ts +54 -4
- package/templates/starter/src/render/materialLighting.ts +5 -5
- package/templates/starter/src/render/postprocessing.ts +11 -10
- package/templates/starter/src/render/quality.ts +14 -1
- package/templates/starter/src/render/temporalAA.ts +8 -7
- package/templates/starter/src/render/temporalAAFrame.ts +30 -9
- package/templates/starter/src/render/temporalAAResolve.ts +15 -1
- package/templates/starter/src/render/temporalClampRelease.ts +183 -0
- package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
- package/templates/starter/src/render/temporalMoire.ts +190 -0
- package/templates/starter/src/render/temporalResolve.ts +75 -16
- package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
- package/templates/starter/src/scenes/Play.ts +53 -32
- package/templates/starter/src/state.ts +2 -0
- package/templates/starter/src/style.css +4 -0
- package/templates/starter/src/ui/Menu.tsx +5 -1
- package/templates/starter/vite.config.ts +2 -0
- package/templates/tower-defense/AGENTS.md +97 -81
- package/templates/tower-defense/CLAUDE.md +97 -81
- package/templates/tower-defense/package.json +7 -7
- package/templates/tower-defense/src/game.ts +1 -1
- package/templates/tower-defense/src/render/backlightControls.ts +10 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
- package/templates/tower-defense/src/render/materialLighting.ts +5 -5
- package/templates/tower-defense/src/render/quality.ts +7 -32
- package/templates/tower-defense/src/scenes/Battle.ts +1 -1
- package/templates/tower-defense/src/style.css +4 -0
- package/templates/tower-defense/tsconfig.json +1 -1
- package/templates/tower-defense/vite.config.ts +2 -0
- package/capabilities.json +0 -9197
- package/templates/AGENTS.md +0 -21
- package/templates/CLAUDE.md +0 -23
- package/templates/action-rpg/.codex/config.toml +0 -23
- package/templates/action-rpg/.cursor/mcp.json +0 -38
- package/templates/action-rpg/.gemini/settings.json +0 -38
- package/templates/action-rpg/.mcp.json +0 -38
- package/templates/action-rpg/.vscode/mcp.json +0 -43
- package/templates/action-rpg/.zed/settings.json +0 -43
- package/templates/action-rpg/opencode.json +0 -49
- package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
- package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
- package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
- package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
- package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
- package/templates/adventure/.codex/config.toml +0 -23
- package/templates/adventure/.cursor/mcp.json +0 -38
- package/templates/adventure/.gemini/settings.json +0 -38
- package/templates/adventure/.mcp.json +0 -38
- package/templates/adventure/.vscode/mcp.json +0 -43
- package/templates/adventure/.zed/settings.json +0 -43
- package/templates/adventure/opencode.json +0 -49
- package/templates/collectathon/.codex/config.toml +0 -23
- package/templates/collectathon/.cursor/mcp.json +0 -38
- package/templates/collectathon/.gemini/settings.json +0 -38
- package/templates/collectathon/.mcp.json +0 -38
- package/templates/collectathon/.vscode/mcp.json +0 -43
- package/templates/collectathon/.zed/settings.json +0 -43
- package/templates/collectathon/opencode.json +0 -49
- package/templates/kart/.codex/config.toml +0 -23
- package/templates/kart/.cursor/mcp.json +0 -38
- package/templates/kart/.gemini/settings.json +0 -38
- package/templates/kart/.mcp.json +0 -38
- package/templates/kart/.vscode/mcp.json +0 -43
- package/templates/kart/.zed/settings.json +0 -43
- package/templates/kart/opencode.json +0 -49
- package/templates/minimal/.codex/config.toml +0 -23
- package/templates/minimal/.cursor/mcp.json +0 -38
- package/templates/minimal/.gemini/settings.json +0 -38
- package/templates/minimal/.mcp.json +0 -38
- package/templates/minimal/.vscode/mcp.json +0 -43
- package/templates/minimal/.zed/settings.json +0 -43
- package/templates/minimal/opencode.json +0 -49
- package/templates/minimal/src/render/environmentContribution.ts +0 -188
- package/templates/minimal/src/render/environmentRadiance.ts +0 -36
- package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
- package/templates/minimal/src/render/environmentSampling.ts +0 -193
- package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
- package/templates/platformer/.codex/config.toml +0 -23
- package/templates/platformer/.cursor/mcp.json +0 -38
- package/templates/platformer/.gemini/settings.json +0 -38
- package/templates/platformer/.mcp.json +0 -38
- package/templates/platformer/.vscode/mcp.json +0 -43
- package/templates/platformer/.zed/settings.json +0 -43
- package/templates/platformer/opencode.json +0 -49
- package/templates/platformer/src/render/environmentContribution.ts +0 -188
- package/templates/platformer/src/render/environmentRadiance.ts +0 -36
- package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
- package/templates/platformer/src/render/environmentSampling.ts +0 -193
- package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
- package/templates/puzzle/.codex/config.toml +0 -23
- package/templates/puzzle/.cursor/mcp.json +0 -38
- package/templates/puzzle/.gemini/settings.json +0 -38
- package/templates/puzzle/.mcp.json +0 -38
- package/templates/puzzle/.vscode/mcp.json +0 -43
- package/templates/puzzle/.zed/settings.json +0 -43
- package/templates/puzzle/opencode.json +0 -49
- package/templates/puzzle/src/render/environmentContribution.ts +0 -188
- package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
- package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
- package/templates/puzzle/src/render/environmentSampling.ts +0 -193
- package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
- package/templates/racing/.codex/config.toml +0 -23
- package/templates/racing/.cursor/mcp.json +0 -38
- package/templates/racing/.gemini/settings.json +0 -38
- package/templates/racing/.mcp.json +0 -38
- package/templates/racing/.vscode/mcp.json +0 -43
- package/templates/racing/.zed/settings.json +0 -43
- package/templates/racing/opencode.json +0 -49
- package/templates/racing/src/render/environmentContribution.ts +0 -188
- package/templates/racing/src/render/environmentRadiance.ts +0 -36
- package/templates/racing/src/render/environmentSampleCache.ts +0 -43
- package/templates/racing/src/render/environmentSampling.ts +0 -193
- package/templates/racing/src/render/environmentSnapshot.ts +0 -53
- package/templates/rain/.codex/config.toml +0 -23
- package/templates/rain/.cursor/mcp.json +0 -38
- package/templates/rain/.gemini/settings.json +0 -38
- package/templates/rain/.mcp.json +0 -38
- package/templates/rain/.vscode/mcp.json +0 -43
- package/templates/rain/.zed/settings.json +0 -43
- package/templates/rain/opencode.json +0 -49
- package/templates/rts/.codex/config.toml +0 -23
- package/templates/rts/.cursor/mcp.json +0 -38
- package/templates/rts/.gemini/settings.json +0 -38
- package/templates/rts/.mcp.json +0 -38
- package/templates/rts/.vscode/mcp.json +0 -43
- package/templates/rts/.zed/settings.json +0 -43
- package/templates/rts/opencode.json +0 -49
- package/templates/rts/src/render/environmentContribution.ts +0 -188
- package/templates/rts/src/render/environmentRadiance.ts +0 -36
- package/templates/rts/src/render/environmentSampleCache.ts +0 -43
- package/templates/rts/src/render/environmentSampling.ts +0 -193
- package/templates/rts/src/render/environmentSnapshot.ts +0 -53
- package/templates/runner/.codex/config.toml +0 -23
- package/templates/runner/.cursor/mcp.json +0 -38
- package/templates/runner/.gemini/settings.json +0 -38
- package/templates/runner/.mcp.json +0 -38
- package/templates/runner/.vscode/mcp.json +0 -43
- package/templates/runner/.zed/settings.json +0 -43
- package/templates/runner/README.md +0 -43
- package/templates/runner/opencode.json +0 -49
- package/templates/runner/src/render/environmentContribution.ts +0 -188
- package/templates/runner/src/render/environmentRadiance.ts +0 -36
- package/templates/runner/src/render/environmentSampleCache.ts +0 -43
- package/templates/runner/src/render/environmentSampling.ts +0 -193
- package/templates/runner/src/render/environmentSnapshot.ts +0 -53
- package/templates/sailing/.codex/config.toml +0 -23
- package/templates/sailing/.cursor/mcp.json +0 -38
- package/templates/sailing/.gemini/settings.json +0 -38
- package/templates/sailing/.mcp.json +0 -38
- package/templates/sailing/.vscode/mcp.json +0 -43
- package/templates/sailing/.zed/settings.json +0 -43
- package/templates/sailing/README.md +0 -28
- package/templates/sailing/opencode.json +0 -49
- package/templates/sailing/src/render/environmentContribution.ts +0 -188
- package/templates/sailing/src/render/environmentRadiance.ts +0 -36
- package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
- package/templates/sailing/src/render/environmentSampling.ts +0 -193
- package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
- package/templates/shooter/.codex/config.toml +0 -23
- package/templates/shooter/.cursor/mcp.json +0 -38
- package/templates/shooter/.gemini/settings.json +0 -38
- package/templates/shooter/.mcp.json +0 -38
- package/templates/shooter/.vscode/mcp.json +0 -43
- package/templates/shooter/.zed/settings.json +0 -43
- package/templates/shooter/opencode.json +0 -49
- package/templates/shooter/src/render/environmentContribution.ts +0 -188
- package/templates/shooter/src/render/environmentRadiance.ts +0 -36
- package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
- package/templates/shooter/src/render/environmentSampling.ts +0 -193
- package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
- package/templates/snow/.codex/config.toml +0 -23
- package/templates/snow/.cursor/mcp.json +0 -38
- package/templates/snow/.gemini/settings.json +0 -38
- package/templates/snow/.mcp.json +0 -38
- package/templates/snow/.vscode/mcp.json +0 -43
- package/templates/snow/.zed/settings.json +0 -43
- package/templates/snow/README.md +0 -26
- package/templates/snow/opencode.json +0 -49
- package/templates/snow/src/render/environmentContribution.ts +0 -188
- package/templates/snow/src/render/environmentRadiance.ts +0 -36
- package/templates/snow/src/render/environmentSampleCache.ts +0 -43
- package/templates/snow/src/render/environmentSampling.ts +0 -193
- package/templates/snow/src/render/environmentSnapshot.ts +0 -53
- package/templates/starter/.codex/config.toml +0 -23
- package/templates/starter/.cursor/mcp.json +0 -38
- package/templates/starter/.gemini/settings.json +0 -38
- package/templates/starter/.mcp.json +0 -38
- package/templates/starter/.vscode/mcp.json +0 -43
- package/templates/starter/.zed/settings.json +0 -43
- package/templates/starter/opencode.json +0 -49
- package/templates/starter/src/render/environmentContribution.ts +0 -188
- package/templates/starter/src/render/environmentRadiance.ts +0 -36
- package/templates/starter/src/render/environmentSampleCache.ts +0 -43
- package/templates/starter/src/render/environmentSampling.ts +0 -193
- package/templates/starter/src/render/environmentSnapshot.ts +0 -53
- package/templates/starter/src/render/rendererGate.ts +0 -36
- package/templates/tower-defense/.codex/config.toml +0 -23
- package/templates/tower-defense/.cursor/mcp.json +0 -38
- package/templates/tower-defense/.gemini/settings.json +0 -38
- package/templates/tower-defense/.mcp.json +0 -38
- package/templates/tower-defense/.vscode/mcp.json +0 -43
- package/templates/tower-defense/.zed/settings.json +0 -43
- package/templates/tower-defense/README.md +0 -16
- package/templates/tower-defense/opencode.json +0 -49
- package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
- package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
- package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
- package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
- package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
|
@@ -1,94 +1,112 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- shared: kit-identity -->
|
|
2
|
+
# AGENTS.md — __PROJECT_NAME__ (Circuit racing, the racing kit)
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
Three laps, ordered checklines, rescue sectors, boost pads, and route-progress ranking. Routing words: racing. `CLAUDE.md` is a copy of this file.
|
|
5
|
+
<!-- /shared -->
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
+
<!-- shared: kit-router -->
|
|
8
|
+
## Authoring flow
|
|
7
9
|
|
|
8
|
-
|
|
10
|
+
Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
|
|
9
11
|
|
|
10
|
-
1. **
|
|
11
|
-
2. **
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
|
|
13
|
+
2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
|
|
14
|
+
3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
|
|
15
|
+
4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
|
|
16
|
+
5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
|
|
17
|
+
6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
|
|
18
|
+
7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
|
|
19
|
+
8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
|
|
20
|
+
|
|
21
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
22
|
+
<!-- /shared -->
|
|
23
|
+
|
|
24
|
+
<!-- shared: kit-mcp -->
|
|
25
|
+
## MCP servers
|
|
26
|
+
|
|
27
|
+
`.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
|
|
18
28
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
29
|
+
- `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
|
|
30
|
+
- `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
|
|
31
|
+
- `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
|
|
32
|
+
- `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
|
|
33
|
+
- `threenative-terrain`: any terrain, from words. `terrain_generate`.
|
|
34
|
+
- `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
|
|
35
|
+
<!-- /shared -->
|
|
23
36
|
|
|
24
|
-
##
|
|
37
|
+
## This kit
|
|
25
38
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
33
|
-
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
34
|
-
- 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 runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
|
|
39
|
+
<!-- shared: kit-files -->
|
|
40
|
+
Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `kart/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `track/`, `ui/`.
|
|
41
|
+
11 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
42
|
+
Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
|
|
43
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-racing.md`.
|
|
44
|
+
<!-- /shared -->
|
|
35
45
|
|
|
36
|
-
|
|
46
|
+
`src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's measured travel direction; `TrackSector.ts` ray-probes the road for rescue.
|
|
47
|
+
`src/conventions.ts` scales the car; suspension and snap-to-ground own floor contact.
|
|
48
|
+
|
|
49
|
+
<!-- shared: kit-commands -->
|
|
50
|
+
## Commands
|
|
37
51
|
|
|
38
52
|
```sh
|
|
39
|
-
pnpm dev
|
|
40
|
-
pnpm
|
|
41
|
-
pnpm build --target desktop
|
|
42
|
-
pnpm test:native
|
|
43
|
-
|
|
44
|
-
|
|
53
|
+
pnpm dev # play in the browser
|
|
54
|
+
pnpm test # typecheck, lint, format, then every playtest
|
|
55
|
+
pnpm build --target desktop # also: web, android, ios
|
|
56
|
+
pnpm test:native # native proof
|
|
57
|
+
npx threenative doctor # build, import, device or blank-frame failure
|
|
58
|
+
npx threenative doctor --fix # refresh agent files
|
|
45
59
|
```
|
|
60
|
+
<!-- /shared -->
|
|
61
|
+
|
|
62
|
+
<!-- shared: kit-conventions -->
|
|
63
|
+
## Conventions
|
|
64
|
+
|
|
65
|
+
Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
|
|
66
|
+
|
|
67
|
+
- **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
|
|
68
|
+
- **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
|
|
69
|
+
- **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
|
|
70
|
+
- **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
|
|
71
|
+
- **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
|
|
72
|
+
- **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
|
|
73
|
+
- **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
|
|
74
|
+
- **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
|
|
75
|
+
- **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
|
|
76
|
+
- **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
|
|
77
|
+
- **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
|
|
78
|
+
- **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
|
|
79
|
+
- **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
|
|
80
|
+
- **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
|
|
81
|
+
- **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
|
|
82
|
+
- **One metre is one metre** `#scale`: `normaliseToMetres`. Override: per-call options.
|
|
83
|
+
- **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
|
|
84
|
+
- **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
|
|
85
|
+
- **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
|
|
86
|
+
- **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
|
|
87
|
+
- **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
|
|
88
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
89
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
90
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
91
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
92
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
93
|
+
- **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
|
|
94
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
95
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
96
|
+
- **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
|
|
97
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
98
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
99
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
100
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
101
|
+
- **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
|
|
102
|
+
<!-- /shared -->
|
|
103
|
+
|
|
104
|
+
<!-- shared: kit-stuck -->
|
|
105
|
+
## When the framework blocks you, write plain Three.js
|
|
106
|
+
|
|
107
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
|
|
108
|
+
|
|
109
|
+
## Stuck
|
|
46
110
|
|
|
47
|
-
`
|
|
48
|
-
|
|
49
|
-
rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both
|
|
50
|
-
cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`.
|
|
51
|
-
`RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that
|
|
52
|
-
same car under a pure-pursuit controller at a constant pace. Keep `playtests/survives.playtest.json` as
|
|
53
|
-
the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
|
|
54
|
-
|
|
55
|
-
**Two things about the vehicle are invisible in the API.** `suspensionStiffness` is a frequency
|
|
56
|
-
squared, so the strut sags `gravity / (4 * stiffness)` and Godot's default of 20 bottoms it out, and a
|
|
57
|
-
positive steering angle turns the chassis toward its own `-z` — so the input is negated once and the
|
|
58
|
-
visual front wheels take that same signed angle. `CarBody.ts` carries every other number.
|
|
59
|
-
|
|
60
|
-
## Portable authoring contracts
|
|
61
|
-
|
|
62
|
-
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.
|
|
63
|
-
|
|
64
|
-
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.
|
|
65
|
-
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable.
|
|
66
|
-
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `ctx.goto(name)` rebuilds without
|
|
67
|
-
resetting game 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`;
|
|
72
|
-
override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
|
|
73
|
-
the source. `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset; the render log reports the override. It has Unreal's bloom with no threshold (`unrealBloomEnabled`), local exposure (`localExposureEnabled`, off on `low`), a cosine-fourth vignette (`vignetteAmount: 0.4`) and no camera motion blur (`motionBlurEnabled: true` is the opt-in). Anti-aliasing is core's: 4x MSAA on `high`, SMAA on `medium` and `low`; `temporalAA: true` is the named opt-in. The grade is neutral and the frame has no film grain. Each stage has a named override: `unrealBloomEnabled: false` returns to Three's `BloomNode` (`bloomStrength`, `bloomRadius`, `bloomThreshold`), and `vignetteAmount: 0` removes the vignette. For a colour grade or grain, add the starter's `grade.ts` and `public/grade.cube`, then set `gradeIntensity` and `grainIntensity`. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/boost and outcome text so a brighter road or sky does not erase the readouts.
|
|
74
|
-
|
|
75
|
-
When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
|
|
76
|
-
retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
|
|
77
|
-
own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
|
|
78
|
-
caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
|
|
79
|
-
(the `<bone>.undefined` failure that plays the bind pose instead of the animation),
|
|
80
|
-
`clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
|
|
81
|
-
clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
|
|
82
|
-
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. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
|
|
83
|
-
|
|
84
|
-
`updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
|
|
85
|
-
## Budget real time for the look
|
|
86
|
-
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
|
|
87
|
-
|
|
88
|
-
Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
89
|
-
|
|
90
|
-
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`.
|
|
91
|
-
## Optional multiplayer transport
|
|
92
|
-
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`.
|
|
93
|
-
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.
|
|
94
|
-
`src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. 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.
|
|
111
|
+
`npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
|
|
112
|
+
<!-- /shared -->
|
|
@@ -1,96 +1,114 @@
|
|
|
1
1
|
<!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<!-- shared: kit-identity -->
|
|
4
|
+
# AGENTS.md — __PROJECT_NAME__ (Circuit racing, the racing kit)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Three laps, ordered checklines, rescue sectors, boost pads, and route-progress ranking. Routing words: racing. `CLAUDE.md` is a copy of this file.
|
|
7
|
+
<!-- /shared -->
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
+
<!-- shared: kit-router -->
|
|
10
|
+
## Authoring flow
|
|
9
11
|
|
|
10
|
-
|
|
12
|
+
Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
|
|
11
13
|
|
|
12
|
-
1. **
|
|
13
|
-
2. **
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
14
|
+
1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
|
|
15
|
+
2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
|
|
16
|
+
3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
|
|
17
|
+
4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
|
|
18
|
+
5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
|
|
19
|
+
6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
|
|
20
|
+
7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
|
|
21
|
+
8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
|
|
22
|
+
|
|
23
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
24
|
+
<!-- /shared -->
|
|
25
|
+
|
|
26
|
+
<!-- shared: kit-mcp -->
|
|
27
|
+
## MCP servers
|
|
28
|
+
|
|
29
|
+
`.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
|
|
20
30
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
31
|
+
- `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
|
|
32
|
+
- `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
|
|
33
|
+
- `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
|
|
34
|
+
- `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
|
|
35
|
+
- `threenative-terrain`: any terrain, from words. `terrain_generate`.
|
|
36
|
+
- `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
|
|
37
|
+
<!-- /shared -->
|
|
25
38
|
|
|
26
|
-
##
|
|
39
|
+
## This kit
|
|
27
40
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
35
|
-
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
36
|
-
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
|
|
41
|
+
<!-- shared: kit-files -->
|
|
42
|
+
Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `kart/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `track/`, `ui/`.
|
|
43
|
+
11 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
44
|
+
Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
|
|
45
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-racing.md`.
|
|
46
|
+
<!-- /shared -->
|
|
37
47
|
|
|
38
|
-
|
|
48
|
+
`src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's measured travel direction; `TrackSector.ts` ray-probes the road for rescue.
|
|
49
|
+
`src/conventions.ts` scales the car; suspension and snap-to-ground own floor contact.
|
|
50
|
+
|
|
51
|
+
<!-- shared: kit-commands -->
|
|
52
|
+
## Commands
|
|
39
53
|
|
|
40
54
|
```sh
|
|
41
|
-
pnpm dev
|
|
42
|
-
pnpm
|
|
43
|
-
pnpm build --target desktop
|
|
44
|
-
pnpm test:native
|
|
45
|
-
|
|
46
|
-
|
|
55
|
+
pnpm dev # play in the browser
|
|
56
|
+
pnpm test # typecheck, lint, format, then every playtest
|
|
57
|
+
pnpm build --target desktop # also: web, android, ios
|
|
58
|
+
pnpm test:native # native proof
|
|
59
|
+
npx threenative doctor # build, import, device or blank-frame failure
|
|
60
|
+
npx threenative doctor --fix # refresh agent files
|
|
47
61
|
```
|
|
62
|
+
<!-- /shared -->
|
|
63
|
+
|
|
64
|
+
<!-- shared: kit-conventions -->
|
|
65
|
+
## Conventions
|
|
66
|
+
|
|
67
|
+
Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
|
|
68
|
+
|
|
69
|
+
- **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
|
|
70
|
+
- **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
|
|
71
|
+
- **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
|
|
72
|
+
- **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
|
|
73
|
+
- **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
|
|
74
|
+
- **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
|
|
75
|
+
- **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
|
|
76
|
+
- **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
|
|
77
|
+
- **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
|
|
78
|
+
- **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
|
|
79
|
+
- **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
|
|
80
|
+
- **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
|
|
81
|
+
- **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
|
|
82
|
+
- **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
|
|
83
|
+
- **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
|
|
84
|
+
- **One metre is one metre** `#scale`: `normaliseToMetres`. Override: per-call options.
|
|
85
|
+
- **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
|
|
86
|
+
- **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
|
|
87
|
+
- **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
|
|
88
|
+
- **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
|
|
89
|
+
- **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
|
|
90
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
91
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
92
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
93
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
94
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
95
|
+
- **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
|
|
96
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
97
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
98
|
+
- **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
|
|
99
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
100
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
101
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
102
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
103
|
+
- **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
|
|
104
|
+
<!-- /shared -->
|
|
105
|
+
|
|
106
|
+
<!-- shared: kit-stuck -->
|
|
107
|
+
## When the framework blocks you, write plain Three.js
|
|
108
|
+
|
|
109
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
|
|
110
|
+
|
|
111
|
+
## Stuck
|
|
48
112
|
|
|
49
|
-
`
|
|
50
|
-
|
|
51
|
-
rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both
|
|
52
|
-
cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`.
|
|
53
|
-
`RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that
|
|
54
|
-
same car under a pure-pursuit controller at a constant pace. Keep `playtests/survives.playtest.json` as
|
|
55
|
-
the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
|
|
56
|
-
|
|
57
|
-
**Two things about the vehicle are invisible in the API.** `suspensionStiffness` is a frequency
|
|
58
|
-
squared, so the strut sags `gravity / (4 * stiffness)` and Godot's default of 20 bottoms it out, and a
|
|
59
|
-
positive steering angle turns the chassis toward its own `-z` — so the input is negated once and the
|
|
60
|
-
visual front wheels take that same signed angle. `CarBody.ts` carries every other number.
|
|
61
|
-
|
|
62
|
-
## Portable authoring contracts
|
|
63
|
-
|
|
64
|
-
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.
|
|
65
|
-
|
|
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
|
-
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable.
|
|
68
|
-
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. `ctx.goto(name)` rebuilds without
|
|
69
|
-
resetting game state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
|
|
70
|
-
is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
|
|
71
|
-
state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
72
|
-
|
|
73
|
-
WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`;
|
|
74
|
-
override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
|
|
75
|
-
the source. `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset; the render log reports the override. It has Unreal's bloom with no threshold (`unrealBloomEnabled`), local exposure (`localExposureEnabled`, off on `low`), a cosine-fourth vignette (`vignetteAmount: 0.4`) and no camera motion blur (`motionBlurEnabled: true` is the opt-in). Anti-aliasing is core's: 4x MSAA on `high`, SMAA on `medium` and `low`; `temporalAA: true` is the named opt-in. The grade is neutral and the frame has no film grain. Each stage has a named override: `unrealBloomEnabled: false` returns to Three's `BloomNode` (`bloomStrength`, `bloomRadius`, `bloomThreshold`), and `vignetteAmount: 0` removes the vignette. For a colour grade or grain, add the starter's `grade.ts` and `public/grade.cube`, then set `gradeIntensity` and `grainIntensity`. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/boost and outcome text so a brighter road or sky does not erase the readouts.
|
|
76
|
-
|
|
77
|
-
When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
|
|
78
|
-
retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
|
|
79
|
-
own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
|
|
80
|
-
caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
|
|
81
|
-
(the `<bone>.undefined` failure that plays the bind pose instead of the animation),
|
|
82
|
-
`clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
|
|
83
|
-
clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
|
|
84
|
-
supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
|
|
85
|
-
|
|
86
|
-
`updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
|
|
87
|
-
## Budget real time for the look
|
|
88
|
-
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
|
|
89
|
-
|
|
90
|
-
Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
91
|
-
|
|
92
|
-
For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
93
|
-
## Optional multiplayer transport
|
|
94
|
-
For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
|
|
95
|
-
Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
|
|
96
|
-
`src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. 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.
|
|
113
|
+
`npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
|
|
114
|
+
<!-- /shared -->
|
|
@@ -19,9 +19,9 @@
|
|
|
19
19
|
"format:check": "biome format src"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@threenative/core": "0.3.
|
|
23
|
-
"@threenative/physics": "0.3.
|
|
24
|
-
"@threenative/ui": "0.3.
|
|
22
|
+
"@threenative/core": "0.3.13",
|
|
23
|
+
"@threenative/physics": "0.3.13",
|
|
24
|
+
"@threenative/ui": "0.3.13",
|
|
25
25
|
"react": "19.2.0",
|
|
26
26
|
"react-dom": "19.2.0",
|
|
27
27
|
"three": "0.187.0"
|
|
@@ -29,13 +29,13 @@
|
|
|
29
29
|
"devDependencies": {
|
|
30
30
|
"@gltf-transform/cli": "4.4.2",
|
|
31
31
|
"@tailwindcss/vite": "4.3.3",
|
|
32
|
-
"@threenative/assets": "0.3.
|
|
33
|
-
"@threenative/playtest": "0.3.
|
|
32
|
+
"@threenative/assets": "0.3.14",
|
|
33
|
+
"@threenative/playtest": "0.3.13",
|
|
34
34
|
"@types/react": "19.2.0",
|
|
35
35
|
"@types/react-dom": "19.2.0",
|
|
36
36
|
"@types/three": "0.187.0",
|
|
37
37
|
"@vitejs/plugin-react": "6.0.5",
|
|
38
|
-
"create-threenative": "0.2.
|
|
38
|
+
"create-threenative": "0.2.18",
|
|
39
39
|
"esbuild": "0.27.0",
|
|
40
40
|
"playwright": "1.62.1",
|
|
41
41
|
"tailwindcss": "4.3.3",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"eslint": "10.13.0"
|
|
46
46
|
},
|
|
47
47
|
"optionalDependencies": {
|
|
48
|
-
"@threenative/runtime-native": "0.3.
|
|
48
|
+
"@threenative/runtime-native": "0.3.13"
|
|
49
49
|
},
|
|
50
50
|
"overrides": {
|
|
51
51
|
"sharp": ">=0.35.4",
|
|
@@ -28,7 +28,7 @@ const game = defineGame<GameState, IPhysicsContext>({
|
|
|
28
28
|
},
|
|
29
29
|
plugins: [rapier({ gravity: { x: 0, y: -24, z: 0 } }), playtest({ events })],
|
|
30
30
|
display: config.display,
|
|
31
|
-
|
|
31
|
+
renderer: config.renderer,
|
|
32
32
|
scenes: { boot: Boot, race: Race },
|
|
33
33
|
seed: 90210,
|
|
34
34
|
start: "boot",
|
|
@@ -235,7 +235,13 @@ function march(
|
|
|
235
235
|
* approximation in RenderMultiScatteredLuminanceLutCS); the full sphere gather overestimated the
|
|
236
236
|
* ground bounce against the Unreal frames by up to 1.6x, so this uses the same two rays.
|
|
237
237
|
*/
|
|
238
|
+
// The table depends on no input: build it once a run, not once a sky refresh.
|
|
239
|
+
let multipleScattering: Multi | undefined;
|
|
238
240
|
function multipleScatteringTable(): Multi {
|
|
241
|
+
multipleScattering ??= buildMultipleScatteringTable();
|
|
242
|
+
return multipleScattering;
|
|
243
|
+
}
|
|
244
|
+
function buildMultipleScatteringTable(): Multi {
|
|
239
245
|
const nh = 12;
|
|
240
246
|
const nc = 16;
|
|
241
247
|
const dirs: Vec3[] = [
|
|
@@ -396,23 +402,12 @@ const SUN_LUX = 6;
|
|
|
396
402
|
export const SUN_KELVIN = 6500;
|
|
397
403
|
|
|
398
404
|
/**
|
|
399
|
-
* The sun in three's light units
|
|
400
|
-
*
|
|
401
|
-
*
|
|
402
|
-
*
|
|
403
|
-
* engine's own L1 capture).
|
|
404
|
-
*/
|
|
405
|
-
export const SUN_ILLUMINANCE = SUN_LUX * Math.PI;
|
|
406
|
-
|
|
407
|
-
/**
|
|
408
|
-
* Sky radiance relative to the sun, as Unreal renders it. TEMPORARY, measured and not derived: with
|
|
409
|
-
* the sun at 6 lux the model above is 1.3x too bright against the Unreal L2 frames, flat across
|
|
410
|
-
* channels and across the 15 and 4 degree suns (1.30 / 1.30 / 1.35 at 19 degrees elevation), so
|
|
411
|
-
* the sky is scaled by 1/1.3. The lens attenuation constant 0.78 (PostProcessEyeAdaptation.cpp,
|
|
412
|
-
* r.EyeAdaptation.LensAttenuation) has the right size but the path that would apply it to the
|
|
413
|
-
* atmosphere and not to the sun is not found in the source yet.
|
|
405
|
+
* The sun in three's light units, which are Unreal's: both shade a diffuse surface as
|
|
406
|
+
* albedo / pi x lux x cos(theta) (Diffuse_Lambert, Engine/Shaders/Private/BRDF.ush:157), and the
|
|
407
|
+
* sky is radiance in the same units. The frame's brightness is the exposure's job, not the light's:
|
|
408
|
+
* with its meter off Unreal exposes by 2.4 (`qualityPreset`), and the L1 cells match at that value.
|
|
414
409
|
*/
|
|
415
|
-
export const
|
|
410
|
+
export const SUN_ILLUMINANCE = SUN_LUX;
|
|
416
411
|
|
|
417
412
|
/**
|
|
418
413
|
* Colour of a black-body-like light at `kelvin` as linear sRGB with unit luminance: the Planckian
|
|
@@ -10,6 +10,11 @@ function finiteColor(color: Color) {
|
|
|
10
10
|
color.b >= 0
|
|
11
11
|
);
|
|
12
12
|
}
|
|
13
|
+
/**
|
|
14
|
+
* Throws when a `IBacklightControls` is missing a light or names a non-finite gain.
|
|
15
|
+
*
|
|
16
|
+
* @situation fail loudly instead of drawing an unlit material when a backlight has no key light
|
|
17
|
+
*/
|
|
13
18
|
export function validateControls(controls: IBacklightControls) {
|
|
14
19
|
if (
|
|
15
20
|
!Number.isFinite(controls.rimGain) ||
|
|
@@ -30,6 +35,11 @@ export function validateControls(controls: IBacklightControls) {
|
|
|
30
35
|
"Backlight controls require finite nonnegative gains, a direction and angular size in (0, 1.5].",
|
|
31
36
|
);
|
|
32
37
|
}
|
|
38
|
+
/**
|
|
39
|
+
* The light and camera a backlit material reads its key direction from.
|
|
40
|
+
*
|
|
41
|
+
* @situation point the backlight at the sun the scene actually has
|
|
42
|
+
*/
|
|
33
43
|
export function resolveKey(
|
|
34
44
|
controls: IBacklightControls,
|
|
35
45
|
direction: Vector3,
|