project_run
Run a Godot project scene (main, current, or custom) and receive live status on the game helper, session activity, and errors detected during playback.
Instructions
Run (play) the Godot project from the editor.
Modes:
"main": Run the project's main scene (default).
"current": Run the currently open scene.
"custom": Run a specific scene (requires
scene).
Idempotent: if the project is already running, returns success with
data.was_already_running=true (no scene switch). To switch scenes,
call project_manage(op="stop") first, then project_run again.
After starting playback, waits briefly for the Godot AI game helper to
check in. The response includes game_status, helper_live
(status == "live"), session_active (status not in {"not_live",
"stopped"}), and any recent_errors observed during the run window.
The top-level booleans mirror the same fields inside game_status.
game_status.status="not_live" means playback launched but the game
did not become live before the helper-ready window elapsed;
"no_helper" means the project has no _mcp_game_helper autoload, as
with some headless/custom-main-loop setups (helper_live=false,
session_active=true); "stopped" means playback stopped or never
became active before liveness could be confirmed (helper_live=false,
session_active=false); "break" means the game process is parked in
a remote-debugger break — during boot this is a GDScript parse/load
error that froze the game before the helper could register, and the
response names the failing script when captured
(game_status.break = {reason, can_debug, pre_live}). A game at
a break cannot continue on its own: call project_manage(op="stop"),
fix the error, and relaunch. Poll editor_state to see late
transitions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "main" | "current" | "custom". Default "main". | main |
| scene | No | Scene path (e.g. "res://levels/level1.tscn"). Required for "custom". | |
| autosave | No | When True (default), Godot persists in-memory MCP scene mutations to disk before running. Pass False for smoke tests where MCP edits should stay in memory. | |
| session_id | No | Optional Godot session to target. Empty = active session. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||