create-threenative 0.2.2 → 0.2.4
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/LICENSE +21 -0
- package/README.md +61 -2
- package/agent-docs/references/assertion-reference.md +819 -0
- package/agent-docs/references/capability-reference.md +4483 -0
- package/agent-docs/references/capture-the-frame.md +60 -0
- package/agent-docs/references/creating-creatures.md +215 -0
- package/agent-docs/references/ctx-cookbook.md +120 -0
- package/agent-docs/references/debug-surface.md +68 -0
- package/agent-docs/references/dream-loop.md +150 -0
- package/agent-docs/references/finding-assets.md +215 -0
- package/agent-docs/references/gameplay-recipes.md +54 -0
- package/agent-docs/references/menu-screens.md +69 -0
- package/agent-docs/references/mobile-memory-budget.md +87 -0
- package/agent-docs/references/sculpt-from-a-reference.md +40 -0
- package/agent-docs/references/trace-a-slow-frame.md +99 -0
- package/agent-docs/references/visual-baseline.md +174 -0
- package/agent-docs/references/webview-ui.md +113 -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 +7 -0
- 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 +7 -0
- package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
- package/agent-files/.claude/agents/threenative-builder.md +7 -0
- package/agent-files/.claude/agents/threenative-verifier.md +7 -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/.threenative/agents/builder.md +32 -0
- package/agent-files/.threenative/agents/verifier.md +31 -0
- package/agent-files/AGENT-ROLES.md +26 -0
- package/agent-files/scripts/reference.mjs +705 -0
- package/agent-files/scripts/visual-loop.mjs +382 -0
- package/capabilities.json +5292 -0
- package/dist/index.d.ts +224 -3
- package/dist/index.js +1972 -73
- package/dist/threenative.d.ts +9 -2
- package/dist/threenative.js +2570 -176
- package/package.json +55 -6
- package/template-assets/icon.png +0 -0
- package/template-assets/loading.ts +325 -0
- package/template-assets/patches/three@0.185.1.patch +522 -0
- package/template-assets/worldEnvironment.ts +758 -0
- package/templates/action-rpg/.codex/config.toml +19 -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 +18 -2
- package/templates/action-rpg/.vscode/mcp.json +36 -0
- package/templates/action-rpg/.zed/settings.json +36 -0
- package/templates/action-rpg/AGENTS.md +84 -29
- package/templates/action-rpg/CLAUDE.md +84 -29
- package/templates/action-rpg/index.html +0 -1
- package/templates/action-rpg/opencode.json +41 -0
- package/templates/action-rpg/package.json +15 -11
- package/templates/action-rpg/playtests/combat.playtest.json +32 -9
- package/templates/action-rpg/playtests/fail.playtest.json +3 -3
- package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
- package/templates/action-rpg/playtests/performance.playtest.json +39 -0
- package/templates/action-rpg/playtests/progress.playtest.json +18 -13
- 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/playtests/win.playtest.json +10 -4
- package/templates/action-rpg/src/conventions.ts +35 -0
- package/templates/action-rpg/src/entities/Enemy.ts +16 -7
- package/templates/action-rpg/src/entities/Player.ts +20 -3
- package/templates/action-rpg/src/game.ts +21 -0
- package/templates/action-rpg/src/render/camera.ts +7 -2
- package/templates/action-rpg/src/render/lighting.ts +11 -4
- package/templates/action-rpg/src/render/loading.ts +278 -43
- 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 +32 -16
- 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 +758 -0
- package/templates/action-rpg/src/scenes/Play.ts +91 -24
- package/templates/action-rpg/src/state.ts +4 -0
- package/templates/action-rpg/src/style.css +65 -1
- package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
- package/templates/action-rpg/src/ui/App.tsx +9 -8
- package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
- package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
- package/templates/action-rpg/src/ui/Hud.tsx +10 -8
- package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
- package/templates/action-rpg/src/ui/main.tsx +14 -0
- package/templates/action-rpg/threenative.config.ts +28 -8
- package/templates/action-rpg/vite.config.ts +32 -2
- package/templates/defense/.codex/config.toml +19 -0
- package/templates/defense/.cursor/mcp.json +32 -0
- package/templates/defense/.gemini/settings.json +32 -0
- package/templates/defense/.mcp.json +18 -2
- package/templates/defense/.vscode/mcp.json +36 -0
- package/templates/defense/.zed/settings.json +36 -0
- package/templates/defense/AGENTS.md +81 -41
- package/templates/defense/CLAUDE.md +81 -41
- package/templates/defense/README.md +2 -1
- package/templates/defense/index.html +0 -1
- package/templates/defense/opencode.json +41 -0
- package/templates/defense/package.json +16 -12
- package/templates/defense/playtests/leak.playtest.json +9 -4
- package/templates/defense/playtests/performance.playtest.json +39 -0
- package/templates/defense/playtests/placement.playtest.json +5 -5
- package/templates/defense/playtests/pointer-placement.playtest.json +156 -0
- package/templates/defense/playtests/scan.playtest.json +4 -4
- package/templates/defense/playtests/survive.playtest.json +25 -6
- package/templates/defense/src/attackers/Attacker.ts +32 -16
- 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 +25 -4
- 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/lighting.ts +6 -1
- package/templates/defense/src/render/loading.ts +274 -38
- 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 +32 -12
- package/templates/defense/src/render/quality.ts +170 -0
- package/templates/defense/src/render/shapes.ts +180 -23
- package/templates/defense/src/render/sky.ts +2 -2
- package/templates/defense/src/render/worldEnvironment.ts +758 -0
- package/templates/defense/src/scenes/Boot.ts +2 -2
- package/templates/defense/src/scenes/Defense.ts +122 -56
- package/templates/defense/src/state.ts +6 -0
- package/templates/defense/src/style.css +65 -1
- 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 +11 -6
- package/templates/defense/src/ui/GameUi.tsx +20 -0
- package/templates/defense/src/ui/Hud.tsx +6 -5
- package/templates/defense/src/ui/main.tsx +14 -0
- package/templates/defense/threenative.config.ts +28 -8
- package/templates/defense/vite.config.ts +34 -1
- package/templates/minimal/.codex/config.toml +19 -0
- package/templates/minimal/.cursor/mcp.json +32 -0
- package/templates/minimal/.gemini/settings.json +32 -0
- package/templates/minimal/.mcp.json +18 -2
- package/templates/minimal/.vscode/mcp.json +36 -0
- package/templates/minimal/.zed/settings.json +36 -0
- package/templates/minimal/AGENTS.md +78 -382
- package/templates/minimal/CLAUDE.md +78 -382
- package/templates/minimal/index.html +0 -1
- package/templates/minimal/opencode.json +41 -0
- package/templates/minimal/package.json +14 -11
- package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
- package/templates/minimal/playtests/play.playtest.json +18 -5
- 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/game.ts +1 -0
- package/templates/minimal/src/main.ts +14 -4
- package/templates/minimal/src/render/camera.ts +1 -1
- package/templates/minimal/src/render/hud.ts +24 -8
- package/templates/minimal/src/render/lighting.ts +23 -2
- package/templates/minimal/src/render/loading.ts +23 -103
- 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 +55 -16
- package/templates/minimal/src/render/quality.ts +162 -0
- package/templates/minimal/src/render/sky.ts +51 -32
- package/templates/minimal/src/render/touch-controls.ts +165 -0
- package/templates/minimal/src/render/worldEnvironment.ts +758 -0
- package/templates/minimal/src/scenes/Play.ts +128 -14
- package/templates/minimal/src/state.ts +8 -1
- package/templates/minimal/src/style.css +20 -0
- package/templates/minimal/threenative.config.ts +22 -10
- package/templates/minimal/vite.config.ts +28 -1
- package/templates/platformer/.codex/config.toml +19 -0
- package/templates/platformer/.cursor/mcp.json +32 -0
- package/templates/platformer/.gemini/settings.json +32 -0
- package/templates/platformer/.mcp.json +18 -2
- package/templates/platformer/.vscode/mcp.json +36 -0
- package/templates/platformer/.zed/settings.json +36 -0
- package/templates/platformer/AGENTS.md +81 -186
- package/templates/platformer/CLAUDE.md +81 -186
- package/templates/platformer/index.html +0 -1
- package/templates/platformer/opencode.json +41 -0
- package/templates/platformer/package.json +17 -14
- package/templates/platformer/playtests/avoidance.playtest.json +6 -1
- package/templates/platformer/playtests/branding.playtest.json +29 -0
- package/templates/platformer/playtests/buffer.playtest.json +1 -1
- package/templates/platformer/playtests/collect.playtest.json +1 -1
- package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
- package/templates/platformer/playtests/coyote.playtest.json +42 -8
- package/templates/platformer/playtests/damage.playtest.json +4 -1
- package/templates/platformer/playtests/dash.playtest.json +2 -2
- package/templates/platformer/playtests/jump.playtest.json +2 -3
- package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
- package/templates/platformer/playtests/oneway.playtest.json +30 -3
- package/templates/platformer/playtests/performance.playtest.json +7 -5
- package/templates/platformer/playtests/respawn.playtest.json +2 -2
- package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
- package/templates/platformer/playtests/stomp.playtest.json +11 -3
- package/templates/platformer/playtests/survives.playtest.json +31 -0
- package/templates/platformer/playtests/terminal-loop-fail.playtest.json +16 -4
- package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
- package/templates/platformer/playtests/touch-controls-web.playtest.json +57 -0
- package/templates/platformer/src/conventions.ts +18 -0
- package/templates/platformer/src/entities/Character.ts +79 -11
- package/templates/platformer/src/entities/Patrol.ts +5 -0
- package/templates/platformer/src/game.ts +27 -2
- package/templates/platformer/src/level/Platform.ts +13 -1
- package/templates/platformer/src/render/lighting.ts +13 -5
- package/templates/platformer/src/render/loading.ts +281 -62
- package/templates/platformer/src/render/palette.ts +4 -1
- package/templates/platformer/src/render/postprocessing.ts +42 -14
- package/templates/platformer/src/render/quality.ts +170 -0
- package/templates/platformer/src/render/touch-controls.ts +54 -36
- package/templates/platformer/src/render/worldEnvironment.ts +758 -0
- package/templates/platformer/src/scenes/Level.ts +97 -32
- package/templates/platformer/src/state.ts +4 -0
- package/templates/platformer/src/style.css +65 -1
- package/templates/platformer/src/ui/App.tsx +9 -4
- package/templates/platformer/src/ui/GameUi.tsx +20 -0
- package/templates/platformer/src/ui/Hud.tsx +6 -5
- package/templates/platformer/src/ui/main.tsx +14 -0
- package/templates/platformer/threenative.config.ts +27 -10
- package/templates/platformer/vite.config.ts +34 -1
- 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 +19 -0
- package/templates/racing/.cursor/mcp.json +32 -0
- package/templates/racing/.gemini/settings.json +32 -0
- package/templates/racing/.mcp.json +18 -2
- package/templates/racing/.vscode/mcp.json +36 -0
- package/templates/racing/.zed/settings.json +36 -0
- package/templates/racing/AGENTS.md +84 -36
- package/templates/racing/CLAUDE.md +84 -36
- package/templates/racing/index.html +0 -1
- package/templates/racing/native-playtests/survives.playtest.json +43 -0
- package/templates/racing/opencode.json +41 -0
- package/templates/racing/package.json +17 -12
- package/templates/racing/playtests/boost.playtest.json +5 -5
- package/templates/racing/playtests/outcome.playtest.json +14 -4
- package/templates/racing/playtests/performance.playtest.json +39 -0
- package/templates/racing/playtests/ranking.playtest.json +2 -2
- package/templates/racing/playtests/rescue.playtest.json +12 -6
- package/templates/racing/playtests/reverse.playtest.json +3 -3
- package/templates/racing/playtests/shortcut.playtest.json +3 -3
- 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/game.ts +24 -1
- package/templates/racing/src/render/camera.ts +15 -8
- package/templates/racing/src/render/lighting.ts +28 -14
- package/templates/racing/src/render/loading.ts +302 -35
- 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 +32 -12
- 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 +758 -0
- package/templates/racing/src/scenes/Race.ts +84 -37
- package/templates/racing/src/state.ts +4 -0
- package/templates/racing/src/style.css +65 -1
- package/templates/racing/src/track/Lap.ts +20 -9
- package/templates/racing/src/track/Ranking.ts +53 -14
- package/templates/racing/src/track/Track.ts +284 -32
- package/templates/racing/src/track/TrackSector.ts +14 -4
- package/templates/racing/src/ui/App.tsx +9 -4
- package/templates/racing/src/ui/GameUi.tsx +20 -0
- package/templates/racing/src/ui/Hud.tsx +6 -5
- package/templates/racing/src/ui/main.tsx +14 -0
- package/templates/racing/threenative.config.ts +28 -8
- package/templates/racing/vite.config.ts +34 -1
- 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 +19 -0
- package/templates/sailing/.cursor/mcp.json +32 -0
- package/templates/sailing/.gemini/settings.json +32 -0
- package/templates/sailing/.mcp.json +32 -0
- package/templates/sailing/.vscode/mcp.json +36 -0
- package/templates/sailing/.zed/settings.json +36 -0
- package/templates/sailing/AGENTS.md +95 -0
- package/templates/sailing/CLAUDE.md +97 -0
- package/templates/sailing/README.md +28 -0
- package/templates/sailing/index.html +12 -0
- package/templates/sailing/kit.json +7 -0
- package/templates/sailing/native-playtests/float.playtest.json +55 -0
- package/templates/sailing/native-playtests/survives.playtest.json +38 -0
- package/templates/sailing/opencode.json +41 -0
- package/templates/sailing/package.json +52 -0
- package/templates/sailing/playtests/fail.playtest.json +24 -0
- 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 +36 -0
- package/templates/sailing/playtests/survives.playtest.json +46 -0
- package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
- package/templates/sailing/playtests/win.playtest.json +31 -0
- package/templates/sailing/public/favicon.svg +5 -0
- package/templates/sailing/src/conventions.ts +8 -0
- package/templates/sailing/src/entities/Ship.ts +233 -0
- package/templates/sailing/src/game.ts +40 -0
- package/templates/sailing/src/main.ts +15 -0
- package/templates/sailing/src/render/camera.ts +28 -0
- package/templates/sailing/src/render/lighting.ts +41 -0
- package/templates/sailing/src/render/loading.ts +325 -0
- package/templates/sailing/src/render/materials.ts +44 -0
- package/templates/sailing/src/render/ocean.ts +179 -0
- package/templates/sailing/src/render/palette.ts +17 -0
- package/templates/sailing/src/render/postprocessing.ts +34 -0
- package/templates/sailing/src/render/props.ts +602 -0
- package/templates/sailing/src/render/quality.ts +140 -0
- package/templates/sailing/src/render/sky.ts +37 -0
- package/templates/sailing/src/render/touch-controls.ts +142 -0
- package/templates/sailing/src/render/worldEnvironment.ts +758 -0
- package/templates/sailing/src/scenes/Boot.ts +12 -0
- package/templates/sailing/src/scenes/Sailing.ts +133 -0
- package/templates/sailing/src/state.ts +10 -0
- package/templates/sailing/src/style.css +81 -0
- package/templates/sailing/src/ui/App.tsx +15 -0
- package/templates/sailing/src/ui/GameUi.tsx +12 -0
- package/templates/sailing/src/ui/Hud.tsx +55 -0
- package/templates/sailing/src/ui/Menu.tsx +30 -0
- package/templates/sailing/src/ui/main.tsx +7 -0
- package/templates/sailing/tailwind.config.ts +2 -0
- package/templates/sailing/threenative.config.ts +40 -0
- package/templates/sailing/tsconfig.json +17 -0
- package/templates/sailing/vite.config.ts +34 -0
- package/templates/shooter/.codex/config.toml +19 -0
- package/templates/shooter/.cursor/mcp.json +32 -0
- package/templates/shooter/.gemini/settings.json +32 -0
- package/templates/shooter/.mcp.json +18 -2
- package/templates/shooter/.vscode/mcp.json +36 -0
- package/templates/shooter/.zed/settings.json +36 -0
- package/templates/shooter/AGENTS.md +81 -54
- package/templates/shooter/CLAUDE.md +81 -54
- package/templates/shooter/index.html +0 -1
- package/templates/shooter/kit.json +2 -2
- package/templates/shooter/opencode.json +41 -0
- package/templates/shooter/package.json +16 -11
- package/templates/shooter/playtests/combat.playtest.json +48 -0
- package/templates/shooter/playtests/fail.playtest.json +5 -4
- package/templates/shooter/playtests/input-control.playtest.json +261 -0
- package/templates/shooter/playtests/per-item.playtest.json +59 -0
- package/templates/shooter/playtests/performance.playtest.json +39 -0
- package/templates/shooter/playtests/shooter.playtest.json +31 -21
- package/templates/shooter/playtests/survives.playtest.json +28 -1
- package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
- package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
- package/templates/shooter/public/favicon.svg +1 -1
- 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 +35 -3
- package/templates/shooter/src/main.ts +3 -13
- package/templates/shooter/src/render/camera.ts +78 -18
- package/templates/shooter/src/render/decals.ts +211 -0
- package/templates/shooter/src/render/lighting.ts +13 -4
- package/templates/shooter/src/render/loading.ts +274 -35
- 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 +32 -17
- 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 +519 -60
- 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 +119 -1
- 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 +758 -0
- package/templates/shooter/src/scenes/Play.ts +385 -97
- package/templates/shooter/src/state.ts +18 -0
- package/templates/shooter/src/style.css +46 -0
- package/templates/shooter/src/ui/App.tsx +10 -12
- package/templates/shooter/src/ui/Crosshair.tsx +25 -0
- package/templates/shooter/src/ui/GameUi.tsx +22 -0
- package/templates/shooter/src/ui/Hud.tsx +14 -10
- package/templates/shooter/src/ui/Menu.tsx +24 -9
- package/templates/shooter/src/ui/main.tsx +15 -0
- package/templates/shooter/src/weapons/Hitscan.ts +3 -4
- package/templates/shooter/src/weapons/Projectile.ts +29 -13
- package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
- package/templates/shooter/threenative.config.ts +28 -8
- package/templates/shooter/vite.config.ts +32 -2
- package/templates/starter/.codex/config.toml +19 -0
- package/templates/starter/.cursor/mcp.json +32 -0
- package/templates/starter/.gemini/settings.json +32 -0
- package/templates/starter/.mcp.json +18 -2
- package/templates/starter/.vscode/mcp.json +36 -0
- package/templates/starter/.zed/settings.json +36 -0
- package/templates/starter/AGENTS.md +72 -426
- package/templates/starter/CLAUDE.md +72 -426
- package/templates/starter/assets/pickup.wav +0 -0
- package/templates/starter/gitignore +4 -0
- package/templates/starter/index.html +0 -1
- package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
- package/templates/starter/native-playtests/render-chain.playtest.json +81 -0
- package/templates/starter/opencode.json +41 -0
- package/templates/starter/package.json +16 -12
- package/templates/starter/playtests/assets.playtest.json +65 -0
- package/templates/starter/playtests/boot-failure.playtest.json +45 -0
- package/templates/starter/playtests/buffer.playtest.json +59 -9
- package/templates/starter/playtests/cloth.playtest.json +113 -0
- package/templates/starter/playtests/coyote.playtest.json +60 -8
- package/templates/starter/playtests/forward.playtest.json +29 -4
- package/templates/starter/playtests/gameover.playtest.json +66 -0
- package/templates/starter/playtests/goal.playtest.json +67 -0
- package/templates/starter/playtests/hot-reload.playtest.json +48 -8
- package/templates/starter/playtests/look.playtest.json +142 -10
- package/templates/starter/playtests/models-baseline.png +0 -0
- package/templates/starter/playtests/models.playtest.json +74 -0
- package/templates/starter/playtests/monitoring.playtest.json +38 -7
- package/templates/starter/playtests/odometer.playtest.json +54 -0
- package/templates/starter/playtests/pause.playtest.json +27 -4
- package/templates/starter/playtests/play.playtest.json +44 -7
- package/templates/starter/playtests/respawn.playtest.json +46 -6
- package/templates/starter/playtests/restart.playtest.json +65 -10
- package/templates/starter/playtests/seed.playtest.json +44 -8
- package/templates/starter/playtests/survives.playtest.json +48 -4
- package/templates/starter/playtests/textures-baseline.png +0 -0
- package/templates/starter/playtests/textures.playtest.json +74 -0
- package/templates/starter/playtests/touch-controls.playtest.json +42 -0
- package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
- package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
- package/templates/starter/src/conventions.ts +18 -0
- package/templates/starter/src/entities/Goal.ts +137 -0
- package/templates/starter/src/entities/Player.ts +111 -10
- package/templates/starter/src/game.ts +27 -0
- package/templates/starter/src/render/adaptiveQuality.ts +195 -0
- package/templates/starter/src/render/camera.ts +31 -5
- package/templates/starter/src/render/coast.ts +199 -0
- package/templates/starter/src/render/easing.ts +5 -0
- package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
- package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
- package/templates/starter/src/render/effects/sparkle.ts +49 -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 +10 -5
- package/templates/starter/src/render/loading.ts +325 -0
- package/templates/starter/src/render/materials.ts +39 -4
- 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/pennant.ts +54 -0
- package/templates/starter/src/render/postprocessing.ts +97 -15
- 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 +40 -0
- package/templates/starter/src/render/shapes.ts +9 -21
- 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 +758 -0
- package/templates/starter/src/scenes/Play.ts +243 -46
- package/templates/starter/src/state.ts +12 -0
- package/templates/starter/src/style.css +72 -8
- package/templates/starter/src/ui/App.tsx +9 -6
- package/templates/starter/src/ui/GameUi.tsx +20 -0
- package/templates/starter/src/ui/Hud.tsx +52 -29
- package/templates/starter/src/ui/Menu.tsx +25 -23
- package/templates/starter/src/ui/main.tsx +14 -0
- package/templates/starter/threenative.config.ts +27 -9
- package/templates/starter/tools/look.mjs +109 -0
- package/templates/starter/vite.config.ts +32 -2
- package/templates/action-rpg/src/physics.ts +0 -40
- package/templates/minimal/assets/.gitkeep +0 -0
- package/templates/minimal/public/.gitkeep +0 -0
- package/templates/minimal/public/icon.png +0 -0
- package/templates/platformer/assets/.gitkeep +0 -0
- package/templates/platformer/public/.gitkeep +0 -0
- package/templates/platformer/public/icon.png +0 -0
- package/templates/shooter/src/physics.ts +0 -49
- package/templates/starter/assets/.gitkeep +0 -0
- package/templates/starter/public/.gitkeep +0 -0
- package/templates/starter/public/icon.png +0 -0
- package/templates/starter/public/pickup.ogg +0 -0
- /package/templates/starter/{public → assets}/native-proof.glb +0 -0
- /package/templates/starter/{public → assets}/native-proof.png +0 -0
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Capture the frame — screenshots that actually render WebGPU
|
|
2
|
+
|
|
3
|
+
Companion to the `Budget real time for the look` section in this project's `AGENTS.md`. Run
|
|
4
|
+
`pnpm dev`, then get eyes on the game. In rough order of preference:
|
|
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
|
+
|
|
13
|
+
1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
|
|
14
|
+
or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
|
|
15
|
+
a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
|
|
16
|
+
console in the same loop you are already coding in. Drive the game, do not just load the
|
|
17
|
+
menu.
|
|
18
|
+
2. **`npx @threenative/playtest <scenario> --browser-recipe webgpu --headed`.** The recipe
|
|
19
|
+
carries the Chromium flags a WebGPU capture needs, including `--enable-features=Vulkan`.
|
|
20
|
+
Do not hand-roll the flag list: without that one flag Chromium never reaches the Linux
|
|
21
|
+
Vulkan driver and serves WebGPU from SwiftShader, its CPU rasteriser — no error, healthy
|
|
22
|
+
limits, and a software renderer's picture. The runner fails such a run with
|
|
23
|
+
`TN_PLAYTEST_SOFTWARE_ADAPTER` and prints the adapter it got; `--allow-software` accepts
|
|
24
|
+
the fallback if you truly want it.
|
|
25
|
+
3. **Ask the user to look**, and say specifically what you want them to check.
|
|
26
|
+
|
|
27
|
+
## Virtual displays
|
|
28
|
+
|
|
29
|
+
On a machine with no screen, run any of those under a virtual display. **Do not use
|
|
30
|
+
`xvfb-run`:** on `xorg-server-xvfb` 21.1.x its cleanup `kill` fails after Xvfb has already
|
|
31
|
+
exited and that failing kill's status replaces the real one, so
|
|
32
|
+
`xvfb-run -a -s '-screen 0 1600x900x24' true` exits `1`. Every gate wrapped in it reports
|
|
33
|
+
failure whether it passed or not. Start `Xvfb` yourself on a free display and export
|
|
34
|
+
`DISPLAY`, or check the command's own exit code separately.
|
|
35
|
+
|
|
36
|
+
## Headless Chromium usually cannot render WebGPU
|
|
37
|
+
|
|
38
|
+
The page loads, the HUD paints, and the 3D canvas comes out blank or black. That looks
|
|
39
|
+
exactly like a bug in your scene, and it is not. Symptoms are `Instance dropped in
|
|
40
|
+
popErrorScope` and `createBuffer failed, size (N) is too large for the implementation` in
|
|
41
|
+
the console.
|
|
42
|
+
|
|
43
|
+
So: if a screenshot comes back black or empty, suspect the capture before you rewrite the
|
|
44
|
+
scene. Confirm the renderer works at all before you go debugging your materials.
|
|
45
|
+
|
|
46
|
+
## The silhouette checklist
|
|
47
|
+
|
|
48
|
+
1. **Look at it.** Boot the game, get the thing on screen, take a screenshot, open the
|
|
49
|
+
screenshot. Reading your own diff is not looking at it.
|
|
50
|
+
2. **Silhouette first.** Can you tell what it is from its outline alone? Break up long
|
|
51
|
+
straight edges — overhangs, fringes, props crossing the line.
|
|
52
|
+
3. **Give it depth.** Something bright behind it, something dark under it. Contact shadows
|
|
53
|
+
and a rim make a prop sit in the world instead of floating on top of it.
|
|
54
|
+
4. **Make it move.** Idle bob, a squash on impact, a particle on pickup, a screen shake on
|
|
55
|
+
damage. A few frames of motion is the cheapest quality-per-line in the whole project.
|
|
56
|
+
5. **Finish the HUD too.** Spacing, hierarchy, a transition on every number that changes.
|
|
57
|
+
|
|
58
|
+
When you think you are done, ask yourself, honestly: *would a player screenshot this?* If
|
|
59
|
+
the answer is no, you are not finished — and no command in this project is going to tell
|
|
60
|
+
you that.
|
|
@@ -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.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# The ctx cookbook — recipes behind the `ctx` surface table
|
|
2
|
+
|
|
3
|
+
Companion to the `The ctx surface` section in this project's `AGENTS.md`. The table there is
|
|
4
|
+
the contract; this page is the how and the why.
|
|
5
|
+
|
|
6
|
+
## Pointer picking with `ctx.raycast()`
|
|
7
|
+
|
|
8
|
+
It defaults to the current pointer position and the whole scene, returns the nearest
|
|
9
|
+
`THREE.Intersection`, and stays under a millisecond on meshes large enough that a plain
|
|
10
|
+
`Raycaster` visibly stutters — it keeps an acceleration structure per geometry and rebuilds it
|
|
11
|
+
when that geometry's positions change. Pass `{ origin, direction }` for a world ray, `{ far }`
|
|
12
|
+
to cap its distance, `{ exclude }` to remove subtrees, and `{ targets }` to narrow it. Use
|
|
13
|
+
`raycastAll` when occlusion or another query needs every hit; results are sorted nearest first.
|
|
14
|
+
`{ screen }` tests a point that is not the pointer. Skinned, instanced and morphed meshes fall
|
|
15
|
+
back to the stock Three.js path automatically, so the result always matches
|
|
16
|
+
`Raycaster.intersectObject`.
|
|
17
|
+
|
|
18
|
+
When scene collapse runs on a large static scene, a mesh with non-empty `userData` stays as the
|
|
19
|
+
original object in the live graph. Put the target or entity metadata you already use for picking
|
|
20
|
+
on the mesh; `ctx.raycast()` then still returns that mesh and its metadata. Meshes without
|
|
21
|
+
`userData` may be merged into fewer draws.
|
|
22
|
+
|
|
23
|
+
## Scene rebuild semantics
|
|
24
|
+
|
|
25
|
+
Calling `ctx.goto("<scene-name>")` from inside the matching scene tears it down and rebuilds
|
|
26
|
+
it: `exit()` runs, scheduled callbacks are cleared, registered entities are cleared, the Three
|
|
27
|
+
scene is emptied, then a fresh instance runs `load()` and `enter()`. Values in `ctx.state` —
|
|
28
|
+
health, score, inventory, or any other game-owned state — survive this scene rebuild. When
|
|
29
|
+
death-and-retry should reset gameplay, reset your own state explicitly before calling
|
|
30
|
+
`ctx.goto()`.
|
|
31
|
+
|
|
32
|
+
Do **not** write a `#reset()` that walks your entities putting them back. It is ~15 lines that
|
|
33
|
+
look right and quietly miss the scheduler and anything you spawned after `enter()`, so the
|
|
34
|
+
second playthrough behaves differently from the first — and no gate in this project will catch
|
|
35
|
+
that.
|
|
36
|
+
|
|
37
|
+
## Timing with `ctx.tween` and `ctx.after`
|
|
38
|
+
|
|
39
|
+
**`ctx.tween` is for timing, not for looks.** Use it for the *when* — a pickup rising over
|
|
40
|
+
0.4s, a door opening, a hit flash — and keep the *what* (colour, shape, easing feel) in
|
|
41
|
+
`src/render/`. Motion driven by a persistent `Math.sin(elapsed)` in `update()` is still the
|
|
42
|
+
right tool for a continuous idle bob; `tween` is for anything that starts, runs once, and
|
|
43
|
+
finishes. `ctx.after(seconds, fn)` and `ctx.every(fn)` schedule on the same clock the scene
|
|
44
|
+
runs on; both handles are cleared when the scene exits.
|
|
45
|
+
|
|
46
|
+
## Seeded randomness
|
|
47
|
+
|
|
48
|
+
**`ctx.random` is deterministic only when `defineGame({ seed })` is configured.** Check
|
|
49
|
+
`src/game.ts`: a declared seed gives replayable values for spawn positions, patrol offsets,
|
|
50
|
+
and level variation; without one, `ctx.random` falls back to `Math.random()`. Add a fixed
|
|
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.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# The debug surface — probing a running game
|
|
2
|
+
|
|
3
|
+
The bridge globals exist but were discovered by trial: six throwaway probe scripts in one
|
|
4
|
+
day, each re-finding the shapes through TypeErrors. This page lists every global a running
|
|
5
|
+
game exposes, what it returns, and how to read it from the browser console. All of them are
|
|
6
|
+
read-only observation surfaces; none exists to drive gameplay.
|
|
7
|
+
|
|
8
|
+
## `window.__THREENATIVE__` — entity snapshot (dev builds only)
|
|
9
|
+
|
|
10
|
+
Installed by `defineGame` when the dev-server flag is on (`installDevTools`); absent in
|
|
11
|
+
production builds.
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
window.__THREENATIVE__.snapshot()
|
|
15
|
+
// → { entities: [{ id, kind?, ...entity debug fields }], ... }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`snapshot()` prefers an entity's own `debug()` and falls back to `autoFields`. This is the
|
|
19
|
+
fastest "what does the game think exists" probe; playtest assertions and the dev overlay
|
|
20
|
+
read the same registry.
|
|
21
|
+
|
|
22
|
+
## `window.__THREENATIVE_PLAYTEST_BRIDGE__` — the harness channel
|
|
23
|
+
|
|
24
|
+
Installed by `playtest()` (core plugin) or `installThreePlaytestBridge`
|
|
25
|
+
(`@threenative/playtest/three`). One object, JSON-safe in and out:
|
|
26
|
+
|
|
27
|
+
| Member | Shape | Use |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| `describe()` | `{ name, protocolVersion, capabilities, limits }` | First call. Tells you what this game's bridge supports and the protocol limits. |
|
|
30
|
+
| `ready()` | `{ ready: true }` | Liveness check before sampling. |
|
|
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
|
+
| `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
|
+
| `applySetup(request)` | applies scenario `setup` placements/resources through the registry | What scenario setup uses; also usable by hand for one-off staging. |
|
|
34
|
+
| `drainEvents(limit)` | event-queue bridges only: returns up to `limit` queued events | Reads events shorter than one state flush. |
|
|
35
|
+
|
|
36
|
+
A console one-liner that works on any bridged game:
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
await window.__THREENATIVE_PLAYTEST_BRIDGE__.describe()
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Missing global means no bridge is installed — semantic assertions against that page fail
|
|
43
|
+
`TN_PLAYTEST_BRIDGE_MISSING`, which is the harness being right, not a bug to work around.
|
|
44
|
+
|
|
45
|
+
## `window.__THREENATIVE_NATIVE__` — native host channel
|
|
46
|
+
|
|
47
|
+
Present only under the native runtime. The host injects its side; core's viewport and
|
|
48
|
+
`@threenative/playtest/three`'s device reporting read it (adapter identity, host snapshot).
|
|
49
|
+
On web this global does not exist — do not probe for it in portable code.
|
|
50
|
+
|
|
51
|
+
## Runner-side markers
|
|
52
|
+
|
|
53
|
+
Two further globals are set by tooling, not the game, and are named here so a stray
|
|
54
|
+
assignment is recognisable: `__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__` (core's playtest
|
|
55
|
+
plugin marks the expected runner contract) and `__THREENATIVE_FRAMEBUFFER_COVERAGE_PROBE__`
|
|
56
|
+
(the framebufferCoverage assertion installs its sampler). Leave both alone in game code.
|
|
57
|
+
|
|
58
|
+
## What does not exist
|
|
59
|
+
|
|
60
|
+
There is no `__THREENATIVE_SCENE__` global. Scene-graph inspection goes through
|
|
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
|
|
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.
|