breakpoint-mcp 1.19.1 → 1.21.1

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. **276 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **286 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/operations.gd

@@ -7,7 +7,7 @@ extends RefCounted
 ## wrapped in the EditorUndoRedoManager so a human can Ctrl-Z anything the assistant did.
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
-const ADDON_VERSION := "1.7.0"
+const ADDON_VERSION := "1.9.1"
 
 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.7.0"
+version="1.9.1"
 script="plugin.gd"

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -47,6 +47,10 @@ const MONITORS := {
 
 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"]
+# 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"]
 
 var _server: TCPServer
 var _clients: Array = [] # Array of {peer, buf}
@@ -219,6 +223,12 @@ func _handle_line(c: Dictionary, line: String) -> void:
 		held.merge(PauseLatch.held_response(method))
 		_send(peer, held)
 		return
+	# 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:
+		_dispatch_async(c, id, method, params)
+		return
 	var result := _dispatch(method, params)
 	var response := {"id": id}
 	response.merge(result)
@@ -324,6 +334,27 @@ func _dispatch(method: String, params: Dictionary) -> Dictionary:
 			return _assert_screen_text(params)
 		"runtime.screenshot_diff":
 			return _screenshot_diff(params)
+		"runtime.anim_play":
+			return _anim_play(params)
+		"runtime.anim_stop":
+			return _anim_stop(params)
+		"runtime.anim_get_state":
+			return _anim_get_state(params)
+		"runtime.node_add":
+			return _node_add(params)
+		"runtime.node_remove":
+			return _node_remove(params)
+		"runtime.time_scale":
+			return _time_scale(params)
+		"runtime.state_digest":
+			return _state_digest(params)
+		"runtime.seed_rng":
+			return _seed_rng(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
+			# method. It is not reached in normal operation.
+			return _err("async_only", "runtime.step_frames is dispatched on the async lane")
 		_:
 			return _err("unknown_method", "No such method: %s" % method)
 
@@ -767,3 +798,215 @@ func _compare_images(frame: Image, reference_img: Image, params: Dictionary, ref
 		"height": h,
 		"reference": reference,
 	})
+
+
+# ----------------------------------------------------- F8: animation ---------
+
+## Resolve a node and require it to be an AnimationPlayer.
+func _resolve_anim_player(path: String):
+	var node := _resolve(path)
+	if node == null:
+		return _err("bad_path", "Node not found: %s" % path)
+	if not (node is AnimationPlayer):
+		return _err("not_animation_player", "%s is not an AnimationPlayer" % node.get_class())
+	return node as AnimationPlayer
+
+
+func _anim_state(ap: AnimationPlayer) -> Dictionary:
+	var anims: Array = []
+	for a in ap.get_animation_list():
+		anims.append(String(a))
+	return {
+		"playing": ap.is_playing(),
+		"current_animation": ap.current_animation,
+		"position": ap.current_animation_position,
+		"length": ap.current_animation_length,
+		"speed_scale": ap.speed_scale,
+		"animations": anims,
+	}
+
+
+func _anim_play(params: Dictionary) -> Dictionary:
+	var res = _resolve_anim_player(String(params.get("path", "")))
+	if res is Dictionary:
+		return res
+	var ap: AnimationPlayer = res
+	var anim := String(params.get("animation", ""))
+	if anim != "" and not ap.has_animation(anim):
+		return _err("no_animation", "AnimationPlayer has no animation '%s'" % anim)
+	var speed := float(params.get("custom_speed", 1.0))
+	var from_end := bool(params.get("from_end", false))
+	ap.play(anim, -1.0, speed, from_end)
+	return _ok({
+		"playing": ap.is_playing(),
+		"current_animation": ap.current_animation,
+		"speed_scale": ap.speed_scale,
+	})
+
+
+func _anim_stop(params: Dictionary) -> Dictionary:
+	var res = _resolve_anim_player(String(params.get("path", "")))
+	if res is Dictionary:
+		return res
+	var ap: AnimationPlayer = res
+	# keep_state:true pauses in place; default stops. pause()/stop() with no args are
+	# stable across Godot 4.2–4.5 (unlike stop()'s changing keep_state parameter).
+	if bool(params.get("keep_state", false)):
+		ap.pause()
+	else:
+		ap.stop()
+	return _ok({
+		"playing": ap.is_playing(),
+		"current_animation": ap.current_animation,
+		"position": ap.current_animation_position,
+	})
+
+
+func _anim_get_state(params: Dictionary) -> Dictionary:
+	var res = _resolve_anim_player(String(params.get("path", "")))
+	if res is Dictionary:
+		return res
+	var ap: AnimationPlayer = res
+	return _ok(_anim_state(ap))
+
+
+# ----------------------------------------------------- F8: node lifecycle ----
+
+func _node_add(params: Dictionary) -> Dictionary:
+	var parent := _resolve(String(params.get("parent", "")))
+	if parent == null:
+		return _err("bad_path", "Parent not found: %s" % params.get("parent", ""))
+	var child: Node = null
+	var scene_path := String(params.get("scene", ""))
+	if scene_path != "":
+		var ps: Variant = load(scene_path)
+		if ps == null or not (ps is PackedScene):
+			return _err("bad_scene", "Could not load PackedScene: %s" % scene_path)
+		child = (ps as PackedScene).instantiate()
+	else:
+		var type_name := String(params.get("type", ""))
+		if type_name == "":
+			return _err("bad_args", "Provide either 'scene' or 'type'")
+		if not ClassDB.class_exists(type_name) or not ClassDB.can_instantiate(type_name):
+			return _err("bad_type", "Cannot instantiate class: %s" % type_name)
+		var obj: Variant = ClassDB.instantiate(type_name)
+		if not (obj is Node):
+			return _err("not_a_node", "%s is not a Node" % type_name)
+		child = obj
+	if child == null:
+		return _err("instantiate_failed", "Failed to instantiate node")
+	var nm := String(params.get("name", ""))
+	if nm != "":
+		child.name = nm
+	parent.add_child(child)
+	return _ok({"added": true, "path": _path_of(child), "type": child.get_class()})
+
+
+func _node_remove(params: Dictionary) -> Dictionary:
+	var node := _resolve(String(params.get("path", "")))
+	if node == null:
+		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
+	if node == _base():
+		return _err("cannot_remove_root", "Refusing to remove the current scene root")
+	var p := _path_of(node)
+	node.queue_free()
+	return _ok({"removed": true, "path": p})
+
+
+# ----------------------------------------------- F4: deterministic playtesting ----
+
+## Async dispatch lane: run a coroutine that awaits frames, then send the id'd response. Started
+## as a bare (un-awaited) call from _handle_line so _process never blocks; it resumes on the
+## engine's frame signals and sends when complete.
+func _dispatch_async(c: Dictionary, id: Variant, method: String, params: Dictionary) -> void:
+	var result: Dictionary
+	match method:
+		"runtime.step_frames":
+			result = await _step_frames(params)
+		_:
+			result = _err("async_only", "not an async method: %s" % method)
+	var peer: StreamPeerTCP = c.get("peer")
+	if peer != null and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+		var response := {"id": id}
+		response.merge(result)
+		_send(peer, response)
+
+
+## Advance the game by an exact number of frames while otherwise frozen. Toggles
+## get_tree().paused false -> (await one frame) -> true per step (the standard Godot frame-step
+## idiom); the bridge keeps servicing the socket throughout because it is PROCESS_MODE_ALWAYS.
+## Restores the caller's prior pause state when done.
+func _step_frames(params: Dictionary) -> Dictionary:
+	var tree := get_tree()
+	if tree == null:
+		return _err("no_tree", "No scene tree")
+	var frames := clampi(int(params.get("frames", 1)), 1, 100000)
+	var kind := String(params.get("kind", "idle"))
+	var prev_scale := Engine.time_scale
+	# Advance by exactly `frames`: restore a normal time scale for the step (the caller froze via
+	# runtime_time_scale{scale:0}, which zeroes delta), and count real frames off the ENGINE frame
+	# counters. Freeze/step are driven by time_scale (delta), NOT get_tree().paused: pause is a
+	# per-node processing gate that desyncs from the frame counter by one frame at the step boundary
+	# (a node advances N-1 for N counted frames), whereas with time_scale the node processes every
+	# frame and the counter matches its work 1:1. time_scale is restored after.
+	Engine.time_scale = 1.0
+	if kind == "physics" or kind == "both":
+		var target_p := Engine.get_physics_frames() + frames
+		while Engine.get_physics_frames() < target_p:
+			await tree.physics_frame
+	else:
+		var target_i := Engine.get_process_frames() + frames
+		while Engine.get_process_frames() < target_i:
+			await tree.process_frame
+	Engine.time_scale = prev_scale
+	return _ok({"frames_advanced": frames, "frame_index": Engine.get_process_frames()})
+
+
+func _time_scale(params: Dictionary) -> Dictionary:
+	var previous := Engine.time_scale
+	var scale := maxf(0.0, float(params.get("scale", 1.0)))
+	Engine.time_scale = scale
+	# scale 0 freezes the game clock (delta -> 0): delta-based motion, tweens, timers and
+	# animations halt. runtime_step_frames temporarily restores a normal scale to advance an exact
+	# number of frames. Deliberately time_scale, not get_tree().paused — pause is a per-node
+	# processing gate that desyncs from the frame counter by one frame at the step boundary.
+	return _ok({"previous": previous, "current": Engine.time_scale})
+
+
+func _seed_rng(params: Dictionary) -> Dictionary:
+	var s := int(params.get("seed", 0))
+	seed(s)
+	return _ok({"seed": s})
+
+
+## Read a compact, stable-ordered snapshot of a subtree's salient state (read-only). Default
+## fields are the common transform/visibility properties; a caller may pass an explicit list.
+func _state_digest(params: Dictionary) -> Dictionary:
+	var root := _resolve(String(params.get("root", "")))
+	if root == null:
+		return _err("bad_path", "Node not found: %s" % params.get("root", ""))
+	var raw_fields: Variant = params.get("fields", [])
+	var fields: Array = raw_fields if typeof(raw_fields) == TYPE_ARRAY else []
+	var max_depth := int(params.get("max_depth", 8))
+	var digest := {}
+	var count := _digest_walk(root, 0, max_depth, fields, digest)
+	return _ok({"digest": digest, "node_count": count})
+
+
+func _digest_walk(node: Node, depth: int, max_depth: int, fields: Array, digest: Dictionary) -> int:
+	var entry := {}
+	if fields.is_empty():
+		for f in _DIGEST_DEFAULT_FIELDS:
+			var dv: Variant = node.get(f)
+			if dv != null:
+				entry[f] = Codec.encode(dv)
+	else:
+		for f in fields:
+			var fn := String(f)
+			entry[fn] = Codec.encode(node.get(fn))
+	digest[_path_of(node)] = entry
+	var count := 1
+	if depth < max_depth:
+		for ch in node.get_children():
+			count += _digest_walk(ch, depth + 1, max_depth, fields, digest)
+	return count

package/dist/cli/doctor.js

@@ -193,7 +193,7 @@ export function checkCapabilities(config) {
             status: "ok",
             severity: "info",
             detail: dropped.length === 0
-                ? `${state} — full 276-tool surface`
+                ? `${state} — full 286-tool surface`
                 : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
             hint: dropped.length === 0
                 ? undefined

package/dist/cli/init.js

@@ -279,7 +279,7 @@ export async function runInit(argv, deps = {}) {
     // Trust groups — surface the secure default so even a bare `init` teaches it.
     say("");
     if (privilegedGroups) {
-        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 276-tool surface loads.`);
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 286-tool surface loads.`);
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");

package/dist/index.js

@@ -35,7 +35,7 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.19.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.21.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);

package/dist/recipes.js

@@ -7,7 +7,7 @@
  * it's **free** (MIT, shipped in the server), and it sits **over typed,
  * schema-validated, undoable tools** — so the contract is executed by the
  * server, not merely described in prose the model might misapply. Recipes are
- * discoverable via MCP `prompts/list`; they add **no tools** (the 276-tool
+ * discoverable via MCP `prompts/list`; they add **no tools** (the 286-tool
  * count is unchanged) and cost nothing until a client pulls one.
  */
 import { z } from "zod";
@@ -27,6 +27,7 @@ export const RECIPE_NAMES = [
     "recipe_screenshot_regression",
     "recipe_type_safe_edit",
     "recipe_csharp_fix_and_debug",
+    "recipe_deterministic_playtest",
 ];
 export function registerRecipes(server) {
     // 1 — 2D player controller, then verify it moves.
@@ -164,5 +165,36 @@ export function registerRecipes(server) {
             SAFETY,
         ].join("\n"));
     });
+    // 7 — Deterministic playtesting: freeze, step exact frames, assert a golden frame.
+    server.registerPrompt("recipe_deterministic_playtest", {
+        title: "Freeze the game, step exact frames, and assert a deterministic golden frame",
+        description: "Turn a flaky run-screenshot-guess loop into a frame-exact, reproducible one: freeze time, advance a fixed number of frames, then assert node state and diff a golden frame.",
+        argsSchema: {
+            scene_path: z.string().optional().describe("Scene to play-test (default res://main.tscn)"),
+            root_path: z.string().optional().describe("Node to snapshot/assert on (default '.', the running scene root)"),
+            frames: z.string().optional().describe("Frames to advance per step (default 30)"),
+            reference_path: z.string().optional().describe("Golden PNG for the screenshot diff (default res://tests/frame.png)"),
+            tolerance: z.string().optional().describe("Max fraction of differing pixels for the diff (default 0.0)"),
+        },
+    }, (a) => {
+        const scene = str(a, "scene_path", "res://main.tscn");
+        const root = str(a, "root_path", ".");
+        const frames = str(a, "frames", "30");
+        const ref = str(a, "reference_path", "res://tests/frame.png");
+        const tol = str(a, "tolerance", "0.0");
+        return recipe("Deterministic, frame-exact playtesting with a golden-frame check.", [
+            `Goal: drive ${scene} to an exact, reproducible frame and assert on it — no wall-clock flakiness.`,
+            "",
+            `1. Boot + freeze: godot_run_project. runtime_time_scale{scale:0} to FREEZE the game (this pauses the SceneTree, so nothing advances on its own). If the run uses randomness, runtime_seed_rng{seed:...} first so the whole playtest is reproducible.`,
+            `2. Baseline: runtime_state_digest{root:"${root}"} to snapshot the frozen state (positions / visibility / modulate, stable-ordered) — this is your deterministic "before".`,
+            `3. Step: runtime_step_frames{frames:${frames}, kind:"physics"} to advance EXACTLY ${frames} frames while frozen (use kind:"both" to also tick _process each step). The game stays frozen afterwards, so your reads are stable.`,
+            `4. Assert: runtime_state_digest{root:"${root}"} (or runtime_assert_node_state) that the node reached the expected, frame-exact state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} — because you stepped a fixed number of frames the frame is reproducible, so the diff is stable (establish ${ref} once with runtime_screenshot on the first green run, then vcs_add it).`,
+            `5. Iterate or thaw: repeat 3–4 to walk frame-by-frame (every step is deterministic), or runtime_time_scale{scale:1} to thaw and resume normal play. godot_stop when done. On a failed assert you are one dbg_set_breakpoints + dbg_launch away from the exact value that diverged.`,
+            "",
+            "Why this beats run-screenshot-guess: freezing plus fixed-frame stepping converts a timing-dependent check into a frame-exact, reproducible one the runtime_assert_* family can verify — the R tier of the W/R/E model, made deterministic.",
+            "",
+            SAFETY,
+        ].join("\n"));
+    });
 }
 //# sourceMappingURL=recipes.js.map

package/dist/schemas.js

@@ -494,6 +494,25 @@ export const outputSchemas = {
         reference: z.string(),
         reason: z.string().optional(),
     },
+    // F8 additions: await/animation/node-lifecycle over the runtime bridge.
+    runtime_await_condition: { met: z.boolean(), polls: z.number(), elapsed_ms: z.number(), value: encodedValue },
+    runtime_anim_play: { playing: z.boolean(), current_animation: z.string(), speed_scale: z.number() },
+    runtime_anim_stop: { playing: z.boolean(), current_animation: z.string(), position: z.number() },
+    runtime_anim_get_state: {
+        playing: z.boolean(),
+        current_animation: z.string(),
+        position: z.number(),
+        length: z.number(),
+        speed_scale: z.number(),
+        animations: z.array(z.string()),
+    },
+    runtime_node_add: { added: z.boolean(), path: z.string(), type: z.string() },
+    runtime_node_remove: { removed: z.boolean(), path: z.string() },
+    // F4 additions: deterministic playtesting (time control / frame stepping / state digest / RNG seed).
+    runtime_time_scale: { previous: z.number(), current: z.number() },
+    runtime_step_frames: { frames_advanced: z.number(), frame_index: z.number() },
+    runtime_state_digest: { digest: z.record(z.record(encodedValue)), node_count: z.number() },
+    runtime_seed_rng: { seed: z.number() },
     // ---- Group K: knowledge & search ----
     // Host-side project index (tools/knowledge.ts) — no bridge/LSP; read the project files directly.
     project_search: {

package/dist/tools/runtime.js

@@ -15,6 +15,31 @@ function fail(err) {
         content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}` }],
     };
 }
+/**
+ * Compare a polled property value against an expected value under one of the
+ * restricted operators exposed by runtime_await_condition. eq/ne use structural
+ * (JSON) equality so tagged-Variant objects compare cleanly; the ordered
+ * operators are numeric-only and are false unless both sides are numbers.
+ */
+function compareValues(actual, expected, op) {
+    const bothNum = typeof actual === "number" && typeof expected === "number";
+    switch (op) {
+        case "ne":
+            return JSON.stringify(actual) !== JSON.stringify(expected);
+        case "gt":
+            return bothNum && actual > expected;
+        case "ge":
+            return bothNum && actual >= expected;
+        case "lt":
+            return bothNum && actual < expected;
+        case "le":
+            return bothNum && actual <= expected;
+        case "eq":
+        default:
+            return JSON.stringify(actual) === JSON.stringify(expected);
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function registerRuntimeTools(server, runtime) {
     const call = async (method, params = {}) => {
         try {
@@ -233,5 +258,186 @@ export function registerRuntimeTools(server, runtime) {
         ...(per_channel_threshold !== undefined ? { per_channel_threshold } : {}),
         ...(region !== undefined ? { region } : {}),
     }));
+    // F8: deterministic-verification helper. Poll a live property until it meets a
+    // comparison, or a timeout elapses. Host-side over runtime.get_property (no new
+    // bridge method), so it works on every engine build the runtime bridge supports.
+    // Read-only: it never mutates the game, so it is not confirmation-gated.
+    server.registerTool("runtime_await_condition", {
+        title: "Runtime await condition",
+        description: "Poll a property on a LIVE node until it satisfies a comparison, or a timeout elapses (read-only verification). " +
+            "op is eq | ne | gt | ge | lt | le (the ordered operators require numeric values). Use this to wait for the " +
+            "running game to reach a state before asserting on it — e.g. wait for hp le 0, then runtime_assert_screen_text.",
+        inputSchema: {
+            path: z.string().describe("Node path (relative to the current scene; '/root/...' absolute allowed)"),
+            property: z.string().describe("Property to read on each poll"),
+            value: z.any().describe("Value to compare the property against (tagged-Variant form for complex types)"),
+            op: z.enum(["eq", "ne", "gt", "ge", "lt", "le"]).optional().describe("Comparison operator (default eq)"),
+            timeout_ms: z.number().int().positive().optional().describe("Maximum time to wait, in ms (default 5000)"),
+            poll_interval_ms: z.number().int().positive().optional().describe("Delay between polls, in ms (default 100)"),
+        },
+    }, async ({ path, property, value, op, timeout_ms, poll_interval_ms }) => {
+        const operator = op ?? "eq";
+        const interval = poll_interval_ms ?? 100;
+        const start = Date.now();
+        const deadline = start + (timeout_ms ?? 5000);
+        let polls = 0;
+        let last = null;
+        for (;;) {
+            polls++;
+            let res;
+            try {
+                res = (await runtime.request("runtime.get_property", { path, property }));
+            }
+            catch (err) {
+                return fail(err);
+            }
+            last = res?.value ?? null;
+            if (compareValues(last, value, operator)) {
+                return ok({ met: true, polls, elapsed_ms: Date.now() - start, value: last });
+            }
+            if (Date.now() >= deadline) {
+                return ok({ met: false, polls, elapsed_ms: Date.now() - start, value: last });
+            }
+            await sleep(interval);
+        }
+    });
+    server.registerTool("runtime_anim_play", {
+        title: "Runtime play animation",
+        description: "Play an animation on a LIVE AnimationPlayer node. DESTRUCTIVE (drives the running game) — gated by confirmation. " +
+            "Omit `animation` to (re)play the currently-assigned one.",
+        inputSchema: {
+            path: z.string().describe("Path to an AnimationPlayer node in the running scene"),
+            animation: z.string().optional().describe("Animation name to play (default: the current/assigned animation)"),
+            custom_speed: z.number().optional().describe("Playback speed multiplier (default 1.0; negative not supported here)"),
+            from_end: z.boolean().optional().describe("Start playback from the end (default false)"),
+            ...confirmField,
+        },
+    }, async ({ path, animation, custom_speed, from_end, confirm }) => {
+        const blocked = await gate(server, confirm, `Play animation "${animation ?? "(current)"}" on ${path}`);
+        if (blocked)
+            return blocked;
+        return call("runtime.anim_play", {
+            path,
+            ...(animation !== undefined ? { animation } : {}),
+            ...(custom_speed !== undefined ? { custom_speed } : {}),
+            ...(from_end !== undefined ? { from_end } : {}),
+        });
+    });
+    server.registerTool("runtime_anim_stop", {
+        title: "Runtime stop animation",
+        description: "Stop (or pause) a LIVE AnimationPlayer node. DESTRUCTIVE (drives the running game) — gated by confirmation. " +
+            "keep_state:true pauses in place; false (default) stops.",
+        inputSchema: {
+            path: z.string().describe("Path to an AnimationPlayer node in the running scene"),
+            keep_state: z.boolean().optional().describe("Pause in place instead of stopping (default false)"),
+            ...confirmField,
+        },
+    }, async ({ path, keep_state, confirm }) => {
+        const blocked = await gate(server, confirm, `Stop animation on ${path}`);
+        if (blocked)
+            return blocked;
+        return call("runtime.anim_stop", { path, ...(keep_state !== undefined ? { keep_state } : {}) });
+    });
+    server.registerTool("runtime_anim_get_state", {
+        title: "Runtime animation state",
+        description: "Read the playback state of a LIVE AnimationPlayer (read-only): current animation, whether it is playing, " +
+            "position, length, speed scale, and the list of available animations.",
+        inputSchema: { path: z.string().describe("Path to an AnimationPlayer node in the running scene") },
+    }, async ({ path }) => call("runtime.anim_get_state", { path }));
+    server.registerTool("runtime_node_add", {
+        title: "Runtime add node",
+        description: "Add a node to the LIVE running game as a child of `parent`. DESTRUCTIVE — gated by confirmation. " +
+            "Provide `scene` (a res:// PackedScene to instantiate) OR `type` (a ClassDB class to instantiate); `name` renames it.",
+        inputSchema: {
+            parent: z.string().describe("Path to the parent node in the running scene"),
+            type: z.string().optional().describe("Class name to instantiate (e.g. Node2D) — mutually exclusive with `scene`"),
+            scene: z.string().optional().describe("res:// path to a PackedScene to instantiate — mutually exclusive with `type`"),
+            name: z.string().optional().describe("Optional name for the new node"),
+            ...confirmField,
+        },
+    }, async ({ parent, type, scene, name, confirm }) => {
+        const blocked = await gate(server, confirm, `Add ${scene ?? type ?? "node"} under ${parent} in the running game`);
+        if (blocked)
+            return blocked;
+        return call("runtime.node_add", {
+            parent,
+            ...(type !== undefined ? { type } : {}),
+            ...(scene !== undefined ? { scene } : {}),
+            ...(name !== undefined ? { name } : {}),
+        });
+    });
+    server.registerTool("runtime_node_remove", {
+        title: "Runtime remove node",
+        description: "Remove (queue_free) a node from the LIVE running game. DESTRUCTIVE — gated by confirmation. " +
+            "Refuses to remove the current scene root.",
+        inputSchema: { path: z.string().describe("Path to the node to remove in the running scene"), ...confirmField },
+    }, async ({ path, confirm }) => {
+        const blocked = await gate(server, confirm, `Remove ${path} from the running game`);
+        if (blocked)
+            return blocked;
+        return call("runtime.node_remove", { path });
+    });
+    // F4: deterministic playtesting — freeze time, step exact frames, snapshot state, seed RNG.
+    server.registerTool("runtime_time_scale", {
+        title: "Runtime time scale",
+        description: "Set Engine.time_scale on the running game: 0 freezes time, 1 is normal, >1 fast, <1 slow-motion. " +
+            "DESTRUCTIVE (alters the running game's clock) — gated by confirmation. Freeze with scale 0, then " +
+            "runtime_step_frames to advance deterministically before asserting.",
+        inputSchema: {
+            scale: z.number().min(0).describe("0 = freeze, 1 = normal, N = slow/fast (negative is clamped to 0)"),
+            ...confirmField,
+        },
+    }, async ({ scale, confirm }) => {
+        const blocked = await gate(server, confirm, `Set time scale to ${scale} on the running game`);
+        if (blocked)
+            return blocked;
+        return call("runtime.time_scale", { scale });
+    });
+    server.registerTool("runtime_step_frames", {
+        title: "Runtime step frames",
+        description: "Advance the running game by an exact number of frames while otherwise frozen, for deterministic, " +
+            "frame-accurate playtesting. DESTRUCTIVE — gated by confirmation. `kind` selects which loop to tick each " +
+            "step: idle (default), physics, or both. Pair with runtime_time_scale{scale:0} to freeze, then assert.",
+        inputSchema: {
+            frames: z.number().int().positive().describe("Number of frames to advance"),
+            kind: z.enum(["idle", "physics", "both"]).optional().describe("Which loop to tick each step (default idle)"),
+            ...confirmField,
+        },
+    }, async ({ frames, kind, confirm }) => {
+        const blocked = await gate(server, confirm, `Advance ${frames} frame(s) of the running game`);
+        if (blocked)
+            return blocked;
+        return call("runtime.step_frames", { frames, ...(kind !== undefined ? { kind } : {}) });
+    });
+    server.registerTool("runtime_state_digest", {
+        title: "Runtime state digest",
+        description: "Capture a compact, stable-ordered JSON snapshot of a live subtree's salient state (read-only) — position, " +
+            "rotation, scale, visibility, and modulate by default, or a caller-supplied field list. Deterministic ordering " +
+            "makes it ideal for frame-by-frame comparison alongside runtime_step_frames.",
+        inputSchema: {
+            root: z.string().describe("Root node path in the running scene"),
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe("Property names to capture per node (default: position/global_position/rotation/scale/visible/modulate when present)"),
+            max_depth: z.number().int().nonnegative().optional().describe("Max recursion depth (default 8)"),
+        },
+    }, async ({ root, fields, max_depth }) => call("runtime.state_digest", {
+        root,
+        ...(fields !== undefined ? { fields } : {}),
+        ...(max_depth !== undefined ? { max_depth } : {}),
+    }));
+    server.registerTool("runtime_seed_rng", {
+        title: "Runtime seed RNG",
+        description: "Seed the running game's GLOBAL random number generator (GDScript seed()) so a playtest is reproducible. " +
+            "DESTRUCTIVE (changes RNG state) — gated by confirmation. Note: seeds only the global RNG (randi/randf), not " +
+            "per-instance RandomNumberGenerators or physics determinism.",
+        inputSchema: { seed: z.number().int().describe("Seed value for the global RNG"), ...confirmField },
+    }, async ({ seed, confirm }) => {
+        const blocked = await gate(server, confirm, `Seed the running game's global RNG with ${seed}`);
+        if (blocked)
+            return blocked;
+        return call("runtime.seed_rng", { seed });
+    });
 }
 //# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.19.1",
+  "version": "1.21.1",
   "description": "MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model, captured console output, and MCP resources.",
   "type": "module",
   "license": "MIT",