create-threenative 0.2.3 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -2
- package/agent-docs/references/assertion-reference.md +173 -6
- package/agent-docs/references/capability-reference.md +1303 -99
- package/agent-docs/references/capture-the-frame.md +7 -0
- package/agent-docs/references/creating-creatures.md +215 -0
- package/agent-docs/references/ctx-cookbook.md +69 -0
- package/agent-docs/references/debug-surface.md +8 -3
- package/agent-docs/references/dream-loop.md +150 -0
- package/agent-docs/references/finding-assets.md +70 -2
- package/agent-docs/references/sculpt-from-a-reference.md +3 -2
- package/agent-docs/references/trace-a-slow-frame.md +99 -0
- package/agent-docs/references/visual-baseline.md +41 -0
- package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
- package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
- package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
- package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
- package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
- package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
- package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
- package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
- package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
- package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
- package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
- package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
- package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
- package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
- package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
- package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
- package/agent-files/scripts/reference.mjs +705 -0
- package/agent-files/scripts/visual-loop.mjs +382 -0
- package/capabilities.json +1881 -131
- package/dist/index.d.ts +39 -6
- package/dist/index.js +297 -32
- package/dist/threenative.js +822 -105
- package/package.json +30 -5
- package/template-assets/loading.ts +12 -2
- package/template-assets/patches/three@0.185.1.patch +249 -14
- package/template-assets/worldEnvironment.ts +758 -0
- package/templates/action-rpg/.codex/config.toml +4 -0
- package/templates/action-rpg/.cursor/mcp.json +32 -0
- package/templates/action-rpg/.gemini/settings.json +32 -0
- package/templates/action-rpg/.mcp.json +15 -3
- package/templates/action-rpg/.vscode/mcp.json +36 -0
- package/templates/action-rpg/.zed/settings.json +36 -0
- package/templates/action-rpg/AGENTS.md +69 -378
- package/templates/action-rpg/CLAUDE.md +69 -378
- package/templates/action-rpg/opencode.json +41 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/combat.playtest.json +9 -0
- package/templates/action-rpg/playtests/performance.playtest.json +24 -7
- package/templates/action-rpg/playtests/survives.playtest.json +27 -0
- package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
- package/templates/action-rpg/src/conventions.ts +35 -0
- package/templates/action-rpg/src/entities/Enemy.ts +2 -3
- package/templates/action-rpg/src/entities/Player.ts +20 -3
- package/templates/action-rpg/src/render/camera.ts +7 -2
- package/templates/action-rpg/src/render/lighting.ts +5 -3
- package/templates/action-rpg/src/render/loading.ts +12 -2
- package/templates/action-rpg/src/render/materials.ts +11 -0
- package/templates/action-rpg/src/render/palette.ts +10 -3
- package/templates/action-rpg/src/render/postprocessing.ts +21 -58
- package/templates/action-rpg/src/render/quality.ts +170 -0
- package/templates/action-rpg/src/render/shapes.ts +185 -26
- package/templates/action-rpg/src/render/touch-controls.ts +185 -0
- package/templates/action-rpg/src/render/vfx.ts +257 -0
- package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
- package/templates/action-rpg/src/scenes/Play.ts +43 -6
- package/templates/action-rpg/src/style.css +20 -0
- package/templates/action-rpg/threenative.config.ts +7 -0
- package/templates/defense/.codex/config.toml +4 -0
- package/templates/defense/.cursor/mcp.json +32 -0
- package/templates/defense/.gemini/settings.json +32 -0
- package/templates/defense/.mcp.json +15 -3
- package/templates/defense/.vscode/mcp.json +36 -0
- package/templates/defense/.zed/settings.json +36 -0
- package/templates/defense/AGENTS.md +62 -385
- package/templates/defense/CLAUDE.md +62 -385
- package/templates/defense/opencode.json +41 -0
- package/templates/defense/package.json +7 -7
- package/templates/defense/playtests/performance.playtest.json +24 -7
- package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
- package/templates/defense/playtests/scan.playtest.json +1 -1
- package/templates/defense/playtests/survive.playtest.json +14 -0
- package/templates/defense/src/attackers/Attacker.ts +4 -4
- package/templates/defense/src/board/Route.ts +22 -8
- package/templates/defense/src/conventions.ts +18 -0
- package/templates/defense/src/entities/Player.ts +11 -3
- package/templates/defense/src/game.ts +2 -3
- package/templates/defense/src/physics.ts +9 -39
- package/templates/defense/src/placement/Buildable.ts +4 -4
- package/templates/defense/src/render/camera.ts +9 -3
- package/templates/defense/src/render/loading.ts +12 -2
- package/templates/defense/src/render/materials.ts +9 -0
- package/templates/defense/src/render/palette.ts +12 -5
- package/templates/defense/src/render/postprocessing.ts +21 -58
- package/templates/defense/src/render/quality.ts +170 -0
- package/templates/defense/src/render/shapes.ts +142 -23
- package/templates/defense/src/render/sky.ts +2 -2
- package/templates/defense/src/render/worldEnvironment.ts +208 -33
- package/templates/defense/src/scenes/Boot.ts +2 -2
- package/templates/defense/src/scenes/Defense.ts +13 -6
- package/templates/defense/src/style.css +20 -0
- package/templates/defense/src/towers/Tower.ts +11 -12
- package/templates/defense/src/towers/targeting.ts +1 -1
- package/templates/defense/src/ui/App.tsx +2 -2
- package/templates/defense/threenative.config.ts +7 -0
- package/templates/minimal/.codex/config.toml +4 -0
- package/templates/minimal/.cursor/mcp.json +32 -0
- package/templates/minimal/.gemini/settings.json +32 -0
- package/templates/minimal/.mcp.json +15 -3
- package/templates/minimal/.vscode/mcp.json +36 -0
- package/templates/minimal/.zed/settings.json +36 -0
- package/templates/minimal/AGENTS.md +76 -485
- package/templates/minimal/CLAUDE.md +76 -485
- package/templates/minimal/opencode.json +41 -0
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/playtests/play.playtest.json +2 -1
- package/templates/minimal/playtests/survives.playtest.json +48 -4
- package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
- package/templates/minimal/src/conventions.ts +18 -0
- package/templates/minimal/src/entities/Player.ts +39 -6
- package/templates/minimal/src/main.ts +14 -4
- package/templates/minimal/src/render/materials.ts +7 -0
- package/templates/minimal/src/render/palette.ts +3 -3
- package/templates/minimal/src/render/postprocessing.ts +17 -56
- package/templates/minimal/src/render/quality.ts +162 -0
- package/templates/minimal/src/render/sky.ts +23 -9
- package/templates/minimal/src/render/touch-controls.ts +165 -0
- package/templates/minimal/src/render/worldEnvironment.ts +208 -33
- package/templates/minimal/src/scenes/Play.ts +47 -11
- package/templates/minimal/src/style.css +20 -0
- package/templates/minimal/threenative.config.ts +7 -0
- package/templates/platformer/.codex/config.toml +4 -0
- package/templates/platformer/.cursor/mcp.json +32 -0
- package/templates/platformer/.gemini/settings.json +32 -0
- package/templates/platformer/.mcp.json +15 -3
- package/templates/platformer/.vscode/mcp.json +36 -0
- package/templates/platformer/.zed/settings.json +36 -0
- package/templates/platformer/AGENTS.md +70 -430
- package/templates/platformer/CLAUDE.md +70 -430
- package/templates/platformer/opencode.json +41 -0
- package/templates/platformer/package.json +7 -7
- package/templates/platformer/playtests/oneway.playtest.json +29 -2
- package/templates/platformer/playtests/performance.playtest.json +2 -1
- package/templates/platformer/playtests/survives.playtest.json +31 -0
- package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
- package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
- package/templates/platformer/src/conventions.ts +18 -0
- package/templates/platformer/src/entities/Character.ts +63 -1
- package/templates/platformer/src/game.ts +3 -1
- package/templates/platformer/src/level/Platform.ts +13 -1
- package/templates/platformer/src/render/lighting.ts +7 -4
- package/templates/platformer/src/render/loading.ts +12 -2
- package/templates/platformer/src/render/palette.ts +4 -1
- package/templates/platformer/src/render/postprocessing.ts +32 -57
- package/templates/platformer/src/render/quality.ts +170 -0
- package/templates/platformer/src/render/worldEnvironment.ts +208 -33
- package/templates/platformer/src/scenes/Level.ts +52 -12
- package/templates/platformer/src/style.css +20 -0
- package/templates/platformer/threenative.config.ts +7 -0
- package/templates/puzzle/.codex/config.toml +19 -0
- package/templates/puzzle/.cursor/mcp.json +32 -0
- package/templates/puzzle/.gemini/settings.json +32 -0
- package/templates/puzzle/.mcp.json +32 -0
- package/templates/puzzle/.vscode/mcp.json +36 -0
- package/templates/puzzle/.zed/settings.json +36 -0
- package/templates/puzzle/AGENTS.md +96 -0
- package/templates/puzzle/CLAUDE.md +98 -0
- package/templates/puzzle/README.md +43 -0
- package/templates/puzzle/index.html +12 -0
- package/templates/puzzle/kit.json +7 -0
- package/templates/puzzle/opencode.json +41 -0
- package/templates/puzzle/package.json +50 -0
- package/templates/puzzle/playtests/carry.playtest.json +71 -0
- package/templates/puzzle/playtests/performance.playtest.json +23 -0
- package/templates/puzzle/playtests/survives.playtest.json +51 -0
- package/templates/puzzle/playtests/swing.playtest.json +38 -0
- package/templates/puzzle/public/favicon.svg +5 -0
- package/templates/puzzle/src/conventions.ts +25 -0
- package/templates/puzzle/src/entities/Ball.ts +70 -0
- package/templates/puzzle/src/entities/Crate.ts +76 -0
- package/templates/puzzle/src/entities/Gripper.ts +69 -0
- package/templates/puzzle/src/entities/Pendulum.ts +89 -0
- package/templates/puzzle/src/game.ts +48 -0
- package/templates/puzzle/src/main.ts +15 -0
- package/templates/puzzle/src/physics.ts +19 -0
- package/templates/puzzle/src/render/camera.ts +37 -0
- package/templates/puzzle/src/render/lighting.ts +55 -0
- package/templates/puzzle/src/render/loading.ts +325 -0
- package/templates/puzzle/src/render/materials.ts +28 -0
- package/templates/puzzle/src/render/palette.ts +31 -0
- package/templates/puzzle/src/render/postprocessing.ts +34 -0
- package/templates/puzzle/src/render/quality.ts +170 -0
- package/templates/puzzle/src/render/shapes.ts +134 -0
- package/templates/puzzle/src/render/sky.ts +16 -0
- package/templates/puzzle/src/render/touch-controls.ts +185 -0
- package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
- package/templates/puzzle/src/room.ts +83 -0
- package/templates/puzzle/src/scenes/Boot.ts +12 -0
- package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
- package/templates/puzzle/src/state.ts +30 -0
- package/templates/puzzle/src/style.css +96 -0
- package/templates/puzzle/src/ui/App.tsx +22 -0
- package/templates/puzzle/src/ui/GameUi.tsx +20 -0
- package/templates/puzzle/src/ui/Hud.tsx +57 -0
- package/templates/puzzle/src/ui/Menu.tsx +7 -0
- package/templates/puzzle/src/ui/main.tsx +14 -0
- package/templates/puzzle/tailwind.config.ts +1 -0
- package/templates/puzzle/threenative.config.ts +49 -0
- package/templates/puzzle/tsconfig.json +17 -0
- package/templates/puzzle/vite.config.ts +38 -0
- package/templates/racing/.codex/config.toml +4 -0
- package/templates/racing/.cursor/mcp.json +32 -0
- package/templates/racing/.gemini/settings.json +32 -0
- package/templates/racing/.mcp.json +15 -3
- package/templates/racing/.vscode/mcp.json +36 -0
- package/templates/racing/.zed/settings.json +36 -0
- package/templates/racing/AGENTS.md +63 -379
- package/templates/racing/CLAUDE.md +63 -379
- package/templates/racing/native-playtests/survives.playtest.json +43 -0
- package/templates/racing/opencode.json +41 -0
- package/templates/racing/package.json +8 -7
- package/templates/racing/playtests/performance.playtest.json +24 -7
- package/templates/racing/playtests/survives.playtest.json +36 -4
- package/templates/racing/playtests/touch-controls.playtest.json +41 -0
- package/templates/racing/src/conventions.ts +6 -0
- package/templates/racing/src/entities/RacingCar.ts +16 -4
- package/templates/racing/src/entities/Rival.ts +5 -2
- package/templates/racing/src/render/camera.ts +7 -4
- package/templates/racing/src/render/lighting.ts +22 -13
- package/templates/racing/src/render/loading.ts +12 -2
- package/templates/racing/src/render/materials.ts +54 -4
- package/templates/racing/src/render/palette.ts +23 -6
- package/templates/racing/src/render/postprocessing.ts +21 -58
- package/templates/racing/src/render/quality.ts +170 -0
- package/templates/racing/src/render/shapes.ts +537 -26
- package/templates/racing/src/render/sky.ts +5 -2
- package/templates/racing/src/render/touch-controls.ts +185 -0
- package/templates/racing/src/render/worldEnvironment.ts +208 -33
- package/templates/racing/src/scenes/Race.ts +17 -2
- package/templates/racing/src/style.css +20 -0
- package/templates/racing/src/track/Track.ts +270 -31
- package/templates/racing/threenative.config.ts +7 -0
- package/templates/runner/.codex/config.toml +19 -0
- package/templates/runner/.cursor/mcp.json +32 -0
- package/templates/runner/.gemini/settings.json +32 -0
- package/templates/runner/.mcp.json +32 -0
- package/templates/runner/.vscode/mcp.json +36 -0
- package/templates/runner/.zed/settings.json +36 -0
- package/templates/runner/AGENTS.md +96 -0
- package/templates/runner/CLAUDE.md +98 -0
- package/templates/runner/README.md +43 -0
- package/templates/runner/index.html +12 -0
- package/templates/runner/kit.json +7 -0
- package/templates/runner/opencode.json +41 -0
- package/templates/runner/package.json +50 -0
- package/templates/runner/playtests/performance.playtest.json +23 -0
- package/templates/runner/playtests/streams.playtest.json +38 -0
- package/templates/runner/playtests/survives.playtest.json +51 -0
- package/templates/runner/public/favicon.svg +5 -0
- package/templates/runner/src/conventions.ts +24 -0
- package/templates/runner/src/entities/Runner.ts +135 -0
- package/templates/runner/src/game.ts +50 -0
- package/templates/runner/src/main.ts +15 -0
- package/templates/runner/src/physics.ts +13 -0
- package/templates/runner/src/render/camera.ts +39 -0
- package/templates/runner/src/render/dust.ts +131 -0
- package/templates/runner/src/render/lighting.ts +57 -0
- package/templates/runner/src/render/loading.ts +325 -0
- package/templates/runner/src/render/materials.ts +27 -0
- package/templates/runner/src/render/palette.ts +30 -0
- package/templates/runner/src/render/postprocessing.ts +34 -0
- package/templates/runner/src/render/quality.ts +170 -0
- package/templates/runner/src/render/shapes.ts +68 -0
- package/templates/runner/src/render/sky.ts +51 -0
- package/templates/runner/src/render/touch-controls.ts +185 -0
- package/templates/runner/src/render/worldEnvironment.ts +758 -0
- package/templates/runner/src/scenes/Boot.ts +12 -0
- package/templates/runner/src/scenes/Run.ts +142 -0
- package/templates/runner/src/state.ts +29 -0
- package/templates/runner/src/style.css +96 -0
- package/templates/runner/src/track.ts +176 -0
- package/templates/runner/src/ui/App.tsx +22 -0
- package/templates/runner/src/ui/GameUi.tsx +20 -0
- package/templates/runner/src/ui/Hud.tsx +55 -0
- package/templates/runner/src/ui/Menu.tsx +7 -0
- package/templates/runner/src/ui/main.tsx +14 -0
- package/templates/runner/tailwind.config.ts +1 -0
- package/templates/runner/threenative.config.ts +49 -0
- package/templates/runner/tsconfig.json +17 -0
- package/templates/runner/vite.config.ts +38 -0
- package/templates/sailing/.codex/config.toml +4 -0
- package/templates/sailing/.cursor/mcp.json +32 -0
- package/templates/sailing/.gemini/settings.json +32 -0
- package/templates/sailing/.mcp.json +15 -3
- package/templates/sailing/.vscode/mcp.json +36 -0
- package/templates/sailing/.zed/settings.json +36 -0
- package/templates/sailing/AGENTS.md +62 -355
- package/templates/sailing/CLAUDE.md +62 -355
- package/templates/sailing/README.md +12 -9
- package/templates/sailing/native-playtests/float.playtest.json +55 -0
- package/templates/sailing/native-playtests/survives.playtest.json +20 -3
- package/templates/sailing/opencode.json +41 -0
- package/templates/sailing/package.json +8 -8
- package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
- package/templates/sailing/playtests/float.playtest.json +59 -0
- package/templates/sailing/playtests/performance.playtest.json +21 -6
- package/templates/sailing/playtests/survives.playtest.json +8 -0
- package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
- package/templates/sailing/src/conventions.ts +8 -0
- package/templates/sailing/src/entities/Ship.ts +150 -13
- package/templates/sailing/src/render/camera.ts +15 -8
- package/templates/sailing/src/render/lighting.ts +10 -5
- package/templates/sailing/src/render/loading.ts +12 -2
- package/templates/sailing/src/render/materials.ts +24 -8
- package/templates/sailing/src/render/ocean.ts +179 -0
- package/templates/sailing/src/render/palette.ts +14 -21
- package/templates/sailing/src/render/postprocessing.ts +23 -22
- package/templates/sailing/src/render/props.ts +584 -34
- package/templates/sailing/src/render/quality.ts +140 -0
- package/templates/sailing/src/render/sky.ts +8 -3
- package/templates/sailing/src/render/touch-controls.ts +142 -0
- package/templates/sailing/src/render/worldEnvironment.ts +206 -38
- package/templates/sailing/src/scenes/Sailing.ts +43 -16
- package/templates/sailing/src/style.css +20 -0
- package/templates/sailing/threenative.config.ts +7 -1
- package/templates/shooter/.codex/config.toml +4 -0
- package/templates/shooter/.cursor/mcp.json +32 -0
- package/templates/shooter/.gemini/settings.json +32 -0
- package/templates/shooter/.mcp.json +15 -3
- package/templates/shooter/.vscode/mcp.json +36 -0
- package/templates/shooter/.zed/settings.json +36 -0
- package/templates/shooter/AGENTS.md +76 -415
- package/templates/shooter/CLAUDE.md +76 -415
- package/templates/shooter/kit.json +2 -2
- package/templates/shooter/opencode.json +41 -0
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/playtests/combat.playtest.json +48 -0
- package/templates/shooter/playtests/input-control.playtest.json +165 -35
- package/templates/shooter/playtests/per-item.playtest.json +3 -3
- package/templates/shooter/playtests/performance.playtest.json +24 -7
- package/templates/shooter/playtests/shooter.playtest.json +13 -7
- package/templates/shooter/playtests/survives.playtest.json +27 -0
- package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
- package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
- package/templates/shooter/src/combat/damage.ts +1 -2
- package/templates/shooter/src/conventions.ts +51 -0
- package/templates/shooter/src/entities/Player.ts +235 -18
- package/templates/shooter/src/entities/Target.ts +2 -2
- package/templates/shooter/src/game.ts +13 -4
- package/templates/shooter/src/render/camera.ts +49 -39
- package/templates/shooter/src/render/decals.ts +211 -0
- package/templates/shooter/src/render/lighting.ts +7 -3
- package/templates/shooter/src/render/loading.ts +12 -2
- package/templates/shooter/src/render/materials.ts +56 -3
- package/templates/shooter/src/render/palette.ts +6 -3
- package/templates/shooter/src/render/postprocessing.ts +21 -58
- package/templates/shooter/src/render/quality.ts +170 -0
- package/templates/shooter/src/render/scale.ts +22 -0
- package/templates/shooter/src/render/shapes.ts +343 -62
- package/templates/shooter/src/render/sky.ts +5 -1
- package/templates/shooter/src/render/touch-controls.ts +305 -0
- package/templates/shooter/src/render/ui.css +85 -0
- package/templates/shooter/src/render/ui.ts +19 -3
- package/templates/shooter/src/render/vfx.ts +215 -0
- package/templates/shooter/src/render/worldEnvironment.ts +208 -33
- package/templates/shooter/src/scenes/Play.ts +171 -56
- package/templates/shooter/src/state.ts +5 -0
- package/templates/shooter/src/style.css +20 -0
- package/templates/shooter/src/ui/Crosshair.tsx +25 -0
- package/templates/shooter/src/ui/GameUi.tsx +2 -0
- package/templates/shooter/src/ui/Hud.tsx +7 -1
- package/templates/shooter/src/weapons/Hitscan.ts +3 -4
- package/templates/shooter/src/weapons/Projectile.ts +8 -3
- package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
- package/templates/shooter/threenative.config.ts +7 -0
- package/templates/starter/.codex/config.toml +4 -0
- package/templates/starter/.cursor/mcp.json +32 -0
- package/templates/starter/.gemini/settings.json +32 -0
- package/templates/starter/.mcp.json +15 -3
- package/templates/starter/.vscode/mcp.json +36 -0
- package/templates/starter/.zed/settings.json +36 -0
- package/templates/starter/AGENTS.md +70 -527
- package/templates/starter/CLAUDE.md +70 -527
- package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
- package/templates/starter/opencode.json +41 -0
- package/templates/starter/package.json +7 -7
- package/templates/starter/playtests/boot-failure.playtest.json +45 -0
- package/templates/starter/playtests/look.playtest.json +110 -6
- package/templates/starter/playtests/play.playtest.json +3 -2
- package/templates/starter/playtests/survives.playtest.json +21 -0
- package/templates/starter/playtests/touch-controls.playtest.json +42 -0
- package/templates/starter/src/conventions.ts +18 -0
- package/templates/starter/src/entities/Goal.ts +18 -3
- package/templates/starter/src/entities/Player.ts +72 -9
- package/templates/starter/src/game.ts +2 -0
- package/templates/starter/src/render/adaptiveQuality.ts +195 -0
- package/templates/starter/src/render/camera.ts +1 -1
- package/templates/starter/src/render/coast.ts +199 -0
- package/templates/starter/src/render/hero.ts +88 -0
- package/templates/starter/src/render/implicitSurface.ts +199 -0
- package/templates/starter/src/render/kuwahara.ts +174 -0
- package/templates/starter/src/render/lighting.ts +4 -4
- package/templates/starter/src/render/loading.ts +12 -2
- package/templates/starter/src/render/materials.ts +25 -6
- package/templates/starter/src/render/outline.ts +141 -0
- package/templates/starter/src/render/painterly.ts +86 -0
- package/templates/starter/src/render/palette.ts +15 -6
- package/templates/starter/src/render/postprocessing.ts +87 -36
- package/templates/starter/src/render/quality.ts +185 -0
- package/templates/starter/src/render/rockRidge.ts +198 -0
- package/templates/starter/src/render/rockRidge.worker.ts +77 -0
- package/templates/starter/src/render/scenery.ts +16 -59
- package/templates/starter/src/render/textureLifetime.ts +53 -0
- package/templates/starter/src/render/touch-controls.ts +165 -0
- package/templates/starter/src/render/water.ts +38 -0
- package/templates/starter/src/render/watercolor.ts +85 -0
- package/templates/starter/src/render/worldEnvironment.ts +208 -33
- package/templates/starter/src/scenes/Play.ts +103 -16
- package/templates/starter/src/style.css +27 -7
- package/templates/starter/threenative.config.ts +7 -7
- package/agent-docs/asset-mcp-loop.md +0 -33
- package/agent-docs/ctx-surface.md +0 -69
- package/agent-docs/engine-capabilities.md +0 -4
- package/agent-docs/framework-blocks-you.md +0 -60
- package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
- package/agent-docs/performance-default.md +0 -42
- package/agent-docs/pixel-budget.md +0 -20
- package/agent-docs/playtest-fail-closed.md +0 -23
- package/agent-docs/sculpt-loop.md +0 -16
- package/templates/action-rpg/src/physics.ts +0 -40
- package/templates/defense/public/icon.png +0 -0
- package/templates/minimal/public/icon.png +0 -0
- package/templates/platformer/public/icon.png +0 -0
- package/templates/racing/public/icon.png +0 -0
- package/templates/sailing/public/icon.png +0 -0
- package/templates/sailing/src/render/water-material.ts +0 -14
- package/templates/sailing/src/render/water-shaders.ts +0 -12
- package/templates/sailing/src/render/wave-nodes.ts +0 -10
- package/templates/shooter/public/icon.png +0 -0
- package/templates/shooter/src/physics.ts +0 -49
- package/templates/starter/public/icon.png +0 -0
- /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
|
@@ -3,6 +3,13 @@
|
|
|
3
3
|
Companion to the `Budget real time for the look` section in this project's `AGENTS.md`. Run
|
|
4
4
|
`pnpm dev`, then get eyes on the game. In rough order of preference:
|
|
5
5
|
|
|
6
|
+
**First, though, when the complaint is "it looks wrong" rather than "show me":** run
|
|
7
|
+
`npx @threenative/playtest doctor --url http://127.0.0.1:5173 --text`. A capture shows you a black
|
|
8
|
+
or washed-out frame; it cannot tell you *why*. The doctor's lighting, materials and camera
|
|
9
|
+
lines can, and they name the three cases that kill a frame while every other number stays healthy —
|
|
10
|
+
lit materials with no visible light, a fog far plane in front of the scene it fogs, and a camera
|
|
11
|
+
far plane that clips it. Capture after that, to see what the numbers already told you.
|
|
12
|
+
|
|
6
13
|
1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
|
|
7
14
|
or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
|
|
8
15
|
a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# Creating an animated creature through the asset MCP
|
|
2
|
+
|
|
3
|
+
Use this recipe when the game needs a bespoke, animated creature. The asset MCP owns the
|
|
4
|
+
packaged anyCreature compiler and local preview/check tools; the game owns the authored spec,
|
|
5
|
+
claims, render source, cook and playback. Do not add anyCreature to `src/` or the player bundle.
|
|
6
|
+
|
|
7
|
+
## 1. Choose the input route
|
|
8
|
+
|
|
9
|
+
For a conventional model, use `finding-assets.md`. For a supplied reference image, first follow
|
|
10
|
+
`sculpt-from-a-reference.md`: record the reference credit, inventory its recognizable regions and
|
|
11
|
+
decide which details are geometry. Then translate that brief into a creature spec. The creature
|
|
12
|
+
tools accept JSON, not an image, and a successful compile is not proof that the result resembles a
|
|
13
|
+
reference.
|
|
14
|
+
|
|
15
|
+
For a thin request such as “a dragon”, call `creature_guide` with `section: "overview"` and ask
|
|
16
|
+
the single direction question described there. Freeze one identity, one signature part, one
|
|
17
|
+
exaggeration, the mass hierarchy, the two focal parts, the stance, the value plan and the attack
|
|
18
|
+
before writing geometry. A specific request still needs one winner when several parts compete for
|
|
19
|
+
attention.
|
|
20
|
+
|
|
21
|
+
## 2. Check the installed tools
|
|
22
|
+
|
|
23
|
+
Start the MCP session from the game root. It reads `.mcp.json` from the launch directory. Put the
|
|
24
|
+
project-local directory in place before starting or restarting the server:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
.threenative/creatures/
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Call:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
// creature_status
|
|
34
|
+
{}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Then call `creature_guide` for `overview`, `syntax`, and the stage you are entering. The guide
|
|
38
|
+
returned by the pinned server is the authority for supported spec fields and current limits; do
|
|
39
|
+
not copy a wolf example's coordinates or invent fields from memory.
|
|
40
|
+
|
|
41
|
+
`creature_status` separates the fixed compiler from optional render dependencies:
|
|
42
|
+
|
|
43
|
+
- Compiler availability is enough for a compile-only loop. It needs no Python, Chromium, account,
|
|
44
|
+
LLM key, setup script or runtime download.
|
|
45
|
+
- Silhouettes need either the reported Python outline backend or the reported Chromium fallback.
|
|
46
|
+
- Hero images and browser claims measurement need Chromium. A missing optional dependency is an
|
|
47
|
+
actionable unavailable result, not visual approval.
|
|
48
|
+
|
|
49
|
+
If `creature_compile`, `creature_preview` or `creature_check` is unavailable because the launch
|
|
50
|
+
root has no `.threenative` directory, create it and restart the MCP. Keep the server's paths
|
|
51
|
+
project-relative; never pass an absolute path, executable, URL or custom working directory.
|
|
52
|
+
|
|
53
|
+
## 3. Author two editable files
|
|
54
|
+
|
|
55
|
+
Keep the source of truth under `.threenative/creatures/`:
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
.threenative/creatures/wyvern.json
|
|
59
|
+
.threenative/creatures/wyvern-claims.json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The first file is the anyCreature spec. Use `creature_guide` with `section: "syntax"` for the
|
|
63
|
+
complete language. At minimum, author the metre `height`, a nonempty `palette`, named `joints`,
|
|
64
|
+
`chains`, `volumes` with `chain` and `material`, and all three animations. A wing or other
|
|
65
|
+
membrane, a conspicuous jaw/horn, and an articulated tail should be authored as the parts they
|
|
66
|
+
are, not as unrelated straight spikes. Keep the bind pose planted and include a forward-
|
|
67
|
+
committing `attack`.
|
|
68
|
+
|
|
69
|
+
The claims file is also ordinary JSON and must have a nonempty `claims` array. Replace every
|
|
70
|
+
placeholder with names and materials in the spec:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"name": "wyvern",
|
|
75
|
+
"claims": [
|
|
76
|
+
{
|
|
77
|
+
"type": "part_exists",
|
|
78
|
+
"part": "wing_skin",
|
|
79
|
+
"stage": "MID",
|
|
80
|
+
"enforce": "block",
|
|
81
|
+
"when": "verify"
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
"type": "part_signature",
|
|
85
|
+
"part": "wing_skin",
|
|
86
|
+
"view": "side",
|
|
87
|
+
"min_share": 0.12,
|
|
88
|
+
"or_min_span": 0.1,
|
|
89
|
+
"stage": "MID",
|
|
90
|
+
"enforce": "advise",
|
|
91
|
+
"when": "allocate"
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"type": "rig_skinned",
|
|
95
|
+
"stage": "HIGH",
|
|
96
|
+
"enforce": "block",
|
|
97
|
+
"when": "verify"
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
"type": "anim_named",
|
|
101
|
+
"names": ["idle", "move", "attack"],
|
|
102
|
+
"stage": "HIGH",
|
|
103
|
+
"enforce": "block",
|
|
104
|
+
"when": "verify"
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
"type": "tri_budget",
|
|
108
|
+
"min": 400,
|
|
109
|
+
"max": 9000,
|
|
110
|
+
"stage": "LOW",
|
|
111
|
+
"enforce": "advise",
|
|
112
|
+
"when": "allocate"
|
|
113
|
+
}
|
|
114
|
+
]
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Claims are measurements, not permission to skip a visual review. `stage` is exactly `LOW`,
|
|
119
|
+
`MID` or `HIGH`; `enforce` is `block` or `advise`; `when` is `allocate` or `verify`. An unknown
|
|
120
|
+
claim, empty stage after filtering, missing required observation or non-finite value fails closed.
|
|
121
|
+
Use the current `creature_guide` claims section for the complete claim-type field list.
|
|
122
|
+
|
|
123
|
+
## 4. Compile into the normal asset source
|
|
124
|
+
|
|
125
|
+
Read the game's asset configuration and pass an explicit output path under its source asset
|
|
126
|
+
directory, normally `assets/creatures/`. Do not put generated source in `public/`, and do not use
|
|
127
|
+
the MCP's provider download directory as a creature default.
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
// creature_compile
|
|
131
|
+
{
|
|
132
|
+
"specPath": ".threenative/creatures/wyvern.json",
|
|
133
|
+
"outputPath": "assets/creatures/wyvern.glb"
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The successful result is the record for this round: retain its `inputSha256`, `outputSha256`,
|
|
138
|
+
`checksSha256`, measurements, clip names, diagnostics path, checks path, source snapshot path and
|
|
139
|
+
receipt path. Read compiler diagnostics, including warnings, before deciding what to revise. The
|
|
140
|
+
MCP validates the emitted GLB and publishes it atomically; a blocked or failed revision must not
|
|
141
|
+
replace the last good file. When revising an existing output, pass its last known
|
|
142
|
+
`expectedOutputSha256` so a stale writer returns `OUTPUT_CONFLICT` instead of overwriting newer
|
|
143
|
+
work. Edit the JSON spec, never the generated GLB.
|
|
144
|
+
|
|
145
|
+
## 5. Inspect, preview and review each round
|
|
146
|
+
|
|
147
|
+
After a successful compile, inspect actual bytes before judging the look:
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
// creature_check — structural
|
|
151
|
+
{
|
|
152
|
+
"glbPath": "assets/creatures/wyvern.glb",
|
|
153
|
+
"mode": "structural"
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Confirm the returned measurements include reachable skin bindings, materials, bounds and clip
|
|
158
|
+
details. A structural pass still returns `visualReview: "notReviewed"`.
|
|
159
|
+
|
|
160
|
+
Request fresh images from the same compiled GLB:
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
// creature_preview — silhouettes
|
|
164
|
+
{
|
|
165
|
+
"glbPath": "assets/creatures/wyvern.glb",
|
|
166
|
+
"mode": "silhouettes"
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
For a colour/lighting view, call the same tool with `"mode": "hero"`. The result names the
|
|
171
|
+
backend, native view names, camera and resolution, preview ID, artifact paths and hashes. Inspect
|
|
172
|
+
the actual images for the identity, signature part, tail, jaw/horn, planted stance and readable
|
|
173
|
+
value hierarchy. The MCP never grades its own images: `visualReview` remains `notReviewed`.
|
|
174
|
+
|
|
175
|
+
Record one small round note beside the returned artifacts: the spec hash, GLB hash, backend,
|
|
176
|
+
what changed, what the independent visual reviewer saw, and the next edit. Do not overwrite a
|
|
177
|
+
previous round's receipt, claims metrics or preview. A comparison using `previousPreviewId` is
|
|
178
|
+
valid only when the server reports matching backend, cameras and resolutions; a backend switch
|
|
179
|
+
requires a new baseline.
|
|
180
|
+
|
|
181
|
+
Run claims by stage, keeping the output for each stage:
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
// creature_check — LOW, then MID, then HIGH
|
|
185
|
+
{
|
|
186
|
+
"glbPath": "assets/creatures/wyvern.glb",
|
|
187
|
+
"mode": "claims",
|
|
188
|
+
"claimsPath": ".threenative/creatures/wyvern-claims.json",
|
|
189
|
+
"stage": "HIGH"
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Run LOW and MID while allocating big forms, then HIGH after colour and animation are authored.
|
|
194
|
+
Treat `advise` as measured feedback and `block` as a required fix. A passing claim response is
|
|
195
|
+
not a substitute for an independent human or host-side visual review.
|
|
196
|
+
|
|
197
|
+
## 6. Deliver it to the game
|
|
198
|
+
|
|
199
|
+
Delivery requires all three real clips: `idle`, `move`, and `attack`. HIGH must find nonempty
|
|
200
|
+
tracks bound to the actual loaded rig, and `attack` must commit toward the space in front of the
|
|
201
|
+
body. Do not rename a missing clip in the game or claim success from a spec field alone.
|
|
202
|
+
|
|
203
|
+
Use the existing asset cook and loader. The source GLB stays under `assets/`; let the normal build
|
|
204
|
+
produce its cooked output, then load it through the same path as every other model. In the
|
|
205
|
+
existing scene, use `SkeletalMesh3D` and `AnimationPlayer` (search the engine capability manifest
|
|
206
|
+
first), set the authored body as `strideRoot` when the scene needs locomotion, and use the measured
|
|
207
|
+
height rather than a universal scale workaround. Play `idle -> move -> attack` in the game and
|
|
208
|
+
assert visible geometry, expected size, skin deformation, bound animation tracks and stable bone
|
|
209
|
+
lengths on every target you claim.
|
|
210
|
+
|
|
211
|
+
The final artifact is complete only after both machine results and independent visual review are
|
|
212
|
+
recorded. If Python or Chromium is unavailable, report a compile-only or structural result and
|
|
213
|
+
leave preview/claims delivery outstanding; never turn an unavailable optional tool into approval.
|
|
214
|
+
If the target is browser and native, run the same consumer scenario on both. Android and iOS stay
|
|
215
|
+
unclaimed unless their own playtests execute.
|
|
@@ -49,3 +49,72 @@ runs on; both handles are cleared when the scene exits.
|
|
|
49
49
|
`src/game.ts`: a declared seed gives replayable values for spawn positions, patrol offsets,
|
|
50
50
|
and level variation; without one, `ctx.random` falls back to `Math.random()`. Add a fixed
|
|
51
51
|
seed when a playtest needs replayable randomness.
|
|
52
|
+
|
|
53
|
+
## Streaming a second asset tier with `ctx.startup.hold()`
|
|
54
|
+
|
|
55
|
+
`ctx.startup.whenReady()` covers **the framework's** launch work — first-use compilation and a
|
|
56
|
+
sustained in-budget frame window — and nothing after it. If your game loads a cheap tier, enters,
|
|
57
|
+
and then streams the rest, readiness resolves in the middle of that and you get one of two bugs.
|
|
58
|
+
|
|
59
|
+
Show the world at `whenReady()` and the player watches it build itself. Measured in a forest game:
|
|
60
|
+
the loading screen lifted on one tree and a black sky, and the wood, the undergrowth, the animals
|
|
61
|
+
and the sky arrived over the next several seconds.
|
|
62
|
+
|
|
63
|
+
Hold your own curtain past `whenReady()` instead and the picture is right, but every
|
|
64
|
+
framework-owned observation of startup now describes a moment nobody experienced:
|
|
65
|
+
`startup.progress` sits pinned at `1`, `startup.phase` reads `ready`, `timeline.readyMs` reports
|
|
66
|
+
the framework's 1.5 s rather than the player's 8.8 s, and `assert.startup`'s `maxReadyMs` passes a
|
|
67
|
+
game that takes nearly nine seconds to show anything.
|
|
68
|
+
|
|
69
|
+
So register the tier instead, in `load()`, before the framework's gate can resolve:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
override async load(ctx: GameCtx): Promise<void> {
|
|
73
|
+
const detail = this.#loadDetailTier(ctx); // not awaited: enter() runs on the critical tier
|
|
74
|
+
ctx.startup.hold("detail-tier", detail);
|
|
75
|
+
await this.#loadCriticalTier(ctx);
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`whenReady()`, `progress`, `phase` and `timeline.readyMs` now all wait for `detail`, so a loading
|
|
80
|
+
screen written the obvious way — hide it when `whenReady()` resolves — is correct again, and the
|
|
81
|
+
proof of startup time is a proof about the player.
|
|
82
|
+
|
|
83
|
+
Three things to know:
|
|
84
|
+
|
|
85
|
+
- **It fails open, twice.** A hold that rejects counts as settled, and the third argument bounds
|
|
86
|
+
how long it may delay the world (45 s by default). A launch slower than it could be is a
|
|
87
|
+
disappointment; a launch that never finishes because one texture 404'd is a bug.
|
|
88
|
+
`timeline.frameworkReadyMs` still reports the framework's own cost, so a slow tier of yours
|
|
89
|
+
cannot hide a framework regression inside it.
|
|
90
|
+
- **It fails closed on your mistakes.** An empty or duplicate label throws, and so does a hold
|
|
91
|
+
registered after startup already resolved — each means you believe you are gating something you
|
|
92
|
+
are not.
|
|
93
|
+
- **Do the loading, then hold, then enter.** Registering the hold is not what starts the work;
|
|
94
|
+
pass a promise that is already running. And register it in `load()`: a hold added from `enter()`
|
|
95
|
+
races the framework's gate on a warm cache.
|
|
96
|
+
|
|
97
|
+
### The one trap: never start held work from `whenReady()`
|
|
98
|
+
|
|
99
|
+
A hold makes readiness wait for your work. So work *started* from `whenReady()` is waiting for a
|
|
100
|
+
gate that is waiting for it:
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
// DEADLOCK. Only the hold's budget breaks it, and it presents as a very slow load.
|
|
104
|
+
void ctx.startup.whenReady().then(() => this.#loadDetailTier(ctx));
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Measured, when exactly this was written: the valley sat on its loading screen for the full 45 s
|
|
108
|
+
budget and then revealed the critical tier, `TN_VALLEY_REVEAL trees=1`. Nothing errored. It reads
|
|
109
|
+
like a slow network, not like a cycle.
|
|
110
|
+
|
|
111
|
+
There is a real reason to want that shape — the framework's first-use compilation is competing for
|
|
112
|
+
the main thread, and streaming into it makes both slower. So wait on the framework's own gate
|
|
113
|
+
instead, which resolves before the holds:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
void ctx.startup.whenFrameworkReady().then(() => this.#loadDetailTier(ctx));
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`timeline.frameworkReadyMs` is when that fires; `timeline.readyMs` is when the player got the
|
|
120
|
+
world.
|
|
@@ -28,7 +28,7 @@ Installed by `playtest()` (core plugin) or `installThreePlaytestBridge`
|
|
|
28
28
|
| --- | --- | --- |
|
|
29
29
|
| `describe()` | `{ name, protocolVersion, capabilities, limits }` | First call. Tells you what this game's bridge supports and the protocol limits. |
|
|
30
30
|
| `ready()` | `{ ready: true }` | Liveness check before sampling. |
|
|
31
|
-
| `sample(request)` | JSON-safe observation snapshot (entities, camera, renderer stats, resources, components) | The main probe. Pass `{}` for the default sample; `request.include` names optional series such as `physicsDebugSeries`. |
|
|
31
|
+
| `sample(request)` | JSON-safe observation snapshot (entities, camera, renderer stats, resources, components, and `scene`: the lights, materials, fog, background, camera framing and world extent) | The main probe. Pass `{}` for the default sample; `request.include` names optional series such as `physicsDebugSeries`. |
|
|
32
32
|
| `advance(ticks)` | fixed-step bridges only: advances exactly N ticks and returns `{ clock, ticks }`; throws if the step count mismatches | Deterministic stepping without wall-clock waits. Throws when the bridge is render-frame. |
|
|
33
33
|
| `applySetup(request)` | applies scenario `setup` placements/resources through the registry | What scenario setup uses; also usable by hand for one-off staging. |
|
|
34
34
|
| `drainEvents(limit)` | event-queue bridges only: returns up to `limit` queued events | Reads events shorter than one state flush. |
|
|
@@ -58,6 +58,11 @@ plugin marks the expected runner contract) and `__THREENATIVE_FRAMEBUFFER_COVERA
|
|
|
58
58
|
## What does not exist
|
|
59
59
|
|
|
60
60
|
There is no `__THREENATIVE_SCENE__` global. Scene-graph inspection goes through
|
|
61
|
-
`sample()`
|
|
62
|
-
|
|
61
|
+
`sample()` — which reports counts, extents and visibility, and under `scene` the lights,
|
|
62
|
+
materials, fog, background and camera framing the renderer was handed — or through your
|
|
63
|
+
own registered entities' `debug()` output, never by reaching into three.js objects from
|
|
63
64
|
the console and treating what you find as an observation surface.
|
|
65
|
+
|
|
66
|
+
`scene` counts and names; it does not read texture contents or shader graphs, and a scene
|
|
67
|
+
past the walk's cap reports `truncated: true` so a floor is never read as a total. A value
|
|
68
|
+
the scene does not carry is absent rather than zero.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Dream Loop: target-driven authoring
|
|
2
|
+
|
|
3
|
+
Use this workflow when a user supplies a target image, asks for a target to be generated, or
|
|
4
|
+
wants to improve an existing game while preserving its identity. It is an explicit authoring
|
|
5
|
+
workflow, not a background scheduler. The builder edits the game; a fresh verifier reviews the
|
|
6
|
+
real capture; the two small generated scripts validate evidence and accounting.
|
|
7
|
+
|
|
8
|
+
## Upstream notice
|
|
9
|
+
|
|
10
|
+
This workflow adapts the mechanics of Dream Loop at revision
|
|
11
|
+
`9bddb901f7d071cfefdd21e264267c757177a9df` by Anshu Chimala:
|
|
12
|
+
https://github.com/achimala/dream-loop/tree/9bddb901f7d071cfefdd21e264267c757177a9df
|
|
13
|
+
|
|
14
|
+
Copyright (c) 2025 Anshu Chimala
|
|
15
|
+
|
|
16
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software
|
|
17
|
+
and associated documentation files (the "Software"), to deal in the Software without
|
|
18
|
+
restriction, including without limitation the rights to use, copy, modify, merge, publish,
|
|
19
|
+
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
|
|
20
|
+
Software is furnished to do so, subject to the following conditions:
|
|
21
|
+
|
|
22
|
+
The above copyright notice and this permission notice shall be included in all copies or
|
|
23
|
+
substantial portions of the Software.
|
|
24
|
+
|
|
25
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
|
|
26
|
+
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
27
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
|
28
|
+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
29
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
30
|
+
|
|
31
|
+
## 1. Lock the target and constraints
|
|
32
|
+
|
|
33
|
+
Start from the user's target. A supplied image takes precedence and needs no image-service key.
|
|
34
|
+
If no image is available, ask the user to choose an existing host image tool or explicitly opt in
|
|
35
|
+
to the generated `scripts/reference.mjs` route. Never invent a target or silently switch models.
|
|
36
|
+
|
|
37
|
+
Create one run directory under `.dream-loop/`, for example `.dream-loop/run-20260909-01/`, and
|
|
38
|
+
keep its `run.json`, prompt, target, captures, and verdicts together. Do not use a `current`
|
|
39
|
+
symlink as evidence. A run record is project-local and must contain at least:
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"schemaVersion": 1,
|
|
44
|
+
"runId": "run-20260909-01",
|
|
45
|
+
"projectRoot": "/absolute/path/to/game",
|
|
46
|
+
"artifactRoot": ".dream-loop/run-20260909-01",
|
|
47
|
+
"builderIdentity": "builder-session-id",
|
|
48
|
+
"currentSourceSha256": "sha256-of-current-source-or-dirty-tree",
|
|
49
|
+
"target": { "path": ".dream-loop/run-20260909-01/target.png", "sha256": "...", "revision": 1 },
|
|
50
|
+
"limits": {
|
|
51
|
+
"startedAt": "2026-09-09T00:00:00.000Z",
|
|
52
|
+
"deadlineAt": "2026-09-09T00:30:00.000Z",
|
|
53
|
+
"maxRounds": 6,
|
|
54
|
+
"maxImageRequests": 4
|
|
55
|
+
},
|
|
56
|
+
"requests": { "pending": [], "completed": [], "unknown": [], "failed": [] },
|
|
57
|
+
"rounds": [],
|
|
58
|
+
"decisionHistory": []
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Record the original target bytes and hash. A user-authorized refinement creates a new target
|
|
63
|
+
revision and preserves the original target, prior scores, start time, and remaining allowance.
|
|
64
|
+
The builder cannot improve a score by replacing the target or by reviewing its own work.
|
|
65
|
+
|
|
66
|
+
## 2. Build and capture the real game
|
|
67
|
+
|
|
68
|
+
Read the existing capture, playtest, asset, and performance recipes. Search the engine capability
|
|
69
|
+
manifest before adding a mechanic or render stage. Keep appearance in the game's `src/render/`.
|
|
70
|
+
The target is a playable camera view: preserve the requested layout, controls, HUD, landmark,
|
|
71
|
+
and identity. A Blender render, a target image displayed over the canvas, or one frozen camera is
|
|
72
|
+
not a gameplay result.
|
|
73
|
+
|
|
74
|
+
For every round, store a capture record with the actual project-relative path and SHA-256,
|
|
75
|
+
target hash, source hash, viewport, deterministic input/scenario identity, adapter/platform,
|
|
76
|
+
and nonempty functional assertions. Store measured steady frame windows and a positive target
|
|
77
|
+
FPS bound. If display configuration is uncapped or the observation is missing, the round cannot
|
|
78
|
+
be accepted. Capture from a second gameplay position when the subject or asset is central to the
|
|
79
|
+
request.
|
|
80
|
+
|
|
81
|
+
## 3. Independent review and validation
|
|
82
|
+
|
|
83
|
+
Start the read-only verifier in a fresh context. Give it the target, current captures, request,
|
|
84
|
+
rubric, functional observations, and performance windows. It returns exactly `PASS`,
|
|
85
|
+
`REQUEST_CHANGES`, or `NOT_OBSERVED`; it does not receive the builder's self-assessment and it
|
|
86
|
+
must not edit the game. Scores are framing/composition 0–3, lighting/readability 0–3,
|
|
87
|
+
material/shape fidelity 0–3, and finish/HUD detail 0–1. The validator recomputes the total.
|
|
88
|
+
Gaps name visible locations and a proposed correction.
|
|
89
|
+
|
|
90
|
+
After the review, run:
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
node scripts/visual-loop.mjs --record .dream-loop/run-20260909-01/run.json
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Exit 0 means the record was valid and a JSON decision was written; read its `decision`. It is
|
|
97
|
+
one of `continue`, `replan`, `accepted`, `stalled`, `budget-exhausted`, or `unavailable`.
|
|
98
|
+
Exit 2 means the record is malformed. A valid exit 0 is never acceptance by itself.
|
|
99
|
+
|
|
100
|
+
The validator refuses stale capture or target hashes, source changes, missing or empty
|
|
101
|
+
assertions, missing independent review, invalid score ranges, missing performance windows,
|
|
102
|
+
cross-run paths, symlink escapes, and a zero/uncapped FPS bound. It retains the best eligible
|
|
103
|
+
round and the latest gaps. Repeated gaps get one changed approach; if that replan does not
|
|
104
|
+
improve the result, the decision is `stalled`.
|
|
105
|
+
|
|
106
|
+
Acceptance requires a fresh capture, all functional assertions passing, a distinct critic,
|
|
107
|
+
`PASS`, a recomputed score of at least 8/10, no required blocker, and every measured performance
|
|
108
|
+
bound passing. Missing, interrupted, exhausted, and stalled runs are not accepted; they report
|
|
109
|
+
the best eligible evidence and the exact stop reason.
|
|
110
|
+
|
|
111
|
+
## 4. Optional OpenRouter target generation
|
|
112
|
+
|
|
113
|
+
Only use this route after the user has chosen it and `OPENROUTER_API_KEY` is present. The default
|
|
114
|
+
candidate is `meta/muse-image`; `--model` is an explicit override. The script qualifies the
|
|
115
|
+
selected model's advertised image input/output support, then uses one non-streaming chat request.
|
|
116
|
+
It does not retry, download a returned URL, forward credentials, or send unrelated project files.
|
|
117
|
+
Reference editing uses `--reference <local-image>` and includes the original screenshot bytes in
|
|
118
|
+
the request. If the model does not advertise the required capability, preserve the run and
|
|
119
|
+
report `unavailable` rather than substituting another endpoint or model.
|
|
120
|
+
|
|
121
|
+
```sh
|
|
122
|
+
node scripts/reference.mjs \
|
|
123
|
+
--record .dream-loop/run-20260909-01/run.json \
|
|
124
|
+
--request-id target-001 \
|
|
125
|
+
--prompt-file .dream-loop/run-20260909-01/prompt.txt \
|
|
126
|
+
--out .dream-loop/run-20260909-01/target.png \
|
|
127
|
+
--model meta/muse-image
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The script reserves the unique request ID and allowance under an exclusive run lock before its
|
|
131
|
+
one POST. It validates the deadline, response size, raster signature, dimensions where available,
|
|
132
|
+
MIME/extension agreement, and the atomic output. A completed ID returns its verified artifact;
|
|
133
|
+
pending or unknown IDs never POST again. A crash after dispatch remains pending and is reconciled
|
|
134
|
+
as unknown on resume. Usage or cost is recorded when returned, otherwise as `unknown`—never zero.
|
|
135
|
+
Errors name a safe category and HTTP status, and may include `Retry-After`; they never print the
|
|
136
|
+
authorization header or raw provider body.
|
|
137
|
+
|
|
138
|
+
## 5. Assets and release evidence
|
|
139
|
+
|
|
140
|
+
Use the existing asset/license and sculpt decision tree. For a bespoke landmark without a
|
|
141
|
+
reference, delegate to target acquisition first; do not invent a reference. Generated reference
|
|
142
|
+
images stay in authoring evidence, not the runtime build. Imported assets retain their returned
|
|
143
|
+
license and credits. Validate UVs, color space, normals, scale, floor contact, silhouette, and
|
|
144
|
+
multiple gameplay positions in browser and every actually executed native target.
|
|
145
|
+
|
|
146
|
+
Keep `.dream-loop/` ignored while the run is active. Promote the final target/captures, sanitized
|
|
147
|
+
request metadata, verdicts, and command output into a cited `docs/verification/` record before
|
|
148
|
+
cleanup. Never stage `.env`, `.env.authoring`, base64 payloads, scratch records, provider keys,
|
|
149
|
+
or upstream preview media. A missing host, provider, platform, or human visual result remains
|
|
150
|
+
`UNVERIFIED`; it does not become a green claim through a file-presence check.
|
|
@@ -6,9 +6,16 @@ asset tools when the asset is conventional; build anything specific to this game
|
|
|
6
6
|
|
|
7
7
|
Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
|
|
8
8
|
your host lists its tools alongside your own. Your host reads that file from the directory it was
|
|
9
|
-
launched in: start the session in this project, not in a parent of it. It advertises
|
|
9
|
+
launched in: start the session in this project, not in a parent of it. It advertises 40; these 8
|
|
10
10
|
are the loop you will use for nearly everything:
|
|
11
11
|
|
|
12
|
+
For a bespoke animated creature, use the complete [`creating-creatures.md`](creating-creatures.md)
|
|
13
|
+
recipe. It keeps the editable spec and claims under `.threenative/creatures/`, compiles the GLB
|
|
14
|
+
into the configured `assets/` source, and requires independent preview review before game
|
|
15
|
+
delivery. The five creature tools are `creature_status`, `creature_guide`, `creature_compile`,
|
|
16
|
+
`creature_preview` and `creature_check`; call `creature_status` first because compile can work
|
|
17
|
+
without optional preview dependencies while a complete preview/check loop may not.
|
|
18
|
+
|
|
12
19
|
1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
|
|
13
20
|
source with its license summary, attribution requirement, browse URL, and whether an agent
|
|
14
21
|
can complete a download from it. **That output is the authority on what is reachable** —
|
|
@@ -28,6 +35,17 @@ are the loop you will use for nearly everything:
|
|
|
28
35
|
ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
|
|
29
36
|
CC0 per asset page, and audio and bundle licenses are per pack.
|
|
30
37
|
|
|
38
|
+
**For a Poly Haven *model*, steps 3-4 collapse into `polyhaven_import_model`.** Poly Haven
|
|
39
|
+
publishes models as a `.gltf` beside a `.bin` and loose texture files and **never as a `.glb`**, so
|
|
40
|
+
doing it by hand means fetching five to eight URLs and rebuilding the directory layout the glTF's
|
|
41
|
+
relative URIs expect before anything will load. Pass `assetId`, an `outputPath` ending in `.glb`,
|
|
42
|
+
a `resolution` (it defaults to `1k`, which is what a game floor wants), and `acceptLicense: true`;
|
|
43
|
+
it downloads through the same guarded path, packs one self-contained GLB that
|
|
44
|
+
`ctx.assets.model()` loads directly, and returns **triangle count and per-texture dimensions** —
|
|
45
|
+
the two numbers `create-threenative inspect` does not report and that every triangle and texture
|
|
46
|
+
budget is written in. Ask for a resolution the asset does not publish and it names the ones that
|
|
47
|
+
exist. Textures and HDRIs still use `asset_download_file`.
|
|
48
|
+
|
|
31
49
|
**Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
|
|
32
50
|
`ambientcg_search_assets` did not tell you, you do not know it.
|
|
33
51
|
|
|
@@ -112,9 +130,29 @@ GLBs up from `assets/` with no extra configuration.
|
|
|
112
130
|
|
|
113
131
|
What the import will and will not do:
|
|
114
132
|
|
|
133
|
+
- **A pack of uncooked editor assets cannot be converted at all**, and this is the common case for
|
|
134
|
+
marketplace packs, which ship as Unreal *source* projects. Cooking is what writes the renderable
|
|
135
|
+
vertex and index buffers into the file; an uncooked package keeps only the editable source mesh
|
|
136
|
+
and lets the editor derive the rest, so there is no geometry for UE Viewer to read. The import
|
|
137
|
+
detects this and fails `UNREAL_SOURCE_UNCOOKED` naming the evidence it found —
|
|
138
|
+
`/Script/UnrealEd`, `AssetImportData`, `SourceModels`. **Believe it and stop.** No engine
|
|
139
|
+
version, `packages` filter or flag changes the answer, and the download is gigabytes each time
|
|
140
|
+
you try. The only route to those meshes is opening the pack in Unreal Editor and exporting FBX
|
|
141
|
+
or glTF yourself. Prefer a listing that ships a non-Unreal format, and treat one that does not as
|
|
142
|
+
a likely dead end before you spend the bandwidth.
|
|
143
|
+
- **A free listing still has to be in the library first.** `fab_import_asset` refuses with
|
|
144
|
+
`FABCLI_NOT_OWNED` until the listing is claimed, and it never claims — by design. Run
|
|
145
|
+
`fabcli claim <uid>`, which needs the interactive `fabcli auth login` session rather
|
|
146
|
+
than the API token `fabcli auth status` reports as authenticated. Note also that `fab_get_asset`
|
|
147
|
+
reports a free CC-BY offer as `isFree: false` with an empty `freeLicenseSlugs`; the listing
|
|
148
|
+
appearing in `fab_search_assets` with `priceMode: "free"` at `startingPrice.amount: 0` is the
|
|
149
|
+
reliable signal, so check the search before concluding a listing costs money.
|
|
115
150
|
- **Only assets you already own**, and only under **Fab Standard (Personal or Professional) or
|
|
116
151
|
CC-BY**. Unreal-Engine-only and legacy entitlements are refused, and a licence it cannot read is
|
|
117
|
-
refused too.
|
|
152
|
+
refused too. The MCP never logs in, claims, or purchases. If FabCLI needs a session, the agent
|
|
153
|
+
must proactively run `fabcli auth login` and complete it through Claude browser or Codex's
|
|
154
|
+
`chrome:control-chrome`, reusing the user's active signed-in browser session. Never inspect,
|
|
155
|
+
copy, print, or persist cookies or tokens; interact with the login page instead.
|
|
118
156
|
Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
|
|
119
157
|
authenticated path it is guarding.
|
|
120
158
|
- **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
|
|
@@ -134,6 +172,36 @@ What the import will and will not do:
|
|
|
134
172
|
`glb`/`fbx`/`obj`/`unity` file with no account at all. Use it when the listing already ships a
|
|
135
173
|
format you can load, and the importer only when it does not.
|
|
136
174
|
|
|
175
|
+
## From a downloaded `.fbx` to a running character
|
|
176
|
+
|
|
177
|
+
An `.fbx`, `.blend`, `.obj` or `.dae` is not a file the runtime can load. Put it in your assets
|
|
178
|
+
directory anyway and the build converts it:
|
|
179
|
+
|
|
180
|
+
1. Download it — `fab_download_free_asset`, `asset_import_unreal`, `asset_download_bundle_entry`,
|
|
181
|
+
or by hand.
|
|
182
|
+
2. Write it into `assets/`, beside your `.glb` files. Nothing else to configure.
|
|
183
|
+
3. Build. `compileAssets` classifies it as a model, converts it to GLB through Blender, then
|
|
184
|
+
optimizes it exactly like an authored GLB — skeleton, animation clips, materials and embedded
|
|
185
|
+
textures survive.
|
|
186
|
+
4. Load it the ordinary way: `ctx.assets.model("hero")`.
|
|
187
|
+
|
|
188
|
+
**Blender must be installed**, and the framework never installs it for you. With no Blender the
|
|
189
|
+
build fails and names the install command for your platform — it does not copy the unusable file
|
|
190
|
+
through and report success. Ask the user before installing anything; it is roughly 350 MB.
|
|
191
|
+
|
|
192
|
+
The `threenative-blender` MCP server answers the rest:
|
|
193
|
+
|
|
194
|
+
- `blender_status` — can this machine convert at all? Never fails; with no Blender it returns
|
|
195
|
+
`available: false` and the install command. Call it first.
|
|
196
|
+
- `blender_inspect` — what is in this file? Mesh, triangle, vertex and bone counts, material
|
|
197
|
+
names, clip names, image names. Use it before committing a download.
|
|
198
|
+
- `blender_convert` — write a GLB somewhere other than the build's output. Zero meshes out is a
|
|
199
|
+
failure, never an empty GLB.
|
|
200
|
+
- `blender_recipes` — the shipped bpy recipes (`decimate`, `unwrap`, `bake_ao`, `retarget`) and
|
|
201
|
+
their **full source text**. Read one and adapt it; do not write bpy cold.
|
|
202
|
+
- `blender_run_python` — run a bpy script of your own. It is not a sandbox and does not claim to
|
|
203
|
+
be; it gives you a resolved Blender and the same fail-closed handling, not extra privilege.
|
|
204
|
+
|
|
137
205
|
## The narrower tools
|
|
138
206
|
|
|
139
207
|
The directory spells out the conditions on each. The Fab tools are covered above; the server
|
|
@@ -12,8 +12,9 @@ Companion to the short `Building what you cannot download` section in this proje
|
|
|
12
12
|
- **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
|
|
13
13
|
landmark, scenery composition, or environment set piece whose silhouette must match. Use
|
|
14
14
|
the sculpt tools to turn that reference into editable `src/render/` source.
|
|
15
|
-
- **Bespoke, without a reference image** —
|
|
16
|
-
|
|
15
|
+
- **Bespoke, without a reference image** — read `agent-docs/dream-loop.md` and acquire one from
|
|
16
|
+
the user or an explicitly selected host/provider tool. Do not invent a reference: comparison
|
|
17
|
+
without evidence is unguided iteration.
|
|
17
18
|
|
|
18
19
|
For a full environment, split the decision: sculpt the signature landmark or bounded scene
|
|
19
20
|
kit that makes the reference recognisable; use the asset tools for interchangeable trees,
|