@satelliteoflove/godot-mcp 3.4.1 → 3.6.0

package/addon/command_router.gd

@@ -21,6 +21,7 @@ func setup(plugin: EditorPlugin) -> void:
 	_register_handler(MCPScene3DCommands.new(), plugin)
 	_register_handler(MCPInputCommands.new(), plugin)
 	_register_handler(MCPProfilerCommands.new(), plugin)
+	_register_handler(MCPRuntimeStateCommands.new(), plugin)
 
 
 func _register_handler(handler: MCPBaseCommand, plugin: EditorPlugin) -> void:

package/addon/commands/runtime_state_commands.gd

@@ -0,0 +1,82 @@
+@tool
+extends MCPBaseCommand
+class_name MCPRuntimeStateCommands
+
+const GENERIC_TIMEOUT := 5.0
+var _last_error: Dictionary = {}
+
+
+func get_commands() -> Dictionary:
+	return {
+		"get_runtime_state": get_runtime_state,
+		"watch_start": watch_start,
+		"watch_collect": watch_collect,
+		"watch_stop": watch_stop,
+	}
+
+
+func get_runtime_state(params: Dictionary) -> Dictionary:
+	var result = await _send_and_wait("get_runtime_state", [params])
+	if result == null:
+		return _last_error
+	if result is Dictionary:
+		return _success(result)
+	return _success({"data": result})
+
+
+func watch_start(params: Dictionary) -> Dictionary:
+	var specs: Array = params.get("specs", [])
+	var hz: int = params.get("hz", 20)
+	var duration_ms: int = params.get("duration_ms", 1000)
+	var result = await _send_and_wait("watch_start", [specs, hz, duration_ms])
+	if result == null:
+		return _last_error
+	if result is Dictionary:
+		return _success(result)
+	return _success({"started": true})
+
+
+func watch_collect(_params: Dictionary) -> Dictionary:
+	var result = await _send_and_wait("watch_collect", [])
+	if result == null:
+		return _last_error
+	if result is Dictionary:
+		return _success(result)
+	return _success({"data": result})
+
+
+func watch_stop(_params: Dictionary) -> Dictionary:
+	var result = await _send_and_wait("watch_stop", [])
+	if result == null:
+		return _last_error
+	if result is Dictionary:
+		return _success(result)
+	return _success({"stopped": true})
+
+
+func _send_and_wait(msg_type: String, args: Array = []):
+	if not EditorInterface.is_playing_scene():
+		_last_error = _error("NOT_RUNNING", "No game is currently running")
+		return null
+
+	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
+	if debugger_plugin == null or not debugger_plugin.has_active_session():
+		_last_error = _error("NO_SESSION", "No active debug session")
+		return null
+
+	var sent: bool = debugger_plugin.send_game_message(msg_type, args)
+	if not sent:
+		_last_error = _error("SEND_FAILED", "Failed to send message to game")
+		return null
+
+	var start_time := Time.get_ticks_msec()
+	while not debugger_plugin.has_response(msg_type):
+		await Engine.get_main_loop().process_frame
+		if (Time.get_ticks_msec() - start_time) / 1000.0 > GENERIC_TIMEOUT:
+			debugger_plugin.clear_response(msg_type)
+			_last_error = _error("TIMEOUT", "Timed out waiting for %s response" % msg_type)
+			return null
+
+	var response = debugger_plugin.get_response(msg_type)
+	debugger_plugin.clear_response(msg_type)
+	return response

package/addon/commands/screenshot_commands.gd

@@ -2,7 +2,8 @@
 extends MCPBaseCommand
 class_name MCPScreenshotCommands
 
-const DEFAULT_MAX_WIDTH := 1920
+const DEFAULT_MAX_WIDTH := 1024
+const DEFAULT_JPEG_QUALITY := 75
 const SCREENSHOT_TIMEOUT := 5.0
 
 var _screenshot_result: Dictionary = {}
@@ -21,6 +22,7 @@ func capture_game_screenshot(params: Dictionary) -> Dictionary:
 		return _error("NOT_RUNNING", "No game is currently running. Use run_project first.")
 
 	var max_width: int = params.get("max_width", DEFAULT_MAX_WIDTH)
+	var quality: float = params.get("quality", DEFAULT_JPEG_QUALITY) / 100.0
 
 	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
 	if debugger_plugin == null:
@@ -33,7 +35,7 @@ func capture_game_screenshot(params: Dictionary) -> Dictionary:
 	_screenshot_result = {}
 
 	debugger_plugin.screenshot_received.connect(_on_screenshot_received, CONNECT_ONE_SHOT)
-	debugger_plugin.request_screenshot(max_width)
+	debugger_plugin.request_screenshot(max_width, quality)
 
 	var start_time := Time.get_ticks_msec()
 	while _screenshot_pending:
@@ -62,6 +64,7 @@ func _on_screenshot_received(success: bool, image_base64: String, width: int, he
 func capture_editor_screenshot(params: Dictionary) -> Dictionary:
 	var viewport_type: String = params.get("viewport", "")
 	var max_width: int = params.get("max_width", DEFAULT_MAX_WIDTH)
+	var quality: float = params.get("quality", DEFAULT_JPEG_QUALITY) / 100.0
 
 	var viewport: SubViewport = null
 
@@ -76,10 +79,10 @@ func capture_editor_screenshot(params: Dictionary) -> Dictionary:
 		return _error("NO_VIEWPORT", "Could not find editor viewport")
 
 	var image := viewport.get_texture().get_image()
-	return _process_and_encode_image(image, max_width)
+	return _process_and_encode_image(image, max_width, quality)
 
 
-func _process_and_encode_image(image: Image, max_width: int) -> Dictionary:
+func _process_and_encode_image(image: Image, max_width: int, quality: float = 0.75) -> Dictionary:
 	if image == null:
 		return _error("CAPTURE_FAILED", "Failed to capture image from viewport")
 
@@ -88,8 +91,8 @@ func _process_and_encode_image(image: Image, max_width: int) -> Dictionary:
 		var new_height := int(image.get_height() * scale_factor)
 		image.resize(max_width, new_height, Image.INTERPOLATE_LANCZOS)
 
-	var png_buffer := image.save_png_to_buffer()
-	var base64 := Marshalls.raw_to_base64(png_buffer)
+	var jpg_buffer := image.save_jpg_to_buffer(quality)
+	var base64 := Marshalls.raw_to_base64(jpg_buffer)
 
 	return _success({
 		"image_base64": base64,

package/addon/core/mcp_debugger_plugin.gd

@@ -97,14 +97,14 @@ func has_active_session() -> bool:
 	return true
 
 
-func request_screenshot(max_width: int = 1920) -> void:
+func request_screenshot(max_width: int = 1024, quality: float = 0.75) -> void:
 	if _active_session_id < 0:
 		screenshot_received.emit(false, "", 0, 0, "No active game session")
 		return
 	_pending_screenshot = true
 	var session := get_session(_active_session_id)
 	if session:
-		session.send_message("godot_mcp:take_screenshot", [max_width])
+		session.send_message("godot_mcp:take_screenshot", [max_width, quality])
 	else:
 		_pending_screenshot = false
 		screenshot_received.emit(false, "", 0, 0, "Could not get debugger session")

package/addon/game_bridge/mcp_game_bridge.gd

@@ -1,10 +1,12 @@
 extends Node
 class_name MCPGameBridge
 
-const DEFAULT_MAX_WIDTH := 1920
+const DEFAULT_MAX_WIDTH := 1024
+const DEFAULT_JPEG_QUALITY := 0.75
 
 var _logger: _MCPGameLogger
 var _profiler: MCPFrameProfiler
+var _sampler: MCPRuntimeStateSampler
 
 
 func _ready() -> void:
@@ -14,6 +16,8 @@ func _ready() -> void:
 	OS.add_logger(_logger)
 	_profiler = MCPFrameProfiler.new()
 	EngineDebugger.register_profiler("mcp_frame_profiler", _profiler)
+	_sampler = MCPRuntimeStateSampler.new()
+	add_child(_sampler)
 	EngineDebugger.register_message_capture("godot_mcp", _on_debugger_message)
 	MCPLog.info("Game bridge initialized")
 
@@ -89,16 +93,29 @@ func _on_debugger_message(message: String, data: Array) -> bool:
 		"get_signal_connections":
 			_handle_get_signal_connections(data)
 			return true
+		"get_runtime_state":
+			_handle_get_runtime_state(data)
+			return true
+		"watch_start":
+			_handle_watch_start(data)
+			return true
+		"watch_collect":
+			_handle_watch_collect()
+			return true
+		"watch_stop":
+			_handle_watch_stop()
+			return true
 	return false
 
 
 func _take_screenshot_deferred(data: Array) -> void:
 	var max_width: int = data[0] if data.size() > 0 else DEFAULT_MAX_WIDTH
+	var quality: float = data[1] if data.size() > 1 else DEFAULT_JPEG_QUALITY
 	await RenderingServer.frame_post_draw
-	_capture_and_send_screenshot(max_width)
+	_capture_and_send_screenshot(max_width, quality)
 
 
-func _capture_and_send_screenshot(max_width: int) -> void:
+func _capture_and_send_screenshot(max_width: int, quality: float = DEFAULT_JPEG_QUALITY) -> void:
 	var viewport := get_viewport()
 	if viewport == null:
 		_send_screenshot_error("NO_VIEWPORT", "Could not get game viewport")
@@ -111,8 +128,8 @@ func _capture_and_send_screenshot(max_width: int) -> void:
 		var scale_factor := float(max_width) / float(image.get_width())
 		var new_height := int(image.get_height() * scale_factor)
 		image.resize(max_width, new_height, Image.INTERPOLATE_LANCZOS)
-	var png_buffer := image.save_png_to_buffer()
-	var base64 := Marshalls.raw_to_base64(png_buffer)
+	var jpg_buffer := image.save_jpg_to_buffer(quality)
+	var base64 := Marshalls.raw_to_base64(jpg_buffer)
 	EngineDebugger.send_message("godot_mcp:screenshot_result", [
 		true,
 		base64,
@@ -374,6 +391,290 @@ func _node_path_string(node: Node, scene_root: Node) -> String:
 	return path
 
 
+func _handle_get_runtime_state(data: Array) -> void:
+	var params: Dictionary = data[0] if data.size() > 0 and data[0] is Dictionary else {}
+
+	var tree := get_tree()
+	var scene_root := tree.current_scene if tree else null
+	if not scene_root:
+		EngineDebugger.send_message("godot_mcp:game_response", ["get_runtime_state", {
+			"scene": "",
+			"selection": "fallback",
+			"entity_count": 0,
+			"entities": [],
+			"hint": "No scene is currently running.",
+		}])
+		return
+
+	var select_mode: String = params.get("select", "auto")
+	var group_name: String = params.get("group", "mcp_watch")
+	var name_filter: String = params.get("name", "")
+	var type_filter: String = params.get("type", "")
+	var max_nodes: int = params.get("max_nodes", 40)
+	var include_fields: Array = params.get("include", [])
+	max_nodes = clampi(max_nodes, 1, 200)
+
+	# Resolve camera for on-screen checks
+	var camera_2d: Camera2D = _find_camera_2d()
+	var camera_viewport_rect := Rect2()
+	if camera_2d:
+		camera_viewport_rect = camera_2d.get_viewport_rect()
+
+	# Determine which selection tier to use
+	var actual_selection: String = select_mode
+	if select_mode == "auto":
+		if _has_group_members(scene_root, group_name):
+			actual_selection = "group"
+		elif _has_mcp_state_nodes(scene_root):
+			actual_selection = "method"
+		else:
+			actual_selection = "fallback"
+
+	# Collect entities
+	var entities: Array = []
+	_collect_runtime_state(scene_root, scene_root, actual_selection, group_name,
+		name_filter, type_filter, include_fields, camera_2d, camera_viewport_rect,
+		max_nodes, entities)
+
+	# Extract camera entity separately if present
+	var camera_entity = null
+	var cam_node := _find_camera_2d() if actual_selection != "fallback" else camera_2d
+	if cam_node:
+		camera_entity = {
+			"type": "Camera2D",
+			"pos": {"x": snapped(cam_node.global_position.x, 0.01), "y": snapped(cam_node.global_position.y, 0.01)},
+			"zoom": {"x": snapped(cam_node.zoom.x, 0.01), "y": snapped(cam_node.zoom.y, 0.01)},
+			"camera": true,
+		}
+
+	var hint := ""
+	if actual_selection == "fallback":
+		hint = ("No nodes found in group '%s' and no _mcp_state() methods detected. " +
+			"For richer data: add key nodes to the '%s' group, then implement " +
+			"`func _mcp_state() -> Dictionary` on them. " +
+			"In _mcp_state(), include both live runtime values (position, health, score) " +
+			"AND static definition context (puzzle clues, level config, item data) — " +
+			"an agent needs both to understand and verify game state.") % [group_name, group_name]
+
+	var result: Dictionary = {
+		"scene": scene_root.scene_file_path,
+		"selection": actual_selection,
+		"entity_count": entities.size(),
+		"entities": entities,
+	}
+	if camera_entity:
+		result["camera"] = camera_entity
+	if not hint.is_empty():
+		result["hint"] = hint
+
+	EngineDebugger.send_message("godot_mcp:game_response", ["get_runtime_state", result])
+
+
+func _has_group_members(scene_root: Node, group_name: String) -> bool:
+	var tree := get_tree()
+	if tree == null:
+		return false
+	return tree.get_nodes_in_group(group_name).size() > 0
+
+
+func _has_mcp_state_nodes(node: Node) -> bool:
+	if node.has_method("_mcp_state"):
+		return true
+	for child in node.get_children():
+		if _has_mcp_state_nodes(child):
+			return true
+	return false
+
+
+func _collect_runtime_state(node: Node, scene_root: Node, selection: String, group_name: String,
+		name_filter: String, type_filter: String, include_fields: Array,
+		camera_2d: Camera2D, viewport_rect: Rect2,
+		max_nodes: int, results: Array) -> void:
+	if results.size() >= max_nodes:
+		return
+
+	var include_node := false
+	match selection:
+		"group":
+			include_node = node.is_in_group(group_name)
+		"method":
+			include_node = node.has_method("_mcp_state")
+		"fallback":
+			include_node = (node is CanvasItem and (node as CanvasItem).is_visible_in_tree())
+
+	if include_node:
+		if not name_filter.is_empty() and not node.name.matchn(name_filter):
+			include_node = false
+		if not type_filter.is_empty() and not node.is_class(type_filter):
+			include_node = false
+
+	if include_node:
+		var entity := _extract_node_state(node, scene_root, include_fields, camera_2d, viewport_rect)
+		if entity != null:
+			results.append(entity)
+
+	for child in node.get_children():
+		if results.size() >= max_nodes:
+			return
+		_collect_runtime_state(child, scene_root, selection, group_name,
+			name_filter, type_filter, include_fields, camera_2d, viewport_rect,
+			max_nodes, results)
+
+
+# _mcp_state() contract: return a Dictionary with two categories —
+#   (1) live runtime values that change during play (cursor pos, health, score, fill counts)
+#   (2) static definition context needed to interpret them (puzzle clues, level layout, config)
+# An agent can observe (1) without (2) but cannot verify correctness without both.
+# Optionally include layout geometry (bounds, sizes) to enable programmatic layout checks.
+# Error handling: _mcp_state() runtime errors are non-fatal in GDScript (Godot prints them
+# and the call returns null); the `is Dictionary` check below handles that silently.
+func _extract_node_state(node: Node, scene_root: Node, include_fields: Array,
+		camera_2d: Camera2D, viewport_rect: Rect2) -> Dictionary:
+	var want := include_fields.is_empty()
+	var want_transform := want or include_fields.has("transform")
+	var want_velocity := want or include_fields.has("velocity")
+	var want_anim := want or include_fields.has("anim")
+	var want_groups := want or include_fields.has("groups")
+	var want_onscreen := want or include_fields.has("onscreen")
+	var want_state := want or include_fields.has("state")
+
+	var entity: Dictionary = {
+		"path": _node_path_string(node, scene_root),
+		"type": node.get_class(),
+	}
+
+	if want_groups:
+		var groups := node.get_groups().filter(func(g): return not g.begins_with("_"))
+		if not groups.is_empty():
+			entity["groups"] = groups
+
+	if want_transform and node is Node2D:
+		var n2d := node as Node2D
+		entity["pos"] = {"x": snapped(n2d.global_position.x, 0.01), "y": snapped(n2d.global_position.y, 0.01)}
+		entity["rot"] = snapped(rad_to_deg(n2d.global_rotation), 0.01)
+		if n2d.scale != Vector2.ONE:
+			entity["scale"] = {"x": snapped(n2d.scale.x, 0.01), "y": snapped(n2d.scale.y, 0.01)}
+
+	if want_transform and node is Node3D:
+		var n3d := node as Node3D
+		entity["pos"] = {
+			"x": snapped(n3d.global_position.x, 0.01),
+			"y": snapped(n3d.global_position.y, 0.01),
+			"z": snapped(n3d.global_position.z, 0.01),
+		}
+		entity["rot"] = {
+			"x": snapped(rad_to_deg(n3d.global_rotation.x), 0.01),
+			"y": snapped(rad_to_deg(n3d.global_rotation.y), 0.01),
+			"z": snapped(rad_to_deg(n3d.global_rotation.z), 0.01),
+		}
+
+	if want_velocity:
+		if node is CharacterBody2D:
+			var v := (node as CharacterBody2D).velocity
+			entity["vel"] = {"x": snapped(v.x, 0.01), "y": snapped(v.y, 0.01)}
+		elif node is RigidBody2D:
+			var v := (node as RigidBody2D).linear_velocity
+			entity["vel"] = {"x": snapped(v.x, 0.01), "y": snapped(v.y, 0.01)}
+			entity["angvel"] = snapped((node as RigidBody2D).angular_velocity, 0.01)
+		elif node is CharacterBody3D:
+			var v := (node as CharacterBody3D).velocity
+			entity["vel"] = {"x": snapped(v.x, 0.01), "y": snapped(v.y, 0.01), "z": snapped(v.z, 0.01)}
+		elif node is RigidBody3D:
+			var v := (node as RigidBody3D).linear_velocity
+			entity["vel"] = {"x": snapped(v.x, 0.01), "y": snapped(v.y, 0.01), "z": snapped(v.z, 0.01)}
+			var av := (node as RigidBody3D).angular_velocity
+			entity["angvel"] = {"x": snapped(av.x, 0.01), "y": snapped(av.y, 0.01), "z": snapped(av.z, 0.01)}
+
+	if want_anim:
+		if node is AnimationPlayer:
+			var ap := node as AnimationPlayer
+			entity["anim"] = ap.current_animation
+			entity["anim_pos"] = snapped(ap.current_animation_position, 0.01)
+			entity["playing"] = ap.is_playing()
+		elif node is AnimatedSprite2D:
+			var asp := node as AnimatedSprite2D
+			entity["anim"] = asp.animation
+			entity["anim_frame"] = asp.frame
+
+	if want_onscreen and camera_2d and node is Node2D:
+		var pos := (node as Node2D).global_position
+		entity["onscreen"] = viewport_rect.has_point(pos)
+
+	if want_state and node.has_method("_mcp_state"):
+		var raw_state = node._mcp_state()
+		if raw_state is Dictionary:
+			var serialized := _serialize_mcp_state(raw_state)
+			if not serialized.is_empty():
+				entity["state"] = serialized
+
+	return entity
+
+
+const _MCP_STATE_MAX_BYTES := 1024
+
+
+func _serialize_mcp_state(state: Dictionary) -> Dictionary:
+	var result: Dictionary = {}
+	for key in state:
+		var val = state[key]
+		var serializable = null
+		match typeof(val):
+			TYPE_BOOL, TYPE_STRING:
+				serializable = val
+			TYPE_INT:
+				serializable = int(val)
+			TYPE_FLOAT:
+				serializable = snapped(float(val), 0.01)
+			TYPE_ARRAY:
+				serializable = val
+			TYPE_DICTIONARY:
+				serializable = val
+			# skip non-serializable types (Objects, NodePaths, RIDs, etc.)
+		if serializable == null:
+			continue
+		result[str(key)] = serializable
+		if JSON.stringify(result).length() > _MCP_STATE_MAX_BYTES:
+			result.erase(str(key))
+			result["_truncated"] = true
+			break
+	return result
+
+
+func _find_camera_2d() -> Camera2D:
+	var viewport := get_viewport()
+	if viewport == null:
+		return null
+	return viewport.get_camera_2d()
+
+
+func _handle_watch_start(data: Array) -> void:
+	if _sampler == null:
+		EngineDebugger.send_message("godot_mcp:game_response", ["watch_start", {"started": false, "error": "Sampler not initialized"}])
+		return
+	var specs: Array = data[0] if data.size() > 0 else []
+	var hz: int = data[1] if data.size() > 1 else 20
+	var duration_ms: int = data[2] if data.size() > 2 else 1000
+	var start_result := _sampler.start(specs, hz, duration_ms)
+	EngineDebugger.send_message("godot_mcp:game_response", ["watch_start", {
+		"started": true,
+		"resolved_fields": start_result.get("resolved_fields", 0),
+	}])
+
+
+func _handle_watch_collect() -> void:
+	if _sampler == null:
+		EngineDebugger.send_message("godot_mcp:game_response", ["watch_collect", {"window_ms": 0, "sample_count": 0, "fields": {}}])
+		return
+	EngineDebugger.send_message("godot_mcp:game_response", ["watch_collect", _sampler.collect()])
+
+
+func _handle_watch_stop() -> void:
+	if _sampler == null:
+		EngineDebugger.send_message("godot_mcp:game_response", ["watch_stop", {"window_ms": 0, "sample_count": 0, "fields": {}}])
+		return
+	EngineDebugger.send_message("godot_mcp:game_response", ["watch_stop", _sampler.stop()])
+
+
 class _MCPGameLogger extends Logger:
 	var _output: PackedStringArray = []
 	var _max_lines := 1000