Play-test & debug

The live loop against a real running game. You ask in plain language; the assistant does the rest. Requires the runtime, input, testing, and debugger toolsets plus the MCPRuntimeProbe autoload in the game's project.

Two run modes — pick the right one

Under the hood

A headless run spawns a separate Godot process — a quick "does it even boot" smoke, no editor, no probe. A live play session drives the game inside the running editor, so you can inspect and steer it. The rest of this page is the live loop.

Mode	Toolset	Answers
Headless smoke test	runtime	"does it run at all" — no editor play session, no probe
Live play session	runtime + input + testing + debugger	interactive inspection, input, assertions, breakpoints

For a one-call report that covers the headless side, just ask the assistant to "run the debug workflow" — that needs no extra toolset.

1. Register the runtime probe

You: "Set up live runtime inspection — add the probe autoload if it's missing."

The assistant checks the project's autoloads and, if the probe isn't registered, adds it. The probe runs in the game (not the editor) and no-ops in exported builds.

2. Play and inspect

You: "Play the main scene and show me the Player's position over time."

The assistant starts a live play session, then can read the running game's real hierarchy (not the editor's copy), sample a property over frames, find UI by its text, and read performance monitors. Pending reads carry a reason token (e.g. capture_pending) — the assistant keeps polling rather than re-issuing.

3. Simulate input

You: "Hold right, release, then press Space."

The assistant synthesizes key, mouse, and action input into the running game, can replay a recorded sequence or record a macro, and reports how many events the game acknowledged. While the game is paused at a debugger break, input is refused — the assistant continues execution first. A frozen injected count is the pause signal, not a bug.

4. Assert state

You: "Assert the Player is visible, then fuzz it with random input."

The assistant asserts live node state, runs a scripted scenario (a sequence of events plus assertions), fuzzes with random input, and compares screenshots — so behavior is checked, not just "it didn't crash".

5. Break and step

You: "Set a breakpoint on player.gd line 42 and step through it."

The assistant sets a breakpoint; breakpoints fire on their own line. A forced break lands on the probe's next frame (no game cooperation needed). Once stopped, it can step over/into/out, evaluate an expression in the running game (evaluate_expression — global scope, not frame-scoped), and continue. The paused-frame stack / variable dump (get_stack_frames, get_frame_variables) is not available on Godot 4.7 (#677).

See the scene (screenshots)

You: "Take a screenshot so you can see the current layout."

The assistant can look at the scene, not just read it — for clients that accept images. Two captures, and you pick by what you want to see:

Tool	Shows	Needs
godot_editor_capture_screenshot	the editor viewport — the scene tab, layout, and gizmos you're looking at	the editor toolset; the editor must be drawing a frame
godot_runtime_capture_game_screenshot	the running game's rendered frame — the actual pixels the player sees	a live play session (runtime) + the probe

Both come back as a base64 PNG image block over the same bridge round-trip: the addon grabs get_viewport().get_texture().get_image() and returns it, and the server hands it to the model as an image. Honest caveats — if the editor window isn't drawing (minimized or unfocused) the editor capture reports editor_not_drawing; a capture taken while the game is paused at a breakpoint shows the frozen frame, not a fresh one. Captures are read_only.

Use it to answer "does this actually look right?" — layout, HUD placement, a sprite that isn't showing — then diff two frames with godot_testing_compare_screenshots to catch a regression.

Debugging failures

Symptom	First move
Crash on play	ask for a headless run and read the errors/warnings
timed_out: true	not a crash — games that never self-quit always time out; tell the assistant the timeout is expected
Script "won't parse"	ask for a parse check; if it flags rescan_pending, re-check before "fixing"
Input does nothing	is the game playing? is the probe registered? a full-screen overlay eating input? paused at a break?
Stuck	ask the assistant for the server info's next_steps, or use the troubleshoot prompt

Ask the assistant to stop the play session when you're done.