project_run
Launch your Godot project from the editor. Supports main, current, or custom scene modes and reports live game status.
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 | |||