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,215 @@
|
|
|
1
|
+
# Finding assets — the full MCP tool loop
|
|
2
|
+
|
|
3
|
+
Companion to the short `Finding assets` section in this project's `AGENTS.md`. Reach for the
|
|
4
|
+
asset tools when the asset is conventional; build anything specific to this game yourself in
|
|
5
|
+
`src/render/`. A fetched asset has to match what the game needs, not merely exist.
|
|
6
|
+
|
|
7
|
+
Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
|
|
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 40; these 8
|
|
10
|
+
are the loop you will use for nearly everything:
|
|
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
|
+
|
|
19
|
+
1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
|
|
20
|
+
source with its license summary, attribution requirement, browse URL, and whether an agent
|
|
21
|
+
can complete a download from it. **That output is the authority on what is reachable** —
|
|
22
|
+
not your memory of some other project.
|
|
23
|
+
2. `polyhaven_search_assets` (CC0 models, textures, HDRIs), `ambientcg_search_assets` (CC0
|
|
24
|
+
materials and textures), or `audio_search_assets` (Kenney, Sonniss).
|
|
25
|
+
3. `polyhaven_list_files` / `ambientcg_list_files` — the license, official URL, byte size and
|
|
26
|
+
md5 of every resolution and format. **Read this before downloading, not after**, and pick a
|
|
27
|
+
sane one: Poly Haven lists 16k PNGs over 1 GB beside 8k JPEGs at 28 MB. A game does not
|
|
28
|
+
need the 16k.
|
|
29
|
+
4. `asset_download_file` for textures and models, `audio_download_asset` for audio. Both take
|
|
30
|
+
`acceptLicense: true` — you are asserting you read step 3. **They ignore any path you pass
|
|
31
|
+
and write to the directories `.mcp.json` sets** (`public/assets/<provider>/<sha>/` and
|
|
32
|
+
`public/audio/<source>/<pack>/`); without that config they would write to `~/Downloads` and
|
|
33
|
+
never reach the game.
|
|
34
|
+
5. Append the file, its source, its license and its URL to `CREDITS.md` **before the turn
|
|
35
|
+
ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
|
|
36
|
+
CC0 per asset page, and audio and bundle licenses are per pack.
|
|
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
|
+
|
|
49
|
+
**Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
|
|
50
|
+
`ambientcg_search_assets` did not tell you, you do not know it.
|
|
51
|
+
|
|
52
|
+
## What arrives is usually a ZIP, not a texture
|
|
53
|
+
|
|
54
|
+
ambientCG and Kenney ship archives: unpack one, keep only the maps you actually use (`_Color`,
|
|
55
|
+
`_NormalGL`, `_Roughness` — not the `.blend`, `.usdc` or displacement), and put those beside
|
|
56
|
+
your code under `public/`. A 1K JPEG set is right for a game; the 8K set of the same material
|
|
57
|
+
is 200 MB.
|
|
58
|
+
|
|
59
|
+
## Two argument shapes that bite
|
|
60
|
+
|
|
61
|
+
Both learned the hard way: `ambientcg_search_assets` takes lowercase `type` values (`material`,
|
|
62
|
+
`hdri`, `3d-model`), and the audio catalog is **pack-level** — `audio_search_assets` matches
|
|
63
|
+
pack names, so `query: "pickup coin"` returns nothing while `kind: "sfx"` returns the packs
|
|
64
|
+
that exist. Pick a pack, download it, unzip it, and choose a file yourself.
|
|
65
|
+
|
|
66
|
+
## Fab: searching, and importing an Unreal asset you own
|
|
67
|
+
|
|
68
|
+
Most Fab listings ship Unreal-only — 272 `.uasset` files and no `.glb` anywhere — so Fab is two
|
|
69
|
+
steps, not one: find the listing, then convert it.
|
|
70
|
+
|
|
71
|
+
**1. Search free first.** `fab_search_assets` talks to Fab's public API anonymously; no account is
|
|
72
|
+
involved. Its default `priceMode: "free"` is the right default and should stay your first query —
|
|
73
|
+
a free asset is one anybody who clones this project can fetch too.
|
|
74
|
+
|
|
75
|
+
```jsonc
|
|
76
|
+
// fab_search_assets
|
|
77
|
+
{
|
|
78
|
+
"query": "cave rocks",
|
|
79
|
+
"formats": ["unreal-engine"], // "gltf", "fbx", "obj", "unity" ... omit for every format
|
|
80
|
+
"priceMode": "any", // SEE BELOW — the default is "free"
|
|
81
|
+
"sort": "relevance", // or rating, newest, price_asc, recently_updated
|
|
82
|
+
"limit": 24
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Then look at what the account already owns.** A paid listing sitting in the library costs
|
|
87
|
+
nothing further to use, and it will never appear in a free search — `priceMode: "free"` returns a
|
|
88
|
+
different result set than `"any"` does. `fab_list_owned` answers that directly, without guessing
|
|
89
|
+
at search terms:
|
|
90
|
+
|
|
91
|
+
```jsonc
|
|
92
|
+
// fab_list_owned
|
|
93
|
+
{ "unrealOnly": true, "query": "vegetation" } // both optional; unrealOnly drops engine installs
|
|
94
|
+
// and plugins the importer cannot take
|
|
95
|
+
// -> [{ listingId, title, url, categories, engineVersions, hasUnrealArtifact }]
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Reach for `priceMode: "any"` in `fab_search_assets` only when you mean to look at paid listings
|
|
99
|
+
the account does *not* own yet — buying is not something these tools can do for you.
|
|
100
|
+
|
|
101
|
+
Each item carries a `title` and an `id` — that `id` is the listing UID the next two tools take.
|
|
102
|
+
`fab_list_filters` returns the usable `formats`, `categories` and `tags` slugs; guessing them
|
|
103
|
+
silently narrows the search instead of erroring.
|
|
104
|
+
|
|
105
|
+
**2. Check the licence.** Search results carry **no licence** — Fab's search endpoint omits it, so
|
|
106
|
+
every item comes back with an empty `licenses` array. `fab_get_asset` is where the slugs live:
|
|
107
|
+
|
|
108
|
+
```jsonc
|
|
109
|
+
{ "listingIdOrUrl": "75f42402-40bb-4a1b-b557-18e2c9604273" }
|
|
110
|
+
// -> licenses: [{ slug: "personal" }, { slug: "professional" }], freeLicenseSlugs: [...]
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
**3. Import.** `fab_import_asset` verifies the entitlement itself, downloads through the FabCLI
|
|
114
|
+
session, converts every static mesh, and writes source GLBs into your `assets/`:
|
|
115
|
+
|
|
116
|
+
```jsonc
|
|
117
|
+
// fab_import_asset
|
|
118
|
+
{
|
|
119
|
+
"listingIdOrUrl": "https://www.fab.com/listings/<uid>",
|
|
120
|
+
"outputDir": "assets/fab/soul-cave",
|
|
121
|
+
"packages": ["SM_S_Soul_Statue"], // omit to convert every static mesh — packs run to gigabytes
|
|
122
|
+
"maxTextureSize": 2048, // omit to keep Unreal's own resolution
|
|
123
|
+
"acceptFabEula": true
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Then load the returned path the ordinary way:
|
|
128
|
+
`ctx.assets.model("fab/soul-cave/.../SM_S_Soul_Statue.glb")`. The normal asset compiler picks the
|
|
129
|
+
GLBs up from `assets/` with no extra configuration.
|
|
130
|
+
|
|
131
|
+
What the import will and will not do:
|
|
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.
|
|
150
|
+
- **Only assets you already own**, and only under **Fab Standard (Personal or Professional) or
|
|
151
|
+
CC-BY**. Unreal-Engine-only and legacy entitlements are refused, and a licence it cannot read is
|
|
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.
|
|
156
|
+
Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
|
|
157
|
+
authenticated path it is guarding.
|
|
158
|
+
- **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
|
|
159
|
+
`THREENATIVE_TOOLCHAIN_AUTOINSTALL=0` to require you install them instead. Linux and Windows only.
|
|
160
|
+
- **`packages` is not optional in practice.** A marketplace pack converts to many gigabytes of
|
|
161
|
+
GLBs; name the handful of meshes your scene uses. Run it once without `packages` against a
|
|
162
|
+
scratch directory if you need to see what a pack contains, then re-run with the names.
|
|
163
|
+
- **Read `import-report.json` before trusting the result.** It reports `materials: "complete"` or
|
|
164
|
+
`"degraded"`, counts textured against total sections, and names every mesh it skipped and every
|
|
165
|
+
texture it could not map. Unreal shader graphs have no glTF equivalent, so some sections arrive
|
|
166
|
+
with a neutral grey and say so. `.umap` levels, Blueprints, Niagara and foliage placement are
|
|
167
|
+
reported as unsupported, never silently dropped.
|
|
168
|
+
- `asset_import_unreal` takes a local `sourceDir` instead of a listing, for a pack you already
|
|
169
|
+
downloaded by any means.
|
|
170
|
+
|
|
171
|
+
`fab_download_free_asset` is the unrelated older path: it downloads a directly-available free
|
|
172
|
+
`glb`/`fbx`/`obj`/`unity` file with no account at all. Use it when the listing already ships a
|
|
173
|
+
format you can load, and the importer only when it does not.
|
|
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
|
+
|
|
205
|
+
## The narrower tools
|
|
206
|
+
|
|
207
|
+
The directory spells out the conditions on each. The Fab tools are covered above; the server
|
|
208
|
+
never purchases anything on any path. `smithsonian_search_assets` returns museum scans at scan resolution, which this project has no
|
|
209
|
+
pipeline to decimate — that geometry is the wrong shape for a game. When in doubt check
|
|
210
|
+
`asset_search_sources` first; its `caution` and license fields are the current truth for the
|
|
211
|
+
pinned version, and they change between versions.
|
|
212
|
+
|
|
213
|
+
Load what you downloaded the ordinary way — `ctx.assets.model("crate.glb")`,
|
|
214
|
+
`ctx.assets.texture(...)`, `ctx.assets.audio(...)` — and write your own material and lighting
|
|
215
|
+
around it in `src/render/`. The framework ships no asset and picks none for you.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Gameplay recipes — movement, input, physics-step timing, and saves
|
|
2
|
+
|
|
3
|
+
Companion to the gameplay sections in this project's `AGENTS.md`.
|
|
4
|
+
|
|
5
|
+
## Forward is -z, and the mapping happens once
|
|
6
|
+
|
|
7
|
+
`input.vector("move").y` is +up; map it to world-space -z for forward with one explicit
|
|
8
|
+
`-move.y` conversion in the player movement code. One conversion site per entity — a second
|
|
9
|
+
one flips the controls.
|
|
10
|
+
|
|
11
|
+
## A gamepad already drives this game
|
|
12
|
+
|
|
13
|
+
`vector` adds the left stick to the action literally named `move`, and
|
|
14
|
+
`jump: { buttons: [0] }` in `src/game.ts` is that pad's south face button — `buttons` is the
|
|
15
|
+
gamepad, `mouseButtons` is the mouse. Two consequences worth knowing before you debug either:
|
|
16
|
+
the stick reaches **only** an action called `move`, so renaming that action or adding a second
|
|
17
|
+
stick-driven one (a `look` axis, say) gets you nothing, and there is no deadzone, so a worn
|
|
18
|
+
stick's resting drift is added every frame and the character creeps. Subtract your own deadzone
|
|
19
|
+
in the entity if that shows up.
|
|
20
|
+
|
|
21
|
+
## moveAndSlide queues motion for the shared physics step
|
|
22
|
+
|
|
23
|
+
`CharacterBody3D.moveAndSlide(dt)` owns gravity through `body.velocity` and queues motion for
|
|
24
|
+
the shared bulk physics step rather than moving its object immediately. Because
|
|
25
|
+
`THREE.Vector3` is mutable, use `const before = mesh.position.clone()` (or copy its `x`, `y`,
|
|
26
|
+
and `z` scalars) before the call, then compare `mesh.position.distanceTo(before)` on the next
|
|
27
|
+
update, after the step. Storing `mesh.position` itself aliases the live transform and reports
|
|
28
|
+
zero. Keep coyote-time and jump-buffer timers in the entity so jump feel stays game-owned.
|
|
29
|
+
|
|
30
|
+
## Save only declared state
|
|
31
|
+
|
|
32
|
+
The framework does not serialize entities, scene graphs, or physics handles, and it never
|
|
33
|
+
will; save those fields in your own object literal:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
const save = JSON.stringify({ state: ctx.state.getState(), playerX: player.mesh.position.x });
|
|
37
|
+
const loaded = JSON.parse(save) as { state: GameState; playerX: number };
|
|
38
|
+
ctx.state.set(loaded.state);
|
|
39
|
+
player.body.teleport({ x: loaded.playerX, y: player.mesh.position.y, z: player.mesh.position.z });
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Hot reload carries JSON-shaped state only
|
|
43
|
+
|
|
44
|
+
`main.ts` calls `acceptHotUpdate(game, import.meta.hot)` for development reloads. The
|
|
45
|
+
framework preserves only store state; seed entities from the carried values such as
|
|
46
|
+
`playerX` in `enter()`, because the scene graph, physics world, audio voices, particles, and
|
|
47
|
+
renderer are rebuilt on every update.
|
|
48
|
+
|
|
49
|
+
## The state bridge throttles
|
|
50
|
+
|
|
51
|
+
The bridge flushes every 100 ms by default: write `ctx.state.set({...})` from `update()` at
|
|
52
|
+
loop rate — it coalesces — and read it from HUD components at ~10 Hz. Per-frame visual
|
|
53
|
+
feedback belongs in scene-owned Three.js objects. If an event must appear in the HUD, give
|
|
54
|
+
it a decay longer than one flush interval.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Menu screens: scenes are the screens
|
|
2
|
+
|
|
3
|
+
Use a scene for every screen that needs a world, camera, lighting, or ordinary Three.js art. Put
|
|
4
|
+
the chrome in `src/ui/` so the same React tree runs beside the web canvas and in the native web
|
|
5
|
+
view.
|
|
6
|
+
|
|
7
|
+
## The flow
|
|
8
|
+
|
|
9
|
+
1. Give the menu scene a static `initialState` with `screen: "menu"` and all fields the game
|
|
10
|
+
state needs.
|
|
11
|
+
2. Render a form in a UI component with `useUiState` and `useUiIntent`. Mark every input and
|
|
12
|
+
button with `data-tn-interactive`.
|
|
13
|
+
3. Validate the intent payload in `src/game.ts`. The game owns the transition:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
if (intent === "start-game" && name.length > 0) {
|
|
17
|
+
void game.goto("play", { carry: { characterName: name } });
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`game.goto()` resets to the destination scene's `initialState`, then merges the serializable
|
|
22
|
+
`carry` patch. `ctx.goto()` rebuilds without resetting state; use it only when the current run
|
|
23
|
+
should survive the rebuild.
|
|
24
|
+
|
|
25
|
+
4. Give the played scene its own initial state with `screen: "playing"`. The carried values are
|
|
26
|
+
available in `enter()` through `ctx.state.getState()` and are also visible to the UI and
|
|
27
|
+
playtest bridge.
|
|
28
|
+
5. Switch the chrome from the published `screen` value. The menu component returns `null` outside
|
|
29
|
+
the menu, and the HUD/menu bar return `null` outside play.
|
|
30
|
+
|
|
31
|
+
## Add a settings screen
|
|
32
|
+
|
|
33
|
+
To insert settings between the menu and play screens, extend the state union with `"settings"`,
|
|
34
|
+
add a `Settings` scene whose `initialState.screen` is `"settings"`, and add a `SettingsUi` form
|
|
35
|
+
that follows the same `useUiState`/`useUiIntent` pattern. Register the scene, render the form
|
|
36
|
+
when `screen === "settings"`, and keep navigation in `src/game.ts`:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
if (intent === "open-settings") void game.goto("settings");
|
|
40
|
+
if (intent === "start-game") {
|
|
41
|
+
void game.goto("play", { carry: { characterName: name, difficulty } });
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The menu's settings button and the settings form's start button both carry
|
|
46
|
+
`data-tn-interactive`. Prove the complete flow with viewport-pixel clicks and assert the carried
|
|
47
|
+
settings resource after the final scene transition.
|
|
48
|
+
|
|
49
|
+
## Prove it with a click scenario
|
|
50
|
+
|
|
51
|
+
`click` uses viewport pixels and emits a real pointer-down/up pair on the web target:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{ "kind": "click", "at": { "x": 640, "y": 365 }, "label": "name-field" }
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Click the form field, use ordinary `input` steps for the text, click submit, then assert the
|
|
58
|
+
carried value through `resources`:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{ "equals": "axo", "id": "state", "path": "characterName" }
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The bridge samples the state after the transition settles. A missing bridge or an unobserved
|
|
65
|
+
entity click target is a named failure, never a skipped step.
|
|
66
|
+
|
|
67
|
+
The native renderer draws quads and has no text input today. Form screens therefore use the shared
|
|
68
|
+
webview UI; `ui: { renderer: "native" }` is appropriate only when the screen does not need text
|
|
69
|
+
entry.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# What memory a phone actually gives you
|
|
2
|
+
|
|
3
|
+
Everything here was measured on a **physical Pixel 8** (Mali-G715, Vulkan, 2400x1080 surface) on
|
|
4
|
+
2026-08-23, running a real game through this framework. No estimates, no emulator.
|
|
5
|
+
|
|
6
|
+
## The headline
|
|
7
|
+
|
|
8
|
+
The game asked the GPU for 393 MiB of textures and buffers. Here is what that turned into:
|
|
9
|
+
|
|
10
|
+
| | |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| What the game asked `createTexture`/`createBuffer` for | 393 MiB |
|
|
13
|
+
| What the driver held (`dumpsys meminfo`: `GL mtrack` + `EGL mtrack`) | ~899 MiB |
|
|
14
|
+
| Process `VmRSS` | ~1.4 GiB |
|
|
15
|
+
|
|
16
|
+
That looks like the driver doubling everything you allocate. **It is not.** About **480 MiB was
|
|
17
|
+
already held at the first presented frame**, before the game had uploaded a single texture, and
|
|
18
|
+
across the entire asset load the driver then grew by *less* than the game requested.
|
|
19
|
+
|
|
20
|
+
So budget like this:
|
|
21
|
+
|
|
22
|
+
> **a ~500 MiB fixed floor, plus roughly the bytes you ask for.**
|
|
23
|
+
|
|
24
|
+
Not as a multiplier on your own textures. The practical consequence is that shaving 50 MiB off
|
|
25
|
+
your textures really does save about 50 MiB — but you start 500 MiB in the hole, and a phone
|
|
26
|
+
begins killing apps well under 2 GiB.
|
|
27
|
+
|
|
28
|
+
## Your sky is charged twice, and the second charge is the expensive one
|
|
29
|
+
|
|
30
|
+
Assigning one equirect to both `scene.background` and `scene.environment` looks free. It is not.
|
|
31
|
+
`scene.environment` builds an image-based light, and three.js sizes that light's render targets
|
|
32
|
+
from the **source equirect's width** — `cubeSize = width / 4`, rounded *down* to a power of two,
|
|
33
|
+
then two render targets of `3 x max(cubeSize, 112)` by `4 x cubeSize` in `rgba16float`.
|
|
34
|
+
|
|
35
|
+
Measured, on a real WebGPU adapter:
|
|
36
|
+
|
|
37
|
+
| equirect width | PMREM pair allocated | cost |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| 3072 | 1536x2048 rgba16float x2 | **48 MiB** |
|
|
40
|
+
| 2048 | 1536x2048 rgba16float x2 | **48 MiB** |
|
|
41
|
+
| 1024 | 768x1024 rgba16float x2 | **12 MiB** |
|
|
42
|
+
| 512 | 384x512 rgba16float x2 | **3 MiB** |
|
|
43
|
+
|
|
44
|
+
Two things fall out of that table.
|
|
45
|
+
|
|
46
|
+
**Halving a 3072 sky to 2048 saves nothing.** The cost moves in power-of-two steps, so only
|
|
47
|
+
crossing a step changes anything. Resizing an asset "a bit smaller" is wasted work.
|
|
48
|
+
|
|
49
|
+
**Split the two uses.** The background is what the player looks at and wants every pixel it has.
|
|
50
|
+
The light does not: PMREM immediately convolves its source into roughness mips, so everything it
|
|
51
|
+
contributes is low-frequency, and the only detail that survives is a mirror reflection. Give the
|
|
52
|
+
environment its own smaller copy of the same image:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// One 3072-wide photograph, downsampled once to 1024 for the light.
|
|
56
|
+
scene.background = skyEquirect; // full resolution — this is the visible sky
|
|
57
|
+
scene.environment = skyEquirectSmall; // 1024x512 copy — this is only ever blurred
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
That is 36 MiB back for a 2.7 MiB texture, with nothing visible changing. Pick 1024 over 512 if
|
|
61
|
+
your scene has polished metal or still water in it, since 512 halves the mirror again.
|
|
62
|
+
|
|
63
|
+
**Do this before you reach for texture compression.** It is one line, it costs nothing at
|
|
64
|
+
runtime, and it is larger than most compression wins on a small texture set.
|
|
65
|
+
|
|
66
|
+
## Where the rest of your budget goes
|
|
67
|
+
|
|
68
|
+
Ordinary things that are bigger than people expect, all from the same measured run:
|
|
69
|
+
|
|
70
|
+
- **Full-screen render targets scale with your device's real resolution, not your design
|
|
71
|
+
resolution.** At 2400x1080 a single `rgba16float` colour target is 19 MiB and a `depth24plus`
|
|
72
|
+
is 9.5 MiB. Post-processing chains multiply that by how many you keep alive.
|
|
73
|
+
- **Mip chains add a third.** A 2048x2048 `rgba8unorm-srgb` with a full mip pyramid is 21 MiB,
|
|
74
|
+
not 16 MiB. Eight 1024x1024 maps with mips are 42 MiB between them.
|
|
75
|
+
- **Buffers are almost never the problem.** In that run, 3038 buffers came to 14 MiB total —
|
|
76
|
+
under 4 % of the footprint. Do not spend your optimisation budget there.
|
|
77
|
+
- **A cubemap conversion is not free.** Setting `scene.background` to an equirect makes the
|
|
78
|
+
renderer build a cubemap from it; at 3072x1536 that cubemap was 54 MiB on its own, separate
|
|
79
|
+
from the 23 MiB source texture and separate again from the image-based light.
|
|
80
|
+
|
|
81
|
+
## How to check your own game
|
|
82
|
+
|
|
83
|
+
On native, the runtime prints its own accounting beside the present tick — watch `logcat` for
|
|
84
|
+
`TN_GPU_TEXTURES` and `TN_GPU_BUFFERS`, which bucket every texture by dimensions, format and mip
|
|
85
|
+
count so you can see which allocation is the big one rather than guessing. Read those numbers as
|
|
86
|
+
*what the game requested*; the driver's own total is a separate figure, and the floor above is why
|
|
87
|
+
the two never match.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Building what you cannot download — sculpt from a reference
|
|
2
|
+
|
|
3
|
+
Companion to the short `Building what you cannot download` section in this project's
|
|
4
|
+
`AGENTS.md`.
|
|
5
|
+
|
|
6
|
+
## Choose one branch before writing code
|
|
7
|
+
|
|
8
|
+
- **Conventional and downloadable** — a crate, an oak plank texture, a click. Use the asset
|
|
9
|
+
tools. Sculpting one of these is slower and worse.
|
|
10
|
+
- **Trivial** — a platform, a wall, a pickup ring. Write it. If `BoxGeometry` finishes the
|
|
11
|
+
job in under 20 lines, that is the answer.
|
|
12
|
+
- **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
|
|
13
|
+
landmark, scenery composition, or environment set piece whose silhouette must match. Use
|
|
14
|
+
the sculpt tools to turn that reference into editable `src/render/` source.
|
|
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.
|
|
18
|
+
|
|
19
|
+
For a full environment, split the decision: sculpt the signature landmark or bounded scene
|
|
20
|
+
kit that makes the reference recognisable; use the asset tools for interchangeable trees,
|
|
21
|
+
rocks, textures, HDRIs, and sounds around it. Do not sculpt an entire world as one object.
|
|
22
|
+
|
|
23
|
+
## The gate loop
|
|
24
|
+
|
|
25
|
+
`.mcp.json` launches `threenative-sculpt-mcp` beside the asset server. It does not generate
|
|
26
|
+
or ship runtime code; it guides the source you write:
|
|
27
|
+
|
|
28
|
+
1. Call `sculpt_plan` with the image path and a one-line intent, then read the returned
|
|
29
|
+
grimoire resources.
|
|
30
|
+
2. Write the returned object contract and loop on `sculpt_spec_gate` until every named
|
|
31
|
+
region and depth requirement passes. Do not write geometry before this gate is green.
|
|
32
|
+
3. For each ordered pass, write or extend one factory in `src/render/`. Capture the real
|
|
33
|
+
frame with `npx @threenative/playtest`; the sculpt server never launches a browser.
|
|
34
|
+
4. Call `sculpt_compare` with the reference and captured frame, then give that evidence to
|
|
35
|
+
`sculpt_pass_gate`. Advance only when it says advance; ambiguity means retry.
|
|
36
|
+
5. Use `sculpt_grimoire` for a named technique topic. It rejects pages containing concrete
|
|
37
|
+
paste-ready material or shader recipes so the tool never owns this game's look.
|
|
38
|
+
|
|
39
|
+
A missing or blank capture is a failed run, never a finished model. Add the reference image,
|
|
40
|
+
its creator, license, and source URL to `CREDITS.md` before the turn ends.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Trace a slow frame — finding the function, not the percentile
|
|
2
|
+
|
|
3
|
+
`TN_FRAME_BUDGET` and `npx @threenative/playtest perf` tell you a frame was slow. They cannot tell
|
|
4
|
+
you what ran inside it. **A percentile says a frame was slow; a trace says which function.** This
|
|
5
|
+
page is the second half.
|
|
6
|
+
|
|
7
|
+
## The rule
|
|
8
|
+
|
|
9
|
+
**Before you attribute a frame-rate or stutter complaint to any cause — and before you change one
|
|
10
|
+
line to fix one — run `npx @threenative/playtest trace --url <url> --text` and name the function
|
|
11
|
+
the trace blames.** Not "when performance looks bad": every time, before the first fix. If you
|
|
12
|
+
skipped it, you are guessing, and the report below is what guessing costs.
|
|
13
|
+
|
|
14
|
+
## Why the rule exists
|
|
15
|
+
|
|
16
|
+
A game came in as "performance is not good, and after a while everything becomes blurry". Two
|
|
17
|
+
hypotheses were formed from the frame meters and both were wrong. One trace overturned them:
|
|
18
|
+
|
|
19
|
+
- **96 frames per second on average, frame-interval p50 8.2 ms.** The game was never slow on
|
|
20
|
+
average. Every statistic that reports a mean was hiding the complaint.
|
|
21
|
+
- **p99 50.3 ms, worst frame 267.9 ms, 28 main-thread tasks over 40 ms.** The pain was entirely in
|
|
22
|
+
the tail. Optimising the median would have moved nothing a player could feel.
|
|
23
|
+
- **GPU 31.5% busy, main thread 46.9% idle.** Neither triangle-bound nor CPU-saturated. An hour of
|
|
24
|
+
draw-call and triangle reduction was already underway and would have changed nothing.
|
|
25
|
+
- **Sampling inside the worst tasks named them**: TSL graph `build`, `analyze`, `_getChildren`,
|
|
26
|
+
plus two stalls at 86% and 97% *idle* where the main thread sat waiting on GPU pipeline
|
|
27
|
+
creation. That is shader compilation arriving during play — a completely different bug from any
|
|
28
|
+
of the three the numbers above had been read as.
|
|
29
|
+
|
|
30
|
+
## Running it
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
npx @threenative/playtest trace --url http://127.0.0.1:5173 --text
|
|
34
|
+
npx @threenative/playtest trace --url http://127.0.0.1:5173 --seconds 45 --key KeyW --key KeyD
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
It launches the game headed with the WebGPU recipe, waits for the engine's startup-ready signal,
|
|
38
|
+
records for `--seconds` while holding the movement keys, writes the raw trace to disk, and prints
|
|
39
|
+
the summary. Defaults worth knowing:
|
|
40
|
+
|
|
41
|
+
| Flag | Default | Why it is there |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `--seconds <n>` | 20 | The traced window. Tail statistics need frames; under about 10 s a p99 is one sample. |
|
|
44
|
+
| `--key <KeyName>` | `KeyW` | Held for the whole window. Repeat for more keys. |
|
|
45
|
+
| `--no-input` | off | Traces a standing camera and warns. A parked viewpoint re-uses everything it drew last frame, which is how the first frame-rate number in this project came back nearly twice the truth. |
|
|
46
|
+
| `--wait-for <js>` | `globalThis.__TN_STARTUP_READY__ === true` | Trace the game, not the load. Point it at your own global if your game reveals its world later; `--no-wait` traces the load too and says so. |
|
|
47
|
+
| `--stall-ms <n>` | 40 | What counts as a blown frame in the task count. |
|
|
48
|
+
| `--out <path>` | `artifacts/traces/trace-<timestamp>.json` | Open this in Chrome DevTools' Performance panel when the summary points somewhere specific. |
|
|
49
|
+
|
|
50
|
+
Exit codes: **0** traced and quotable, **1** traced but part of the answer is missing or
|
|
51
|
+
untrustworthy (the reason is printed with a `TN_TRACE_` code), **2** no trace was recorded at all.
|
|
52
|
+
|
|
53
|
+
## Reading the summary
|
|
54
|
+
|
|
55
|
+
Read it in this order, because each line rules out a whole class of fix:
|
|
56
|
+
|
|
57
|
+
1. **Frame interval p50 / p90 / p99 / max.** If p50 is fine and p99 is not, the problem is hitches,
|
|
58
|
+
not throughput — and nothing that lowers average cost will fix it.
|
|
59
|
+
2. **GPU busy %.** Low means the GPU is not the wall, so fewer triangles, fewer draws and cheaper
|
|
60
|
+
materials are all the wrong lane.
|
|
61
|
+
3. **Main thread idle %.** High *and* a low GPU busy means the frame is waiting on something —
|
|
62
|
+
pipeline creation, a texture upload, a network read — not computing.
|
|
63
|
+
4. **Tasks over the threshold.** The count and the worst few. This is the complaint, quantified.
|
|
64
|
+
5. **Top self time.** The functions. This is the answer; everything above it narrows which answer
|
|
65
|
+
is plausible.
|
|
66
|
+
|
|
67
|
+
Only then open the raw trace file, and only if the summary points somewhere specific.
|
|
68
|
+
|
|
69
|
+
## The trap that produces a confident wrong number
|
|
70
|
+
|
|
71
|
+
**A frame rate measured on a virtual display is wrong, not missing.** Under a private Xvfb there
|
|
72
|
+
is no vsync and no compositor, so the present wait lands inside the engine's `update` phase.
|
|
73
|
+
Measured on one build, same 12 s window, only `DISPLAY` differing:
|
|
74
|
+
|
|
75
|
+
| | Xvfb | real display |
|
|
76
|
+
| --- | ---: | ---: |
|
|
77
|
+
| fps | 13.3 | 57.7 |
|
|
78
|
+
| frame p50 | 68.5 ms | 8.5 ms |
|
|
79
|
+
| `update` p50 | **66.1 ms** | 1.0 ms |
|
|
80
|
+
| `render` p50 | 2.0 ms | 7.3 ms |
|
|
81
|
+
|
|
82
|
+
Read as a report, that is 66 ms of game CPU per frame, and it sends you looking for an expensive
|
|
83
|
+
loop in a frame callback. There is not one: a CPU profile over the same window came back **84%
|
|
84
|
+
idle**.
|
|
85
|
+
|
|
86
|
+
So `trace` refuses to print a frame rate when it detects a virtual display, and exits 1 saying so.
|
|
87
|
+
Set `TN_PLAYTEST_HOST_DISPLAY=1` to run on the real display and get a quotable one; pass
|
|
88
|
+
`--allow-virtual-display` to accept the function attribution alone and exit 0. The frame rate stays
|
|
89
|
+
suppressed either way — acknowledging the trap does not give the display a vsync.
|
|
90
|
+
|
|
91
|
+
The same command also refuses when WebGPU came from SwiftShader, Chromium's CPU rasteriser
|
|
92
|
+
(`TN_TRACE_SOFTWARE_ADAPTER`): a trace of software rendering names software rendering's functions.
|
|
93
|
+
`agent-docs/capture-the-frame.md` covers that adapter trap in full.
|
|
94
|
+
|
|
95
|
+
## After the trace
|
|
96
|
+
|
|
97
|
+
Say what the trace blamed, in the report, with the number beside it. "Tail, not throughput: p50
|
|
98
|
+
8.2 ms, p99 50.3 ms, 28 tasks over 40 ms; top self time is pipeline creation inside `build`" is a
|
|
99
|
+
finding. "Performance is better now" is not, and neither is a fix whose evidence is a mean.
|