|
| 1 | +# Game Studio Agent Architecture |
| 2 | + |
| 3 | +Indie game development managed through 48 coordinated Claude Code subagents. |
| 4 | +Each agent owns a specific domain, enforcing separation of concerns and quality. |
| 5 | + |
| 6 | +## Technology Stack |
| 7 | + |
| 8 | +- **Engine**: Godot 4.3 |
| 9 | +- **Language**: GDScript (primary), C++ via GDExtension (performance-critical) |
| 10 | +- **Version Control**: Git with trunk-based development |
| 11 | +- **Build System**: SCons (engine), Godot Export Templates |
| 12 | +- **Asset Pipeline**: Godot Import System + custom resource pipeline |
| 13 | + |
| 14 | +> **Note**: Engine-specialist agents exist for Godot, Unity, and Unreal with |
| 15 | +> dedicated sub-specialists. Use the set matching your engine. |
| 16 | +
|
| 17 | +## Project Structure |
| 18 | + |
| 19 | +@.claude/docs/directory-structure.md |
| 20 | + |
| 21 | +## Engine Version Reference |
| 22 | + |
| 23 | +@.claude/docs/engine-reference/godot/VERSION.md |
| 24 | + |
| 25 | +## Technical Preferences |
| 26 | + |
| 27 | +@.claude/docs/technical-preferences.md |
| 28 | + |
| 29 | +## Coordination Rules |
| 30 | + |
| 31 | +@.claude/docs/coordination-rules.md |
| 32 | + |
| 33 | +## Coding Standards |
| 34 | + |
| 35 | +@.claude/docs/coding-standards.md |
| 36 | + |
| 37 | +## Context Management |
| 38 | + |
| 39 | +@.claude/docs/context-management.md |
| 40 | + |
| 41 | +## GDScript Development Skills |
| 42 | + |
| 43 | +@.claude/skills/gdscript-patterns/SKILL.md |
| 44 | + |
| 45 | +> Load this before writing any GDScript. Contains type inference rules, known Godot 4 quirks, |
| 46 | +> collision layer bitmask table, and common runtime pitfalls. |
| 47 | +
|
| 48 | +## Scene Builder & Headless Workflow |
| 49 | + |
| 50 | +@.claude/skills/godot-scene-builder/SKILL.md |
| 51 | + |
| 52 | +> Load when building `.tscn` files programmatically, running headless validation, |
| 53 | +> or capturing screenshots on Windows via `--write-movie`. |
| 54 | +
|
| 55 | +## Asset Generation (Gemini / Imagen 3) |
| 56 | + |
| 57 | +@.claude/skills/asset-gen/SKILL.md |
| 58 | + |
| 59 | +> Load when generating sprites, textures, backgrounds, or reference art. |
| 60 | +> Uses Imagen 3 for text-to-image and Gemini Flash for image editing/variants. |
| 61 | +> Includes background removal via `rembg`. |
| 62 | +
|
| 63 | +## Response Format |
| 64 | + |
| 65 | +- Always end every response with a "## Suggested Next Steps" section containing actionable prompts/things the user can ask to continue progressing on their game. |
| 66 | + |
| 67 | +# RULES ALWAYS TO FOLLOW |
| 68 | + |
| 69 | +- Always run full test suite and auto capture test after each code change. Verify the screenshots by viewing all images. Only report task completion to the user after all tests have passed successfully. Ensure structural and behavioral integrity through rigorous validation before finality. |
| 70 | +- Transparency is mandatory regarding incomplete data migration or pending content. Never claim a task is complete if there is content missing or data pending, even if the code architecture is finished. Playability and data completeness are as important as structural code integrity. |
| 71 | +- On Windows, always use 'godot_console.exe' with the '--headless' flag for CLI tasks and automated testing. The standard 'godot.exe' detaches from the terminal and does not stream output/logs back to the console, making it unsuitable for remote agent diagnostics. |
| 72 | +- All shell commands on this Windows machine are executed via PowerShell. When constructing commands (e.g. for Godot CLI), ensure syntax is PowerShell-compliant (e.g. using $env:VARIABLE instead of %VARIABLE%). |
| 73 | +- CRITICAL: NEVER use destructive Git commands (like 'git checkout --orphan', 'git rm -rf .', or forcing branch switches) for local deployments. This wipes untracked and ignored files (like .claude/, .env, and local assets) from the disk. ALWAYS use GitHub Actions or isolated worktrees for deployment tasks to protect the user's workspace. Failure to do so causes catastrophic data loss. |
| 74 | +- ALWAYS ask for explicit user confirmation before pushing any changes to a remote repository (e.g., git push). Never assume permission to push, even for fixes. |
| 75 | + |
| 76 | +# Godot Commands |
| 77 | + |
| 78 | +- Godot binary: `godot` |
| 79 | +- GUT tests: `godot --headless -s addons/gut/gut_cmdln.gd -gdir=res://tests/ -gprefix=test_ -gexit 2>&1` |
| 80 | +- If doesn't work then `& "C:\Users\Grace\AppData\Local\Godot_v4.3\godot.exe" --headless -s addons/gut/gut_cmdln.gd -gdir=res://tests/ -gprefix=test_ -gexit 2>&1` (last resort) |
| 81 | +- ALWAYS try `godot` before using `& "C:\Users\Grace\AppData\Local\Godot_v4.3\godot.exe"` |
| 82 | +- Android exports that invoke the Gradle build must run on Java 17. Java 21 fails with `Invalid Java version 21. Version 17 is the required Java version for Godot gradle builds.` |
| 83 | +- On this machine, set `$env:JAVA_HOME = 'C:\Program Files\Microsoft\jdk-17.0.18.8-hotspot'` and prepend `$env:JAVA_HOME\bin` to `$env:Path` before running Android export or `android/build/gradlew.bat`. |
| 84 | +- If a CLI Android rebuild needs the signed fallback path, run `android/build_signed_debug.ps1` from the repo root instead of calling `gradlew assembleDebug` directly. |
| 85 | + |
| 86 | +# Automated Playtesting (MCP + Screenshots) |
| 87 | + |
| 88 | +- `tools/playtest_capture.gd` exists as a dev capture helper, but it is not currently registered in `project.godot` as an autoload. Add it temporarily when a session needs gameplay-event screenshots or scripted captures, then remove it again. |
| 89 | +- Screenshot output path (Windows): `C:\Users\Grace\AppData\Roaming\Godot\app_userdata\NekoDash\playtest_screenshots\` |
| 90 | +- `src/ui/web_capture_router.gd` is the only always-registered capture-related autoload. It ships with current exports because it is in `project.godot`, applies the Web viewport fix on HTML5 builds, and only routes capture flows when the build has the custom feature `dev_capture` and the URL includes `capture_ui=1`. |
| 91 | +- UI regression screenshot gate (required after UI edits): run `godot --path . --script tools/ui_snapshot_capture.gd 2>&1`, then inspect `user://playtest_screenshots/ui_verify/options_current.png`, `pause_current.png`, and `level_complete_current.png` before marking the task complete. |
| 92 | +- On Windows headless runs, `tools/ui_snapshot_capture.gd` can fail to produce images with the dummy renderer. When that happens, use `tools/web_ui_snapshot_capture.ps1` against a served `Web Dev Capture` export and inspect those PNGs instead. |
| 93 | +- Recommended playtest loop: |
| 94 | + 1. Launch scene with `mcp_godot_run_project` (`res://scenes/gameplay/gameplay.tscn`) |
| 95 | + 2. Read runtime logs via `mcp_godot_get_debug_output` |
| 96 | + 3. Open produced screenshots via `view_image` |
| 97 | + 4. Stop process via `mcp_godot_stop_project` |
| 98 | +- For end-to-end scripted movement tests, use `tools/playtest_runner.gd` as temporary autoload `PlaytestRunner`. |
| 99 | +- Remove any temporary playtest autoloads from `project.godot` after the run unless persistent auto-playtesting is intentionally desired. |
| 100 | +- Current export audit: see `docs/export-capture-audit.md`. Fresh May 10 Windows/Web/Android rebuilds exclude the dev-only capture, test, and editor tooling; use `Web Dev Capture` when browser-driven capture routing is required. Android packaging is verified again, but it depends on running the export under Java 17. |
0 commit comments