@satelliteoflove/godot-mcp 3.11.0 → 3.13.0

package/addon/commands/game_time_commands.gd

@@ -4,10 +4,11 @@ class_name MCPGameTimeCommands
 
 # Game-time control relay: freeze / step / step_until / thaw / status execute in
 # the game bridge (see mcp_game_bridge.gd); this side only forwards over the
-# debugger channel and waits. Timeout cascade: a step/step_until request is
-# capped at 20s of game time and the bridge's wall budget returns by 25s, so the
-# 28s relay timeout below fires only if the bridge is gone — and stays under the
-# server's 30s command timeout so errors surface typed instead of generic.
+# debugger channel and waits. Timeout cascade (#276): the server derives the
+# whole stagger from the call's in-game budget and pushes relay_timeout_ms down
+# in params; we wait exactly that long, so the bridge (which returns by its
+# pushed wall budget) answers first and errors surface typed. BASE_TIMEOUT and
+# STEP_TIMEOUT are fallbacks only — for an older server that pushes no budget.
 const BASE_TIMEOUT := 10.0
 const STEP_TIMEOUT := 28.0
 
@@ -29,11 +30,11 @@ func game_time_freeze(params: Dictionary) -> Dictionary:
 
 
 func game_time_step(params: Dictionary) -> Dictionary:
-	return await _relay("game_time_step", [params], STEP_TIMEOUT)
+	return await _relay("game_time_step", [params], _relay_timeout(params, STEP_TIMEOUT))
 
 
 func game_time_step_until(params: Dictionary) -> Dictionary:
-	return await _relay("game_time_step_until", [params], STEP_TIMEOUT)
+	return await _relay("game_time_step_until", [params], _relay_timeout(params, STEP_TIMEOUT))
 
 
 func game_time_thaw(params: Dictionary) -> Dictionary:
@@ -44,6 +45,13 @@ func game_time_status(params: Dictionary) -> Dictionary:
 	return await _relay("game_time_status", [params], BASE_TIMEOUT)
 
 
+func _relay_timeout(params: Dictionary, fallback: float) -> float:
+	# Use the server-pushed relay budget when present (#276); the local constant
+	# is only a fallback for an older server that does not derive the cascade.
+	var ms: float = float(params.get("relay_timeout_ms", fallback * 1000.0))
+	return ms / 1000.0
+
+
 func _relay(msg_type: String, args: Array, timeout: float) -> Dictionary:
 	var response = await _send_and_wait(msg_type, args, timeout)
 	if response == null:

package/addon/commands/input_commands.gd

@@ -14,6 +14,9 @@ var _input_map_pending: bool = false
 
 var _sequence_result: Dictionary = {}
 var _sequence_pending: bool = false
+# Frames captured mid-sequence (#239), collected from sequence_capture_received
+# signals and attached to the result once the sequence completes.
+var _sequence_captures: Array = []
 
 
 var _type_text_result: Dictionary = {}
@@ -31,19 +34,30 @@ func get_commands() -> Dictionary:
 	}
 
 
+# Total wall budget for a long-running input command. The server derives the
+# whole cascade and pushes relay_timeout_ms down in params (#276); the local
+# fallback is used only for an older server that pushes no budget.
+func _pushed_budget(params: Dictionary, fallback: float) -> float:
+	if params.has("relay_timeout_ms"):
+		return float(params["relay_timeout_ms"]) / 1000.0
+	return fallback
+
+
 # Block until the running game's bridge reports it can consume input, bounded by
-# READY_TIMEOUT. Returns true once ready, false if the game stops or never comes
-# up in time. In the common case (game already running) this returns immediately
-# without waiting a frame. Gating input on this is the fix for #241: the debug
-# session connects before the main scene loads, so input dispatched on
-# has_active_session() alone lands in a game with nothing to receive it.
-func _await_bridge_ready(debugger_plugin) -> bool:
-	var start_time := Time.get_ticks_msec()
+# READY_TIMEOUT and the shared call deadline (op_start + total_budget) so the
+# ready-wait can never eat the budget the command itself needs (#276). Returns
+# true once ready, false if the game stops or never comes up in time. In the
+# common case (game already running) this returns immediately without waiting a
+# frame. Gating input on this is the fix for #241: the debug session connects
+# before the main scene loads, so input dispatched on has_active_session() alone
+# lands in a game with nothing to receive it.
+func _await_bridge_ready(debugger_plugin, op_start: int, total_budget: float) -> bool:
 	while not debugger_plugin.is_bridge_ready():
 		if not EditorInterface.is_playing_scene():
 			return false  # game stopped or crashed while we waited
 		await Engine.get_main_loop().process_frame
-		if (Time.get_ticks_msec() - start_time) / 1000.0 > READY_TIMEOUT:
+		var elapsed := (Time.get_ticks_msec() - op_start) / 1000.0
+		if elapsed > READY_TIMEOUT or elapsed > total_budget:
 			return false
 	return true
 
@@ -132,6 +146,8 @@ func _on_input_map_received(actions: Array, error: String) -> void:
 func execute_input_sequence(params: Dictionary) -> Dictionary:
 	var inputs: Array = params.get("inputs", [])
 	var report: Array = params.get("report", [])
+	var screenshots: Array = params.get("screenshot_at_ms", [])
+	var screenshot_max_width: int = int(params.get("screenshot_max_width", 640))
 	if inputs.is_empty():
 		return _error("INVALID_PARAMS", "inputs array is required and must not be empty")
 
@@ -141,35 +157,54 @@ func execute_input_sequence(params: Dictionary) -> Dictionary:
 	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
 	if debugger_plugin == null:
 		return _error("NO_SESSION", "No active debug session")
-	if not await _await_bridge_ready(debugger_plugin):
-		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
-
+	# One deadline for the whole call, stamped BEFORE the ready-wait so the
+	# bridge-ready gap is folded into the budget instead of stacking on top of
+	# it (#276). Prefer the server-pushed budget; the fallback (older server) is
+	# the longest input/capture offset plus headroom, floored at INPUT_TIMEOUT,
+	# plus the ready-wait that now counts against the same deadline.
+	var op_start := Time.get_ticks_msec()
 	var max_end_time: float = 0.0
 	for input in inputs:
 		var start_ms: float = input.get("start_ms", 0.0)
 		var duration_ms: float = input.get("duration_ms", 0.0)
 		max_end_time = max(max_end_time, start_ms + duration_ms)
+	for shot_ms in screenshots:
+		max_end_time = max(max_end_time, float(shot_ms))
+	var fallback: float = max(INPUT_TIMEOUT, (max_end_time / 1000.0) + 5.0) + READY_TIMEOUT
+	var timeout := _pushed_budget(params, fallback)
 
-	var timeout := max(INPUT_TIMEOUT, (max_end_time / 1000.0) + 5.0)
+	if not await _await_bridge_ready(debugger_plugin, op_start, timeout):
+		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
 
 	_sequence_pending = true
 	_sequence_result = {}
+	_sequence_captures = []
 
+	# Captures stream in as separate signals before the final result; collect
+	# them for the duration of the wait (not one-shot), then detach.
+	debugger_plugin.sequence_capture_received.connect(_on_sequence_capture)
 	debugger_plugin.input_sequence_completed.connect(_on_sequence_completed, CONNECT_ONE_SHOT)
-	debugger_plugin.request_input_sequence(inputs, report)
+	debugger_plugin.request_input_sequence(inputs, report, screenshots, screenshot_max_width)
 
-	var start_time := Time.get_ticks_msec()
 	while _sequence_pending:
 		await Engine.get_main_loop().process_frame
-		if (Time.get_ticks_msec() - start_time) / 1000.0 > timeout:
+		if (Time.get_ticks_msec() - op_start) / 1000.0 > timeout:
 			_sequence_pending = false
 			if debugger_plugin.input_sequence_completed.is_connected(_on_sequence_completed):
 				debugger_plugin.input_sequence_completed.disconnect(_on_sequence_completed)
+			if debugger_plugin.sequence_capture_received.is_connected(_on_sequence_capture):
+				debugger_plugin.sequence_capture_received.disconnect(_on_sequence_capture)
 			return _error("TIMEOUT", "Timed out waiting for input sequence to complete")
 
+	if debugger_plugin.sequence_capture_received.is_connected(_on_sequence_capture):
+		debugger_plugin.sequence_capture_received.disconnect(_on_sequence_capture)
+
 	if _sequence_result.has("error"):
 		return _error("SEQUENCE_ERROR", _sequence_result.get("error", "Unknown error"))
 
+	if not _sequence_captures.is_empty():
+		_sequence_result["captures"] = _sequence_captures
+
 	return _success(_sequence_result)
 
 
@@ -178,6 +213,18 @@ func _on_sequence_completed(result: Dictionary) -> void:
 	_sequence_result = result
 
 
+func _on_sequence_capture(requested_ms: int, actual_ms: int, ok: bool, image_base64: String, width: int, height: int, error: String) -> void:
+	_sequence_captures.append({
+		"requested_ms": requested_ms,
+		"actual_ms": actual_ms,
+		"ok": ok,
+		"image_base64": image_base64,
+		"width": width,
+		"height": height,
+		"error": error,
+	})
+
+
 func type_text(params: Dictionary) -> Dictionary:
 	var text: String = params.get("text", "")
 	var delay_ms: int = int(params.get("delay_ms", 50))
@@ -192,10 +239,14 @@ func type_text(params: Dictionary) -> Dictionary:
 	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
 	if debugger_plugin == null:
 		return _error("NO_SESSION", "No active debug session")
-	if not await _await_bridge_ready(debugger_plugin):
-		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
+	# Shared deadline (ready-wait + typing), stamped before the ready-wait so the
+	# gap is folded into the budget (#276); server-pushed budget or local fallback.
+	var op_start := Time.get_ticks_msec()
+	var fallback: float = max(INPUT_TIMEOUT, (text.length() * delay_ms / 1000.0) + 5.0) + READY_TIMEOUT
+	var timeout := _pushed_budget(params, fallback)
 
-	var timeout := max(INPUT_TIMEOUT, (text.length() * delay_ms / 1000.0) + 5.0)
+	if not await _await_bridge_ready(debugger_plugin, op_start, timeout):
+		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
 
 	_type_text_pending = true
 	_type_text_result = {}
@@ -203,10 +254,9 @@ func type_text(params: Dictionary) -> Dictionary:
 	debugger_plugin.type_text_completed.connect(_on_type_text_completed, CONNECT_ONE_SHOT)
 	debugger_plugin.request_type_text(text, delay_ms, submit)
 
-	var start_time := Time.get_ticks_msec()
 	while _type_text_pending:
 		await Engine.get_main_loop().process_frame
-		if (Time.get_ticks_msec() - start_time) / 1000.0 > timeout:
+		if (Time.get_ticks_msec() - op_start) / 1000.0 > timeout:
 			_type_text_pending = false
 			if debugger_plugin.type_text_completed.is_connected(_on_type_text_completed):
 				debugger_plugin.type_text_completed.disconnect(_on_type_text_completed)

package/addon/commands/screenshot_commands.gd

@@ -3,7 +3,6 @@ extends MCPBaseCommand
 class_name MCPScreenshotCommands
 
 const DEFAULT_MAX_WIDTH := 900
-const DEFAULT_JPEG_QUALITY := 75
 const SCREENSHOT_TIMEOUT := 5.0
 
 var _screenshot_result: Dictionary = {}
@@ -22,7 +21,6 @@ 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:
@@ -35,7 +33,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, quality)
+	debugger_plugin.request_screenshot(max_width)
 
 	var start_time := Time.get_ticks_msec()
 	while _screenshot_pending:
@@ -64,7 +62,6 @@ 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
 
@@ -80,10 +77,12 @@ 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, quality)
+	return _process_and_encode_image(image, max_width)
 
 
-func _process_and_encode_image(image: Image, max_width: int, quality: float = 0.75) -> Dictionary:
+# Lossless PNG, not JPEG: vision-token cost is set by resolution, not codec, so
+# JPEG only added compression artifacts. max_width bounds the resolution cost.
+func _process_and_encode_image(image: Image, max_width: int) -> Dictionary:
 	if image == null:
 		return _error("CAPTURE_FAILED", "Failed to capture image from viewport")
 
@@ -92,8 +91,8 @@ func _process_and_encode_image(image: Image, max_width: int, quality: float = 0.
 		var new_height := int(image.get_height() * scale_factor)
 		image.resize(max_width, new_height, Image.INTERPOLATE_LANCZOS)
 
-	var jpg_buffer := image.save_jpg_to_buffer(quality)
-	var base64 := Marshalls.raw_to_base64(jpg_buffer)
+	var png_buffer := image.save_png_to_buffer()
+	var base64 := Marshalls.raw_to_base64(png_buffer)
 
 	return _success({
 		"image_base64": base64,

package/addon/core/mcp_debugger_plugin.gd

@@ -8,6 +8,7 @@ signal performance_metrics_received(metrics: Dictionary)
 signal find_nodes_received(matches: Array, count: int, error: String)
 signal input_map_received(actions: Array, error: String)
 signal input_sequence_completed(result: Dictionary)
+signal sequence_capture_received(requested_ms: int, actual_ms: int, ok: bool, image_base64: String, width: int, height: int, error: String)
 signal type_text_completed(result: Dictionary)
 signal game_response(message_type: String, data: Variant)
 signal bridge_ready()
@@ -52,6 +53,9 @@ func _capture(message: String, data: Array, session_id: int) -> bool:
 		"godot_mcp:input_sequence_result":
 			_handle_input_sequence_result(data)
 			return true
+		"godot_mcp:sequence_capture":
+			_handle_sequence_capture(data)
+			return true
 		"godot_mcp:type_text_result":
 			_handle_type_text_result(data)
 			return true
@@ -124,14 +128,14 @@ func is_bridge_ready() -> bool:
 	return _bridge_ready and has_active_session()
 
 
-func request_screenshot(max_width: int = 1024, quality: float = 0.75) -> void:
+func request_screenshot(max_width: int = 1024) -> 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, quality])
+		session.send_message("godot_mcp:take_screenshot", [max_width])
 	else:
 		_pending_screenshot = false
 		screenshot_received.emit(false, "", 0, 0, "Could not get debugger session")
@@ -229,14 +233,14 @@ func _handle_input_map_result(data: Array) -> void:
 	input_map_received.emit(actions, error)
 
 
-func request_input_sequence(inputs: Array, report: Array = []) -> void:
+func request_input_sequence(inputs: Array, report: Array = [], screenshots: Array = [], screenshot_max_width: int = 640) -> void:
 	if _active_session_id < 0:
 		input_sequence_completed.emit({"error": "No active game session"})
 		return
 	_pending_input_sequence = true
 	var session := get_session(_active_session_id)
 	if session:
-		session.send_message("godot_mcp:execute_input_sequence", [inputs, report])
+		session.send_message("godot_mcp:execute_input_sequence", [inputs, report, screenshots, screenshot_max_width])
 	else:
 		_pending_input_sequence = false
 		input_sequence_completed.emit({"error": "Could not get debugger session"})
@@ -248,6 +252,20 @@ func _handle_input_sequence_result(data: Array) -> void:
 	input_sequence_completed.emit(result)
 
 
+# A mid-sequence frame capture (#239) arriving on its own message. Re-emitted for
+# the editor command to collect; the final input_sequence_result follows once the
+# bridge has sent every requested frame.
+func _handle_sequence_capture(data: Array) -> void:
+	var requested_ms: int = int(data[0]) if data.size() > 0 else 0
+	var actual_ms: int = int(data[1]) if data.size() > 1 else 0
+	var ok: bool = bool(data[2]) if data.size() > 2 else false
+	var base64: String = String(data[3]) if data.size() > 3 else ""
+	var width: int = int(data[4]) if data.size() > 4 else 0
+	var height: int = int(data[5]) if data.size() > 5 else 0
+	var error: String = String(data[6]) if data.size() > 6 else ""
+	sequence_capture_received.emit(requested_ms, actual_ms, ok, base64, width, height, error)
+
+
 func request_type_text(text: String, delay_ms: int, submit: bool) -> void:
 	if _active_session_id < 0:
 		type_text_completed.emit({"error": "No active game session"})

package/addon/game_bridge/mcp_game_bridge.gd

@@ -2,7 +2,6 @@ extends Node
 class_name MCPGameBridge
 
 const DEFAULT_MAX_WIDTH := 1024
-const DEFAULT_JPEG_QUALITY := 0.75
 const Onscreen := preload("onscreen.gd")
 
 # Cap on frames waited for the main scene to appear before announcing ready
@@ -119,8 +118,12 @@ func _sequence_process(delta: float) -> void:
 	if _sequence_draining:
 		if tree and not tree.paused:
 			_sequence_gameplay_ms += delta * 1000.0
-		_sequence_settle_remaining -= 1
-		if _sequence_settle_remaining <= 0:
+		if _sequence_settle_remaining > 0:
+			_sequence_settle_remaining -= 1
+		# Finalize only once the settle frames have elapsed (so an effect probe's
+		# `after` reflects the final input) AND every deferred frame capture has
+		# been sent back.
+		if _sequence_settle_remaining <= 0 and _sequence_captures_pending == 0:
 			_emit_sequence_result()
 		return
 
@@ -145,13 +148,28 @@ func _sequence_process(delta: float) -> void:
 			_held_actions.erase(seq_event.action)
 			_actions_completed += 1
 
-	if _sequence_events.is_empty():
-		if _sequence_report.is_empty():
+	# Trigger any frame captures whose offset has arrived (#239). Capture is
+	# deferred to frame_post_draw, so it completes a frame or two later; the
+	# pending count keeps the result from being sent until every frame is in.
+	while _sequence_capture_offsets.size() > 0 and int(_sequence_capture_offsets[0]) <= elapsed:
+		var off: int = int(_sequence_capture_offsets.pop_front())
+		_sequence_captures_pending += 1
+		_capture_sequence_frame.call_deferred(off)
+
+	# Done when both the input timeline and the capture schedule are exhausted;
+	# captures scheduled past the last input keep the window open until their
+	# offsets arrive.
+	if _sequence_events.is_empty() and _sequence_capture_offsets.is_empty():
+		if not _sequence_report.is_empty():
+			# Defer so the effect probe's `after` reflects the final input.
+			_sequence_draining = true
+			_sequence_settle_remaining = SEQUENCE_SETTLE_FRAMES
+		elif _sequence_captures_pending == 0:
 			_emit_sequence_result()
 		else:
-			# Defer the result so the effect probe's `after` reflects the final input.
+			# No probe, but captures are still resolving — wait for them.
 			_sequence_draining = true
-			_sequence_settle_remaining = SEQUENCE_SETTLE_FRAMES
+			_sequence_settle_remaining = 0
 
 
 # Assemble and send the input-sequence result, then reset probe state. Carries an
@@ -203,6 +221,42 @@ func _compute_report_deltas(before: Dictionary, after: Dictionary) -> Dictionary
 	return {"report": deltas, "any_changed": any_changed}
 
 
+# Capture one frame mid-sequence (#239) and stream it back on its own message.
+# Deferred from _sequence_process to frame_post_draw so it reads the rendered
+# frame nearest the requested offset; the actual elapsed offset is reported
+# alongside so the agent knows exactly when each frame landed. Each capture rides
+# its own message, and the count gates the result.
+#
+# Encoded as lossless PNG, deliberately not JPEG: vision-token cost is a function
+# of resolution (≈ width*height/750), not of file size or codec, so JPEG would
+# only add compression artifacts for zero token saving. The token lever is
+# _sequence_capture_max_width (resolution); PNG just costs more transport bytes.
+func _capture_sequence_frame(requested_offset_ms: int) -> void:
+	await RenderingServer.frame_post_draw
+	var actual_ms := Time.get_ticks_msec() - _sequence_start_time
+	var viewport := get_viewport()
+	if viewport == null:
+		_send_sequence_capture(requested_offset_ms, actual_ms, false, "", 0, 0, "NO_VIEWPORT: could not get game viewport")
+		return
+	var image := viewport.get_texture().get_image()
+	if image == null:
+		_send_sequence_capture(requested_offset_ms, actual_ms, false, "", 0, 0, "CAPTURE_FAILED: could not read viewport image")
+		return
+	if _sequence_capture_max_width > 0 and image.get_width() > _sequence_capture_max_width:
+		var scale_factor := float(_sequence_capture_max_width) / float(image.get_width())
+		image.resize(_sequence_capture_max_width, int(image.get_height() * scale_factor), Image.INTERPOLATE_LANCZOS)
+	var png_buffer := image.save_png_to_buffer()
+	var base64 := Marshalls.raw_to_base64(png_buffer)
+	_send_sequence_capture(requested_offset_ms, actual_ms, true, base64, image.get_width(), image.get_height(), "")
+
+
+func _send_sequence_capture(requested_ms: int, actual_ms: int, ok: bool, base64: String, width: int, height: int, error: String) -> void:
+	# Decrement first: the result is gated on this reaching zero, and a capture
+	# that errors must still release its slot or the sequence would never finish.
+	_sequence_captures_pending = maxi(0, _sequence_captures_pending - 1)
+	EngineDebugger.send_message("godot_mcp:sequence_capture", [requested_ms, actual_ms, ok, base64, width, height, error])
+
+
 var _sequence_events: Array = []
 var _sequence_start_time: int = 0
 var _sequence_running: bool = false
@@ -222,6 +276,20 @@ const SEQUENCE_SETTLE_FRAMES := 2
 var _sequence_report: Array = []
 var _sequence_report_inputs: Array = []
 var _sequence_report_before: Dictionary = {}
+# Mid-sequence frame capture (#239): offsets (ms from start, sorted) still to be
+# captured during the real-time run, the capture params, and the count of
+# deferred captures not yet sent — the result is held until this reaches zero.
+var _sequence_capture_offsets: Array = []
+var _sequence_captures_pending: int = 0
+var _sequence_capture_max_width: int = 640
+const SEQUENCE_MAX_CAPTURES := 8
+# Non-binding sanity backstop only (#276). The server derives the per-call
+# timeout from the sequence span and rejects offsets beyond what the ceiling
+# permits before they ever reach here, so this just guards a malformed direct
+# message. Kept far above any server-permitted budget so it never silently
+# clamps a legitimate offset (which would reintroduce the cross-layer drift
+# that #276 removed).
+const SEQUENCE_MAX_CAPTURE_OFFSET_MS := 300000
 # Actions whose press has been injected but whose paired release has not yet
 # fired. Used to guarantee a release even if the queue is cleared mid-flight
 # (new sequence) or the node leaves the tree — otherwise the dropped release
@@ -311,12 +379,14 @@ func _on_debugger_message(message: String, data: Array) -> bool:
 
 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, quality)
+	_capture_and_send_screenshot(max_width)
 
 
-func _capture_and_send_screenshot(max_width: int, quality: float = DEFAULT_JPEG_QUALITY) -> void:
+# Lossless PNG, not JPEG: image vision-token cost scales with resolution, not
+# codec, so JPEG only traded fidelity (compression artifacts) for nothing. Width
+# is downscaled to max_width to bound that resolution-driven cost.
+func _capture_and_send_screenshot(max_width: int) -> void:
 	var viewport := get_viewport()
 	if viewport == null:
 		_send_screenshot_error("NO_VIEWPORT", "Could not get game viewport")
@@ -329,8 +399,8 @@ func _capture_and_send_screenshot(max_width: int, quality: float = DEFAULT_JPEG_
 		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 jpg_buffer := image.save_jpg_to_buffer(quality)
-	var base64 := Marshalls.raw_to_base64(jpg_buffer)
+	var png_buffer := image.save_png_to_buffer()
+	var base64 := Marshalls.raw_to_base64(png_buffer)
 	EngineDebugger.send_message("godot_mcp:screenshot_result", [
 		true,
 		base64,
@@ -1084,6 +1154,8 @@ func _event_to_string(event: InputEvent) -> String:
 func _handle_execute_input_sequence(data: Array) -> void:
 	var inputs: Array = data[0] if data.size() > 0 else []
 	var report: Array = data[1] if data.size() > 1 and data[1] is Array else []
+	var screenshot_offsets: Array = data[2] if data.size() > 2 and data[2] is Array else []
+	var cap_max_width: int = int(data[3]) if data.size() > 3 else 640
 
 	if inputs.is_empty():
 		EngineDebugger.send_message("godot_mcp:input_sequence_result", [{
@@ -1091,6 +1163,15 @@ func _handle_execute_input_sequence(data: Array) -> void:
 		}])
 		return
 
+	# Normalize the optional frame-capture schedule (#239): clamp each offset,
+	# cap the count, and sort so _sequence_process can pop them in order.
+	var capture_offsets: Array = []
+	for o in screenshot_offsets:
+		if capture_offsets.size() >= SEQUENCE_MAX_CAPTURES:
+			break
+		capture_offsets.append(clampi(int(o), 0, SEQUENCE_MAX_CAPTURE_OFFSET_MS))
+	capture_offsets.sort()
+
 	# Compile the optional effect probe up front, before touching any input state,
 	# so a bad expression rejects the call cleanly (same contract as step_until's
 	# report). Reuses the predicate context: autoloads by name, plus `tree`/`root`.
@@ -1117,12 +1198,15 @@ func _handle_execute_input_sequence(data: Array) -> void:
 	_sequence_gameplay_ms = 0.0
 	_sequence_draining = false
 	_sequence_settle_remaining = 0
-	# Clear probe state up front so an early return below (unknown action) cannot
-	# leave a stale report to be drained against an interrupted window. It is
-	# re-armed from report_compiled once the timeline is validated.
+	# Clear probe and capture state up front so an early return below (unknown
+	# action) cannot leave a stale report or capture schedule to be acted on
+	# against an interrupted window. Both are re-armed once the timeline validates.
 	_sequence_report = []
 	_sequence_report_inputs = []
 	_sequence_report_before = {}
+	_sequence_capture_offsets = []
+	_sequence_captures_pending = 0
+	_sequence_capture_max_width = cap_max_width
 
 	for input in inputs:
 		var action_name: String = input.get("action_name", "")
@@ -1158,6 +1242,9 @@ func _handle_execute_input_sequence(data: Array) -> void:
 	_sequence_report_inputs = report_inputs
 	_sequence_report_before = _evaluate_report(report_compiled, report_inputs) if not report_compiled.is_empty() else {}
 
+	# Arm the capture schedule (validated and sorted above).
+	_sequence_capture_offsets = capture_offsets
+
 	_sequence_start_time = Time.get_ticks_msec()
 	_sequence_running = true
 	_update_processing()
@@ -1247,10 +1334,15 @@ func _type_text_async(text: String, delay_ms: int, submit: bool) -> void:
 # ---------------------------------------------------------------------------
 
 const LAUNCH_FROZEN_ENV := "GODOT_MCP_LAUNCH_FROZEN"
-# Timeout cascade: step request <= 20s game time, wall budget 25s, editor
-# relay 28s, server command timeout 30s. Each layer answers before the one
-# above it gives up.
-const STEP_MAX_MS := 20000
+# Timeout cascade (#276): the server derives the whole stagger from the call's
+# in-game budget and pushes wall_budget_ms down here. The bridge returns by that
+# wall budget, the editor relay waits a margin longer, the server socket a
+# margin longer still — each answers before the one above gives up.
+#   STEP_MAX_MS         non-binding sanity backstop (the server already clamps the request)
+#   STEP_DEFAULT_MS     budget used when a call omits max_ms (older server that sends no default)
+#   STEP_WALL_BUDGET_MS wall-budget fallback when the server pushes no wall_budget_ms
+const STEP_MAX_MS := 300000
+const STEP_DEFAULT_MS := 20000
 const STEP_MAX_FRAMES := 1200
 const STEP_WALL_BUDGET_MS := 25000
 const STEP_MAX_TRANSITIONS := 50
@@ -1273,6 +1365,7 @@ var _step_gameplay_ms := 0.0  # the unpaused portion: what gameplay actually exp
 var _step_frames := 0
 var _step_physics_ticks := 0
 var _step_wall_start := 0
+var _step_wall_budget_ms := STEP_WALL_BUDGET_MS  # set per-call from the server-pushed wall_budget_ms (#276)
 var _step_events: Array = []  # in-step input timeline, scheduled on the game-time clock
 var _step_events_fired := 0
 var _step_transitions: Array = []
@@ -1430,6 +1523,7 @@ func _handle_game_time_step(data: Array) -> void:
 	_step_finish_pending = false
 	_step_wall_exceeded = false
 	_step_wall_start = Time.get_ticks_msec()
+	_step_wall_budget_ms = int(params.get("wall_budget_ms", STEP_WALL_BUDGET_MS))
 	_step_predicate = null
 	_step_response_type = "game_time_step"
 	_step_active = true
@@ -1546,9 +1640,9 @@ func _handle_game_time_step_until(data: Array) -> void:
 		_send_game_time_response("game_time_step_until", {"error": "step_until requires a non-empty `until` expression"})
 		return
 
-	var max_ms: int = int(params.get("max_ms", STEP_MAX_MS))
+	var max_ms: int = int(params.get("max_ms", STEP_DEFAULT_MS))
 	if max_ms <= 0:
-		max_ms = STEP_MAX_MS
+		max_ms = STEP_DEFAULT_MS
 	max_ms = mini(max_ms, STEP_MAX_MS)
 
 	# Compile and validate the predicate against the live tree before committing
@@ -1611,6 +1705,7 @@ func _handle_game_time_step_until(data: Array) -> void:
 	_step_finish_pending = false
 	_step_wall_exceeded = false
 	_step_wall_start = Time.get_ticks_msec()
+	_step_wall_budget_ms = int(params.get("wall_budget_ms", STEP_WALL_BUDGET_MS))
 	_step_predicate = expr
 	_step_predicate_inputs = ctx_inputs
 	_step_predicate_met = false
@@ -1682,7 +1777,7 @@ func _step_process(delta: float) -> void:
 			_step_predicate_met = true
 			done = true
 
-	if Time.get_ticks_msec() - _step_wall_start > STEP_WALL_BUDGET_MS:
+	if Time.get_ticks_msec() - _step_wall_start > _step_wall_budget_ms:
 		# Slow-mo, Engine.time_scale = 0, or a pause-held window can starve
 		# the game-time clock; the wall budget guarantees the call returns
 		# (partial, honestly reported) before the editor relay gives up.

package/addon/plugin.cfg

@@ -3,6 +3,6 @@
 name="Godot MCP"
 description="Model Context Protocol server for AI assistant integration"
 author="godot-mcp"
-version="3.11.0"
+version="3.13.0"
 script="plugin.gd"
 godot_version_min="4.5"

package/dist/__tests__/connection/timeouts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timeouts.test.d.ts.map

package/dist/__tests__/connection/timeouts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/connection/timeouts.test.ts"],"names":[],"mappings":""}