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
|
@@ -2,6 +2,7 @@ import tailwindcss from "@tailwindcss/vite";
|
|
|
2
2
|
import { watchAssets } from "@threenative/assets";
|
|
3
3
|
import react from "@vitejs/plugin-react";
|
|
4
4
|
import {
|
|
5
|
+
createEngineCatalogPlugin,
|
|
5
6
|
createEngineFreshnessPlugin,
|
|
6
7
|
createWebBrandPlugin,
|
|
7
8
|
webRuntimeDecoders,
|
|
@@ -36,6 +37,7 @@ export default defineConfig({
|
|
|
36
37
|
plugins: [
|
|
37
38
|
createEngineFreshnessPlugin(),
|
|
38
39
|
createWebBrandPlugin(),
|
|
40
|
+
createEngineCatalogPlugin(),
|
|
39
41
|
react(),
|
|
40
42
|
tailwindcss(),
|
|
41
43
|
assetsWatchPlugin(),
|
|
@@ -1,58 +1,109 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- shared: kit-identity -->
|
|
2
|
+
# AGENTS.md — __PROJECT_NAME__ (Hop Garden, the collectathon kit)
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
A stout sprout-keeper in a knit beanie runs one free-roam island with a triple jump, long jump, backflip, side flip, wall kick, dive, ground pound and ledge grab, collecting three Sunseeds past bumblets, hoppers and spiked thornbacks. Routing words: collectathon, mario, sm64, super-mario, 3d-platformer. `CLAUDE.md` is a copy of this file.
|
|
5
|
+
<!-- /shared -->
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<!-- shared: kit-router -->
|
|
8
|
+
## Authoring flow
|
|
6
9
|
|
|
7
|
-
|
|
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).
|
|
8
11
|
|
|
9
|
-
|
|
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.
|
|
10
20
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this course needs no navigation: walkers chase in a straight line inside a leash, and the course is authored geometry, so the hero collides with exactly the triangles it sees and desktop/native stays honest.
|
|
14
|
-
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. 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.
|
|
21
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
22
|
+
<!-- /shared -->
|
|
15
23
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
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); never stall the game.
|
|
24
|
+
<!-- shared: kit-mcp -->
|
|
25
|
+
## MCP servers
|
|
19
26
|
|
|
20
|
-
|
|
21
|
-
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
22
|
-
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
|
|
23
|
-
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
24
|
-
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
25
|
-
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
26
|
-
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
|
|
27
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
28
|
-
- 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.
|
|
29
|
-
## Commands and map
|
|
30
|
-
|
|
31
|
-
```sh
|
|
32
|
-
pnpm dev
|
|
33
|
-
pnpm build
|
|
34
|
-
pnpm build --target desktop
|
|
35
|
-
pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
|
|
36
|
-
pnpm typecheck
|
|
37
|
-
```
|
|
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.
|
|
38
28
|
|
|
39
|
-
|
|
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 -->
|
|
40
36
|
|
|
41
|
-
|
|
37
|
+
## This kit
|
|
42
38
|
|
|
43
|
-
|
|
44
|
-
|
|
39
|
+
<!-- shared: kit-files -->
|
|
40
|
+
Source in `src/`: `entities/`, `game.ts`, `level/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
|
|
41
|
+
23 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
42
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-collectathon.md`.
|
|
43
|
+
<!-- /shared -->
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
`HERO_FEEL` in `src/entities/Hero.ts` is the one table of metres and seconds the course is laid out from; change a number and a gap in `src/level/Course.ts` changes meaning. The camera and sun are written in `afterPhysics`.
|
|
46
|
+
Every model and animation is procedural. Tiling textures are `assets/tex-*.webp`, loaded by `loadSurfaces(ctx.assets)` in `src/render/surface.ts`. Keep `assets/` at most 1.5 MB.
|
|
47
|
+
`buildStaticColliders` builds collision from the tagged course meshes; this course needs no navigation, so walkers chase in a straight line.
|
|
47
48
|
|
|
48
|
-
|
|
49
|
+
<!-- shared: kit-commands -->
|
|
50
|
+
## Commands
|
|
49
51
|
|
|
50
|
-
|
|
52
|
+
```sh
|
|
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 studio # open the game in Studio
|
|
57
|
+
npx threenative doctor # build, import, device or blank-frame failure
|
|
58
|
+
npx threenative doctor --fix # refresh agent files
|
|
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
|
+
- **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
|
|
82
|
+
- **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
|
|
83
|
+
- **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
|
|
84
|
+
- **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
|
|
85
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
86
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
87
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
88
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
89
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
90
|
+
- **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
|
|
91
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
92
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
93
|
+
- **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`.
|
|
94
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
95
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
96
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
97
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
98
|
+
- **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
|
|
99
|
+
<!-- /shared -->
|
|
100
|
+
|
|
101
|
+
<!-- shared: kit-stuck -->
|
|
102
|
+
## When the framework blocks you, write plain Three.js
|
|
51
103
|
|
|
52
|
-
|
|
53
|
-
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. 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.
|
|
104
|
+
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.
|
|
54
105
|
|
|
55
|
-
|
|
106
|
+
## Stuck
|
|
56
107
|
|
|
57
|
-
|
|
58
|
-
|
|
108
|
+
`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.
|
|
109
|
+
<!-- /shared -->
|
|
@@ -1,60 +1,111 @@
|
|
|
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__ (Hop Garden, the collectathon kit)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
A stout sprout-keeper in a knit beanie runs one free-roam island with a triple jump, long jump, backflip, side flip, wall kick, dive, ground pound and ledge grab, collecting three Sunseeds past bumblets, hoppers and spiked thornbacks. Routing words: collectathon, mario, sm64, super-mario, 3d-platformer. `CLAUDE.md` is a copy of this file.
|
|
7
|
+
<!-- /shared -->
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
<!-- shared: kit-router -->
|
|
10
|
+
## Authoring flow
|
|
8
11
|
|
|
9
|
-
|
|
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).
|
|
10
13
|
|
|
11
|
-
|
|
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.
|
|
12
22
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this course needs no navigation: walkers chase in a straight line inside a leash, and the course is authored geometry, so the hero collides with exactly the triangles it sees and desktop/native stays honest.
|
|
16
|
-
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. 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.
|
|
23
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
24
|
+
<!-- /shared -->
|
|
17
25
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
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); never stall the game.
|
|
26
|
+
<!-- shared: kit-mcp -->
|
|
27
|
+
## MCP servers
|
|
21
28
|
|
|
22
|
-
|
|
23
|
-
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
24
|
-
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
|
|
25
|
-
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
26
|
-
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
27
|
-
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
28
|
-
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
|
|
29
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
30
|
-
- 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.
|
|
31
|
-
## Commands and map
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
pnpm dev
|
|
35
|
-
pnpm build
|
|
36
|
-
pnpm build --target desktop
|
|
37
|
-
pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
|
|
38
|
-
pnpm typecheck
|
|
39
|
-
```
|
|
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.
|
|
40
30
|
|
|
41
|
-
|
|
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 -->
|
|
42
38
|
|
|
43
|
-
|
|
39
|
+
## This kit
|
|
44
40
|
|
|
45
|
-
|
|
46
|
-
|
|
41
|
+
<!-- shared: kit-files -->
|
|
42
|
+
Source in `src/`: `entities/`, `game.ts`, `level/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
|
|
43
|
+
23 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
44
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-collectathon.md`.
|
|
45
|
+
<!-- /shared -->
|
|
47
46
|
|
|
48
|
-
|
|
47
|
+
`HERO_FEEL` in `src/entities/Hero.ts` is the one table of metres and seconds the course is laid out from; change a number and a gap in `src/level/Course.ts` changes meaning. The camera and sun are written in `afterPhysics`.
|
|
48
|
+
Every model and animation is procedural. Tiling textures are `assets/tex-*.webp`, loaded by `loadSurfaces(ctx.assets)` in `src/render/surface.ts`. Keep `assets/` at most 1.5 MB.
|
|
49
|
+
`buildStaticColliders` builds collision from the tagged course meshes; this course needs no navigation, so walkers chase in a straight line.
|
|
49
50
|
|
|
50
|
-
|
|
51
|
+
<!-- shared: kit-commands -->
|
|
52
|
+
## Commands
|
|
51
53
|
|
|
52
|
-
|
|
54
|
+
```sh
|
|
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 studio # open the game in Studio
|
|
59
|
+
npx threenative doctor # build, import, device or blank-frame failure
|
|
60
|
+
npx threenative doctor --fix # refresh agent files
|
|
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
|
+
- **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
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
88
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
89
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
90
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
91
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
92
|
+
- **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
|
|
93
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
94
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
95
|
+
- **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`.
|
|
96
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
97
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
98
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
99
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
100
|
+
- **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
|
|
101
|
+
<!-- /shared -->
|
|
102
|
+
|
|
103
|
+
<!-- shared: kit-stuck -->
|
|
104
|
+
## When the framework blocks you, write plain Three.js
|
|
53
105
|
|
|
54
|
-
|
|
55
|
-
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. 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.
|
|
106
|
+
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.
|
|
56
107
|
|
|
57
|
-
|
|
108
|
+
## Stuck
|
|
58
109
|
|
|
59
|
-
|
|
60
|
-
|
|
110
|
+
`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.
|
|
111
|
+
<!-- /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"
|
|
@@ -30,11 +30,11 @@
|
|
|
30
30
|
"@tailwindcss/vite": "4.3.3",
|
|
31
31
|
"@vitejs/plugin-react": "6.0.5",
|
|
32
32
|
"@types/three": "0.187.0",
|
|
33
|
-
"@threenative/assets": "0.3.
|
|
34
|
-
"@threenative/playtest": "0.3.
|
|
33
|
+
"@threenative/assets": "0.3.14",
|
|
34
|
+
"@threenative/playtest": "0.3.13",
|
|
35
35
|
"@types/react": "19.2.0",
|
|
36
36
|
"@types/react-dom": "19.2.0",
|
|
37
|
-
"create-threenative": "0.2.
|
|
37
|
+
"create-threenative": "0.2.18",
|
|
38
38
|
"esbuild": "0.27.0",
|
|
39
39
|
"playwright": "1.62.1",
|
|
40
40
|
"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",
|
|
@@ -26,7 +26,7 @@ const game = defineGame<GameState, IPhysicsContext>({
|
|
|
26
26
|
},
|
|
27
27
|
plugins: [rapier({ gravity: { x: 0, y: -36, z: 0 } }), playtest({ events })],
|
|
28
28
|
display: config.display,
|
|
29
|
-
|
|
29
|
+
renderer: config.renderer,
|
|
30
30
|
scenes: { play: Play },
|
|
31
31
|
// The course is procedural; the seed makes its rocks, grass and coin wobble the same every run.
|
|
32
32
|
seed: 6402,
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { WaveField } from "@threenative/core";
|
|
1
|
+
import { type IAssetLoader, WaveField } from "@threenative/core";
|
|
2
2
|
import {
|
|
3
3
|
Box3,
|
|
4
4
|
BoxGeometry,
|
|
@@ -19,7 +19,14 @@ import {
|
|
|
19
19
|
import { HERO_FEEL } from "../entities/Hero.js";
|
|
20
20
|
import type { WalkerKind } from "../entities/Walker.js";
|
|
21
21
|
import { buildCastle, buildSignpost, planarUv, wrapUv } from "../render/castle.js";
|
|
22
|
-
import {
|
|
22
|
+
import {
|
|
23
|
+
type IMeadow,
|
|
24
|
+
type IPlantingRecord,
|
|
25
|
+
type IPlantingSite,
|
|
26
|
+
buildPlanting,
|
|
27
|
+
checkedPlanting,
|
|
28
|
+
planPlanting,
|
|
29
|
+
} from "../render/foliage.js";
|
|
23
30
|
import { farHills, paintGround } from "../render/ground.js";
|
|
24
31
|
import { mottle, patches } from "../render/materials.js";
|
|
25
32
|
import {
|
|
@@ -191,6 +198,18 @@ function auditCourse(
|
|
|
191
198
|
* A boulder `size` metres across its middle: an icosphere pushed in and out by a few seeded waves and
|
|
192
199
|
* flattened a little, smooth-shaded, so it reads as weathered rock and not as a faceted gem.
|
|
193
200
|
*/
|
|
201
|
+
/**
|
|
202
|
+
* `Math.hypot(dx, dz) < reach`, asked thousands of times by the planting: squared distances settle
|
|
203
|
+
* every case more than a millionth from the edge, and the edge itself takes the same `hypot`.
|
|
204
|
+
*/
|
|
205
|
+
function within(dx: number, dz: number, reach: number): boolean {
|
|
206
|
+
const squared = dx * dx + dz * dz;
|
|
207
|
+
const edge = reach * reach;
|
|
208
|
+
if (squared > edge * 1.000001) return false;
|
|
209
|
+
if (squared < edge * 0.999999 && reach > 0) return true;
|
|
210
|
+
return Math.hypot(dx, dz) < reach;
|
|
211
|
+
}
|
|
212
|
+
|
|
194
213
|
function boulderGeometry(size: number, rng: () => number): BufferGeometry {
|
|
195
214
|
const geometry = new IcosahedronGeometry(size, 2);
|
|
196
215
|
const position = geometry.attributes.position;
|
|
@@ -216,11 +235,31 @@ export function makeRng(seed: number): () => number {
|
|
|
216
235
|
};
|
|
217
236
|
}
|
|
218
237
|
|
|
238
|
+
/**
|
|
239
|
+
* The island planted: drawn from `site` on a run that has nothing stored, and read back from
|
|
240
|
+
* `memo` on the next run of this build, so `buildPlanting` has the same placements either way.
|
|
241
|
+
*/
|
|
242
|
+
async function planted(
|
|
243
|
+
site: IPlantingSite,
|
|
244
|
+
memo: IAssetLoader["memo"] | undefined,
|
|
245
|
+
): Promise<{ group: Group; meadow: IMeadow }> {
|
|
246
|
+
if (memo === undefined) return buildPlanting(planPlanting(site), site);
|
|
247
|
+
const record: IPlantingRecord = await memo("planting", () => planPlanting(site));
|
|
248
|
+
// The memo hands back flat arrays either way, so a hit costs a length check, not a rebuild.
|
|
249
|
+
return buildPlanting(checkedPlanting(record), site);
|
|
250
|
+
}
|
|
251
|
+
|
|
219
252
|
/**
|
|
220
253
|
* `surfaces` are the loaded textures (`loadSurfaces` in surface.ts); `grassShare` is the share of
|
|
221
|
-
* grass tufts the quality tier draws (`GRASS_SHARE` in `quality.ts`).
|
|
254
|
+
* grass tufts the quality tier draws (`GRASS_SHARE` in `quality.ts`). `memo` keeps the planting
|
|
255
|
+
* between runs; without one every run draws it.
|
|
222
256
|
*/
|
|
223
|
-
export function buildCourse(
|
|
257
|
+
export async function buildCourse(
|
|
258
|
+
rng: () => number,
|
|
259
|
+
surfaces: ISurfaces,
|
|
260
|
+
grassShare = 1,
|
|
261
|
+
memo?: IAssetLoader["memo"],
|
|
262
|
+
): Promise<ICourse> {
|
|
224
263
|
const group = new Group();
|
|
225
264
|
group.name = "course";
|
|
226
265
|
const [doorX, doorZ] = COURSE.castle.door;
|
|
@@ -451,7 +490,7 @@ export function buildCourse(rng: () => number, surfaces: ISurfaces, grassShare =
|
|
|
451
490
|
/** Every pickup: scenery keeps a clear metre round each, so none hangs inside a tree or a rock. */
|
|
452
491
|
const pickups = [...coins, ...gems, ...Object.values(seeds)];
|
|
453
492
|
const nearPickup = (x: number, zz: number, reach: number): boolean =>
|
|
454
|
-
pickups.some(([kx, , kz]) =>
|
|
493
|
+
pickups.some(([kx, , kz]) => within(x - kx, zz - kz, reach));
|
|
455
494
|
|
|
456
495
|
// Scenery: boulders where the ground breaks into a slope, never on a route and never inside a
|
|
457
496
|
// landmark (a rock through the shaft's wall, under the pillar's coin ring or in the castle).
|
|
@@ -499,11 +538,11 @@ export function buildCourse(rng: () => number, surfaces: ISurfaces, grassShare =
|
|
|
499
538
|
|
|
500
539
|
// Planting (`render/foliage.ts`): never on a route a scenario runs, a landmark or a boulder.
|
|
501
540
|
const taken = [...keepOut, ...boulders] as const;
|
|
502
|
-
const
|
|
541
|
+
const plantingSite: IPlantingSite = {
|
|
503
542
|
bounds: TERRAIN_BOUNDS,
|
|
504
543
|
clear: (x, zz, w) =>
|
|
505
544
|
!onRoute(x, zz, w) &&
|
|
506
|
-
!taken.some(([kx, kz, kr]) =>
|
|
545
|
+
!taken.some(([kx, kz, kr]) => within(x - kx, zz - kz, kr + w)) &&
|
|
507
546
|
!nearPickup(x, zz, w + 1),
|
|
508
547
|
flatness: terrain.flatness,
|
|
509
548
|
grassShare,
|
|
@@ -519,7 +558,8 @@ export function buildCourse(rng: () => number, surfaces: ISurfaces, grassShare =
|
|
|
519
558
|
surfaces,
|
|
520
559
|
// The islet's drum cliff radius at the waterline: it narrows to 92% over its height.
|
|
521
560
|
shores: [[COURSE.islet.at[0], COURSE.islet.at[1], COURSE.islet.radius * 0.98]],
|
|
522
|
-
}
|
|
561
|
+
};
|
|
562
|
+
const planting = await planted(plantingSite, memo);
|
|
523
563
|
group.add(planting.group);
|
|
524
564
|
|
|
525
565
|
// The world's shape on a 1 m grid of land: the climb from the shore to the top, the share of
|
|
@@ -555,8 +595,14 @@ export function buildCourse(rng: () => number, surfaces: ISurfaces, grassShare =
|
|
|
555
595
|
steepShare: steep / landCells,
|
|
556
596
|
};
|
|
557
597
|
|
|
598
|
+
let audit: ICourse["audit"] | undefined;
|
|
558
599
|
return {
|
|
559
|
-
|
|
600
|
+
// Measured on first read, not on every load: only the debug snapshot and the layout
|
|
601
|
+
// playtests read it, and walking every solid's bounds cost a run ~0.1 s.
|
|
602
|
+
get audit() {
|
|
603
|
+
audit ??= { ...auditCourse(group, pickups, ground), ...world };
|
|
604
|
+
return audit;
|
|
605
|
+
},
|
|
560
606
|
checkpoints: [
|
|
561
607
|
new Vector3(...COURSE.spawn),
|
|
562
608
|
new Vector3(...onGround(sx + 9, 0, sz + 13)),
|