Build godot games

Build Godot Games

Produce a runnable vertical slice before expanding content. Keep game rules deterministic, scenes composable, and every automated claim backed by a Godot run, a test, or a captured frame.

Choose the Path

• For a new project, run scripts/scaffold_game.py with an output path, a 2d or 3d dimension, and optional networking.
• For an existing project, run scripts/inspect_project.py, then trace the affected scenes, scripts, signals, resources, and autoloads before editing.
• For a broken project, reproduce the smallest failing path, record the error and expected behavior, patch one cause, then rerun the same path.
• For a card or turn-based game, keep rules in plain RefCounted/Resource classes and use nodes only for presentation and input.
• For online play, read references/networking.md before adding RPCs or trusting client state.

Runtime: Python 3.10+ and Godot 4.x Requirements

• Use Python 3.10 or newer for bundled scripts; no third-party Python package is required.
• Use an official Godot 4.x executable for parser, import, runtime, and rendered-frame checks.
• Provide a working graphical display for --visual; headless structural and smoke checks do not require one.
• Use network access only to install dependencies or publish when the user authorizes it. The scaffold and QA scripts themselves are local-first.

End-to-End Workflow

1. Write a vertical-slice contract containing the player loop, win/loss condition, controls, target platform, viewport, and acceptance checks.
2. Confirm the Godot major/minor version, renderer, and unfamiliar APIs against the installed editor or official class reference. Target Godot 4.x unless the project proves otherwise.
3. Establish scene ownership, typed data resources, signals, input actions, and save/network boundaries. Read references/architecture.md for the default layout.
4. Build one playable scene with placeholder visuals. Include movement, attack feedback, one enemy behavior, health/state UI, and restart or recovery.
5. Keep player intent separate from simulation. Put reusable health, cooldown, damage, state-machine, and targeting logic in components or plain classes.
6. Generate or import art only after collision sizes, camera framing, silhouettes, and timing work with placeholders. Read references/art-and-visual-qa.md before generating production assets.
7. Run scripts/inspect_project.py, then scripts/run_qa.py against the project. Add --gut only when GUT already exists, and add --visual when a display is available.
8. Fix failures from first cause to symptom: parser errors, missing resources, invalid node paths, input/state errors, physics/collision errors, then visual defects.
9. Rerun the game path and tests after every behavior change. Do not call a bug fixed from static inspection alone.
10. Expand content only after the vertical slice meets its acceptance checks.

Scaffold a Playable Baseline

python3 scripts/scaffold_game.py /path/to/game --dimension 2d --title "My Game"
python3 scripts/scaffold_game.py /path/to/game-3d --dimension 3d --networked
python3 scripts/inspect_project.py /path/to/game --json
python3 scripts/run_qa.py /path/to/game --require-godot

The generated project includes keyboard/gamepad movement, attack feedback, a pursuing enemy, health UI, procedural placeholder visuals, a QA screenshot hook, and optional ENet session setup. Treat it as a vertical-slice baseline, not a finished game framework.

Build Core Modules

• 2D player: use CharacterBody2D, normalized input, move_and_slide(), explicit attack/cooldown state, and collision layers with documented meaning.
• 3D player: move on the XZ plane relative to camera intent, separate body facing from camera control, and keep physics in _physics_process.
• Enemy AI: start with perceive, approach, attack, recover. Add navigation only when direct pursuit fails the level geometry.
• Combat: pass typed damage events or explicit parameters. Server authority decides hits in network games.
• UI: subscribe to signals; do not make HUD nodes poll or own gameplay state.
• Animation: let AnimationPlayer, AnimationTree, or Tweens present simulation state. Never make a visual animation the sole source of authoritative damage.
• Cards/turns: isolate zones, target validation, effect queues, seeded randomness, immutable results, and combat logs from the scene tree.

Read references/core-modules.md for implementation rules and acceptance checks, then references/scene-animation-and-card-patterns.md for composition details.

Validate and Repair

Run the narrowest useful checks first:

python3 scripts/run_qa.py /path/to/game
python3 scripts/run_qa.py /path/to/game --gut
python3 scripts/run_qa.py /path/to/game --visual --screenshot /tmp/game-frame.png
godot --headless --editor --path /path/to/game --quit
godot --headless --path /path/to/game --quit-after 180

When a visual check fails, inspect the captured frame itself. Check blank-frame ratio, color variance, viewport bounds, camera framing, UI clipping, z-order/depth, animation state, and placeholder/resource loading. Read references/debugging.md for the repair order.

Export a Verified Build

List and dry-run presets before creating an artifact:

python3 scripts/export_project.py /path/to/game --list
python3 scripts/export_project.py /path/to/game --preset Web --dry-run
python3 scripts/export_project.py /path/to/game --preset Web

Require matching export templates and test the exported artifact on the target platform. Read references/release-and-export.md before changing presets, permissions, signing, server features, or CI release jobs.

Guardrails

• Do not publish generated art unless its source, license, and model terms permit redistribution.
• Do not commit API keys, export credentials, private player data, paid assets, or editor caches.
• Do not promise automatic repair without rerunning the failing path.
• Do not use client RPC input as trusted game state.
• Do not invent uid:// values or commit .godot/ editor cache.
• Do not expand to inventory, quests, matchmaking, or live services until the requested vertical slice works.
• Preserve existing project conventions when extending a real repository.

Resources

• scripts/scaffold_game.py: generate a runnable Godot 4 2D or 3D baseline.
• scripts/inspect_project.py: emit a text or JSON project inventory and actionable findings.
• scripts/run_qa.py: validate structure, parse each script, run Godot/GUT checks, capture a frame, and inspect pixels.
• scripts/export_project.py: inspect and safely execute exact export presets.
• references/architecture.md: scene, data, signal, and test boundaries.
• references/api-and-project-inspection.md: version-aware API lookup, inventory, imports, parser checks, and GUT.
• references/core-modules.md: player, AI, combat, UI, animation, and card-game patterns.
• references/scene-animation-and-card-patterns.md: robust scene composition, animation ownership, and deterministic effect queues.
• references/art-and-visual-qa.md: asset pipeline and visual acceptance workflow.
• references/networking.md: authoritative ENet/RPC design and security.
• references/debugging.md: reproducible repair loop and failure taxonomy.
• references/release-and-export.md: export presets, artifact verification, and platform release gates.
• references/source-reshape-case-study.md: transferable engineering lessons from the Source Reshape card-battle project.
• references/acknowledgements.md: original authors and public skills that informed this workflow.