Report game liveness from project_run (#606)

Author: Clubhouse1661

docs/TOOLS.md

@@ -14,7 +14,7 @@ not the MCP tool names.
 
 | Tool | Description |
 |------|-------------|
-| `editor_state` | Editor version, project name, current scene, readiness, play state |
+| `editor_state` | Editor version, project name, current scene, readiness, play state, and game liveness status |
 | `scene_get_hierarchy` | Paginated scene tree walk (depth, offset, limit) |
 | `node_get_properties` | Full property snapshot of a node |
 | `session_activate` | Pin subsequent calls to a specific connected editor |
@@ -27,7 +27,7 @@ not the MCP tool names.
 | `node_create` / `node_set_property` / `node_find` | Common node writes + search |
 | `scene_open` / `scene_save` | Open and save scenes |
 | `script_create` / `script_attach` / `script_patch` | Create, attach, anchor-edit GDScript files |
-| `project_run` | Play the project (autosave persists in-memory MCP edits unless `autosave=False`) |
+| `project_run` | Play the project, then wait briefly for game liveness (autosave persists in-memory MCP edits unless `autosave=False`) |
 | `test_run` | Run GDScript test suites in the editor |
 | `logs_read` | Read plugin / game / editor / combined log buffers. `source="editor"` surfaces parse errors, GDScript reload warnings, @tool/EditorPlugin runtime errors, push_error/push_warning, and visible Debugger dock Errors-tab rows — use this when the editor's Output or Debugger Errors panel shows red/yellow rows |
 | `editor_screenshot` | Capture editor viewport, cinematic camera, or running game framebuffer |
@@ -40,6 +40,27 @@ Godot `_log_error` code/rationale when available, error type, resolved source
 location, and stack/error-tree context corresponding to the Debugger dock's
 Errors tab.
 
+`project_run` starts playback and waits briefly for the running game to become
+live through `_mcp_game_helper`. Its response includes `game_status`,
+`helper_live`, `session_active`, and any `recent_errors` found while waiting.
+The booleans are derived once inside `game_status` and mirrored at the top
+level for convenience.
+`game_status.status="live"` means the helper checked in. `"not_live"` means the
+game launched but did not become live before the helper-ready window elapsed;
+if a run-scoped parse/load error appeared, the response names it and points to
+`logs_read(source="editor", include_details=true)`. `"no_helper"` means the
+game launched but this project has no `_mcp_game_helper` autoload, as with some
+headless/custom-main-loop setups: `helper_live=false` while
+`session_active=true`. `"launching"` is a soft "not live yet" state and can
+reconcile on a later `editor_state` poll.
+
+`editor_state` includes the same `game_status` object in addition to the legacy
+`is_playing` boolean and `game_capture_ready`. It also mirrors
+`game_status.helper_live` (`game_status.status=="live"`) and
+`game_status.session_active` (`game_status.status` is not `"not_live"` or
+`"stopped"`). `is_playing` remains raw editor play-state for compatibility; use
+`game_status.status` for liveness decisions.
+
 For game logs, `logs_read(source="game")` returns lines from the current game
 run only. Each play-start creates a new `run_id`, even if the game never reaches
 the `_mcp_game_helper` hello beacon; prior run lines stay retained but do not
@@ -51,12 +72,15 @@ one. There is no single `source="game"` call that returns every retained game
 line across all runs; consumers that need history should retain run ids and
 query each run explicitly.
 
-Game and combined log responses also include `game_status` and a liveness-based
-`is_running`. `is_running` is no longer raw editor play-state: it is `false` for
+Game and combined log responses also include `game_status`, `helper_live`, and
+`session_active`; the top-level booleans mirror `game_status.helper_live` and
+`game_status.session_active`. For compatibility, `is_running` is retained as an
+alias of `session_active`; it is no longer raw editor play-state. Both are `false` for
 `game_status.status` of `"not_live"` or `"stopped"`, and `true` for `"live"`,
 `"launching"`, or `"no_helper"`. This lets a parse/load failure that leaves the
 editor play button active report as not running, while a legitimate headless or
-custom-main-loop project without `_mcp_game_helper` remains running with
+custom-main-loop project without `_mcp_game_helper` remains active with
+`helper_live=false`, `session_active=true`, and
 `game_status.status="no_helper"`.
 
 For incremental editor-log polling, call `logs_read(source="editor")` once and

plugin/addons/godot_ai/debugger/mcp_debugger_plugin.gd

@@ -142,6 +142,14 @@ func is_game_capture_ready() -> bool:
 	return _game_run_active and _game_ready and _ready_run_token == _game_run_token
 
 
+static func with_liveness_flags(status: Dictionary) -> Dictionary:
+	var enriched := status.duplicate(true)
+	var state := str(enriched.get("status", "stopped"))
+	enriched["helper_live"] = state == "live"
+	enriched["session_active"] = not state in ["not_live", "stopped"]
+	return enriched
+
+
 func get_game_status(now_msec: int = -1, ready_wait_sec: float = GAME_READY_WAIT_SEC) -> Dictionary:
 	var resolved_now := Time.get_ticks_msec() if now_msec < 0 else now_msec
 	var ready_wait_msec := maxi(0, int(ready_wait_sec * 1000.0))
@@ -157,7 +165,7 @@ func get_game_status(now_msec: int = -1, ready_wait_sec: float = GAME_READY_WAIT
 			status = "not_live"
 		else:
 			status = "launching"
-	return {
+	return with_liveness_flags({
 		"status": status,
 		"run_token": _game_run_token,
 		"active": _game_run_active,
@@ -167,12 +175,12 @@ func get_game_status(now_msec: int = -1, ready_wait_sec: float = GAME_READY_WAIT
 		"elapsed_msec": elapsed_msec,
 		"ready_wait_msec": ready_wait_msec,
 		"editor_log_cursor": _game_run_started_editor_cursor,
-	}
+	})
 
 
 func _explain_not_live(status: Dictionary, code: String = ErrorCodes.INTERNAL_ERROR) -> Dictionary:
 	var state := str(status.get("status", "stopped"))
-	var errors_info := _recent_editor_errors_since(int(status.get("editor_log_cursor", 0)))
+	var errors_info := recent_editor_errors_since(int(status.get("editor_log_cursor", 0)))
 	var recent_errors: Array = errors_info.get("errors", [])
 	var recent_errors_scope := str(errors_info.get("scope", "none"))
 	var truncated := bool(errors_info.get("truncated", false))
@@ -209,6 +217,10 @@ func _explain_not_live(status: Dictionary, code: String = ErrorCodes.INTERNAL_ER
 	return err
 
 
+func recent_editor_errors_since(cursor: int) -> Dictionary:
+	return _recent_editor_errors_since(cursor)
+
+
 func _recent_editor_errors_since(cursor: int) -> Dictionary:
 	var out: Array[Dictionary] = []
 	var truncated := false

plugin/addons/godot_ai/dispatcher.gd

@@ -16,6 +16,7 @@ const DEFAULT_DEFERRED_TIMEOUT_MS := 4500
 const DEFERRED_TIMEOUT_MS_BY_COMMAND := {
 	"create_script": 4500,
 	"stop_project": 4500,
+	"run_project": 6000,
 	"take_screenshot": 30000,
 	"game_eval": 15000,
 	"game_command": 15000,

plugin/addons/godot_ai/handlers/editor_handler.gd

@@ -28,6 +28,7 @@ func _init(log_buffer: McpLogBuffer, connection: McpConnection = null, debugger_
 
 func get_editor_state(_params: Dictionary) -> Dictionary:
 	var scene_root := EditorInterface.get_edited_scene_root()
+	var game_status := _current_game_status()
 	var data := {
 		"godot_version": Engine.get_version_info().get("string", "unknown"),
 		"project_name": ProjectSettings.get_setting("application/config/name", ""),
@@ -38,6 +39,9 @@ func get_editor_state(_params: Dictionary) -> Dictionary:
 		## false between Play→Stop cycles. Lets capture-source=game callers
 		## poll for a real ready signal instead of guessing with sleep().
 		"game_capture_ready": _debugger_plugin != null and _debugger_plugin.is_game_capture_ready(),
+		"game_status": game_status,
+		"helper_live": bool(game_status.get("helper_live", false)),
+		"session_active": bool(game_status.get("session_active", false)),
 	}
 	## Half-installed addon tree from a failed self-update rollback. When
 	## non-empty, the agent / dock paint the operator-facing recovery copy
@@ -93,20 +97,15 @@ func get_logs(params: Dictionary) -> Dictionary:
 
 func _current_game_status() -> Dictionary:
 	if _debugger_plugin == null:
-		return {
+		return McpDebuggerPlugin.with_liveness_flags({
 			"status": "stopped",
 			"active": false,
 			"ready": false,
 			"helper_expected": true,
-		}
+		})
 	return _debugger_plugin.get_game_status()
 
 
-func _is_game_log_running(game_status: Dictionary) -> bool:
-	var status := str(game_status.get("status", "stopped"))
-	return not status in ["not_live", "stopped"]
-
-
 func _get_plugin_logs(count: int, offset: int) -> Dictionary:
 	var all_lines := _log_buffer.get_recent(_log_buffer.total_count())
 	var page: Array[Dictionary] = []
@@ -126,6 +125,8 @@ func _get_plugin_logs(count: int, offset: int) -> Dictionary:
 
 func _get_game_logs(count: int, offset: int, include_details: bool, since_run_id: String = "") -> Dictionary:
 	var game_status := _current_game_status()
+	var helper_live := bool(game_status.get("helper_live", false))
+	var session_active := bool(game_status.get("session_active", false))
 	if _game_log_buffer == null:
 		return {
 			"data": {
@@ -136,7 +137,9 @@ func _get_game_logs(count: int, offset: int, include_details: bool, since_run_id
 				"offset": offset,
 				"run_id": "",
 				"current_run_id": "",
-				"is_running": false,
+				"is_running": session_active,
+				"helper_live": helper_live,
+				"session_active": session_active,
 				"game_status": game_status,
 				"dropped_count": 0,
 				"stale_run_id": false,
@@ -156,7 +159,9 @@ func _get_game_logs(count: int, offset: int, include_details: bool, since_run_id
 			"offset": offset,
 			"run_id": target_run_id,
 			"current_run_id": current_run_id,
-			"is_running": _is_game_log_running(game_status),
+			"is_running": session_active,
+			"helper_live": helper_live,
+			"session_active": session_active,
 			"game_status": game_status,
 			"dropped_count": _game_log_buffer.dropped_count(),
 			"stale_run_id": stale_run_id,
@@ -266,7 +271,9 @@ func _get_all_logs(count: int, offset: int, include_details: bool) -> Dictionary
 			"offset": offset,
 			"run_id": run_id,
 			"current_run_id": current_run_id,
-			"is_running": _is_game_log_running(game_status),
+			"is_running": bool(game_status.get("session_active", false)),
+			"helper_live": bool(game_status.get("helper_live", false)),
+			"session_active": bool(game_status.get("session_active", false)),
 			"game_status": game_status,
 			"dropped_count": dropped,
 		}