create-threenative 0.2.3 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -2
- package/agent-docs/references/assertion-reference.md +173 -6
- package/agent-docs/references/capability-reference.md +1303 -99
- package/agent-docs/references/capture-the-frame.md +7 -0
- package/agent-docs/references/creating-creatures.md +215 -0
- package/agent-docs/references/ctx-cookbook.md +69 -0
- package/agent-docs/references/debug-surface.md +8 -3
- package/agent-docs/references/dream-loop.md +150 -0
- package/agent-docs/references/finding-assets.md +70 -2
- package/agent-docs/references/sculpt-from-a-reference.md +3 -2
- package/agent-docs/references/trace-a-slow-frame.md +99 -0
- package/agent-docs/references/visual-baseline.md +41 -0
- package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
- package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
- package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
- package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
- package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
- package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
- package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
- package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
- package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
- package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
- package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
- package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
- package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
- package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
- package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
- package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
- package/agent-files/scripts/reference.mjs +705 -0
- package/agent-files/scripts/visual-loop.mjs +382 -0
- package/capabilities.json +1881 -131
- package/dist/index.d.ts +39 -6
- package/dist/index.js +297 -32
- package/dist/threenative.js +822 -105
- package/package.json +30 -5
- package/template-assets/loading.ts +12 -2
- package/template-assets/patches/three@0.185.1.patch +249 -14
- package/template-assets/worldEnvironment.ts +758 -0
- package/templates/action-rpg/.codex/config.toml +4 -0
- package/templates/action-rpg/.cursor/mcp.json +32 -0
- package/templates/action-rpg/.gemini/settings.json +32 -0
- package/templates/action-rpg/.mcp.json +15 -3
- package/templates/action-rpg/.vscode/mcp.json +36 -0
- package/templates/action-rpg/.zed/settings.json +36 -0
- package/templates/action-rpg/AGENTS.md +69 -378
- package/templates/action-rpg/CLAUDE.md +69 -378
- package/templates/action-rpg/opencode.json +41 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/combat.playtest.json +9 -0
- package/templates/action-rpg/playtests/performance.playtest.json +24 -7
- package/templates/action-rpg/playtests/survives.playtest.json +27 -0
- package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
- package/templates/action-rpg/src/conventions.ts +35 -0
- package/templates/action-rpg/src/entities/Enemy.ts +2 -3
- package/templates/action-rpg/src/entities/Player.ts +20 -3
- package/templates/action-rpg/src/render/camera.ts +7 -2
- package/templates/action-rpg/src/render/lighting.ts +5 -3
- package/templates/action-rpg/src/render/loading.ts +12 -2
- package/templates/action-rpg/src/render/materials.ts +11 -0
- package/templates/action-rpg/src/render/palette.ts +10 -3
- package/templates/action-rpg/src/render/postprocessing.ts +21 -58
- package/templates/action-rpg/src/render/quality.ts +170 -0
- package/templates/action-rpg/src/render/shapes.ts +185 -26
- package/templates/action-rpg/src/render/touch-controls.ts +185 -0
- package/templates/action-rpg/src/render/vfx.ts +257 -0
- package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
- package/templates/action-rpg/src/scenes/Play.ts +43 -6
- package/templates/action-rpg/src/style.css +20 -0
- package/templates/action-rpg/threenative.config.ts +7 -0
- package/templates/defense/.codex/config.toml +4 -0
- package/templates/defense/.cursor/mcp.json +32 -0
- package/templates/defense/.gemini/settings.json +32 -0
- package/templates/defense/.mcp.json +15 -3
- package/templates/defense/.vscode/mcp.json +36 -0
- package/templates/defense/.zed/settings.json +36 -0
- package/templates/defense/AGENTS.md +62 -385
- package/templates/defense/CLAUDE.md +62 -385
- package/templates/defense/opencode.json +41 -0
- package/templates/defense/package.json +7 -7
- package/templates/defense/playtests/performance.playtest.json +24 -7
- package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
- package/templates/defense/playtests/scan.playtest.json +1 -1
- package/templates/defense/playtests/survive.playtest.json +14 -0
- package/templates/defense/src/attackers/Attacker.ts +4 -4
- package/templates/defense/src/board/Route.ts +22 -8
- package/templates/defense/src/conventions.ts +18 -0
- package/templates/defense/src/entities/Player.ts +11 -3
- package/templates/defense/src/game.ts +2 -3
- package/templates/defense/src/physics.ts +9 -39
- package/templates/defense/src/placement/Buildable.ts +4 -4
- package/templates/defense/src/render/camera.ts +9 -3
- package/templates/defense/src/render/loading.ts +12 -2
- package/templates/defense/src/render/materials.ts +9 -0
- package/templates/defense/src/render/palette.ts +12 -5
- package/templates/defense/src/render/postprocessing.ts +21 -58
- package/templates/defense/src/render/quality.ts +170 -0
- package/templates/defense/src/render/shapes.ts +142 -23
- package/templates/defense/src/render/sky.ts +2 -2
- package/templates/defense/src/render/worldEnvironment.ts +208 -33
- package/templates/defense/src/scenes/Boot.ts +2 -2
- package/templates/defense/src/scenes/Defense.ts +13 -6
- package/templates/defense/src/style.css +20 -0
- package/templates/defense/src/towers/Tower.ts +11 -12
- package/templates/defense/src/towers/targeting.ts +1 -1
- package/templates/defense/src/ui/App.tsx +2 -2
- package/templates/defense/threenative.config.ts +7 -0
- package/templates/minimal/.codex/config.toml +4 -0
- package/templates/minimal/.cursor/mcp.json +32 -0
- package/templates/minimal/.gemini/settings.json +32 -0
- package/templates/minimal/.mcp.json +15 -3
- package/templates/minimal/.vscode/mcp.json +36 -0
- package/templates/minimal/.zed/settings.json +36 -0
- package/templates/minimal/AGENTS.md +76 -485
- package/templates/minimal/CLAUDE.md +76 -485
- package/templates/minimal/opencode.json +41 -0
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/playtests/play.playtest.json +2 -1
- package/templates/minimal/playtests/survives.playtest.json +48 -4
- package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
- package/templates/minimal/src/conventions.ts +18 -0
- package/templates/minimal/src/entities/Player.ts +39 -6
- package/templates/minimal/src/main.ts +14 -4
- package/templates/minimal/src/render/materials.ts +7 -0
- package/templates/minimal/src/render/palette.ts +3 -3
- package/templates/minimal/src/render/postprocessing.ts +17 -56
- package/templates/minimal/src/render/quality.ts +162 -0
- package/templates/minimal/src/render/sky.ts +23 -9
- package/templates/minimal/src/render/touch-controls.ts +165 -0
- package/templates/minimal/src/render/worldEnvironment.ts +208 -33
- package/templates/minimal/src/scenes/Play.ts +47 -11
- package/templates/minimal/src/style.css +20 -0
- package/templates/minimal/threenative.config.ts +7 -0
- package/templates/platformer/.codex/config.toml +4 -0
- package/templates/platformer/.cursor/mcp.json +32 -0
- package/templates/platformer/.gemini/settings.json +32 -0
- package/templates/platformer/.mcp.json +15 -3
- package/templates/platformer/.vscode/mcp.json +36 -0
- package/templates/platformer/.zed/settings.json +36 -0
- package/templates/platformer/AGENTS.md +70 -430
- package/templates/platformer/CLAUDE.md +70 -430
- package/templates/platformer/opencode.json +41 -0
- package/templates/platformer/package.json +7 -7
- package/templates/platformer/playtests/oneway.playtest.json +29 -2
- package/templates/platformer/playtests/performance.playtest.json +2 -1
- package/templates/platformer/playtests/survives.playtest.json +31 -0
- package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
- package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
- package/templates/platformer/src/conventions.ts +18 -0
- package/templates/platformer/src/entities/Character.ts +63 -1
- package/templates/platformer/src/game.ts +3 -1
- package/templates/platformer/src/level/Platform.ts +13 -1
- package/templates/platformer/src/render/lighting.ts +7 -4
- package/templates/platformer/src/render/loading.ts +12 -2
- package/templates/platformer/src/render/palette.ts +4 -1
- package/templates/platformer/src/render/postprocessing.ts +32 -57
- package/templates/platformer/src/render/quality.ts +170 -0
- package/templates/platformer/src/render/worldEnvironment.ts +208 -33
- package/templates/platformer/src/scenes/Level.ts +52 -12
- package/templates/platformer/src/style.css +20 -0
- package/templates/platformer/threenative.config.ts +7 -0
- package/templates/puzzle/.codex/config.toml +19 -0
- package/templates/puzzle/.cursor/mcp.json +32 -0
- package/templates/puzzle/.gemini/settings.json +32 -0
- package/templates/puzzle/.mcp.json +32 -0
- package/templates/puzzle/.vscode/mcp.json +36 -0
- package/templates/puzzle/.zed/settings.json +36 -0
- package/templates/puzzle/AGENTS.md +96 -0
- package/templates/puzzle/CLAUDE.md +98 -0
- package/templates/puzzle/README.md +43 -0
- package/templates/puzzle/index.html +12 -0
- package/templates/puzzle/kit.json +7 -0
- package/templates/puzzle/opencode.json +41 -0
- package/templates/puzzle/package.json +50 -0
- package/templates/puzzle/playtests/carry.playtest.json +71 -0
- package/templates/puzzle/playtests/performance.playtest.json +23 -0
- package/templates/puzzle/playtests/survives.playtest.json +51 -0
- package/templates/puzzle/playtests/swing.playtest.json +38 -0
- package/templates/puzzle/public/favicon.svg +5 -0
- package/templates/puzzle/src/conventions.ts +25 -0
- package/templates/puzzle/src/entities/Ball.ts +70 -0
- package/templates/puzzle/src/entities/Crate.ts +76 -0
- package/templates/puzzle/src/entities/Gripper.ts +69 -0
- package/templates/puzzle/src/entities/Pendulum.ts +89 -0
- package/templates/puzzle/src/game.ts +48 -0
- package/templates/puzzle/src/main.ts +15 -0
- package/templates/puzzle/src/physics.ts +19 -0
- package/templates/puzzle/src/render/camera.ts +37 -0
- package/templates/puzzle/src/render/lighting.ts +55 -0
- package/templates/puzzle/src/render/loading.ts +325 -0
- package/templates/puzzle/src/render/materials.ts +28 -0
- package/templates/puzzle/src/render/palette.ts +31 -0
- package/templates/puzzle/src/render/postprocessing.ts +34 -0
- package/templates/puzzle/src/render/quality.ts +170 -0
- package/templates/puzzle/src/render/shapes.ts +134 -0
- package/templates/puzzle/src/render/sky.ts +16 -0
- package/templates/puzzle/src/render/touch-controls.ts +185 -0
- package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
- package/templates/puzzle/src/room.ts +83 -0
- package/templates/puzzle/src/scenes/Boot.ts +12 -0
- package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
- package/templates/puzzle/src/state.ts +30 -0
- package/templates/puzzle/src/style.css +96 -0
- package/templates/puzzle/src/ui/App.tsx +22 -0
- package/templates/puzzle/src/ui/GameUi.tsx +20 -0
- package/templates/puzzle/src/ui/Hud.tsx +57 -0
- package/templates/puzzle/src/ui/Menu.tsx +7 -0
- package/templates/puzzle/src/ui/main.tsx +14 -0
- package/templates/puzzle/tailwind.config.ts +1 -0
- package/templates/puzzle/threenative.config.ts +49 -0
- package/templates/puzzle/tsconfig.json +17 -0
- package/templates/puzzle/vite.config.ts +38 -0
- package/templates/racing/.codex/config.toml +4 -0
- package/templates/racing/.cursor/mcp.json +32 -0
- package/templates/racing/.gemini/settings.json +32 -0
- package/templates/racing/.mcp.json +15 -3
- package/templates/racing/.vscode/mcp.json +36 -0
- package/templates/racing/.zed/settings.json +36 -0
- package/templates/racing/AGENTS.md +63 -379
- package/templates/racing/CLAUDE.md +63 -379
- package/templates/racing/native-playtests/survives.playtest.json +43 -0
- package/templates/racing/opencode.json +41 -0
- package/templates/racing/package.json +8 -7
- package/templates/racing/playtests/performance.playtest.json +24 -7
- package/templates/racing/playtests/survives.playtest.json +36 -4
- package/templates/racing/playtests/touch-controls.playtest.json +41 -0
- package/templates/racing/src/conventions.ts +6 -0
- package/templates/racing/src/entities/RacingCar.ts +16 -4
- package/templates/racing/src/entities/Rival.ts +5 -2
- package/templates/racing/src/render/camera.ts +7 -4
- package/templates/racing/src/render/lighting.ts +22 -13
- package/templates/racing/src/render/loading.ts +12 -2
- package/templates/racing/src/render/materials.ts +54 -4
- package/templates/racing/src/render/palette.ts +23 -6
- package/templates/racing/src/render/postprocessing.ts +21 -58
- package/templates/racing/src/render/quality.ts +170 -0
- package/templates/racing/src/render/shapes.ts +537 -26
- package/templates/racing/src/render/sky.ts +5 -2
- package/templates/racing/src/render/touch-controls.ts +185 -0
- package/templates/racing/src/render/worldEnvironment.ts +208 -33
- package/templates/racing/src/scenes/Race.ts +17 -2
- package/templates/racing/src/style.css +20 -0
- package/templates/racing/src/track/Track.ts +270 -31
- package/templates/racing/threenative.config.ts +7 -0
- package/templates/runner/.codex/config.toml +19 -0
- package/templates/runner/.cursor/mcp.json +32 -0
- package/templates/runner/.gemini/settings.json +32 -0
- package/templates/runner/.mcp.json +32 -0
- package/templates/runner/.vscode/mcp.json +36 -0
- package/templates/runner/.zed/settings.json +36 -0
- package/templates/runner/AGENTS.md +96 -0
- package/templates/runner/CLAUDE.md +98 -0
- package/templates/runner/README.md +43 -0
- package/templates/runner/index.html +12 -0
- package/templates/runner/kit.json +7 -0
- package/templates/runner/opencode.json +41 -0
- package/templates/runner/package.json +50 -0
- package/templates/runner/playtests/performance.playtest.json +23 -0
- package/templates/runner/playtests/streams.playtest.json +38 -0
- package/templates/runner/playtests/survives.playtest.json +51 -0
- package/templates/runner/public/favicon.svg +5 -0
- package/templates/runner/src/conventions.ts +24 -0
- package/templates/runner/src/entities/Runner.ts +135 -0
- package/templates/runner/src/game.ts +50 -0
- package/templates/runner/src/main.ts +15 -0
- package/templates/runner/src/physics.ts +13 -0
- package/templates/runner/src/render/camera.ts +39 -0
- package/templates/runner/src/render/dust.ts +131 -0
- package/templates/runner/src/render/lighting.ts +57 -0
- package/templates/runner/src/render/loading.ts +325 -0
- package/templates/runner/src/render/materials.ts +27 -0
- package/templates/runner/src/render/palette.ts +30 -0
- package/templates/runner/src/render/postprocessing.ts +34 -0
- package/templates/runner/src/render/quality.ts +170 -0
- package/templates/runner/src/render/shapes.ts +68 -0
- package/templates/runner/src/render/sky.ts +51 -0
- package/templates/runner/src/render/touch-controls.ts +185 -0
- package/templates/runner/src/render/worldEnvironment.ts +758 -0
- package/templates/runner/src/scenes/Boot.ts +12 -0
- package/templates/runner/src/scenes/Run.ts +142 -0
- package/templates/runner/src/state.ts +29 -0
- package/templates/runner/src/style.css +96 -0
- package/templates/runner/src/track.ts +176 -0
- package/templates/runner/src/ui/App.tsx +22 -0
- package/templates/runner/src/ui/GameUi.tsx +20 -0
- package/templates/runner/src/ui/Hud.tsx +55 -0
- package/templates/runner/src/ui/Menu.tsx +7 -0
- package/templates/runner/src/ui/main.tsx +14 -0
- package/templates/runner/tailwind.config.ts +1 -0
- package/templates/runner/threenative.config.ts +49 -0
- package/templates/runner/tsconfig.json +17 -0
- package/templates/runner/vite.config.ts +38 -0
- package/templates/sailing/.codex/config.toml +4 -0
- package/templates/sailing/.cursor/mcp.json +32 -0
- package/templates/sailing/.gemini/settings.json +32 -0
- package/templates/sailing/.mcp.json +15 -3
- package/templates/sailing/.vscode/mcp.json +36 -0
- package/templates/sailing/.zed/settings.json +36 -0
- package/templates/sailing/AGENTS.md +62 -355
- package/templates/sailing/CLAUDE.md +62 -355
- package/templates/sailing/README.md +12 -9
- package/templates/sailing/native-playtests/float.playtest.json +55 -0
- package/templates/sailing/native-playtests/survives.playtest.json +20 -3
- package/templates/sailing/opencode.json +41 -0
- package/templates/sailing/package.json +8 -8
- package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
- package/templates/sailing/playtests/float.playtest.json +59 -0
- package/templates/sailing/playtests/performance.playtest.json +21 -6
- package/templates/sailing/playtests/survives.playtest.json +8 -0
- package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
- package/templates/sailing/src/conventions.ts +8 -0
- package/templates/sailing/src/entities/Ship.ts +150 -13
- package/templates/sailing/src/render/camera.ts +15 -8
- package/templates/sailing/src/render/lighting.ts +10 -5
- package/templates/sailing/src/render/loading.ts +12 -2
- package/templates/sailing/src/render/materials.ts +24 -8
- package/templates/sailing/src/render/ocean.ts +179 -0
- package/templates/sailing/src/render/palette.ts +14 -21
- package/templates/sailing/src/render/postprocessing.ts +23 -22
- package/templates/sailing/src/render/props.ts +584 -34
- package/templates/sailing/src/render/quality.ts +140 -0
- package/templates/sailing/src/render/sky.ts +8 -3
- package/templates/sailing/src/render/touch-controls.ts +142 -0
- package/templates/sailing/src/render/worldEnvironment.ts +206 -38
- package/templates/sailing/src/scenes/Sailing.ts +43 -16
- package/templates/sailing/src/style.css +20 -0
- package/templates/sailing/threenative.config.ts +7 -1
- package/templates/shooter/.codex/config.toml +4 -0
- package/templates/shooter/.cursor/mcp.json +32 -0
- package/templates/shooter/.gemini/settings.json +32 -0
- package/templates/shooter/.mcp.json +15 -3
- package/templates/shooter/.vscode/mcp.json +36 -0
- package/templates/shooter/.zed/settings.json +36 -0
- package/templates/shooter/AGENTS.md +76 -415
- package/templates/shooter/CLAUDE.md +76 -415
- package/templates/shooter/kit.json +2 -2
- package/templates/shooter/opencode.json +41 -0
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/playtests/combat.playtest.json +48 -0
- package/templates/shooter/playtests/input-control.playtest.json +165 -35
- package/templates/shooter/playtests/per-item.playtest.json +3 -3
- package/templates/shooter/playtests/performance.playtest.json +24 -7
- package/templates/shooter/playtests/shooter.playtest.json +13 -7
- package/templates/shooter/playtests/survives.playtest.json +27 -0
- package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
- package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
- package/templates/shooter/src/combat/damage.ts +1 -2
- package/templates/shooter/src/conventions.ts +51 -0
- package/templates/shooter/src/entities/Player.ts +235 -18
- package/templates/shooter/src/entities/Target.ts +2 -2
- package/templates/shooter/src/game.ts +13 -4
- package/templates/shooter/src/render/camera.ts +49 -39
- package/templates/shooter/src/render/decals.ts +211 -0
- package/templates/shooter/src/render/lighting.ts +7 -3
- package/templates/shooter/src/render/loading.ts +12 -2
- package/templates/shooter/src/render/materials.ts +56 -3
- package/templates/shooter/src/render/palette.ts +6 -3
- package/templates/shooter/src/render/postprocessing.ts +21 -58
- package/templates/shooter/src/render/quality.ts +170 -0
- package/templates/shooter/src/render/scale.ts +22 -0
- package/templates/shooter/src/render/shapes.ts +343 -62
- package/templates/shooter/src/render/sky.ts +5 -1
- package/templates/shooter/src/render/touch-controls.ts +305 -0
- package/templates/shooter/src/render/ui.css +85 -0
- package/templates/shooter/src/render/ui.ts +19 -3
- package/templates/shooter/src/render/vfx.ts +215 -0
- package/templates/shooter/src/render/worldEnvironment.ts +208 -33
- package/templates/shooter/src/scenes/Play.ts +171 -56
- package/templates/shooter/src/state.ts +5 -0
- package/templates/shooter/src/style.css +20 -0
- package/templates/shooter/src/ui/Crosshair.tsx +25 -0
- package/templates/shooter/src/ui/GameUi.tsx +2 -0
- package/templates/shooter/src/ui/Hud.tsx +7 -1
- package/templates/shooter/src/weapons/Hitscan.ts +3 -4
- package/templates/shooter/src/weapons/Projectile.ts +8 -3
- package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
- package/templates/shooter/threenative.config.ts +7 -0
- package/templates/starter/.codex/config.toml +4 -0
- package/templates/starter/.cursor/mcp.json +32 -0
- package/templates/starter/.gemini/settings.json +32 -0
- package/templates/starter/.mcp.json +15 -3
- package/templates/starter/.vscode/mcp.json +36 -0
- package/templates/starter/.zed/settings.json +36 -0
- package/templates/starter/AGENTS.md +70 -527
- package/templates/starter/CLAUDE.md +70 -527
- package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
- package/templates/starter/opencode.json +41 -0
- package/templates/starter/package.json +7 -7
- package/templates/starter/playtests/boot-failure.playtest.json +45 -0
- package/templates/starter/playtests/look.playtest.json +110 -6
- package/templates/starter/playtests/play.playtest.json +3 -2
- package/templates/starter/playtests/survives.playtest.json +21 -0
- package/templates/starter/playtests/touch-controls.playtest.json +42 -0
- package/templates/starter/src/conventions.ts +18 -0
- package/templates/starter/src/entities/Goal.ts +18 -3
- package/templates/starter/src/entities/Player.ts +72 -9
- package/templates/starter/src/game.ts +2 -0
- package/templates/starter/src/render/adaptiveQuality.ts +195 -0
- package/templates/starter/src/render/camera.ts +1 -1
- package/templates/starter/src/render/coast.ts +199 -0
- package/templates/starter/src/render/hero.ts +88 -0
- package/templates/starter/src/render/implicitSurface.ts +199 -0
- package/templates/starter/src/render/kuwahara.ts +174 -0
- package/templates/starter/src/render/lighting.ts +4 -4
- package/templates/starter/src/render/loading.ts +12 -2
- package/templates/starter/src/render/materials.ts +25 -6
- package/templates/starter/src/render/outline.ts +141 -0
- package/templates/starter/src/render/painterly.ts +86 -0
- package/templates/starter/src/render/palette.ts +15 -6
- package/templates/starter/src/render/postprocessing.ts +87 -36
- package/templates/starter/src/render/quality.ts +185 -0
- package/templates/starter/src/render/rockRidge.ts +198 -0
- package/templates/starter/src/render/rockRidge.worker.ts +77 -0
- package/templates/starter/src/render/scenery.ts +16 -59
- package/templates/starter/src/render/textureLifetime.ts +53 -0
- package/templates/starter/src/render/touch-controls.ts +165 -0
- package/templates/starter/src/render/water.ts +38 -0
- package/templates/starter/src/render/watercolor.ts +85 -0
- package/templates/starter/src/render/worldEnvironment.ts +208 -33
- package/templates/starter/src/scenes/Play.ts +103 -16
- package/templates/starter/src/style.css +27 -7
- package/templates/starter/threenative.config.ts +7 -7
- package/agent-docs/asset-mcp-loop.md +0 -33
- package/agent-docs/ctx-surface.md +0 -69
- package/agent-docs/engine-capabilities.md +0 -4
- package/agent-docs/framework-blocks-you.md +0 -60
- package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
- package/agent-docs/performance-default.md +0 -42
- package/agent-docs/pixel-budget.md +0 -20
- package/agent-docs/playtest-fail-closed.md +0 -23
- package/agent-docs/sculpt-loop.md +0 -16
- package/templates/action-rpg/src/physics.ts +0 -40
- package/templates/defense/public/icon.png +0 -0
- package/templates/minimal/public/icon.png +0 -0
- package/templates/platformer/public/icon.png +0 -0
- package/templates/racing/public/icon.png +0 -0
- package/templates/sailing/public/icon.png +0 -0
- package/templates/sailing/src/render/water-material.ts +0 -14
- package/templates/sailing/src/render/water-shaders.ts +0 -12
- package/templates/sailing/src/render/wave-nodes.ts +0 -10
- package/templates/shooter/public/icon.png +0 -0
- package/templates/shooter/src/physics.ts +0 -49
- package/templates/starter/public/icon.png +0 -0
- /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
|
@@ -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.
|
|
@@ -131,3 +131,44 @@ reason** — `godraysEnabled is false`, `light 'sun' does not cast shadows`, `re
|
|
|
131
131
|
stage you turned on that is not in that line as `applied: true` did not run, and the reason says
|
|
132
132
|
why. An unknown `ssgiQuality` or `tonemapMode` throws at construction rather than quietly
|
|
133
133
|
becoming the default.
|
|
134
|
+
|
|
135
|
+
## Shafts of light — the one recipe that is easy to get wrong
|
|
136
|
+
|
|
137
|
+
You want the beam a cathedral window or a hole in a cave roof throws. **Do not build cone
|
|
138
|
+
geometry for it.** A hand-authored additive cone draws its own silhouette, stacks two layers where
|
|
139
|
+
you see through both walls, and reads as a plastic tube; the `godRays` stage is the supported
|
|
140
|
+
route and it is already wired.
|
|
141
|
+
|
|
142
|
+
Four things have to be true, and three of them fail silently:
|
|
143
|
+
|
|
144
|
+
1. **`renderer.shadowMap.enabled = true`.** The stage raymarches the sun's shadow map, and three
|
|
145
|
+
does not allocate one until something asks for it. With no shadow map the stage refuses — and
|
|
146
|
+
because it refuses at build time it takes the *whole chain* with it, so SSGI, SSR and your
|
|
147
|
+
tonemap all quietly stop too. The symptom is a flat, ungraded frame, not a missing beam.
|
|
148
|
+
`ctx.renderer` is the framework's wrapper; `ctx.renderer.raw` is the three renderer that has
|
|
149
|
+
`shadowMap`. Setting it on the wrong one throws `Cannot set properties of undefined`.
|
|
150
|
+
2. **The light casts shadows and reaches the room.** `castShadow = true`, and a shadow-camera
|
|
151
|
+
frustum wide enough to contain the space — the default 10 m ortho extent shadows nothing in a
|
|
152
|
+
50 m hall, and a shaft is only visible where the map says the air is lit.
|
|
153
|
+
3. **The beam has to pass through the opening.** Position the light so the line from it through
|
|
154
|
+
the hole lands where you want the pool of light; a sun placed for a pleasing angle usually
|
|
155
|
+
misses the hole entirely and lights the far wall instead.
|
|
156
|
+
4. **`godraysFloor` is the dial that separates beams from fog.** This is the one people miss. The
|
|
157
|
+
pass adds haze to every pixel, not only to the beams. `godraysFloor` subtracts that out-of-beam
|
|
158
|
+
scatter *before* `godraysIntensity` multiplies, so with the floor near zero, raising intensity
|
|
159
|
+
scales the veil over the whole room and the frame just gets milkier. Raise the floor first,
|
|
160
|
+
then the intensity.
|
|
161
|
+
|
|
162
|
+
Measured band on an interior (lumen-hall, across many captures):
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
godraysDensity: 0.7, // above ~0.8 the haze stops being confined to the beams
|
|
166
|
+
godraysFloor: 0.08, // subtracts the veil; raise this before raising intensity
|
|
167
|
+
godraysIntensity: 3.0, // only scales what survives the floor
|
|
168
|
+
godraysMaxDensity: 0.6, // clamp; a no-op at this density, louder at higher ones
|
|
169
|
+
godraysSteps: 56, // below ~24 leaves visible slabs at each step boundary
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
A useful check that costs nothing: if turning godrays off moves the **median** brightness of the
|
|
173
|
+
frame by more than a few points, the stage is fogging the room rather than drawing shafts. Beams
|
|
174
|
+
change the bright end of the histogram, not the middle.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: file-engine-bug
|
|
3
|
+
description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session. Use when doctor and a minimal repro separate an engine bug from a game or machine problem, and you have pasted output proving it.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Filing an engine bug
|
|
7
|
+
|
|
8
|
+
A confirmed engine bug is filed upstream in the same turn you proved it — on the user's behalf,
|
|
9
|
+
under the user's own `gh` session. Never create an account, never request a token, never open a
|
|
10
|
+
browser flow: `gh` is already authenticated as the user, and that is the identity the report
|
|
11
|
+
carries. Keep the report factual; it goes out in their name.
|
|
12
|
+
|
|
13
|
+
## 1. Confirm it is an engine bug
|
|
14
|
+
|
|
15
|
+
`npx threenative doctor` and `npx @threenative/playtest doctor` separate project, machine, and
|
|
16
|
+
engine failures. It is an engine bug when an `@threenative/*` API is broken, missing, or acts
|
|
17
|
+
against its contract (capability detail or `AGENTS.md`), and a minimal repro shows it — not a
|
|
18
|
+
fix that lives in this game's source, and not a machine problem doctor names.
|
|
19
|
+
|
|
20
|
+
Implement the workaround first and continue the game (`AGENTS.md`: never stall on a framework
|
|
21
|
+
bug). Filing does not wait for the workaround to be clean.
|
|
22
|
+
|
|
23
|
+
## 2. Search before filing
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or three keywords>"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
An open issue already covering it: add your repro and output as a comment
|
|
30
|
+
(`gh issue comment <number> --body-file <file>`) instead of a new report.
|
|
31
|
+
|
|
32
|
+
## 3. File it
|
|
33
|
+
|
|
34
|
+
Write the body to a file first; quoting goes through `--body-file`, never inline:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
gh issue create --repo ThreeNativeHQ/threenative \
|
|
38
|
+
--title "<area>: <what is wrong, stated as behaviour>" \
|
|
39
|
+
--body-file bug-report.md
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The body carries, in this order:
|
|
43
|
+
|
|
44
|
+
- **Expected** — what the capability's contract says happens.
|
|
45
|
+
- **Actual** — what happened, with the exact error id (`TN_*`) and the output you ran (doctor,
|
|
46
|
+
playtest, perf) pasted, not summarised.
|
|
47
|
+
- **Repro** — the smallest game code that shows it, and which template it reproduces in.
|
|
48
|
+
- **Environment** — platform and target, browser and adapter for web, `@threenative/*` versions
|
|
49
|
+
from the project's `package.json`.
|
|
50
|
+
- **Workaround** — what the game shipped with to keep moving.
|
|
51
|
+
|
|
52
|
+
## 4. When not to file
|
|
53
|
+
|
|
54
|
+
- `gh auth status` fails or `gh` is missing: do not authenticate for the user and do not stall —
|
|
55
|
+
hand them the drafted title and body file and name the one command that files it.
|
|
56
|
+
- The bug is real but you cannot prove it with pasted output yet: file nothing. Report it to the
|
|
57
|
+
user as suspected, with the repro to run.
|
|
58
|
+
|
|
59
|
+
The final summary to the user names the issue URL, or the reason no issue exists.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: prd-creator
|
|
3
|
+
description: Turn a ThreeNative game idea or change into an approved game plan and implementation tasks before authoring code. Use after threenative-capabilities has recorded a capability or no-match for every mechanic, and before any game source is written.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative game PRD
|
|
7
|
+
|
|
8
|
+
Use this after `threenative-capabilities` has recorded a capability or no-match for the full request
|
|
9
|
+
and every concrete mechanic. The outcome is a small, distinctive, playable plan grounded in the
|
|
10
|
+
engine surface and explicitly approved by the user, not a generic genre template.
|
|
11
|
+
|
|
12
|
+
## Plan
|
|
13
|
+
|
|
14
|
+
1. Inspect the existing game, its instructions, and the capability discovery record. If discovery
|
|
15
|
+
is missing or the requested mechanics changed, invoke `threenative-capabilities` before drafting.
|
|
16
|
+
2. Preserve the request's fantasy. Define the smallest playable loop that depends on its setting,
|
|
17
|
+
traversal, combat, or simulation rather than reskinning a generic character game.
|
|
18
|
+
3. Specify controls, camera, core mechanics, win/loss states, game state, progression, visual and
|
|
19
|
+
audio direction, asset needs and licences, target platforms, performance risks, and non-goals.
|
|
20
|
+
4. Define fail-closed playtest acceptance criteria for the loop, including observable state and a
|
|
21
|
+
real capture for visible changes. Unexecuted platforms remain unverified.
|
|
22
|
+
5. Record prerequisites: required tools/MCPs, service access, test users, and environment variable
|
|
23
|
+
names. Use placeholders only; never read or write real secrets into planning artifacts.
|
|
24
|
+
|
|
25
|
+
Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
|
|
26
|
+
`.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
|
|
27
|
+
bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
|
|
28
|
+
The first task verifies prerequisites; later tasks include implementation, playtest proof, and
|
|
29
|
+
visual inspection. Preserve the pre-planning capability decisions in the relevant task checks.
|
|
30
|
+
|
|
31
|
+
## Approval gate
|
|
32
|
+
|
|
33
|
+
Present the plan and direct the user to approve it or request changes. Do not edit game source,
|
|
34
|
+
download assets, authenticate services, or begin implementation while planning. Revise the plan
|
|
35
|
+
when the user gives feedback.
|
|
36
|
+
|
|
37
|
+
Start implementation only after explicit approval and a clear execution instruction such as
|
|
38
|
+
"execute", "implement", "build it", or an equivalent phrase. One message may contain both. After
|
|
39
|
+
that handoff, execute the approved tasks without silently expanding the scope; repeat capability
|
|
40
|
+
discovery only when the requested mechanics or target platforms change.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-assets
|
|
3
|
+
description: Find, import, license, or sculpt assets for a portable ThreeNative game. Use when the game needs textures, materials, HDRIs, sounds, or models, when importing an owned Fab or Unreal pack, or when sculpting bespoke geometry from a reference image.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative assets and sculpting
|
|
7
|
+
|
|
8
|
+
Use tools for conventional textures, materials, HDRIs, sounds, and models; write bespoke visuals
|
|
9
|
+
in `src/render/`. Start the session from the game root so the project-scoped MCP config is read.
|
|
10
|
+
|
|
11
|
+
1. Run `asset_search_sources` to learn what is reachable, then search with
|
|
12
|
+
`polyhaven_search_assets`, `ambientcg_search_assets`, or `audio_search_assets`.
|
|
13
|
+
2. List files with `polyhaven_list_files`/`ambientcg_list_files` before downloading; read the
|
|
14
|
+
license and choose a sane resolution.
|
|
15
|
+
3. Download with `asset_download_file`/`audio_download_asset` and `acceptLicense: true`; tools
|
|
16
|
+
write to the configured project directory.
|
|
17
|
+
4. Add file, source, license, and URL to `CREDITS.md`. Never state a license not returned by a tool.
|
|
18
|
+
|
|
19
|
+
Many Fab listings are Unreal-only rather than ready-to-load GLBs. Search with `fab_search_assets`,
|
|
20
|
+
check owned listings with `fab_list_owned`, then use `fab_import_asset` to download and convert an
|
|
21
|
+
owned listing; use `asset_import_unreal` for an already-downloaded local pack. Both write textured
|
|
22
|
+
`.glb` files under `assets/`. If they report `UNREAL_SOURCE_UNCOOKED`, stop: source editor assets
|
|
23
|
+
need Unreal Editor export and cannot be recovered by retrying the converter.
|
|
24
|
+
|
|
25
|
+
If FabCLI needs a session, proactively run `fabcli auth login`. Use Claude browser, or Codex's
|
|
26
|
+
`chrome:control-chrome`, to complete the login with the user's active browser session, then retry
|
|
27
|
+
the MCP call. Never read, copy, print, or persist browser cookies or tokens. The MCP checks
|
|
28
|
+
entitlement and accepts only Fab Standard or CC-BY; it never claims or buys. Full arguments:
|
|
29
|
+
`agent-docs/finding-assets.md`.
|
|
30
|
+
|
|
31
|
+
For a bespoke animated creature, follow `agent-docs/creating-creatures.md`. Call the five
|
|
32
|
+
`creature_*` tools through the project asset server, keep the editable spec and claims in
|
|
33
|
+
`.threenative/creatures/`, compile into the configured `assets/` source, and get independent
|
|
34
|
+
visual review before delivery. `creature_status` distinguishes compile-only availability from
|
|
35
|
+
optional preview/check dependencies; an unavailable renderer is not approval.
|
|
36
|
+
|
|
37
|
+
Choose the sculpt branch before coding: conventional → asset tools; trivial → portable geometry;
|
|
38
|
+
bespoke with a reference → `sculpt_plan`, `sculpt_spec_gate` until every region passes, one
|
|
39
|
+
factory per pass in `src/render/`, then `sculpt_compare` and `sculpt_pass_gate` against a real
|
|
40
|
+
capture; bespoke without a reference → read `agent-docs/dream-loop.md` and acquire a
|
|
41
|
+
user-supplied or explicitly authorized target before sculpting. Use `node scripts/reference.mjs`
|
|
42
|
+
only when the user selected its provider/model; never invent a reference or hide a missing key.
|
|
43
|
+
`sculpt_grimoire` supplies techniques. `threenative-sculpt-mcp` guides source and never launches
|
|
44
|
+
a browser. A missing/blank capture fails; credit the reference before the turn ends. See
|
|
45
|
+
`agent-docs/sculpt-from-a-reference.md`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: threenative-builder
|
|
3
|
-
description: Build one bounded ThreeNative change and report its evidence.
|
|
3
|
+
description: Build one bounded ThreeNative change and report its evidence. Use when dispatched as the builder against a single task; the complete role and framework contract is `.threenative/agents/builder.md`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Read `.threenative/agents/builder.md` and `AGENTS.md` before acting. Follow those files as the
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-capabilities
|
|
3
|
+
description: Discover and use the ThreeNative capability surface before writing a game system. Use before prd-creator drafts a plan, and before building or replacing any world, traversal, interaction, simulation, combat, camera, audio, UI, entity, movement, navigation, attachment, particle, terrain, or measurement system.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative capabilities
|
|
7
|
+
|
|
8
|
+
This is a critical planning prerequisite. Use it before `prd-creator` drafts a plan, and before
|
|
9
|
+
replacing any world, traversal, interaction, simulation, combat, camera, audio, UI, entity,
|
|
10
|
+
movement, navigation, attachment, particle, terrain, or measurement system.
|
|
11
|
+
|
|
12
|
+
1. Infer the concrete mechanics from the request. Preserve its distinctive fantasy with the
|
|
13
|
+
smallest characteristic loop; ask one short question only when two core loops remain equally
|
|
14
|
+
plausible.
|
|
15
|
+
2. Search the full request with `engine_search_capabilities` using `scope: "request"`, then search
|
|
16
|
+
every mechanic with `scope: "mechanic"`. Check each returned `matchedSituation`.
|
|
17
|
+
3. Record a capability or no-match for every mechanic before writing a replacement. Describe
|
|
18
|
+
situations plainly, such as *"enemy walks around a wall"*.
|
|
19
|
+
4. Hand the recorded matches, inspected constraints, and no-matches to `prd-creator`; the PRD must
|
|
20
|
+
plan against this actual engine surface.
|
|
21
|
+
|
|
22
|
+
The manifest is the complete public surface; grep misses subpath exports such as
|
|
23
|
+
`@threenative/physics/navigation`. If MCP is unavailable after `npx threenative doctor`, use
|
|
24
|
+
`agent-docs/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
|
|
25
|
+
Returned constraints are binding: import navigation from its returned subpath, use `attachToBone`
|
|
26
|
+
for held weapons (add a portable `Bone` named `RightHand` when needed), and never invent platform
|
|
27
|
+
support. One game rewrote 446 installed lines and ran at 9 FPS; discovery prevents that.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-context
|
|
3
|
+
description: Use the portable ThreeNative ctx lifecycle, scheduling, randomness, pointer, and raycast APIs. Use when writing scene changes, timers, tweens, randomness, pointer or drag handling, raycasts, or startup gating rather than hand-rolling them, and when `pnpm budgets` rejects a raw construct.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative context surface
|
|
7
|
+
|
|
8
|
+
These are properties on `ctx`, never imports; use them before writing equivalent game plumbing.
|
|
9
|
+
The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
|
|
10
|
+
`engine_search_capabilities`.
|
|
11
|
+
|
|
12
|
+
| Use | Instead of | Contract |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| `ctx.goto("<scene-name>")` | hand reset | async scene rebuild |
|
|
15
|
+
| `ctx.tween(...)` | `Math.sin`/`lerp` accumulator | timed interpolation with optional `ease` |
|
|
16
|
+
| `ctx.after(...)` / `ctx.every(...)` | timer branches in `update` | disposable schedules |
|
|
17
|
+
| `ctx.random.range(-1, 1)` | `Math.random()` | reproducible when `seed` is configured |
|
|
18
|
+
| `ctx.pointer.on(...)` / `ctx.pointer.drag(...)` | hover/press/drag bookkeeping | web/native pointer-id stream |
|
|
19
|
+
| `ctx.raycast()` / `ctx.raycastAll()` | `new Raycaster()` | backend-neutral intersections |
|
|
20
|
+
| `ctx.startup.hold(label, work)` | a loading screen that waits past `whenReady()` | the game's own launch work joins the readiness gate |
|
|
21
|
+
|
|
22
|
+
`ctx.pointer` dispatches entered, exited, pressed, released, tapped, drag-started, dragged, and
|
|
23
|
+
drag-ended events. Register a mesh/model root; only registered objects are raycast and events bubble
|
|
24
|
+
through parents.
|
|
25
|
+
|
|
26
|
+
`ctx.goto(name)` rebuilds the scene without resetting state; values in `ctx.state` survive. From a
|
|
27
|
+
frame function, `goto` and then `return` immediately because the old scene is torn down. For a full
|
|
28
|
+
restart, `game.goto("<scene-name>")` from React resets declared initial state first. A state reset
|
|
29
|
+
uses `ctx.state.set({ /* copy this game's initial-state shape */ })` before the goto. `ctx.random` is
|
|
30
|
+
deterministic only when `defineGame({ seed })` is configured.
|
|
31
|
+
|
|
32
|
+
`pnpm budgets` rejects superseded raw constructs such as `new Audio(`, `Math.random(`,
|
|
33
|
+
`new Raycaster(`, `.visible = false`, and `new Box3().setFromObject(`; use the named capability or
|
|
34
|
+
annotate a genuinely necessary line with a non-empty `// engine-override: reason`.
|
|
35
|
+
|
|
36
|
+
<!-- generated: superseded-constructs -->
|
|
37
|
+
|
|
38
|
+
**Reinvention fails CI.** `pnpm budgets` scans this project's `src/` for these raw
|
|
39
|
+
constructs and fails, naming the capability instead. The list and the gate are generated
|
|
40
|
+
from the capabilities' own doc tags, so they cannot disagree:
|
|
41
|
+
|
|
42
|
+
| Rather than write | Use instead | Import from |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `new Audio(` | `AudioBus` | `@threenative/core` |
|
|
45
|
+
| `Math.random(` | `createRandom` | `@threenative/core` |
|
|
46
|
+
| `new Box3().setFromObject(` | `normaliseToMetres` | `@threenative/core` |
|
|
47
|
+
| `.visible = false` | `prewarm` | `@threenative/core` |
|
|
48
|
+
| `new Raycaster(` | `ScenePicker` | `@threenative/core` |
|
|
49
|
+
|
|
50
|
+
When the raw construct is genuinely right, annotate that exact line with a non-empty
|
|
51
|
+
reason — a bare `// engine-override:` still fails:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
const bounds = new Box3().setFromObject(viewmodel); // engine-override: measuring, not scaling
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
<!-- /generated -->
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-performance
|
|
3
|
+
description: Measure ThreeNative frame budgets and report platform evidence without guessing. Use when a frame budget, FPS floor, or platform performance claim is in question, when reading `TN_FRAME_BUDGET`, or when writing a bounded performance assertion.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative performance evidence
|
|
7
|
+
|
|
8
|
+
Refill scratch and pool objects. Static GLBs may use `assets.models.lightmap:{atlasSize,padding}`;
|
|
9
|
+
load through `ctx.assets.model()`, remove it to roll back, and never claim Android/iOS from a
|
|
10
|
+
web/desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`, and
|
|
11
|
+
`residual`; `defineGame({ frameBudget: false })` silences output, never measurement.
|
|
12
|
+
|
|
13
|
+
Unexecuted platforms stay unverified; never invent numbers. Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. The bounded proof shape is
|
|
14
|
+
`{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12}}}` and its
|
|
15
|
+
fields are defined in `agent-docs/assertion-reference.md#performance`.
|
|
16
|
+
|
|
17
|
+
|Tier|Measure|Floor|Target|
|
|
18
|
+
|---|---|---:|---:|
|
|
19
|
+
|1|Starter/browser-desktop|60fps|display-refresh|
|
|
20
|
+
|1|Starter/browser-Android|30fps|58fps|
|
|
21
|
+
|1|Starter/native-desktop|60fps|display-refresh|
|
|
22
|
+
|1|Starter/native-Android|55fps|58fps|
|
|
23
|
+
|1|Starter/native-iOS|unverified|no-number|
|
|
24
|
+
|1|All-platform/hostGap-p95|—|≤4ms|
|
|
25
|
+
|1|All-platform/update-p95|—|≤2ms|
|
|
26
|
+
|1|All-platform/residual-p95|—|≤0.5ms|
|
|
27
|
+
|1|All-platform/overlay-p95|—|≤1ms|
|
|
28
|
+
|2|Same-device-fps-parity|.85|.95|
|
|
29
|
+
|2|Inverted-render-p95-parity|.80|.95|
|
|
30
|
+
|3|Light|55fps|58fps|
|
|
31
|
+
|3|Medium|30fps|58fps|
|
|
32
|
+
|3|Heavy|30fps|58fps|
|
|
33
|
+
|4|Sustained-duration|10min|10min|
|
|
34
|
+
|4|Final/opening-fps|.75|.90|
|
|
35
|
+
|4|Last-minute-heavy|25fps|50fps|
|
|
36
|
+
|4|Peak-battery-temperature|≤45C|≤40C|
|
|
37
|
+
|4|Thermal-status|≤2|≤1|
|
|
38
|
+
|4|Whole-device-current|—|report;not-gated|
|
|
39
|
+
|
|
40
|
+
On Android, budget roughly a 500 MiB driver floor before your own textures; a dual-use
|
|
41
|
+
equirectangular environment adds about 48 MiB. Fix it with `agent-docs/mobile-memory-budget.md`,
|
|
42
|
+
which carries the measurement conditions behind both numbers.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-playtest
|
|
3
|
+
description: Diagnose a ThreeNative game, prove behavior, and keep playtests fail-closed. Use for a blank, black, or washed-out frame, a browser, device, or import failure, or when writing or repairing a playtest scenario and its assertions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative diagnosis and playtests
|
|
7
|
+
|
|
8
|
+
For browser, blank-frame, device, or import failures, run `npx threenative doctor` and
|
|
9
|
+
`npx @threenative/playtest doctor` first. For a running game, use:
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npx @threenative/playtest doctor --url http://127.0.0.1:5173 --text
|
|
13
|
+
npx @threenative/playtest playtests/<name>.playtest.json --browser-recipe webgpu --headed
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Read visibility, scale, draw cost, frame rate, advancing state, and errors. Missing output means
|
|
17
|
+
unobserved, never zero.
|
|
18
|
+
|
|
19
|
+
**Read the room before you reach for a screenshot.** `doctor --url` also reports three lines named
|
|
20
|
+
lighting, materials and camera — how many lights the renderer can see, what materials are mounted,
|
|
21
|
+
the background, the fog, and the camera's position and clip planes — and it names the three ways a
|
|
22
|
+
frame dies while every other number looks healthy: lit materials with no visible light, a fog far
|
|
23
|
+
plane in front of the scene it fogs, and a camera far plane that clips it. A black or washed-out
|
|
24
|
+
frame is a question those lines answer and a screenshot cannot.
|
|
25
|
+
|
|
26
|
+
Bound the same things in a scenario so the check outlives the session:
|
|
27
|
+
`assert.scene` takes `minVisibleLights`, `litMaterialsAreLit`, `fogClearsScene` and
|
|
28
|
+
`cameraClearsScene`; `assert.animation[]` takes `maxFootSlide` and `strideSynced`, which catch a
|
|
29
|
+
character skating across the floor when the clip and the ground disagree. Both fail closed — a
|
|
30
|
+
bridge that reports no scene has not reported a well-lit one. For a relative-placement question, publish a scene probe with derived
|
|
31
|
+
`checks`, drive it with Playwright, sweep candidates in one run, and turn the winning check into a
|
|
32
|
+
playtest assertion.
|
|
33
|
+
|
|
34
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
35
|
+
piece with portable Three.js/plain code. Keep the loop, scenes, input, entity registry, and bridge;
|
|
36
|
+
avoid `document`, `window`, `localStorage`, dynamic `import()`, and raw physics handles. **Report
|
|
37
|
+
what blocked you**: API, expectation, result, and replacement. Never stall on a framework bug.
|
|
38
|
+
|
|
39
|
+
Playtests fail closed: a missing entity, absent observation, or empty assertion set fails. Every
|
|
40
|
+
`allowTrivial` waiver needs a 20-character reason; `true` alone is invalid, and all-waived
|
|
41
|
+
triviality fails `TN_PLAYTEST_SCENARIO_ASSERTS_NOTHING`. Use `holdTicks`/`waitTicks` for fixed-step
|
|
42
|
+
time (`holdFrames`/`waitFrames` are compatibility aliases); `warmupFrames` means RAF warmup.
|
|
43
|
+
Read `agent-docs/assertion-reference.md` for assertion fields and `agent-docs/debug-surface.md`
|
|
44
|
+
for bridge globals. The JSON-safe bridge resource is `state`; `GameState` is a deprecated alias.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-ui
|
|
3
|
+
description: Build a native-safe ThreeNative React UI that communicates through state and intents. Use when adding or changing a HUD, menu, or any React UI that must also run on native, where the layout key set is fixed and CSS does not exist.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ThreeNative UI
|
|
7
|
+
|
|
8
|
+
Use `View` and `Text` from `@threenative/core/react` for native UI; `react-dom` is web-only.
|
|
9
|
+
Native layout is pixel-based and absolute unless `direction` is `row` or `column`. Supported keys
|
|
10
|
+
are `left`, `right`, `top`, `bottom`, `centerX`, `centerY`, `width`, `height`, `padding`,
|
|
11
|
+
`direction`, `gap`, `align`, `background`, `color`, `opacity`, `fontSize`, `letterSpacing`,
|
|
12
|
+
`textAlign`, and `zIndex`; CSS, Tailwind, flex grow/wrap, borders, radius, transforms, images, SVG,
|
|
13
|
+
and events do not exist in the native renderer.
|
|
14
|
+
|
|
15
|
+
On native, game and UI are separate processes. The UI reads published JSON-safe state and sends
|
|
16
|
+
intents; `src/game.ts` decides their meaning. `useUiState<GameState>()` is undefined until the first
|
|
17
|
+
snapshot, and `useUiIntent()` sends commands. Mark every touch target `data-tn-interactive`; the
|
|
18
|
+
host routes marked pointer-down events to UI and unmarked touches to the game. Share state and
|
|
19
|
+
components, but keep appearance in `src/ui/`. The full state, hit-region, and renderer contract is
|
|
20
|
+
`agent-docs/webview-ui.md`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: threenative-verifier
|
|
3
|
-
description: Independently verify a ThreeNative change without editing it.
|
|
3
|
+
description: Independently verify a ThreeNative change without editing it. Use when a change needs a fresh read-only check that its evidence actually holds; the complete role and framework contract is `.threenative/agents/verifier.md`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Read `.threenative/agents/verifier.md` and `AGENTS.md` before acting. Follow those files as the
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threenative-visuals
|
|
3
|
+
description: Capture, inspect, and budget the player-visible look of a ThreeNative game. Use when a player-visible feature needs a real capture before it is called done, when matching a reference image, or when tuning lighting, probe volumes, or resolution scale.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Budget real time for the look
|
|
7
|
+
|
|
8
|
+
`typecheck`, `lint`, tests, and playtests can all pass on grey boxes and a black screen. A
|
|
9
|
+
player-visible feature is done only after opening a real capture and checking silhouettes, depth,
|
|
10
|
+
contact shadows, rim light, motion, and the HUD. Spend roughly as much effort on presentation as
|
|
11
|
+
mechanics.
|
|
12
|
+
|
|
13
|
+
Use browser automation on the user's real Chrome when available; otherwise run
|
|
14
|
+
`npx @threenative/playtest <scenario> --browser-recipe webgpu --headed`. The recipe includes
|
|
15
|
+
`--enable-features=Vulkan`; without it Chromium may use SwiftShader and the runner reports
|
|
16
|
+
`TN_PLAYTEST_SOFTWARE_ADAPTER`. **Do not use `xvfb-run`**: its cleanup can replace the real exit
|
|
17
|
+
status. A black headless capture is a capture failure until proven otherwise.
|
|
18
|
+
|
|
19
|
+
For reference matching, solve lighting first: search `engine_search_capabilities` before adding
|
|
20
|
+
effects, read `TN_RENDER_CHAIN`, and use `agent-docs/visual-baseline.md` and
|
|
21
|
+
`agent-docs/capture-the-frame.md` for the per-file baseline and capture recipe.
|
|
22
|
+
|
|
23
|
+
For a supplied or explicitly generated target, read `agent-docs/dream-loop.md`. It is the shared
|
|
24
|
+
workflow for locking the target, preserving its hash, obtaining a fresh gameplay capture, and
|
|
25
|
+
asking the read-only verifier for an independent `PASS`, `REQUEST_CHANGES`, or `NOT_OBSERVED`.
|
|
26
|
+
Run `node scripts/visual-loop.mjs --record <run>/run.json` before and after each round; read its
|
|
27
|
+
JSON `decision` instead of treating exit 0 as acceptance. If a target must be generated or edited,
|
|
28
|
+
use `node scripts/reference.mjs` with a unique `--request-id`, the exact prompt file, and the
|
|
29
|
+
user-selected model. A supplied target works without credentials; missing evidence or a provider
|
|
30
|
+
failure remains unavailable and never becomes a visual pass.
|
|
31
|
+
|
|
32
|
+
For off-screen diffuse light, add `ProbeVolume` after static geometry/lights, bake on demand, and
|
|
33
|
+
sample it into a game-owned material before screen-space GI. It owns no look; moving lights need a
|
|
34
|
+
new bake. Keep `TN_PROBE_VOLUME`'s stale state, probe count, atlas bytes, progress, and bake cost
|
|
35
|
+
visible while tuning bounds, density, and `bakeBudgetMs`.
|
|
36
|
+
|
|
37
|
+
`renderer.resolutionScale: "auto"` scales only the 3D drawing buffer to hold `display.maxFps`;
|
|
38
|
+
never hand-author a device constant. A `(0, 1]` value pins it; invalid values fail at config load.
|
|
39
|
+
Both modes report `TN_FRAME_BUDGET.surface` (`resolutionScale`, `scaleSource`, sample count, and
|
|
40
|
+
buffer size), and `display: config.display` must reach `defineGame`. See the pixel-budget details
|
|
41
|
+
in `agent-docs/visual-baseline.md` and the engine's measurement skill.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: file-engine-bug
|
|
3
|
+
description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session. Use when doctor and a minimal repro separate an engine bug from a game or machine problem, and you have pasted output proving it.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Filing an engine bug
|
|
7
|
+
|
|
8
|
+
A confirmed engine bug is filed upstream in the same turn you proved it — on the user's behalf,
|
|
9
|
+
under the user's own `gh` session. Never create an account, never request a token, never open a
|
|
10
|
+
browser flow: `gh` is already authenticated as the user, and that is the identity the report
|
|
11
|
+
carries. Keep the report factual; it goes out in their name.
|
|
12
|
+
|
|
13
|
+
## 1. Confirm it is an engine bug
|
|
14
|
+
|
|
15
|
+
`npx threenative doctor` and `npx @threenative/playtest doctor` separate project, machine, and
|
|
16
|
+
engine failures. It is an engine bug when an `@threenative/*` API is broken, missing, or acts
|
|
17
|
+
against its contract (capability detail or `AGENTS.md`), and a minimal repro shows it — not a
|
|
18
|
+
fix that lives in this game's source, and not a machine problem doctor names.
|
|
19
|
+
|
|
20
|
+
Implement the workaround first and continue the game (`AGENTS.md`: never stall on a framework
|
|
21
|
+
bug). Filing does not wait for the workaround to be clean.
|
|
22
|
+
|
|
23
|
+
## 2. Search before filing
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or three keywords>"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
An open issue already covering it: add your repro and output as a comment
|
|
30
|
+
(`gh issue comment <number> --body-file <file>`) instead of a new report.
|
|
31
|
+
|
|
32
|
+
## 3. File it
|
|
33
|
+
|
|
34
|
+
Write the body to a file first; quoting goes through `--body-file`, never inline:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
gh issue create --repo ThreeNativeHQ/threenative \
|
|
38
|
+
--title "<area>: <what is wrong, stated as behaviour>" \
|
|
39
|
+
--body-file bug-report.md
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The body carries, in this order:
|
|
43
|
+
|
|
44
|
+
- **Expected** — what the capability's contract says happens.
|
|
45
|
+
- **Actual** — what happened, with the exact error id (`TN_*`) and the output you ran (doctor,
|
|
46
|
+
playtest, perf) pasted, not summarised.
|
|
47
|
+
- **Repro** — the smallest game code that shows it, and which template it reproduces in.
|
|
48
|
+
- **Environment** — platform and target, browser and adapter for web, `@threenative/*` versions
|
|
49
|
+
from the project's `package.json`.
|
|
50
|
+
- **Workaround** — what the game shipped with to keep moving.
|
|
51
|
+
|
|
52
|
+
## 4. When not to file
|
|
53
|
+
|
|
54
|
+
- `gh auth status` fails or `gh` is missing: do not authenticate for the user and do not stall —
|
|
55
|
+
hand them the drafted title and body file and name the one command that files it.
|
|
56
|
+
- The bug is real but you cannot prove it with pasted output yet: file nothing. Report it to the
|
|
57
|
+
user as suspected, with the repro to run.
|
|
58
|
+
|
|
59
|
+
The final summary to the user names the issue URL, or the reason no issue exists.
|