@satelliteoflove/godot-mcp 3.7.0 → 3.8.0

package/addon/command_router.gd

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

package/addon/command_router.gd.uid

@@ -0,0 +1 @@
+uid://bhjejek8ivdv8

package/addon/commands/animation_commands.gd.uid

@@ -0,0 +1 @@
+uid://dg4xlid3mi2mi

package/addon/commands/debug_commands.gd

@@ -3,6 +3,8 @@ extends MCPBaseCommand
 class_name MCPDebugCommands
 
 const DEBUG_OUTPUT_TIMEOUT := 5.0
+# Keep in sync with LAUNCH_FROZEN_ENV in mcp_game_bridge.gd.
+const LAUNCH_FROZEN_ENV := "GODOT_MCP_LAUNCH_FROZEN"
 
 var _debug_output_result: PackedStringArray = []
 var _debug_output_pending: bool = false
@@ -21,15 +23,32 @@ func get_commands() -> Dictionary:
 
 func run_project(params: Dictionary) -> Dictionary:
 	var scene_path: String = params.get("scene_path", "")
+	var frozen: bool = params.get("frozen", false)
 
 	MCPLogger.clear()
 
+	# Launch-frozen: the spawned game inherits the editor's environment, so
+	# setting this before play makes the bridge freeze the tree in _ready —
+	# before the first process frame. Deterministic, unlike sending a freeze
+	# message after the debug session comes up (which races the game's first
+	# frames against the agent's latency).
+	if frozen:
+		OS.set_environment(LAUNCH_FROZEN_ENV, "1")
+
 	if scene_path.is_empty():
 		EditorInterface.play_main_scene()
 	else:
 		EditorInterface.play_custom_scene(scene_path)
 
-	return _success({})
+	if frozen:
+		# The child captured its environment at spawn; clear promptly so a
+		# manual F5 run doesn't inherit the freeze. Two frames covers a
+		# deferred spawn. (Godot has no unset; empty fails the == "1" check.)
+		await Engine.get_main_loop().process_frame
+		await Engine.get_main_loop().process_frame
+		OS.set_environment(LAUNCH_FROZEN_ENV, "")
+
+	return _success({"frozen": frozen})
 
 
 func stop_project(_params: Dictionary) -> Dictionary:

package/addon/commands/debug_commands.gd.uid

@@ -0,0 +1 @@
+uid://cquyem31g4y4b

package/addon/commands/game_time_commands.gd

@@ -0,0 +1,78 @@
+@tool
+extends MCPBaseCommand
+class_name MCPGameTimeCommands
+
+# Game-time control relay: freeze / step / thaw / status execute in the game
+# bridge (see mcp_game_bridge.gd); this side only forwards over the debugger
+# channel and waits. Timeout cascade: the step 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.
+const BASE_TIMEOUT := 10.0
+const STEP_TIMEOUT := 28.0
+
+var _last_error: Dictionary = {}
+
+
+func get_commands() -> Dictionary:
+	return {
+		"game_time_freeze": game_time_freeze,
+		"game_time_step": game_time_step,
+		"game_time_thaw": game_time_thaw,
+		"game_time_status": game_time_status,
+	}
+
+
+func game_time_freeze(params: Dictionary) -> Dictionary:
+	return await _relay("game_time_freeze", [params], BASE_TIMEOUT)
+
+
+func game_time_step(params: Dictionary) -> Dictionary:
+	return await _relay("game_time_step", [params], STEP_TIMEOUT)
+
+
+func game_time_thaw(params: Dictionary) -> Dictionary:
+	return await _relay("game_time_thaw", [params], BASE_TIMEOUT)
+
+
+func game_time_status(params: Dictionary) -> Dictionary:
+	return await _relay("game_time_status", [params], BASE_TIMEOUT)
+
+
+func _relay(msg_type: String, args: Array, timeout: float) -> Dictionary:
+	var response = await _send_and_wait(msg_type, args, timeout)
+	if response == null:
+		return _last_error
+	if response is Dictionary and response.has("error"):
+		return _error("GAME_TIME_ERROR", str(response["error"]))
+	if response is Dictionary:
+		return _success(response)
+	return _success({"data": response})
+
+
+func _send_and_wait(msg_type: String, args: Array, timeout: float):
+	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 > 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/game_time_commands.gd.uid

@@ -0,0 +1 @@
+uid://c2pfjqe2yv0c4

package/addon/commands/node_commands.gd.uid

@@ -0,0 +1 @@
+uid://bke2rvqtw381m

package/addon/commands/profiler_commands.gd.uid

@@ -0,0 +1 @@
+uid://c17gnisv1uqju

package/addon/commands/project_commands.gd.uid

@@ -0,0 +1 @@
+uid://es4uegishf00

package/addon/commands/resource_commands.gd.uid

@@ -0,0 +1 @@
+uid://yts2tlf0btx5

package/addon/commands/runtime_state_commands.gd.uid

@@ -0,0 +1 @@
+uid://bns7tsagruukm

package/addon/commands/scene3d_commands.gd.uid

@@ -0,0 +1 @@
+uid://cniw11jpk5y82

package/addon/commands/scene_commands.gd.uid

@@ -0,0 +1 @@
+uid://ngt4k3u88sj3

package/addon/commands/screenshot_commands.gd.uid

@@ -0,0 +1 @@
+uid://c578gd4ovecgt

package/addon/commands/script_commands.gd.uid

@@ -0,0 +1 @@
+uid://b1om27ef4rvws

package/addon/commands/selection_commands.gd.uid

@@ -0,0 +1 @@
+uid://ciy2n67gqdsla

package/addon/commands/tilemap_commands.gd.uid

@@ -0,0 +1 @@
+uid://cietp5vxfv072

package/addon/core/base_command.gd.uid

@@ -0,0 +1 @@
+uid://cwqpmprsn6g2

package/addon/core/mcp_constants.gd.uid

@@ -0,0 +1 @@
+uid://hkoghrp3us8j

package/addon/core/mcp_debugger_plugin.gd.uid

@@ -0,0 +1 @@
+uid://daogurpabpiap

package/addon/core/mcp_enums.gd.uid

@@ -0,0 +1 @@
+uid://b1yx7jiol72rg

package/addon/core/mcp_logger.gd

@@ -34,7 +34,7 @@ func _log_error(function: String, file: String, line: int, code: String,
 	for backtrace in script_backtraces:
 		for i in backtrace.get_frame_count():
 			frames.append({
-				"file": backtrace.get_frame_source(i),
+				"file": backtrace.get_frame_file(i),
 				"line": backtrace.get_frame_line(i),
 				"function": backtrace.get_frame_function(i),
 			})

package/addon/core/mcp_logger.gd.uid

@@ -0,0 +1 @@
+uid://yv8gf1cuf48v

package/addon/core/mcp_utils.gd.uid

@@ -0,0 +1 @@
+uid://dckosaj3snxdo

package/addon/game_bridge/mcp_frame_profiler.gd.uid

@@ -0,0 +1 @@
+uid://cihxpb547p4du

package/addon/game_bridge/mcp_game_bridge.gd

@@ -11,6 +11,13 @@ var _sampler: MCPRuntimeStateSampler
 
 
 func _ready() -> void:
+	# The bridge must keep processing while the scene tree is paused. Input
+	# sequences are driven from _process, so without this a press that toggles
+	# `paused = true` freezes the runner mid-sequence: the paired release never
+	# fires and the editor-side wait times out (~30s) — pause menus, a primary
+	# injection target, become undrivable. The bridge answers to the debugger,
+	# not the game's pause state. Children (the sampler) inherit this mode.
+	process_mode = Node.PROCESS_MODE_ALWAYS
 	if not EngineDebugger.is_active():
 		return
 	_logger = _MCPGameLogger.new()
@@ -20,17 +27,42 @@ func _ready() -> void:
 	_sampler = MCPRuntimeStateSampler.new()
 	add_child(_sampler)
 	EngineDebugger.register_message_capture("godot_mcp", _on_debugger_message)
+	set_physics_process(false)  # only counts ticks during a step window
 	MCPLog.info("Game bridge initialized")
 
+	# Launch-frozen: the editor sets this env var just before spawning the game
+	# (godot_editor run with frozen=true), so the freeze lands before the first
+	# process frame — agent latency between run and the first input costs the
+	# game nothing. Scene _ready callbacks still run; processing does not start.
+	if OS.get_environment(LAUNCH_FROZEN_ENV) == "1":
+		_launched_frozen = true
+		_engage_freeze()
+		MCPLog.info("Game bridge: launched frozen")
+
 
 func _exit_tree() -> void:
+	# Guaranteed cleanup: never leave an action latched when the bridge node
+	# leaves the tree (game shutdown / scene change). Safe if nothing is held.
+	_release_held_actions()
 	if EngineDebugger.is_active():
 		EngineDebugger.unregister_message_capture("godot_mcp")
 		if _profiler:
 			EngineDebugger.unregister_profiler("mcp_frame_profiler")
 
 
-func _process(_delta: float) -> void:
+func _process(delta: float) -> void:
+	_game_time_process(delta)
+	_sequence_process()
+
+
+# Processing is needed by three independent features; only switch it off when
+# none of them is active (the frozen monitor must run every frame, so the old
+# "disable after the sequence" shortcut no longer applies unconditionally).
+func _update_processing() -> void:
+	set_process(_sequence_running or _frozen or _step_active)
+
+
+func _sequence_process() -> void:
 	if not _sequence_running or _sequence_events.is_empty():
 		return
 
@@ -43,12 +75,15 @@ func _process(_delta: float) -> void:
 		input_event.pressed = seq_event.is_press
 		input_event.strength = 1.0 if seq_event.is_press else 0.0
 		Input.parse_input_event(input_event)
-		if not seq_event.is_press:
+		if seq_event.is_press:
+			_held_actions[seq_event.action] = true
+		else:
+			_held_actions.erase(seq_event.action)
 			_actions_completed += 1
 
 	if _sequence_events.is_empty():
 		_sequence_running = false
-		set_process(false)
+		_update_processing()
 		EngineDebugger.send_message("godot_mcp:input_sequence_result", [{
 			"completed": true,
 			"actions_executed": _actions_completed,
@@ -60,6 +95,29 @@ var _sequence_start_time: int = 0
 var _sequence_running: bool = false
 var _actions_completed: int = 0
 var _actions_total: int = 0
+# 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
+# latches the action "pressed" in the Input singleton (the stuck-held bug).
+var _held_actions: Dictionary = {}
+
+
+# Release any action still held from an interrupted sequence. A release here is a
+# guaranteed cleanup, never a queued step that a clear could drop. Safe to call
+# when nothing is held.
+func _release_held_actions() -> void:
+	if _held_actions.is_empty():
+		return
+	for action in _held_actions.keys():
+		var release := InputEventAction.new()
+		release.action = action
+		release.pressed = false
+		release.strength = 0.0
+		Input.parse_input_event(release)
+	# Flush so the release takes effect immediately — _exit_tree may not get
+	# another frame, and a cleanup should be deterministic, not deferred.
+	Input.flush_buffered_events()
+	_held_actions.clear()
 
 
 func _on_debugger_message(message: String, data: Array) -> bool:
@@ -106,6 +164,18 @@ func _on_debugger_message(message: String, data: Array) -> bool:
 		"watch_stop":
 			_handle_watch_stop()
 			return true
+		"game_time_freeze":
+			_handle_game_time_freeze(data)
+			return true
+		"game_time_step":
+			_handle_game_time_step(data)
+			return true
+		"game_time_thaw":
+			_handle_game_time_thaw(data)
+			return true
+		"game_time_status":
+			_handle_game_time_status(data)
+			return true
 	return false
 
 
@@ -890,6 +960,10 @@ func _handle_execute_input_sequence(data: Array) -> void:
 		}])
 		return
 
+	# Release anything still held from a prior, interrupted sequence BEFORE
+	# clearing the queue — otherwise that sequence's unfired releases are dropped
+	# and its actions stay latched (stuck-held bug).
+	_release_held_actions()
 	_sequence_events.clear()
 	_actions_completed = 0
 	_actions_total = inputs.size()
@@ -925,7 +999,7 @@ func _handle_execute_input_sequence(data: Array) -> void:
 
 	_sequence_start_time = Time.get_ticks_msec()
 	_sequence_running = true
-	set_process(true)
+	_update_processing()
 
 
 func _handle_type_text(data: Array) -> void:
@@ -982,3 +1056,324 @@ func _type_text_async(text: String, delay_ms: int, submit: bool) -> void:
 		"chars_typed": text.length(),
 		"submitted": submit,
 	}])
+
+
+# ---------------------------------------------------------------------------
+# Game-time control (freeze / step / thaw / status)
+#
+# Real-time games race ahead of high-latency agents: 10-40s of consequences
+# land between every observation and the action it informs. These primitives
+# make game time answer to the agent's clock instead: freeze the tree, think
+# arbitrarily long (all observation tools work while frozen — rendering
+# continues during pause), then step forward a bounded slice of game time
+# with inputs riding inside the window.
+#
+# tree.paused is a single bit that two parties now write: the game's own
+# pause menu and this freeze. The bridge layers them — effective state is
+# (game_paused OR frozen) — by observing and re-asserting: it cannot
+# intercept writes, but it processes every frame (PROCESS_MODE_ALWAYS, and
+# as an autoload it runs BEFORE the scene), so a game-code flip is caught on
+# the next frame, recorded as the game layer's new intent, and overridden
+# while frozen. step/thaw restore the game's wish, not whatever we found.
+#
+# What freeze means: exactly what runs during the game's own pause menu runs
+# during freeze (WHEN_PAUSED/ALWAYS nodes, process_always timers). A game
+# with a correct pause menu has already partitioned pause-immune from
+# pausable code; freeze rides that contract. Games that "pause" by writing
+# Engine.time_scale = 0 instead are frozen solid too, but their pause is
+# invisible to the layer model (it looks like gameplay state, not pause
+# state) — documented limitation.
+# ---------------------------------------------------------------------------
+
+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
+const STEP_MAX_FRAMES := 1200
+const STEP_WALL_BUDGET_MS := 25000
+const STEP_MAX_TRANSITIONS := 50
+const FREEZE_CONTESTED_THRESHOLD := 10
+
+var _frozen := false
+var _game_paused := false  # the game layer's own pause intent, inferred by observation
+var _launched_frozen := false
+var _freeze_started_ticks := 0
+var _freeze_transition_count := 0
+
+var _step_active := false
+var _step_finish_pending := false
+var _step_needs_settle := false
+var _step_wall_exceeded := false
+var _step_target_ms := 0.0
+var _step_target_frames := 0
+var _step_elapsed_ms := 0.0  # accumulated scaled delta = game time (wall-of-step, includes game-paused stretches)
+var _step_gameplay_ms := 0.0  # the unpaused portion: what gameplay actually experienced
+var _step_frames := 0
+var _step_physics_ticks := 0
+var _step_wall_start := 0
+var _step_events: Array = []  # in-step input timeline, scheduled on the game-time clock
+var _step_events_fired := 0
+var _step_transitions: Array = []
+var _step_last_tree_paused := false
+
+
+func _send_game_time_response(msg_type: String, result: Dictionary) -> void:
+	EngineDebugger.send_message("godot_mcp:game_response", [msg_type, result])
+
+
+func _engage_freeze() -> void:
+	if _frozen:
+		return
+	var tree := get_tree()
+	_game_paused = tree.paused
+	_frozen = true
+	_freeze_started_ticks = Time.get_ticks_msec()
+	_freeze_transition_count = 0
+	tree.paused = true
+	_update_processing()
+
+
+# Per-frame monitor: dispatches to the step runner during a window, otherwise
+# holds the freeze against game-code writes.
+func _game_time_process(delta: float) -> void:
+	if _step_active:
+		_step_process(delta)
+		return
+	if not _frozen:
+		return
+	var tree := get_tree()
+	if not tree.paused:
+		# Game code unpaused under the freeze (a WHEN_PAUSED resume button, an
+		# auto-unpausing cutscene). Record the game layer's new intent and
+		# re-assert — the freeze answers to the agent; the game's wish is
+		# restored on step/thaw. Only unpause flips are observable here: while
+		# frozen, tree.paused is already true.
+		_game_paused = false
+		_freeze_transition_count += 1
+		tree.paused = true
+
+
+func _physics_process(_delta: float) -> void:
+	if _step_active and not _step_finish_pending and not get_tree().paused:
+		_step_physics_ticks += 1
+
+
+func _handle_game_time_freeze(_data: Array) -> void:
+	if _step_active:
+		_send_game_time_response("game_time_freeze", {"error": "Step in progress"})
+		return
+	var was_frozen := _frozen
+	_engage_freeze()
+	_send_game_time_response("game_time_freeze", {
+		"frozen": true,
+		"was_frozen": was_frozen,
+		"game_paused": _game_paused,
+	})
+
+
+func _handle_game_time_thaw(_data: Array) -> void:
+	if _step_active:
+		_send_game_time_response("game_time_thaw", {"error": "Step in progress"})
+		return
+	var was_frozen := _frozen
+	var result: Dictionary = {"frozen": false, "was_frozen": was_frozen}
+	if was_frozen:
+		# Real wall-clock the freeze was held; game time did not advance while frozen.
+		result["frozen_wall_ms"] = Time.get_ticks_msec() - _freeze_started_ticks
+		_frozen = false
+		get_tree().paused = _game_paused
+		_update_processing()
+	result["game_paused"] = _game_paused if was_frozen else get_tree().paused
+	_send_game_time_response("game_time_thaw", result)
+
+
+func _handle_game_time_status(_data: Array) -> void:
+	var tree := get_tree()
+	var tree_paused: bool = tree.paused if tree else false
+	var result: Dictionary = {
+		"frozen": _frozen,
+		"game_paused": _game_paused if _frozen else tree_paused,
+		"tree_paused": tree_paused,
+		"engine_time_scale": Engine.time_scale,
+		"physics_ticks_per_second": Engine.physics_ticks_per_second,
+	}
+	# `frozen` is the authoritative current state. `launched_frozen` is a historical
+	# fact (this run booted frozen via GODOT_MCP_LAUNCH_FROZEN) and stays true after
+	# thaw, so it must not be read as the present freeze state.
+	if _launched_frozen:
+		result["launched_frozen"] = true
+	if _frozen:
+		# Real wall-clock since freeze engaged, not game time (which is stopped).
+		result["frozen_wall_ms"] = Time.get_ticks_msec() - _freeze_started_ticks
+		result["freeze_transitions"] = _freeze_transition_count
+		if _freeze_transition_count >= FREEZE_CONTESTED_THRESHOLD:
+			# Something (an ALWAYS-mode node?) is repeatedly unpausing under
+			# the freeze. Each re-assert can leak up to one frame; report the
+			# contest rather than pretend the freeze is airtight.
+			result["freeze_contested"] = true
+	if _step_active:
+		result["step_active"] = true
+	_send_game_time_response("game_time_status", result)
+
+
+func _handle_game_time_step(data: Array) -> void:
+	var params: Dictionary = data[0] if data.size() > 0 and data[0] is Dictionary else {}
+	if _step_active:
+		_send_game_time_response("game_time_step", {"error": "Step already in progress"})
+		return
+
+	var duration_ms: int = int(params.get("duration_ms", 0))
+	var frames: int = int(params.get("frames", 0))
+	if duration_ms <= 0 and frames <= 0:
+		_send_game_time_response("game_time_step", {"error": "step requires duration_ms or frames"})
+		return
+	duration_ms = mini(duration_ms, STEP_MAX_MS)
+	frames = mini(frames, STEP_MAX_FRAMES)
+
+	# Validate and schedule the in-step input timeline (start_ms is game-time
+	# from window start). Inputs must ride inside the step: an event injected
+	# while frozen lands on a frame gameplay never processes, so its
+	# is_action_just_pressed edge would be silently missed.
+	var inputs: Array = params.get("inputs", [])
+	var events: Array = []
+	for input in inputs:
+		var action_name: String = input.get("action_name", "")
+		if action_name.is_empty():
+			continue
+		if not InputMap.has_action(action_name):
+			_send_game_time_response("game_time_step", {"error": "Unknown action: %s" % action_name})
+			return
+		var start_ms: int = int(input.get("start_ms", 0))
+		var dur: int = int(input.get("duration_ms", 0))
+		events.append({"time": start_ms, "action": action_name, "is_press": true})
+		events.append({"time": start_ms + dur, "action": action_name, "is_press": false})
+	events.sort_custom(func(a: Dictionary, b: Dictionary) -> bool:
+		return a.time < b.time
+	)
+
+	# Step from a running game is allowed — it freezes first, so "advance
+	# 500ms then wait for me" is a single atomic call.
+	_engage_freeze()
+
+	_step_target_ms = float(duration_ms)
+	_step_target_frames = frames
+	_step_elapsed_ms = 0.0
+	_step_gameplay_ms = 0.0
+	_step_frames = 0
+	_step_physics_ticks = 0
+	_step_events = events
+	_step_events_fired = 0
+	_step_transitions = []
+	_step_needs_settle = false
+	_step_finish_pending = false
+	_step_wall_exceeded = false
+	_step_wall_start = Time.get_ticks_msec()
+	_step_active = true
+
+	# Open the window: restore the game layer's own pause wish for the
+	# duration. If the game's menu is holding it paused, the window still
+	# elapses (and reports gameplay_ms ~0) — never deadlock waiting for
+	# gameplay time that cannot come.
+	var tree := get_tree()
+	tree.paused = _game_paused
+	_step_last_tree_paused = tree.paused
+	set_physics_process(true)
+	_update_processing()
+
+
+func _step_process(delta: float) -> void:
+	var tree := get_tree()
+
+	# The bridge processes before the scene, so a frame is counted here BEFORE
+	# gameplay runs it. Ending the window therefore always defers one frame:
+	# pausing in the same _process call would steal the frame just counted.
+	if _step_finish_pending:
+		_finish_step()
+		return
+
+	# Game-layer pause flips during the window are the game's own doing (a
+	# stepped input opened the menu, an auto-pausing cutscene). Track intent
+	# and report; never fight it mid-window.
+	if tree.paused != _step_last_tree_paused:
+		_step_last_tree_paused = tree.paused
+		_game_paused = tree.paused
+		if _step_transitions.size() < STEP_MAX_TRANSITIONS:
+			_step_transitions.append({"at_ms": roundi(_step_elapsed_ms), "paused": tree.paused})
+
+	_step_frames += 1
+	_step_elapsed_ms += delta * 1000.0
+	if not tree.paused:
+		_step_gameplay_ms += delta * 1000.0
+
+	while _step_events.size() > 0 and _step_events[0].time <= _step_elapsed_ms:
+		var ev: Dictionary = _step_events.pop_front()
+		var input_event := InputEventAction.new()
+		input_event.action = ev.action
+		input_event.pressed = ev.is_press
+		input_event.strength = 1.0 if ev.is_press else 0.0
+		Input.parse_input_event(input_event)
+		_step_events_fired += 1
+		_step_needs_settle = true
+		if ev.is_press:
+			_held_actions[ev.action] = true
+		else:
+			_held_actions.erase(ev.action)
+
+	var done := false
+	if _step_target_frames > 0:
+		done = _step_frames >= _step_target_frames
+	else:
+		done = _step_elapsed_ms >= _step_target_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.
+		_step_wall_exceeded = true
+		done = true
+
+	if done:
+		if _step_needs_settle:
+			# Injected events flush at the top of the NEXT frame; gameplay
+			# needs that frame unpaused or the final just_pressed edge is
+			# lost. Run exactly one settle frame, then finish.
+			_step_needs_settle = false
+		else:
+			_step_finish_pending = true
+
+
+func _finish_step() -> void:
+	# Releases are guaranteed cleanup, never queued steps: no holds survive
+	# across the freeze boundary (cross-step holds are a deliberate non-goal).
+	var forced := _held_actions.size()
+	_release_held_actions()
+	var dropped := _step_events.size()
+	_step_events.clear()
+
+	get_tree().paused = true  # the freeze layer re-engages
+	_step_last_tree_paused = true
+	_step_active = false
+	_step_finish_pending = false
+	set_physics_process(false)
+	_update_processing()
+
+	var result: Dictionary = {
+		"completed": true,
+		"frozen": true,
+		"elapsed_ms": roundi(_step_elapsed_ms),
+		"gameplay_ms": roundi(_step_gameplay_ms),
+		"frames": _step_frames,
+		"physics_ticks": _step_physics_ticks,
+		"game_paused": _game_paused,
+	}
+	if _step_events_fired > 0:
+		result["events_fired"] = _step_events_fired
+	if forced > 0:
+		result["forced_releases"] = forced
+	if dropped > 0:
+		result["events_dropped"] = dropped
+	if not _step_transitions.is_empty():
+		result["pause_transitions"] = _step_transitions
+	if _step_wall_exceeded:
+		result["wall_budget_exceeded"] = true
+	_send_game_time_response("game_time_step", result)