Godot (MCP + headless) for Rogue Gauntlet

Purpose

Validate real Godot behavior — scene/resource loading, UID resolution, mesh-library
alignment, editor-authored data, runtime smoke checks — and author/edit .tres/.tscn
correctly. Keep ordinary C# verification on dotnet build; reach for Godot only when the
task depends on scenes, resources, or runtime behavior.

Project setup

• Project root: the repo root. In a git worktree the root is the worktree directory.
• Gameplay scene: res://scenes/main/main.tscn — run this for level-generation/gameplay checks.
• Project main scene: res://scenes/menu/main_menu.tscn.
• Godot binary: /Applications/Godot_mono.app/Contents/MacOS/Godot (the mono/C# build; not Godot.app). Use scripts/godot.sh to resolve it automatically.
• dotnet binary: /usr/local/share/dotnet/dotnet — it is not on the agent shell's PATH.

Gotchas

Concrete corrections — each is a mistake that happens without being told otherwise:

• dotnet is not on PATH. A bare dotnet build fails with "command not found". Use
  /usr/local/share/dotnet/dotnet build "Rogue Gauntlet.sln".
• Import before headless-loading any resource. A fresh or worktree checkout has no
  .godot/imported/ cache, so loading a .tres/scene fails with
  Unable to open file: res://.godot/imported/...ctex|.scn plus cascading parse errors that
  look real but are not. Run the import step (below) once first.
• Wrong Godot binary. The MCP server may default to /Applications/Godot.app/... and
  report spawn ... ENOENT. Fall back to the local binary via scripts/godot.sh.
• Worktree path discipline. When in a worktree, the project root is the worktree dir, not
  the main checkout. Pass --path "<worktree>" to Godot and use absolute worktree paths when
  editing, or builds/edits silently hit the wrong tree.
• One [GlobalClass] Resource per .cs file. A .tres references a script by file, so
  multiple resource classes in one file make sub-resource typing ambiguous and break loads. A
  plain enum may share a file. (Detail: references/tres-authoring.md.)
• New C# scripts need a .cs.uid sidecar that .tres files reference; the import step
  generates it. (Detail: references/tres-authoring.md.)
• GDScript can validate C# without a test project. A loaded resource exposes public C#
  properties via obj.get("PropName") — even computed, non-[Export] ones — and public
  methods via obj.call("Method", args), but only when the signature is Godot-marshalable.
  Methods taking object or generic IEnumerable<T> are not exposed (has_method returns
  false); give logic you want to probe simple/Godot-typed signatures.
• Shutdown noise. Headless leak/ObjectDB "resources still in use / leaked at exit" messages
  on forced quit are noise unless preceded by real load/script/resource errors during the run.
• Headless navmesh bake error is expected. A headless main.tscn run prints an error +
  C# backtrace from NavigationRegion3D.BakeNavigationMesh (MapGenerator.BakeNavigationMesh);
  generation continues and logs Map generated. It is a NavigationServer-in-headless
  limitation, not a real failure. Confirm Map generated. and that the player spawns; bake
  navmesh visually in the editor when it actually matters.
• Bulk-generating files via Bash bypasses the Read-before-Write safety check. Writing many
  new files at once (e.g. a script/heredoc loop creating a batch of wrapper .tscns) is easy to
  reach for over N individual Write calls, but it skips the "must Read before overwrite"
  protection Write gets — a filename collision with an existing (even orphaned/dead) file
  silently clobbers it with no diff shown. Check git status/existence for every target
  filename first, or use Write per-file when the count is manageable.
• A model that renders fine in the item catalog can still be broken when equipped. See the
  assets skill's in-hand verification section — floating-and-auto-framed vs. bone-attached
  are different enough contexts that one passing does not imply the other passes.
• _ready() on freshly-added nodes is deferred, not synchronous. In a --script main-loop
  script, some_node.add_child(x) does NOT run x's (or an autoload's) _ready() before the
  next call returns — it fires on a later frame. Calling logic that depends on a node's own
  _ready()-wired references (e.g. MapGenerator.GenerateMap(), which needs its GridMap child
  refs) immediately after add_child runs against not-yet-initialized state and silently
  produces empty/wrong results, no error printed. Wait at least one _process() tick after
  adding the node before calling into it (see render_level_topdown.gd's state machine).

Core workflow

1. Compile: /usr/local/share/dotnet/dotnet build "Rogue Gauntlet.sln" (the default check
   for any C# change; do this before touching Godot).
2. Import (only after adding/changing scripts or resources, or on a fresh/worktree checkout):
   scripts/godot.sh --headless --path "$PWD" --import. This builds the import cache and
   generates .cs.uid sidecars.
3. Validate / smoke-test the specific thing that changed — a resource load, a scene boot,
   or a logic probe (below). Prefer a targeted scene + seed over the whole game.

Commands

# Compile (default verification)
/usr/local/share/dotnet/dotnet build "Rogue Gauntlet.sln"

# Build the import cache + UIDs (run from the project/worktree root)
.agents/skills/godot-mcp/scripts/godot.sh --headless --path "$PWD" --import

# Headless gameplay smoke (spawns player + level, then quits after N frames)
.agents/skills/godot-mcp/scripts/godot.sh --headless --path "$PWD" res://scenes/main/main.tscn --quit-after 150

# Launch the editor for visual checks (GridMaps, tiles, lighting, UI)
.agents/skills/godot-mcp/scripts/godot.sh --editor --path "$PWD"

Headless validation harness

Run a GDScript file as the main loop to exercise the project without the editor:
scripts/godot.sh --headless --path "$PWD" --script <file.gd> -- <args...>. The script
extends SceneTree, does its work in _init(), reads args after -- via
OS.get_cmdline_user_args(), and calls quit().

• Validate a resource loads and reads back correctly (use after hand-authoring a .tres):

  .agents/skills/godot-mcp/scripts/godot.sh --headless --path "$PWD" --script \
    .agents/skills/godot-mcp/scripts/inspect_resource.gd -- res://path/to/new.tres

• Probe C# logic for a one-off check: write a small extends SceneTree script in the
  scratchpad that loads a resource and calls its marshalable methods / reads its properties
  (see the GDScript gotcha above), then run it with --script. Do not commit one-offs.

Visual verification: top-down level/room screenshots

Reasoning about tile coordinates or trusting an editor-only gizmo (e.g. DoorwayMarker's arrow,
which only draws inside the actual Godot editor process) can't confirm what a generated level or
room actually looks like. scripts/render_level_topdown.gd renders a real top-down screenshot of
a generated level instead, with an overlay drawn straight from MapGenerator.GetConnectorDebugInfo()
(Godot-native return types, since MapData itself can't marshal to GDScript) showing every
connector's position and per-direction open (green) / sealed (red) status, plus doorway (yellow)
vs inferred (cyan) markers. This must run windowed, not headless — the headless renderer
produces blank images:

.agents/skills/godot-mcp/scripts/godot.sh --path "$PWD" --script \
  .agents/skills/godot-mcp/scripts/render_level_topdown.gd -- <outfile.png> [seed] [image_size]

Then Read the resulting PNG to inspect it. Use this whenever a change to room layout, doorway
placement, wall generation, or rotation needs a visual sanity check instead of (or in addition to)
numeric probes/tests — e.g. confirming a doorway's connector tile is flush with its wall gap, or
that a rotated room's markers still point the right way.

MCP tools

When the MCP server is correctly configured, prefer it for editor/runtime interaction:
godot_get_project_info (open check), godot_launch_editor, godot_run_project +
godot_get_debug_output + godot_stop_project (run and inspect), godot_get_uid /
godot_update_project_uids (UID issues), godot_export_mesh_library (intentional library
changes). If MCP reports ENOENT on Godot.app, use scripts/godot.sh via Bash instead.

Bundled scripts

• scripts/godot.sh — resolves the working Godot binary and runs it with the given args.
• scripts/inspect_resource.gd — loads one or more res:// resources and prints their script
  properties; reports OK/FAIL/MISSING per path. The reusable resource validator.
• scripts/render_level_topdown.gd — renders a windowed top-down screenshot of a generated
  level with a connector/doorway overlay. See "Visual verification" above.

Authoring .tres / .tscn by text

Before creating or editing a .tres/.tscn in a text editor (rather than the Godot editor),
read references/tres-authoring.md — it covers load_steps counting, enum-as-int and
array serialization, sub-resource layout, the one-[GlobalClass]-per-file rule, UID sidecars,
the missing-res://-prefix trap, and the wrapper-.tscn pattern for correcting a raw model's
grip orientation or scale. Always validate the result with inspect_resource.gd.

Rules

• Do not replace dotnet build with Godot's C# solution build on this machine; the Godot CLI
  solution build times out with engine shutdown errors. Use dotnet.
• Do not commit temporary probe scenes/scripts. Put one-offs in the scratchpad; if a
  res://tmp_* file is unavoidable, delete it before finishing.
• Do not edit .tscn/.tres blindly when a visual result matters; launch the editor or build
  a focused test scene.
• Prefer deterministic checks: run a specific scene and seed when debugging generation.
• Keep this skill focused on Godot-specific validation; do not use it for general file search
  or ordinary C# refactors.