breakpoint-mcp 1.87.0 → 1.89.0

package/README.md

@@ -3,7 +3,7 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **293 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **295 tools
 + 6 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).

package/addon/breakpoint_mcp/bridge_secret.gd

@@ -21,6 +21,14 @@ const SECRET_PATH := "res://.godot/breakpoint_mcp.secret"
 ## The shortest BREAKPOINT_RUNTIME_SECRET an opted-in debug export accepts (see
 ## runtime_listen_policy). The minted secret is 64 hex characters.
 const EXPORT_SECRET_MIN_LEN := 32
+## 🆕 BP-0037 — the project setting that turns strict mode on (default false, opt-in through
+## 1.x). Under it the plugin registers no autoload, the game attaches runtime_bridge.gd
+## itself from its own debug-only code, and the bridge listens only with the switch.
+const STRICT_SETTING := "breakpoint_mcp/runtime/strict"
+## 🆕 BP-0037 — the developer switch: this environment variable set to 1/true, or this user
+## argument after `--` on the game's command line.
+const SWITCH_ENV := "BREAKPOINT_RUNTIME"
+const SWITCH_ARG := "--breakpoint-runtime"
 
 
 ## Return the shared secret, minting + persisting a fresh one if none exists.
@@ -69,14 +77,26 @@ static func load_or_mint() -> String:
 ## Pure — no OS calls, no files — so the decision is unit-tested headless; the caller
 ## passes the four facts in. `warn` is true only when someone ASKED for an exported
 ## bridge and is being refused; a plain shipped game stays silent.
-static func runtime_listen_policy(editor_build: bool, debug_build: bool, exported_optin: String, env_secret: String) -> Dictionary:
+##
+## 🆕 BP-0037 — TWO MORE FACTS, AND ONE TEST MOVED TO THE FRONT. `debug_build` is now read
+## FIRST, ahead of every other test: a build where OS.is_debug_build() is false never
+## listens, whatever else is true of it (the only such build that reaches here is a release
+## export, which already never listened, so nothing changes for a project that does not
+## opt in). `strict` is the project setting `breakpoint_mcp/runtime/strict` (STRICT_SETTING,
+## default false); when it is true the bridge listens only with the developer switch —
+## BREAKPOINT_RUNTIME=1 in the environment or `--breakpoint-runtime` after `--` — which
+## Breakpoint's own game launchers set (runtime_switch_on). Strict is opt-in through 1.x.
+static func runtime_listen_policy(editor_build: bool, debug_build: bool, exported_optin: String, env_secret: String, strict: bool = false, switch_on: bool = false) -> Dictionary:
+	var optin := exported_optin.strip_edges().to_lower()
+	var asked := optin == "1" or optin == "true" or (strict and switch_on)
+	if not debug_build:
+		return {"listen": false, "secret_source": "", "warn": asked, "reason": "not a debug build (OS.is_debug_build() is false): the runtime bridge never listens in a release build, whatever its environment says"}
+	if strict and not switch_on:
+		return {"listen": false, "secret_source": "", "warn": optin == "1" or optin == "true", "reason": "strict mode (%s=true): the runtime bridge listens only with BREAKPOINT_RUNTIME=1 or --breakpoint-runtime" % STRICT_SETTING}
 	if editor_build:
 		return {"listen": true, "secret_source": "project", "warn": false, "reason": "development run (editor build)"}
-	var optin := exported_optin.strip_edges().to_lower()
 	if not (optin == "1" or optin == "true"):
 		return {"listen": false, "secret_source": "", "warn": false, "reason": "exported build: the runtime bridge listens only in development runs"}
-	if not debug_build:
-		return {"listen": false, "secret_source": "", "warn": true, "reason": "BREAKPOINT_RUNTIME_EXPORTED is honoured only in a debug export; a release export never listens"}
 	if env_secret.strip_edges().length() < EXPORT_SECRET_MIN_LEN:
 		return {"listen": false, "secret_source": "", "warn": true, "reason": "BREAKPOINT_RUNTIME_EXPORTED=1 needs BREAKPOINT_RUNTIME_SECRET of at least %d characters; an exported build never mints its own" % EXPORT_SECRET_MIN_LEN}
 	# The validated secret travels IN the decision, so nothing downstream re-reads the
@@ -84,6 +104,19 @@ static func runtime_listen_policy(editor_build: bool, debug_build: bool, exporte
 	return {"listen": true, "secret_source": "env", "secret": env_secret.strip_edges(), "warn": false, "reason": "debug export, opted in with BREAKPOINT_RUNTIME_EXPORTED"}
 
 
+## 🆕 BP-0037 — whether the developer switch is set. Pure, like the policy: the caller passes
+## OS.get_environment(SWITCH_ENV) and OS.get_cmdline_user_args().
+static func runtime_switch_on(env_value: String, user_args: PackedStringArray) -> bool:
+	var v := env_value.strip_edges().to_lower()
+	return v == "1" or v == "true" or user_args.has(SWITCH_ARG)
+
+
+## 🆕 BP-0037 — whether this project is in strict mode. Strict only on a real `true`: a
+## missing setting, or any other value, is the 1.x default (not strict).
+static func runtime_strict(setting_value: Variant) -> bool:
+	return typeof(setting_value) == TYPE_BOOL and bool(setting_value)
+
+
 ## A development run is an EDITOR build that is NOT an export TEMPLATE. Both are compiled-in
 ## feature tags, and the second condition is what makes the first trustworthy: custom
 ## features — an export preset's list, or `_custom_features` in an override.cfg, which the

package/addon/breakpoint_mcp/error_remedies.gd

@@ -93,8 +93,9 @@ const RUNTIME_REMEDIES := {
 	"emit_failed": "Check the argument count and types against the signal's declaration, then emit again.",
 	"bad_action": "Call `inputmap_list` for the actions the project declares before injecting one.",
 	"bad_kind": "Pass one of the kinds the message lists to `runtime_inject_input`.",
+	"bad_event": "Pass the fields the message names for that kind to `runtime_inject_input`; a pointer's x and y are pixels of the frame `runtime_screenshot` returns.",
 	"bad_regex": "Simplify the pattern and call again — it did not compile as a Godot RegEx.",
-	"bad_reference": "Pass a reference image the project can load — `runtime_screenshot` writes one you can diff against later.",
+	"bad_reference": "Pass a reference image the project can load — `runtime_screenshot_save` writes one you can diff against later.",
 	"not_animation_player": "Call `runtime_get_tree` and pass the path of an AnimationPlayer node.",
 	"no_animation": "Call `runtime_anim_get_state` for the animations the player actually holds.",
 	"bad_scene": "Pass a res:// .tscn path that loads in the running project; `scene_get_dependencies` reports what a scene needs.",
@@ -108,6 +109,9 @@ const RUNTIME_REMEDIES := {
 	"set_ignored": "Check the property exists on this node with `runtime_get_property`, and that its setter accepts the value — nothing changed.",
 	"bad_event_field": "Send the field tagged — `{\"__type__\": \"Vector2\", \"x\": .., \"y\": ..}` — or omit it and let the event land at its default position.",
 	"bad_params": "Fix the parameter named above and call again — the message carries the accepted shape.",
+	"no_state_registry": "Set Engine metadata \"breakpoint_state\" to a Dictionary of name -> Callable from the game's own debug code, then call again.",
+	"unknown_state": "Call `runtime_read_state` without a name for the names the game registered, then pass one of them.",
+	"state_reader_gone": "Set the reader again from an object that is still alive, then call again.",
 }
 
 

package/addon/breakpoint_mcp/operations.gd

@@ -8,7 +8,7 @@ extends RefCounted
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
-const ADDON_VERSION := "1.17.0"
+const ADDON_VERSION := "1.19.0"
 
 var _plugin: EditorPlugin
 

package/addon/breakpoint_mcp/plugin.cfg

@@ -3,5 +3,5 @@
 name="Breakpoint MCP"
 description="Exposes the live Godot editor and the running game to an MCP host so an AI assistant can drive them: scene/node/resource CRUD with full undo/redo, project settings, ClassDB, editor + in-game screenshots, and an in-game runtime bridge (live SceneTree, property get/set, method calls, signals, input injection, Performance monitors). Pairs with the breakpoint-mcp MCP host."
 author="James Livingston"
-version="1.17.0"
+version="1.19.0"
 script="plugin.gd"

package/addon/breakpoint_mcp/plugin.gd

@@ -14,6 +14,7 @@ extends EditorPlugin
 const BridgeServer := preload("res://addons/breakpoint_mcp/bridge_server.gd")
 const StatusDock := preload("res://addons/breakpoint_mcp/status_dock.gd")
 const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
+const BridgeSecret := preload("res://addons/breakpoint_mcp/bridge_secret.gd")
 const RUNTIME_AUTOLOAD := "BreakpointRuntimeBridge"
 const RUNTIME_SCRIPT := "res://addons/breakpoint_mcp/runtime_bridge.gd"
 
@@ -36,7 +37,15 @@ func _enter_tree() -> void:
 	_dock = dock
 	# Inject the runtime bridge into every run of the project so the runtime_*
 	# tools work as soon as the game starts. Removed cleanly on disable.
-	add_autoload_singleton(RUNTIME_AUTOLOAD, RUNTIME_SCRIPT)
+	# 🆕 BP-0037 — STRICT MODE (`breakpoint_mcp/runtime/strict=true`, opt-in through 1.x):
+	# the plugin neither adds nor removes the autoload. The game attaches the bridge itself,
+	# by path, from its own debug-only code (runtime_bridge.gd's header), so an export that
+	# leaves this folder out keeps no autoload entry pointing into it.
+	if _strict():
+		if ProjectSettings.has_setting("autoload/" + RUNTIME_AUTOLOAD):
+			push_warning("[breakpoint_mcp] strict mode is on but project.godot still registers the %s autoload; remove it (Project Settings > Globals > Autoload) and attach the bridge by path — strict mode never edits it" % RUNTIME_AUTOLOAD)
+	else:
+		add_autoload_singleton(RUNTIME_AUTOLOAD, RUNTIME_SCRIPT)
 	# D3: emit resources/updated triggers. Selection + edited scene are reflected
 	# in godot://editor-state; the edited tree in godot://scene-tree.
 	_selection = EditorInterface.get_selection()
@@ -60,7 +69,8 @@ func _exit_tree() -> void:
 	_selection = null
 	if scene_changed.is_connected(_on_scene_changed):
 		scene_changed.disconnect(_on_scene_changed)
-	remove_autoload_singleton(RUNTIME_AUTOLOAD)
+	if not _strict():
+		remove_autoload_singleton(RUNTIME_AUTOLOAD)
 	if _server:
 		_server.shutdown()
 		_server.queue_free()
@@ -70,6 +80,11 @@ func _exit_tree() -> void:
 	print("[breakpoint_mcp] plugin disabled")
 
 
+## 🆕 BP-0037 — whether this project opted into strict mode (bridge_secret.gd).
+func _strict() -> bool:
+	return BridgeSecret.runtime_strict(ProjectSettings.get_setting(BridgeSecret.STRICT_SETTING, false))
+
+
 ## D3: the editor selection changed — godot://editor-state reflects the selection.
 func _on_selection_changed() -> void:
 	if _server:

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -15,6 +15,17 @@ extends Node
 ## An EXPORTED game carries this autoload too, and there it stays closed: no socket, no
 ## secret written, no logger hooked (325, BP-0023 — see bridge_secret.gd's
 ## runtime_listen_policy for the one opt-in, debug exports only).
+##
+## STRICT MODE (BP-0037, opt-in through 1.x): a project that sets
+## `breakpoint_mcp/runtime/strict=true` gets no autoload from the plugin. The game attaches
+## this script itself, from its own debug-only code, by path — so an export preset that
+## leaves `addons/breakpoint_mcp/` out leaves no reference behind:
+##     const BP := "res://addons/breakpoint_mcp/runtime_bridge.gd"
+##     if OS.is_debug_build() and ResourceLoader.exists(BP):
+##         var bridge: Node = load(BP).new()
+##         bridge.name = "BreakpointRuntimeBridge"
+##         get_tree().root.add_child.call_deferred(bridge)
+## and the bridge then listens only with BREAKPOINT_RUNTIME=1 or `--breakpoint-runtime`.
 
 ## The addon version this GAME is running, answered on `ping`.
 ##
@@ -25,7 +36,7 @@ extends Node
 ## and the process that is already running keeps the addon it loaded. Held in lockstep
 ## with `plugin.cfg` and with `operations.gd`'s copy by contract_check check 14, which
 ## exists because two of those literals disagreed for two releases.
-const ADDON_VERSION := "1.17.0"
+const ADDON_VERSION := "1.19.0"
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
 const DEFAULT_PORT := 9081
@@ -76,6 +87,14 @@ const BridgeSecret := preload("res://addons/breakpoint_mcp/bridge_secret.gd")
 const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
 # F4: methods dispatched on the async lane (they await frames); see _handle_line / _dispatch_async.
 const ASYNC_METHODS := ["runtime.step_frames"]
+# 🆕 BP-0041 (1.19.0): the input kinds runtime.inject_input answers, in the order the
+# refusal lists them. `pointer` alone rides the async lane (a tap or drag spans frames).
+const INPUT_KINDS := ["action", "key", "mouse_button", "mouse_motion", "joypad_button", "joypad_motion", "pointer"]
+const POINTER_ACTIONS := ["press", "move", "release", "tap", "drag"]
+# The pointer's `button` is a MouseButton index, as on mouse_button: 1 left, 2 right, 3 middle.
+const POINTER_MASKS := {MOUSE_BUTTON_LEFT: MOUSE_BUTTON_MASK_LEFT, MOUSE_BUTTON_RIGHT: MOUSE_BUTTON_MASK_RIGHT, MOUSE_BUTTON_MIDDLE: MOUSE_BUTTON_MASK_MIDDLE}
+const STRETCH_MODES := ["disabled", "canvas_items", "viewport"]
+const STRETCH_ASPECTS := ["ignore", "keep", "keep_width", "keep_height", "expand"]
 # F4: default salient fields captured by runtime.state_digest when no explicit list is given.
 const _DIGEST_DEFAULT_FIELDS := ["position", "global_position", "rotation", "scale", "visible", "modulate"]
 
@@ -96,9 +115,14 @@ var _in_capture: bool = false
 ## 🔴 325 (BP-0023): the listen decision, taken first in _ready (bridge_secret.gd's
 ## runtime_listen_policy). Read by _setup_auth for where the secret comes from.
 var _policy: Dictionary = {}
+## 🆕 BP-0041: where the injected pointer last was and which buttons it holds, so a
+## `press`, `move` and `release` sent as three calls carry the relative motion and the
+## button_mask one real gesture would.
+var _pointer_at := Vector2.ZERO
+var _pointer_mask: int = 0
 
 
-## The four facts the listen policy is decided on. A method and not inline so the
+## The facts the listen policy is decided on. A method and not inline so the
 ## headless smoke can stand an exported build up inside an editor binary — the only
 ## binary CI has — by overriding this one function and nothing else.
 func _policy_facts() -> Dictionary:
@@ -107,6 +131,9 @@ func _policy_facts() -> Dictionary:
 		"debug_build": OS.is_debug_build(),
 		"exported_optin": OS.get_environment("BREAKPOINT_RUNTIME_EXPORTED"),
 		"env_secret": OS.get_environment("BREAKPOINT_RUNTIME_SECRET"),
+		# 🆕 BP-0037 — strict mode and its developer switch (bridge_secret.gd).
+		"strict": BridgeSecret.runtime_strict(ProjectSettings.get_setting(BridgeSecret.STRICT_SETTING, false)),
+		"switch": BridgeSecret.runtime_switch_on(OS.get_environment(BridgeSecret.SWITCH_ENV), OS.get_cmdline_user_args()),
 	}
 
 
@@ -117,7 +144,7 @@ func _ready() -> void:
 	# that calls it — and a shipped game prints nothing unless someone asked for the
 	# bridge and is being refused.
 	var f := _policy_facts()
-	_policy = BridgeSecret.runtime_listen_policy(bool(f["editor_build"]), bool(f["debug_build"]), String(f["exported_optin"]), String(f["env_secret"]))
+	_policy = BridgeSecret.runtime_listen_policy(bool(f["editor_build"]), bool(f["debug_build"]), String(f["exported_optin"]), String(f["env_secret"]), bool(f.get("strict", false)), bool(f.get("switch", false)))
 	if not bool(_policy["listen"]):
 		set_process(false)
 		if bool(_policy["warn"]):
@@ -294,7 +321,7 @@ func _handle_line(c: Dictionary, line: String) -> void:
 	# F4: async lane — methods that await frames can't use the synchronous dispatch (which sends
 	# its response immediately). Start a coroutine that sends the id'd response when done; the host
 	# correlates responses by id, so an out-of-order async response is fine.
-	if method in ASYNC_METHODS:
+	if method in ASYNC_METHODS or _is_pointer(method, params):
 		_dispatch_async(c, id, method, params)
 		return
 	# D1a: the engine-error echo. The ring already receives every push_error /
@@ -471,6 +498,8 @@ func _dispatch(method: String, params: Dictionary) -> Dictionary:
 			return _state_digest(params)
 		"runtime.seed_rng":
 			return _seed_rng(params)
+		"runtime.read_state":
+			return _read_state(params)
 		"runtime.step_frames":
 			# Dispatched on the async lane (see _handle_line / _dispatch_async); this placeholder
 			# keeps the static contract check (which scans _dispatch case labels) aware of the
@@ -714,32 +743,242 @@ func _inject_input(params: Dictionary) -> Dictionary:
 				Input.action_release(action)
 			return _ok({"injected": true, "kind": kind})
 		"key":
+			# 🆕 BP-0041: keys bound in the editor's Input Map are stored by PHYSICAL key (the
+			# dialog's default), and an event carrying only `keycode` never matches one — so
+			# today's key kind reached `_input` but not the actions. A key with none of the
+			# three codes is KEY_NONE, which matches nothing, so it is refused, not injected.
+			if not (ev.has("keycode") or ev.has("physical_keycode") or ev.has("key_label")):
+				return _err("bad_event", "A key event needs at least one of event.keycode, event.physical_keycode or event.key_label; with none it is KEY_NONE and matches no key and no action.")
 			var k := InputEventKey.new()
 			k.keycode = int(ev.get("keycode", 0))
+			k.physical_keycode = int(ev.get("physical_keycode", 0))
+			k.key_label = int(ev.get("key_label", 0))
+			k.unicode = int(ev.get("unicode", 0))
+			k.echo = bool(ev.get("echo", false))
 			k.pressed = bool(ev.get("pressed", true))
+			_apply_modifiers(k, ev)
 			Input.parse_input_event(k)
 			return _ok({"injected": true, "kind": kind})
 		"mouse_button":
 			var mb := InputEventMouseButton.new()
 			mb.button_index = int(ev.get("button", 1))
 			mb.pressed = bool(ev.get("pressed", true))
-			var pos_err := _apply_vector2(ev, "position", func(v: Vector2) -> void: mb.position = v)
+			mb.double_click = bool(ev.get("double_click", false))
+			var in_frame := String(ev.get("space", "window")) == "frame"
+			var pos_err := _apply_vector2(ev, "position", func(v: Vector2) -> void: mb.position = _frame_to_window(v) if in_frame else v)
 			if not pos_err.is_empty():
 				return pos_err
+			mb.global_position = mb.position
+			_apply_modifiers(mb, ev)
 			Input.parse_input_event(mb)
 			return _ok({"injected": true, "kind": kind})
 		"mouse_motion":
 			var mm := InputEventMouseMotion.new()
-			var mpos_err := _apply_vector2(ev, "position", func(v: Vector2) -> void: mm.position = v)
+			var m_in_frame := String(ev.get("space", "window")) == "frame"
+			var mpos_err := _apply_vector2(ev, "position", func(v: Vector2) -> void: mm.position = _frame_to_window(v) if m_in_frame else v)
 			if not mpos_err.is_empty():
 				return mpos_err
 			var rel_err := _apply_vector2(ev, "relative", func(v: Vector2) -> void: mm.relative = v)
 			if not rel_err.is_empty():
 				return rel_err
+			mm.global_position = mm.position
+			mm.button_mask = int(ev.get("button_mask", 0))
+			_apply_modifiers(mm, ev)
 			Input.parse_input_event(mm)
 			return _ok({"injected": true, "kind": kind})
+		"joypad_button":
+			if not ev.has("button"):
+				return _err("bad_event", "A joypad_button event needs event.button, Godot's JoyButton index (0 is the bottom face button).")
+			var jb := InputEventJoypadButton.new()
+			jb.device = int(ev.get("device", 0))
+			jb.button_index = int(ev.get("button"))
+			jb.pressed = bool(ev.get("pressed", true))
+			jb.pressure = float(ev.get("pressure", 1.0 if jb.pressed else 0.0))
+			Input.parse_input_event(jb)
+			return _ok({"injected": true, "kind": kind})
+		"joypad_motion":
+			if not ev.has("axis"):
+				return _err("bad_event", "A joypad_motion event needs event.axis, Godot's JoyAxis index (0 to 5), and event.value from -1 to 1.")
+			var jm := InputEventJoypadMotion.new()
+			jm.device = int(ev.get("device", 0))
+			jm.axis = int(ev.get("axis"))
+			jm.axis_value = clampf(float(ev.get("value", 0.0)), -1.0, 1.0)
+			Input.parse_input_event(jm)
+			return _ok({"injected": true, "kind": kind})
+		"pointer":
+			# Reached only from a caller that bypassed _handle_line's routing; the lane is async.
+			return _err("async_only", "runtime.inject_input with kind pointer is dispatched on the async lane")
 		_:
-			return _err("bad_kind", "Unknown input kind: %s" % kind)
+			return _err("bad_kind", "Unknown input kind: %s. The kinds are %s." % [kind, ", ".join(INPUT_KINDS)])
+
+
+## 🆕 BP-0041 — the four modifier flags, on any event that carries them.
+func _apply_modifiers(e: InputEventWithModifiers, ev: Dictionary) -> void:
+	e.shift_pressed = bool(ev.get("shift", false))
+	e.ctrl_pressed = bool(ev.get("ctrl", false))
+	e.alt_pressed = bool(ev.get("alt", false))
+	e.meta_pressed = bool(ev.get("meta", false))
+
+
+## 🆕 BP-0041 — true when this call is a `pointer` gesture, which awaits frames and so
+## rides the async lane like runtime.step_frames.
+static func _is_pointer(method: String, params: Dictionary) -> bool:
+	if method != "runtime.inject_input":
+		return false
+	var ev: Variant = params.get("event")
+	return typeof(ev) == TYPE_DICTIONARY and String((ev as Dictionary).get("kind", "")) == "pointer"
+
+
+## 🆕 BP-0041 — the geometry that relates `runtime.screenshot`'s frame to the window.
+## `texture` is the frame's own pixel size (the image's, NOT `ViewportTexture.get_size()`:
+## measured windowed on 4.7 under canvas_items, that answered 685x386 for an 888x500 frame); `visible_rect` is the viewport's coordinate
+## space (what input events and Controls use); `window` is the OS window's client size;
+## the stretch fields are the root window's content scale settings.
+func _viewport_block(vp: Viewport, frame_size: Vector2) -> Dictionary:
+	var tex_size := frame_size
+	var vis := vp.get_visible_rect()
+	var win: Window = vp as Window if vp is Window else vp.get_window()
+	var block := {
+		"texture": [tex_size.x, tex_size.y],
+		"visible_rect": [vis.position.x, vis.position.y, vis.size.x, vis.size.y],
+		"window": [vis.size.x, vis.size.y],
+		"stretch_mode": "disabled",
+		"stretch_aspect": "ignore",
+		"content_scale_factor": 1.0,
+	}
+	if win != null:
+		block["window"] = [float(win.size.x), float(win.size.y)]
+		block["stretch_mode"] = STRETCH_MODES[clampi(int(win.content_scale_mode), 0, STRETCH_MODES.size() - 1)]
+		block["stretch_aspect"] = STRETCH_ASPECTS[clampi(int(win.content_scale_aspect), 0, STRETCH_ASPECTS.size() - 1)]
+		block["content_scale_factor"] = win.content_scale_factor
+	return block
+
+
+## 🆕 BP-0041 — the transform that carries a pixel of the frame `runtime.screenshot`
+## returns to a window pixel, in all three stretch modes.
+##
+## Godot's root window maps viewport coordinates to the window with
+## `get_final_transform()` = window_transform * stretch_transform * global_canvas_transform
+## (window.cpp, 4.3-4.7), and `Viewport._make_input_local` INVERTS exactly that for every
+## event. The frame is the viewport's render target, whose pixels are viewport coordinates
+## times the stretch scale — so frame -> window is `window_transform` alone: the letterbox
+## offset under canvas_items, offset and upscale under viewport, identity when disabled.
+## Measured windowed on the Mac (4.7, 1000x500 window, 1152x648 base, aspect keep): taps and
+## drags at frame pixels landed on their targets under all three modes.
+func _frame_transform() -> Transform2D:
+	var vp := get_viewport()
+	if vp == null:
+		return Transform2D.IDENTITY
+	if vp.has_method("get_stretch_transform"):  # bound from Godot 4.4
+		var inner: Transform2D = vp.call("get_stretch_transform") * vp.global_canvas_transform
+		return vp.get_final_transform() * inner.affine_inverse()
+	# 4.2 / 4.3 bind no stretch accessor, so the frame's own size says the stretch scale.
+	var tex := vp.get_texture()
+	var img: Image = tex.get_image() if tex != null else null
+	if img == null or img.get_width() <= 0 or img.get_height() <= 0:
+		return Transform2D.IDENTITY
+	var vis := vp.get_visible_rect()
+	var to_local := Transform2D(0.0, vis.size / Vector2(img.get_width(), img.get_height()), 0.0, vis.position)
+	return vp.get_final_transform() * to_local
+
+
+func _frame_to_window(f: Vector2) -> Vector2:
+	return _frame_transform() * f
+
+
+## 🆕 BP-0041 — the pointer kind: press / move / release / tap / drag, at points given in
+## the frame's pixels (`space` "frame", the default) or the window's (`space` "window").
+## The reply carries the window points actually sent, so a miss is visible in the reply.
+func _inject_pointer(ev_in: Variant) -> Dictionary:
+	if typeof(ev_in) != TYPE_DICTIONARY:
+		return _err("bad_event", "event must be an object.")
+	var ev: Dictionary = ev_in
+	var action := String(ev.get("action", ""))
+	if not action in POINTER_ACTIONS:
+		return _err("bad_event", "A pointer event needs event.action, one of %s; got %s." % [", ".join(POINTER_ACTIONS), JSON.stringify(action)])
+	if not (ev.has("x") and ev.has("y")):
+		return _err("bad_event", "A pointer event needs event.x and event.y, pixels of the frame runtime_screenshot returns.")
+	if action == "drag" and not (ev.has("to_x") and ev.has("to_y")):
+		return _err("bad_event", "A pointer drag needs event.to_x and event.to_y, where the button is released.")
+	var bname := int(ev.get("button", MOUSE_BUTTON_LEFT))
+	if not POINTER_MASKS.has(bname):
+		return _err("bad_event", "A pointer's event.button is a MouseButton index: 1 left, 2 right or 3 middle; got %s." % JSON.stringify(ev.get("button")))
+	var in_frame := String(ev.get("space", "frame")) != "window"
+	var warp := bool(ev.get("warp", false))
+	var per_step := clampi(int(ev.get("frames_per_step", 1)), 1, 10)
+	var xf := _frame_transform() if in_frame else Transform2D.IDENTITY
+	var start := xf * Vector2(float(ev.get("x")), float(ev.get("y")))
+	var points: Array = []
+	var frames := 0
+	match action:
+		"press":
+			_pointer_button(start, bname, true, warp)
+			points.append(start)
+		"release":
+			_pointer_button(start, bname, false, warp)
+			points.append(start)
+		"move":
+			_pointer_motion(start, warp)
+			points.append(start)
+		"tap":
+			_pointer_button(start, bname, true, warp)
+			points.append(start)
+			frames += await _pointer_wait(per_step)
+			_pointer_button(start, bname, false, warp)
+			points.append(start)
+		"drag":
+			var end := xf * Vector2(float(ev.get("to_x")), float(ev.get("to_y")))
+			var steps := clampi(int(ev.get("steps", 8)), 1, 60)
+			_pointer_button(start, bname, true, warp)
+			points.append(start)
+			for i in range(1, steps + 1):
+				frames += await _pointer_wait(per_step)
+				var p := start.lerp(end, float(i) / float(steps))
+				_pointer_motion(p, warp)
+				points.append(p)
+			frames += await _pointer_wait(per_step)
+			_pointer_button(end, bname, false, warp)
+			points.append(end)
+	var sent: Array = []
+	for p in points:
+		sent.append([(p as Vector2).x, (p as Vector2).y])
+	return _ok({"injected": true, "kind": "pointer", "window_points": sent, "frames": frames})
+
+
+func _pointer_wait(n: int) -> int:
+	var tree := get_tree()
+	for _i in n:
+		await tree.process_frame
+	return n
+
+
+func _pointer_button(at: Vector2, bname: int, pressed: bool, warp: bool) -> void:
+	if warp:
+		Input.warp_mouse(at)
+	if pressed:
+		_pointer_mask |= int(POINTER_MASKS[bname])
+	else:
+		_pointer_mask &= ~int(POINTER_MASKS[bname])
+	var mb := InputEventMouseButton.new()
+	mb.button_index = bname
+	mb.pressed = pressed
+	mb.position = at
+	mb.global_position = at
+	mb.button_mask = _pointer_mask
+	Input.parse_input_event(mb)
+	_pointer_at = at
+
+
+func _pointer_motion(at: Vector2, warp: bool) -> void:
+	if warp:
+		Input.warp_mouse(at)
+	var mm := InputEventMouseMotion.new()
+	mm.position = at
+	mm.global_position = at
+	mm.relative = at - _pointer_at
+	mm.button_mask = _pointer_mask
+	Input.parse_input_event(mm)
+	_pointer_at = at
 
 
 ## Apply an OPTIONAL Vector2 field of a synthetic input event, or say why not.
@@ -825,6 +1064,7 @@ func _screenshot() -> Dictionary:
 		"base64": Marshalls.raw_to_base64(buf),
 		"width": img.get_width(),
 		"height": img.get_height(),
+		"viewport": _viewport_block(vp, Vector2(img.get_width(), img.get_height())),
 	})
 
 
@@ -1172,6 +1412,46 @@ func _anim_get_state(params: Dictionary) -> Dictionary:
 	return _ok(_anim_state(ap))
 
 
+# ------------------------------------------- BP-0037 D: state the game exposes ----
+
+## The Engine metadata key a game registers its state readers under. The game needs no
+## reference to this folder or any class in it — it writes a Dictionary of
+## name -> Callable to Engine metadata from its own debug-only code:
+##     if OS.is_debug_build():
+##         var reg: Dictionary = Engine.get_meta(&"breakpoint_state", {})
+##         reg["mixer"] = _debug_mixer_state
+##         Engine.set_meta(&"breakpoint_state", reg)
+## so it compiles and runs unchanged in an export that leaves addons/breakpoint_mcp/ out.
+const STATE_META := &"breakpoint_state"
+
+
+## runtime.read_state — read-only by construction: it reads the registry and calls only
+## what the game chose to register there. No `name` lists the registered names.
+func _read_state(params: Dictionary) -> Dictionary:
+	if not Engine.has_meta(STATE_META) or typeof(Engine.get_meta(STATE_META)) != TYPE_DICTIONARY:
+		return _err("no_state_registry", "The game registered no state readers: Engine metadata \"breakpoint_state\" is not a Dictionary of name -> Callable.")
+	var reg: Dictionary = Engine.get_meta(STATE_META)
+	var names: Array = []
+	var by_name := {}
+	for k in reg.keys():
+		names.append(String(k))
+		by_name[String(k)] = reg[k]
+	names.sort()
+	var state_name := String(params.get("name", ""))
+	if state_name == "":
+		return _ok({"names": names})
+	if not by_name.has(state_name):
+		return _err("unknown_state", "No state reader named \"%s\". Registered: %s" % [state_name, ", ".join(PackedStringArray(names)) if not names.is_empty() else "(none)"])
+	var reader: Variant = by_name[state_name]
+	if typeof(reader) != TYPE_CALLABLE or not (reader as Callable).is_valid():
+		return _err("state_reader_gone", "The reader registered as \"%s\" is no longer callable — the object behind it was freed." % state_name)
+	var args: Array = []
+	for a in params.get("args", []):
+		args.append(Codec.decode(a))
+	var value: Variant = (reader as Callable).callv(args)
+	return _ok({"names": names, "name": state_name, "value": Codec.encode(value)})
+
+
 # ----------------------------------------------------- F8: node lifecycle ----
 
 func _node_add(params: Dictionary) -> Dictionary:
@@ -1258,6 +1538,8 @@ func _dispatch_async(c: Dictionary, id: Variant, method: String, params: Diction
 	match method:
 		"runtime.step_frames":
 			result = await _step_frames(params)
+		"runtime.inject_input":
+			result = await _inject_pointer(params.get("event", {}))
 		_:
 			result = _err("async_only", "not an async method: %s" % method)
 	var peer: StreamPeerTCP = c.get("peer")

package/dist/annotations.js

@@ -14,7 +14,7 @@ const READ_ONLY = [
     "resource_load", "runtime_anim_get_state", "runtime_assert_node_state", "runtime_assert_perf",
     "runtime_assert_scene_structure", "runtime_assert_screen_text", "runtime_await_condition", "runtime_get_log",
     "runtime_get_monitors", "runtime_get_property", "runtime_get_tree", "runtime_screenshot",
-    "runtime_peers_digest", "runtime_screenshot_diff", "runtime_state_digest", "scene_get_dependencies",
+    "runtime_peers_digest", "runtime_read_state", "runtime_screenshot_diff", "runtime_state_digest", "scene_get_dependencies",
     "scene_get_tree", "scene_list_open", "screenshot_editor", "selection_get", "signal_list",
     "signal_list_connections", "test_detect", "test_list", "tilemap_get_cell", "vcs_blame", "vcs_branch_list",
     "vcs_diff", "vcs_log", "vcs_show", "vcs_status",
@@ -85,8 +85,8 @@ const IDEMPOTENT = [
     "resource_set_import_settings", "resource_set_property", "rigidbody_set_properties", "runtime_anim_get_state",
     "runtime_anim_stop", "runtime_assert_node_state", "runtime_assert_perf", "runtime_assert_scene_structure",
     "runtime_assert_screen_text", "runtime_await_condition", "runtime_get_log", "runtime_get_monitors",
-    "runtime_get_property", "runtime_get_tree", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest",
-    "runtime_screenshot", "runtime_screenshot_diff", "runtime_seed_rng", "runtime_set_property",
+    "runtime_get_property", "runtime_get_tree", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest", "runtime_read_state",
+    "runtime_screenshot", "runtime_screenshot_diff", "runtime_screenshot_save", "runtime_seed_rng", "runtime_set_property",
     "runtime_state_digest", "runtime_time_scale", "scene_get_dependencies", "scene_get_tree", "scene_list_open", "scene_new", "scene_open",
     "scene_pack", "scene_reload", "scene_save", "scene_save_as", "screenshot_editor", "selection_get",
     "selection_set", "shader_create", "shader_set_code", "shadermaterial_create", "shadermaterial_set_param",
@@ -156,8 +156,8 @@ export const ALL_ANNOTATED = [
     "runtime_anim_play", "runtime_anim_stop", "runtime_assert_node_state", "runtime_assert_perf",
     "runtime_assert_scene_structure", "runtime_assert_screen_text", "runtime_await_condition", "runtime_call_method",
     "runtime_emit_signal", "runtime_get_log", "runtime_get_monitors", "runtime_get_property", "runtime_get_tree",
-    "runtime_inject_input", "runtime_node_add", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest",
-    "runtime_screenshot", "runtime_screenshot_diff", "runtime_seed_rng", "runtime_set_property",
+    "runtime_inject_input", "runtime_node_add", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest", "runtime_read_state",
+    "runtime_screenshot", "runtime_screenshot_diff", "runtime_screenshot_save", "runtime_seed_rng", "runtime_set_property",
     "runtime_spawn_peers", "runtime_state_digest", "runtime_step_frames", "runtime_time_scale", "scene_close",
     "scene_get_dependencies", "scene_get_tree",
     "scene_list_open", "scene_new", "scene_open", "scene_pack", "scene_reload", "scene_save", "scene_save_as",