Playtest loop

The runtime and input groups reach the running game, a separate process from the editor. The editor brokers that hop over file IPC, so you can drive and inspect a live playtest.

Play, drive, inspect, stop#

godot-mcp scene play --mode main
godot-mcp runtime tree
godot-mcp input action --action ui_accept --pressed true
godot-mcp runtime get --node-path Player --properties '["position", "velocity"]'
godot-mcp runtime screenshot --save-path user://shot.png
godot-mcp scene stop

runtime.screenshot works even under a headless editor, because the game is a separate windowed process.

Wait for a signal#

runtime.await_signal blocks until a signal fires on a node in the running game and returns its serialized arguments:

godot-mcp runtime await-signal --node-path Player --signal died --timeout 10

A timeout returns fired: false as a success payload, so an agent can branch on it rather than treating it as an error.

Poll runtime errors#

runtime.errors returns structured errors and warnings the running game captured through an OS.add_logger hook:

godot-mcp runtime errors --clear

Each entry is { kind, message, code, backtrace[] } with the real game-script frame in backtrace[0]. It is pull-based: the agent polls on demand, and runtime errors are unambiguously real.

Debug the running game#

The debug group turns a playtest into a debugging session. Breakpoints are armed through the editor’s own script gutter, so they show in the gutter and the Breakpoints list, persist for later runs, and hit a game that is already running, with no restart:

godot-mcp debug set-breakpoint --path res://player.gd --line 42
godot-mcp debug state                          # paused? reason, stack, variables
godot-mcp debug frame --index 1                # another stack frame's variables
godot-mcp debug step --mode over               # also: into, out
godot-mcp debug resume
godot-mcp debug pause                          # break into a game that is running
godot-mcp debug clear-breakpoints

The guardrails do the thinking with you: a line that can never be hit (a blank, a comment, a declaration) is refused with the first executable line suggested instead, and arming a per-frame callback like _process comes with a warning, because every resume would re-break immediately.

Edited a script while the game is paused on a bug? Push the fix into the live process:

godot-mcp debug resume
godot-mcp debug reload-scripts        # every .gd changed since the run started

Every live instance starts running the new code and keeps the state it had. Any run started by scene play accepts reloads (it launches with the editor’s script-sync options armed); a run launched by hand needs both Synchronize options ticked in the editor’s Debug menu.

Direct-to-player channel#

Everything above brokers through the open editor. You can also drive a standalone running game with no editor at all, which suits QA rigs and packaged dev builds. Enable Project → Project Settings → Godot Mcp → Runtime → Direct Server, run a debug build of the game, then add the --game flag:

godot-mcp --game runtime tree
godot-mcp --game runtime eval --code "emit(1 + 1)"
godot-mcp --game input action --action ui_accept --pressed true

The game hosts its own 127.0.0.1-only WebSocket server (ports 9200-9215, GODOT_MCP_GAME_PORT pins one) and writes a discovery file in its user:// dir, so --game finds it automatically from inside the project. The runtime.* and input.* commands behave identically to the editor-brokered path.