breakpoint-mcp 1.19.1 → 1.23.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/addon/breakpoint_mcp/operations.gd +1 -1
- package/addon/breakpoint_mcp/plugin.cfg +1 -1
- package/addon/breakpoint_mcp/runtime_bridge.gd +243 -0
- package/dist/annotations.js +225 -0
- package/dist/capabilities.js +5 -1
- package/dist/cli/doctor.js +1 -1
- package/dist/cli/init.js +1 -1
- package/dist/cli/tools.js +193 -0
- package/dist/index.js +26 -4
- package/dist/peers.js +238 -0
- package/dist/recipes.js +65 -1
- package/dist/schemas.js +36 -0
- package/dist/secret.js +49 -0
- package/dist/tools/processes.js +25 -1
- package/dist/tools/runtime.js +467 -36
- package/dist/toolsets.js +7 -1
- package/package.json +1 -1
package/dist/tools/runtime.js
CHANGED
|
@@ -1,9 +1,22 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
+
import { MAX_PEERS } from "../peers.js";
|
|
2
3
|
import { gate } from "../confirm.js";
|
|
3
4
|
import { ok } from "./lsp-common.js";
|
|
4
5
|
const confirmField = {
|
|
5
6
|
confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
|
|
6
7
|
};
|
|
8
|
+
/**
|
|
9
|
+
* F6: address a spawned headless peer instead of the default running game.
|
|
10
|
+
* Threaded onto the runtime tools a multi-process playtest actually drives —
|
|
11
|
+
* seed, freeze, step, read, invoke, await, log — rather than minting a parallel
|
|
12
|
+
* set of peer-specific tools. Omitting it is byte-identical to pre-F6 behaviour.
|
|
13
|
+
*/
|
|
14
|
+
const peerField = {
|
|
15
|
+
peer: z
|
|
16
|
+
.string()
|
|
17
|
+
.optional()
|
|
18
|
+
.describe("Target a headless peer by id (from runtime_spawn_peers). Omit to address the default running game."),
|
|
19
|
+
};
|
|
7
20
|
/**
|
|
8
21
|
* Runtime-bridge tools (Plane C). Each forwards to the in-game autoload
|
|
9
22
|
* (BreakpointRuntimeBridge) over TCP. These only work while the project is running.
|
|
@@ -15,10 +28,63 @@ function fail(err) {
|
|
|
15
28
|
content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}` }],
|
|
16
29
|
};
|
|
17
30
|
}
|
|
18
|
-
|
|
19
|
-
|
|
31
|
+
/**
|
|
32
|
+
* Compare a polled property value against an expected value under one of the
|
|
33
|
+
* restricted operators exposed by runtime_await_condition. eq/ne use structural
|
|
34
|
+
* (JSON) equality so tagged-Variant objects compare cleanly; the ordered
|
|
35
|
+
* operators are numeric-only and are false unless both sides are numbers.
|
|
36
|
+
*/
|
|
37
|
+
function compareValues(actual, expected, op) {
|
|
38
|
+
const bothNum = typeof actual === "number" && typeof expected === "number";
|
|
39
|
+
switch (op) {
|
|
40
|
+
case "ne":
|
|
41
|
+
return JSON.stringify(actual) !== JSON.stringify(expected);
|
|
42
|
+
case "gt":
|
|
43
|
+
return bothNum && actual > expected;
|
|
44
|
+
case "ge":
|
|
45
|
+
return bothNum && actual >= expected;
|
|
46
|
+
case "lt":
|
|
47
|
+
return bothNum && actual < expected;
|
|
48
|
+
case "le":
|
|
49
|
+
return bothNum && actual <= expected;
|
|
50
|
+
case "eq":
|
|
51
|
+
default:
|
|
52
|
+
return JSON.stringify(actual) === JSON.stringify(expected);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
56
|
+
/**
|
|
57
|
+
* Stable stringification of a state digest: object keys sorted at every level,
|
|
58
|
+
* so convergence is a property of the CONTENT and not of key order.
|
|
59
|
+
*
|
|
60
|
+
* The addon already emits a stable-ordered digest, and JS preserves string-key
|
|
61
|
+
* insertion order, so a plain JSON.stringify would compare correctly today.
|
|
62
|
+
* Sorting anyway costs nothing and means the convergence claim does not quietly
|
|
63
|
+
* depend on an ordering guarantee made two layers away.
|
|
64
|
+
*/
|
|
65
|
+
function canonical(value) {
|
|
66
|
+
const walk = (v) => {
|
|
67
|
+
if (Array.isArray(v))
|
|
68
|
+
return v.map(walk);
|
|
69
|
+
if (v && typeof v === "object") {
|
|
70
|
+
const src = v;
|
|
71
|
+
const out = {};
|
|
72
|
+
for (const k of Object.keys(src).sort())
|
|
73
|
+
out[k] = walk(src[k]);
|
|
74
|
+
return out;
|
|
75
|
+
}
|
|
76
|
+
return v;
|
|
77
|
+
};
|
|
78
|
+
return JSON.stringify(walk(value));
|
|
79
|
+
}
|
|
80
|
+
export function registerRuntimeTools(server, runtime, peers) {
|
|
81
|
+
/** The bridge addressing `peer`, or the default running game when omitted. */
|
|
82
|
+
const clientFor = (peer) => (peer ? peers.clientFor(peer) : runtime);
|
|
83
|
+
/** Human label for confirmation prompts, so a gated op names its target process. */
|
|
84
|
+
const target = (peer) => (peer ? `peer ${peer}` : "the running game");
|
|
85
|
+
const call = async (method, params = {}, peer) => {
|
|
20
86
|
try {
|
|
21
|
-
return ok(await
|
|
87
|
+
return ok(await clientFor(peer).request(method, params));
|
|
22
88
|
}
|
|
23
89
|
catch (err) {
|
|
24
90
|
return fail(err);
|
|
@@ -27,42 +93,45 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
27
93
|
server.registerTool("runtime_get_tree", {
|
|
28
94
|
title: "Runtime scene tree",
|
|
29
95
|
description: "Traverse the LIVE SceneTree of the running game (name, type, path, visibility, children).",
|
|
30
|
-
inputSchema: {
|
|
31
|
-
|
|
96
|
+
inputSchema: {
|
|
97
|
+
max_depth: z.number().int().positive().optional().describe("Max recursion depth (default 64)"),
|
|
98
|
+
...peerField,
|
|
99
|
+
},
|
|
100
|
+
}, async ({ max_depth, peer }) => call("runtime.get_tree", max_depth ? { max_depth } : {}, peer));
|
|
32
101
|
server.registerTool("runtime_get_property", {
|
|
33
102
|
title: "Runtime get property",
|
|
34
103
|
description: "Read a property from a live node (path relative to the current scene; '/root/...' absolute allowed).",
|
|
35
|
-
inputSchema: { path: z.string(), property: z.string() },
|
|
36
|
-
}, async ({ path, property }) => call("runtime.get_property", { path, property }));
|
|
104
|
+
inputSchema: { path: z.string(), property: z.string(), ...peerField },
|
|
105
|
+
}, async ({ path, property, peer }) => call("runtime.get_property", { path, property }, peer));
|
|
37
106
|
server.registerTool("runtime_set_property", {
|
|
38
107
|
title: "Runtime set property",
|
|
39
108
|
description: "Set a property on a live node. DESTRUCTIVE (mutates running game state) — gated by confirmation. Rich types use the {\"__type__\":...} convention.",
|
|
40
|
-
inputSchema: { path: z.string(), property: z.string(), value: z.any(), ...confirmField },
|
|
41
|
-
}, async ({ path, property, value, confirm }) => {
|
|
42
|
-
const blocked = await gate(server, confirm, `Set live property ${path}.${property}`);
|
|
109
|
+
inputSchema: { path: z.string(), property: z.string(), value: z.any(), ...confirmField, ...peerField },
|
|
110
|
+
}, async ({ path, property, value, confirm, peer }) => {
|
|
111
|
+
const blocked = await gate(server, confirm, `Set live property ${path}.${property} on ${target(peer)}`);
|
|
43
112
|
if (blocked)
|
|
44
113
|
return blocked;
|
|
45
|
-
return call("runtime.set_property", { path, property, value });
|
|
114
|
+
return call("runtime.set_property", { path, property, value }, peer);
|
|
46
115
|
});
|
|
47
116
|
server.registerTool("runtime_call_method", {
|
|
48
117
|
title: "Runtime call method",
|
|
49
118
|
description: "Invoke a method on a live node. DESTRUCTIVE (arbitrary invocation) — gated by confirmation. Args use the tagged-Variant convention.",
|
|
50
|
-
inputSchema: { path: z.string(), method: z.string(), args: z.array(z.any()).optional(), ...confirmField },
|
|
51
|
-
}, async ({ path, method, args, confirm }) => {
|
|
52
|
-
const blocked = await gate(server, confirm, `Call ${path}.${method}() on
|
|
119
|
+
inputSchema: { path: z.string(), method: z.string(), args: z.array(z.any()).optional(), ...confirmField, ...peerField },
|
|
120
|
+
}, async ({ path, method, args, confirm, peer }) => {
|
|
121
|
+
const blocked = await gate(server, confirm, `Call ${path}.${method}() on ${target(peer)}`);
|
|
53
122
|
if (blocked)
|
|
54
123
|
return blocked;
|
|
55
|
-
return call("runtime.call_method", { path, method, args: args ?? [] });
|
|
124
|
+
return call("runtime.call_method", { path, method, args: args ?? [] }, peer);
|
|
56
125
|
});
|
|
57
126
|
server.registerTool("runtime_emit_signal", {
|
|
58
127
|
title: "Runtime emit signal",
|
|
59
128
|
description: "Emit a signal from a live node. DESTRUCTIVE — gated by confirmation.",
|
|
60
|
-
inputSchema: { path: z.string(), signal: z.string(), args: z.array(z.any()).optional(), ...confirmField },
|
|
61
|
-
}, async ({ path, signal, args, confirm }) => {
|
|
62
|
-
const blocked = await gate(server, confirm, `Emit signal "${signal}" from ${path}`);
|
|
129
|
+
inputSchema: { path: z.string(), signal: z.string(), args: z.array(z.any()).optional(), ...confirmField, ...peerField },
|
|
130
|
+
}, async ({ path, signal, args, confirm, peer }) => {
|
|
131
|
+
const blocked = await gate(server, confirm, `Emit signal "${signal}" from ${path} on ${target(peer)}`);
|
|
63
132
|
if (blocked)
|
|
64
133
|
return blocked;
|
|
65
|
-
return call("runtime.emit_signal", { path, signal, args: args ?? [] });
|
|
134
|
+
return call("runtime.emit_signal", { path, signal, args: args ?? [] }, peer);
|
|
66
135
|
});
|
|
67
136
|
server.registerTool("runtime_inject_input", {
|
|
68
137
|
title: "Runtime inject input",
|
|
@@ -81,26 +150,27 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
81
150
|
relative: z.any().optional(),
|
|
82
151
|
}),
|
|
83
152
|
...confirmField,
|
|
153
|
+
...peerField,
|
|
84
154
|
},
|
|
85
|
-
}, async ({ event, confirm }) => {
|
|
86
|
-
const blocked = await gate(server, confirm, `Inject ${event.kind} input event into
|
|
155
|
+
}, async ({ event, confirm, peer }) => {
|
|
156
|
+
const blocked = await gate(server, confirm, `Inject ${event.kind} input event into ${target(peer)}`);
|
|
87
157
|
if (blocked)
|
|
88
158
|
return blocked;
|
|
89
|
-
return call("runtime.inject_input", { event });
|
|
159
|
+
return call("runtime.inject_input", { event }, peer);
|
|
90
160
|
});
|
|
91
161
|
server.registerTool("runtime_get_monitors", {
|
|
92
162
|
title: "Runtime performance monitors",
|
|
93
163
|
description: "Read live Performance monitors (FPS, draw calls, node count, physics, audio output latency, ...). " +
|
|
94
164
|
"Pass specific keys or omit for all. Keys include time/fps, render/total_draw_calls, audio/output_latency.",
|
|
95
|
-
inputSchema: { keys: z.array(z.string()).optional() },
|
|
96
|
-
}, async ({ keys }) => call("runtime.get_monitors", keys ? { keys } : {}));
|
|
165
|
+
inputSchema: { keys: z.array(z.string()).optional(), ...peerField },
|
|
166
|
+
}, async ({ keys, peer }) => call("runtime.get_monitors", keys ? { keys } : {}, peer));
|
|
97
167
|
server.registerTool("runtime_screenshot", {
|
|
98
168
|
title: "Runtime screenshot",
|
|
99
169
|
description: "Capture the current game frame as a PNG and return it as image content so the assistant can see the running game.",
|
|
100
|
-
inputSchema: {},
|
|
101
|
-
}, async () => {
|
|
170
|
+
inputSchema: { ...peerField },
|
|
171
|
+
}, async ({ peer }) => {
|
|
102
172
|
try {
|
|
103
|
-
const r = (await
|
|
173
|
+
const r = (await clientFor(peer).request("runtime.screenshot", {}));
|
|
104
174
|
return {
|
|
105
175
|
content: [
|
|
106
176
|
{ type: "image", data: r.base64, mimeType: r.mime },
|
|
@@ -119,8 +189,9 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
119
189
|
inputSchema: {
|
|
120
190
|
since_seq: z.number().int().optional().describe("Return only entries with seq greater than this (default 0)"),
|
|
121
191
|
levels: z.array(z.string()).optional().describe("Filter to these levels, e.g. [\"error\",\"warning\"]"),
|
|
192
|
+
...peerField,
|
|
122
193
|
},
|
|
123
|
-
}, async ({ since_seq, levels }) => call("runtime.get_log", { since_seq: since_seq ?? 0, levels: levels ?? [] }));
|
|
194
|
+
}, async ({ since_seq, levels, peer }) => call("runtime.get_log", { since_seq: since_seq ?? 0, levels: levels ?? [] }, peer));
|
|
124
195
|
server.registerTool("runtime_assert_node_state", {
|
|
125
196
|
title: "Runtime assert node state",
|
|
126
197
|
description: "Assert that properties of a LIVE node equal expected values (read-only verification). " +
|
|
@@ -135,8 +206,9 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
135
206
|
.nonnegative()
|
|
136
207
|
.optional()
|
|
137
208
|
.describe("Absolute tolerance for numeric comparisons (default 0 = exact match)"),
|
|
209
|
+
...peerField,
|
|
138
210
|
},
|
|
139
|
-
}, async ({ path, expect, tolerance }) => call("runtime.assert_node_state", tolerance !== undefined ? { path, expect, tolerance } : { path, expect }));
|
|
211
|
+
}, async ({ path, expect, tolerance, peer }) => call("runtime.assert_node_state", tolerance !== undefined ? { path, expect, tolerance } : { path, expect }, peer));
|
|
140
212
|
server.registerTool("runtime_assert_scene_structure", {
|
|
141
213
|
title: "Runtime assert scene structure",
|
|
142
214
|
description: "Assert the LIVE SceneTree matches structural expectations (read-only). Each entry asserts a node " +
|
|
@@ -149,8 +221,9 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
149
221
|
absent: z.boolean().optional(),
|
|
150
222
|
}))
|
|
151
223
|
.describe("List of node expectations: {path, type?, absent?}."),
|
|
224
|
+
...peerField,
|
|
152
225
|
},
|
|
153
|
-
}, async ({ expect }) => call("runtime.assert_scene_structure", { expect }));
|
|
226
|
+
}, async ({ expect, peer }) => call("runtime.assert_scene_structure", { expect }, peer));
|
|
154
227
|
server.registerTool("runtime_assert_perf", {
|
|
155
228
|
title: "Runtime assert perf",
|
|
156
229
|
description: "Assert that live Performance monitors meet a caller-supplied baseline within tolerance (read-only). " +
|
|
@@ -169,12 +242,13 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
169
242
|
.record(z.enum(["higher_better", "lower_better"]))
|
|
170
243
|
.optional()
|
|
171
244
|
.describe("Per-key override of the pass direction (defaults: time/fps higher_better, else lower_better)"),
|
|
245
|
+
...peerField,
|
|
172
246
|
},
|
|
173
|
-
}, async ({ baseline, tolerance, direction }) => call("runtime.assert_perf", {
|
|
247
|
+
}, async ({ baseline, tolerance, direction, peer }) => call("runtime.assert_perf", {
|
|
174
248
|
baseline,
|
|
175
249
|
...(tolerance !== undefined ? { tolerance } : {}),
|
|
176
250
|
...(direction !== undefined ? { direction } : {}),
|
|
177
|
-
}));
|
|
251
|
+
}, peer));
|
|
178
252
|
server.registerTool("runtime_assert_screen_text", {
|
|
179
253
|
title: "Runtime assert screen text",
|
|
180
254
|
description: "Assert that on-screen text is present (or absent) by scanning visible Control text in the LIVE scene tree " +
|
|
@@ -194,14 +268,15 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
194
268
|
.positive()
|
|
195
269
|
.optional()
|
|
196
270
|
.describe("Require at least this many matches (implies present)"),
|
|
271
|
+
...peerField,
|
|
197
272
|
},
|
|
198
|
-
}, async ({ text, present, regex, case_sensitive, min_count }) => call("runtime.assert_screen_text", {
|
|
273
|
+
}, async ({ text, present, regex, case_sensitive, min_count, peer }) => call("runtime.assert_screen_text", {
|
|
199
274
|
text,
|
|
200
275
|
...(present !== undefined ? { present } : {}),
|
|
201
276
|
...(regex !== undefined ? { regex } : {}),
|
|
202
277
|
...(case_sensitive !== undefined ? { case_sensitive } : {}),
|
|
203
278
|
...(min_count !== undefined ? { min_count } : {}),
|
|
204
|
-
}));
|
|
279
|
+
}, peer));
|
|
205
280
|
server.registerTool("runtime_screenshot_diff", {
|
|
206
281
|
title: "Runtime screenshot diff",
|
|
207
282
|
description: "Capture the current frame and compare it to a reference PNG at a project path, returning diff stats and a " +
|
|
@@ -226,12 +301,368 @@ export function registerRuntimeTools(server, runtime) {
|
|
|
226
301
|
.object({ x: z.number().int(), y: z.number().int(), w: z.number().int(), h: z.number().int() })
|
|
227
302
|
.optional()
|
|
228
303
|
.describe("Optional sub-region (applied to both frame and reference) to compare"),
|
|
304
|
+
...peerField,
|
|
229
305
|
},
|
|
230
|
-
}, async ({ reference, tolerance, per_channel_threshold, region }) => call("runtime.screenshot_diff", {
|
|
306
|
+
}, async ({ reference, tolerance, per_channel_threshold, region, peer }) => call("runtime.screenshot_diff", {
|
|
231
307
|
reference,
|
|
232
308
|
...(tolerance !== undefined ? { tolerance } : {}),
|
|
233
309
|
...(per_channel_threshold !== undefined ? { per_channel_threshold } : {}),
|
|
234
310
|
...(region !== undefined ? { region } : {}),
|
|
235
|
-
}));
|
|
311
|
+
}, peer));
|
|
312
|
+
// F8: deterministic-verification helper. Poll a live property until it meets a
|
|
313
|
+
// comparison, or a timeout elapses. Host-side over runtime.get_property (no new
|
|
314
|
+
// bridge method), so it works on every engine build the runtime bridge supports.
|
|
315
|
+
// Read-only: it never mutates the game, so it is not confirmation-gated.
|
|
316
|
+
server.registerTool("runtime_await_condition", {
|
|
317
|
+
title: "Runtime await condition",
|
|
318
|
+
description: "Poll a property on a LIVE node until it satisfies a comparison, or a timeout elapses (read-only verification). " +
|
|
319
|
+
"op is eq | ne | gt | ge | lt | le (the ordered operators require numeric values). Use this to wait for the " +
|
|
320
|
+
"running game to reach a state before asserting on it — e.g. wait for hp le 0, then runtime_assert_screen_text.",
|
|
321
|
+
inputSchema: {
|
|
322
|
+
path: z.string().describe("Node path (relative to the current scene; '/root/...' absolute allowed)"),
|
|
323
|
+
property: z.string().describe("Property to read on each poll"),
|
|
324
|
+
value: z.any().describe("Value to compare the property against (tagged-Variant form for complex types)"),
|
|
325
|
+
op: z.enum(["eq", "ne", "gt", "ge", "lt", "le"]).optional().describe("Comparison operator (default eq)"),
|
|
326
|
+
timeout_ms: z.number().int().positive().optional().describe("Maximum time to wait, in ms (default 5000)"),
|
|
327
|
+
poll_interval_ms: z.number().int().positive().optional().describe("Delay between polls, in ms (default 100)"),
|
|
328
|
+
...peerField,
|
|
329
|
+
},
|
|
330
|
+
}, async ({ path, property, value, op, timeout_ms, poll_interval_ms, peer }) => {
|
|
331
|
+
const operator = op ?? "eq";
|
|
332
|
+
const interval = poll_interval_ms ?? 100;
|
|
333
|
+
const start = Date.now();
|
|
334
|
+
const deadline = start + (timeout_ms ?? 5000);
|
|
335
|
+
let polls = 0;
|
|
336
|
+
let last = null;
|
|
337
|
+
let client;
|
|
338
|
+
try {
|
|
339
|
+
client = clientFor(peer);
|
|
340
|
+
}
|
|
341
|
+
catch (err) {
|
|
342
|
+
return fail(err);
|
|
343
|
+
}
|
|
344
|
+
for (;;) {
|
|
345
|
+
polls++;
|
|
346
|
+
let res;
|
|
347
|
+
try {
|
|
348
|
+
res = (await client.request("runtime.get_property", { path, property }));
|
|
349
|
+
}
|
|
350
|
+
catch (err) {
|
|
351
|
+
return fail(err);
|
|
352
|
+
}
|
|
353
|
+
last = res?.value ?? null;
|
|
354
|
+
if (compareValues(last, value, operator)) {
|
|
355
|
+
return ok({ met: true, polls, elapsed_ms: Date.now() - start, value: last });
|
|
356
|
+
}
|
|
357
|
+
if (Date.now() >= deadline) {
|
|
358
|
+
return ok({ met: false, polls, elapsed_ms: Date.now() - start, value: last });
|
|
359
|
+
}
|
|
360
|
+
await sleep(interval);
|
|
361
|
+
}
|
|
362
|
+
});
|
|
363
|
+
server.registerTool("runtime_anim_play", {
|
|
364
|
+
title: "Runtime play animation",
|
|
365
|
+
description: "Play an animation on a LIVE AnimationPlayer node. DESTRUCTIVE (drives the running game) — gated by confirmation. " +
|
|
366
|
+
"Omit `animation` to (re)play the currently-assigned one.",
|
|
367
|
+
inputSchema: {
|
|
368
|
+
path: z.string().describe("Path to an AnimationPlayer node in the running scene"),
|
|
369
|
+
animation: z.string().optional().describe("Animation name to play (default: the current/assigned animation)"),
|
|
370
|
+
custom_speed: z.number().optional().describe("Playback speed multiplier (default 1.0; negative not supported here)"),
|
|
371
|
+
from_end: z.boolean().optional().describe("Start playback from the end (default false)"),
|
|
372
|
+
...confirmField,
|
|
373
|
+
...peerField,
|
|
374
|
+
},
|
|
375
|
+
}, async ({ path, animation, custom_speed, from_end, confirm, peer }) => {
|
|
376
|
+
const blocked = await gate(server, confirm, `Play animation "${animation ?? "(current)"}" on ${path} in ${target(peer)}`);
|
|
377
|
+
if (blocked)
|
|
378
|
+
return blocked;
|
|
379
|
+
return call("runtime.anim_play", {
|
|
380
|
+
path,
|
|
381
|
+
...(animation !== undefined ? { animation } : {}),
|
|
382
|
+
...(custom_speed !== undefined ? { custom_speed } : {}),
|
|
383
|
+
...(from_end !== undefined ? { from_end } : {}),
|
|
384
|
+
}, peer);
|
|
385
|
+
});
|
|
386
|
+
server.registerTool("runtime_anim_stop", {
|
|
387
|
+
title: "Runtime stop animation",
|
|
388
|
+
description: "Stop (or pause) a LIVE AnimationPlayer node. DESTRUCTIVE (drives the running game) — gated by confirmation. " +
|
|
389
|
+
"keep_state:true pauses in place; false (default) stops.",
|
|
390
|
+
inputSchema: {
|
|
391
|
+
path: z.string().describe("Path to an AnimationPlayer node in the running scene"),
|
|
392
|
+
keep_state: z.boolean().optional().describe("Pause in place instead of stopping (default false)"),
|
|
393
|
+
...confirmField,
|
|
394
|
+
...peerField,
|
|
395
|
+
},
|
|
396
|
+
}, async ({ path, keep_state, confirm, peer }) => {
|
|
397
|
+
const blocked = await gate(server, confirm, `Stop animation on ${path} in ${target(peer)}`);
|
|
398
|
+
if (blocked)
|
|
399
|
+
return blocked;
|
|
400
|
+
return call("runtime.anim_stop", { path, ...(keep_state !== undefined ? { keep_state } : {}) }, peer);
|
|
401
|
+
});
|
|
402
|
+
server.registerTool("runtime_anim_get_state", {
|
|
403
|
+
title: "Runtime animation state",
|
|
404
|
+
description: "Read the playback state of a LIVE AnimationPlayer (read-only): current animation, whether it is playing, " +
|
|
405
|
+
"position, length, speed scale, and the list of available animations.",
|
|
406
|
+
inputSchema: { path: z.string().describe("Path to an AnimationPlayer node in the running scene"), ...peerField },
|
|
407
|
+
}, async ({ path, peer }) => call("runtime.anim_get_state", { path }, peer));
|
|
408
|
+
server.registerTool("runtime_node_add", {
|
|
409
|
+
title: "Runtime add node",
|
|
410
|
+
description: "Add a node to the LIVE running game as a child of `parent`. DESTRUCTIVE — gated by confirmation. " +
|
|
411
|
+
"Provide `scene` (a res:// PackedScene to instantiate) OR `type` (a ClassDB class to instantiate); `name` renames it.",
|
|
412
|
+
inputSchema: {
|
|
413
|
+
parent: z.string().describe("Path to the parent node in the running scene"),
|
|
414
|
+
type: z.string().optional().describe("Class name to instantiate (e.g. Node2D) — mutually exclusive with `scene`"),
|
|
415
|
+
scene: z.string().optional().describe("res:// path to a PackedScene to instantiate — mutually exclusive with `type`"),
|
|
416
|
+
name: z.string().optional().describe("Optional name for the new node"),
|
|
417
|
+
...confirmField,
|
|
418
|
+
...peerField,
|
|
419
|
+
},
|
|
420
|
+
}, async ({ parent, type, scene, name, confirm, peer }) => {
|
|
421
|
+
const blocked = await gate(server, confirm, `Add ${scene ?? type ?? "node"} under ${parent} in ${target(peer)}`);
|
|
422
|
+
if (blocked)
|
|
423
|
+
return blocked;
|
|
424
|
+
return call("runtime.node_add", {
|
|
425
|
+
parent,
|
|
426
|
+
...(type !== undefined ? { type } : {}),
|
|
427
|
+
...(scene !== undefined ? { scene } : {}),
|
|
428
|
+
...(name !== undefined ? { name } : {}),
|
|
429
|
+
}, peer);
|
|
430
|
+
});
|
|
431
|
+
server.registerTool("runtime_node_remove", {
|
|
432
|
+
title: "Runtime remove node",
|
|
433
|
+
description: "Remove (queue_free) a node from the LIVE running game. DESTRUCTIVE — gated by confirmation. " +
|
|
434
|
+
"Refuses to remove the current scene root.",
|
|
435
|
+
inputSchema: {
|
|
436
|
+
path: z.string().describe("Path to the node to remove in the running scene"),
|
|
437
|
+
...confirmField,
|
|
438
|
+
...peerField,
|
|
439
|
+
},
|
|
440
|
+
}, async ({ path, confirm, peer }) => {
|
|
441
|
+
const blocked = await gate(server, confirm, `Remove ${path} from ${target(peer)}`);
|
|
442
|
+
if (blocked)
|
|
443
|
+
return blocked;
|
|
444
|
+
return call("runtime.node_remove", { path }, peer);
|
|
445
|
+
});
|
|
446
|
+
// F4: deterministic playtesting — freeze time, step exact frames, snapshot state, seed RNG.
|
|
447
|
+
server.registerTool("runtime_time_scale", {
|
|
448
|
+
title: "Runtime time scale",
|
|
449
|
+
description: "Set Engine.time_scale on the running game: 0 freezes time, 1 is normal, >1 fast, <1 slow-motion. " +
|
|
450
|
+
"DESTRUCTIVE (alters the running game's clock) — gated by confirmation. Freeze with scale 0, then " +
|
|
451
|
+
"runtime_step_frames to advance deterministically before asserting.",
|
|
452
|
+
inputSchema: {
|
|
453
|
+
scale: z.number().min(0).describe("0 = freeze, 1 = normal, N = slow/fast (negative is clamped to 0)"),
|
|
454
|
+
...confirmField,
|
|
455
|
+
...peerField,
|
|
456
|
+
},
|
|
457
|
+
}, async ({ scale, confirm, peer }) => {
|
|
458
|
+
const blocked = await gate(server, confirm, `Set time scale to ${scale} on ${target(peer)}`);
|
|
459
|
+
if (blocked)
|
|
460
|
+
return blocked;
|
|
461
|
+
return call("runtime.time_scale", { scale }, peer);
|
|
462
|
+
});
|
|
463
|
+
server.registerTool("runtime_step_frames", {
|
|
464
|
+
title: "Runtime step frames",
|
|
465
|
+
description: "Advance the running game by an exact number of frames while otherwise frozen, for deterministic, " +
|
|
466
|
+
"frame-accurate playtesting. DESTRUCTIVE — gated by confirmation. `kind` selects which loop to tick each " +
|
|
467
|
+
"step: idle (default), physics, or both. Pair with runtime_time_scale{scale:0} to freeze, then assert.",
|
|
468
|
+
inputSchema: {
|
|
469
|
+
frames: z.number().int().positive().describe("Number of frames to advance"),
|
|
470
|
+
kind: z.enum(["idle", "physics", "both"]).optional().describe("Which loop to tick each step (default idle)"),
|
|
471
|
+
...confirmField,
|
|
472
|
+
...peerField,
|
|
473
|
+
},
|
|
474
|
+
}, async ({ frames, kind, confirm, peer }) => {
|
|
475
|
+
const blocked = await gate(server, confirm, `Advance ${frames} frame(s) of ${target(peer)}`);
|
|
476
|
+
if (blocked)
|
|
477
|
+
return blocked;
|
|
478
|
+
return call("runtime.step_frames", { frames, ...(kind !== undefined ? { kind } : {}) }, peer);
|
|
479
|
+
});
|
|
480
|
+
server.registerTool("runtime_state_digest", {
|
|
481
|
+
title: "Runtime state digest",
|
|
482
|
+
description: "Capture a compact, stable-ordered JSON snapshot of a live subtree's salient state (read-only) — position, " +
|
|
483
|
+
"rotation, scale, visibility, and modulate by default, or a caller-supplied field list. Deterministic ordering " +
|
|
484
|
+
"makes it ideal for frame-by-frame comparison alongside runtime_step_frames.",
|
|
485
|
+
inputSchema: {
|
|
486
|
+
root: z.string().describe("Root node path in the running scene"),
|
|
487
|
+
fields: z
|
|
488
|
+
.array(z.string())
|
|
489
|
+
.optional()
|
|
490
|
+
.describe("Property names to capture per node (default: position/global_position/rotation/scale/visible/modulate when present)"),
|
|
491
|
+
max_depth: z.number().int().nonnegative().optional().describe("Max recursion depth (default 8)"),
|
|
492
|
+
...peerField,
|
|
493
|
+
},
|
|
494
|
+
}, async ({ root, fields, max_depth, peer }) => call("runtime.state_digest", {
|
|
495
|
+
root,
|
|
496
|
+
...(fields !== undefined ? { fields } : {}),
|
|
497
|
+
...(max_depth !== undefined ? { max_depth } : {}),
|
|
498
|
+
}, peer));
|
|
499
|
+
server.registerTool("runtime_seed_rng", {
|
|
500
|
+
title: "Runtime seed RNG",
|
|
501
|
+
description: "Seed the running game's GLOBAL random number generator (GDScript seed()) so a playtest is reproducible. " +
|
|
502
|
+
"DESTRUCTIVE (changes RNG state) — gated by confirmation. Seeds only the global RNG (randi/randf), not " +
|
|
503
|
+
"per-instance RandomNumberGenerators or physics determinism. IMPORTANT when comparing peers: this is ONE " +
|
|
504
|
+
"stream shared by every caller in the project, and FREEZING DOES NOT STOP IT BEING CONSUMED — time_scale 0 " +
|
|
505
|
+
"makes delta 0 but _process/_physics_process still fire, so code that draws unconditionally burns draws at " +
|
|
506
|
+
"wall-clock rate even while frozen, including in the gap between this call and runtime_step_frames. For peers " +
|
|
507
|
+
"to converge the global stream must be consumed ONLY on frames you are actually stepping: guard draws on " +
|
|
508
|
+
"delta > 0, and give idle-frame code its own RandomNumberGenerator. Measured on real Godot 4.3 — with both, " +
|
|
509
|
+
"three peers converge byte-equal even with a deliberate stagger between each peer's seed and step; with " +
|
|
510
|
+
"either violated, they diverge every time.",
|
|
511
|
+
inputSchema: { seed: z.number().int().describe("Seed value for the global RNG"), ...confirmField, ...peerField },
|
|
512
|
+
}, async ({ seed, confirm, peer }) => {
|
|
513
|
+
const blocked = await gate(server, confirm, `Seed the global RNG of ${target(peer)} with ${seed}`);
|
|
514
|
+
if (blocked)
|
|
515
|
+
return blocked;
|
|
516
|
+
return call("runtime.seed_rng", { seed }, peer);
|
|
517
|
+
});
|
|
518
|
+
// F6: multi-peer deterministic playtesting. Three tools, not eight — a `peer`
|
|
519
|
+
// argument aimed at the existing runtime family beats minting parallel ones,
|
|
520
|
+
// so there is no `call_rpc_runtime` (use runtime_call_method{peer}) and no
|
|
521
|
+
// `mp_diagnose` aggregate (use runtime_get_log{peer}).
|
|
522
|
+
server.registerTool("runtime_spawn_peers", {
|
|
523
|
+
title: "Runtime spawn headless peers",
|
|
524
|
+
description: "Spawn 1-" +
|
|
525
|
+
MAX_PEERS +
|
|
526
|
+
" HEADLESS Godot peers of this project as child processes, each on its own loopback runtime port, and " +
|
|
527
|
+
"wait until every one answers on its bridge. Returns peer ids for the `peer` argument on runtime_step_frames, " +
|
|
528
|
+
"runtime_time_scale, runtime_seed_rng, runtime_get_property, runtime_call_method, runtime_await_condition and " +
|
|
529
|
+
"runtime_get_log — in fact every runtime tool that talks to the running game takes `peer`, so anything you can " +
|
|
530
|
+
"do to the default game you can do to one peer. Pair with runtime_peers_digest to assert that independently-" +
|
|
531
|
+
"driven peers converge, and read its preconditions before expecting them to. Each child " +
|
|
532
|
+
"gets BREAKPOINT_PEER_ID / BREAKPOINT_PEER_INDEX (and BREAKPOINT_PEER_ROLE when `role` is given) in its " +
|
|
533
|
+
"environment, so game code can branch on which peer it is via OS.get_environment(). Local loopback testing only: " +
|
|
534
|
+
"this hosts no relay, lobby or signalling server. Requires the Breakpoint MCP addon enabled in the project.",
|
|
535
|
+
inputSchema: {
|
|
536
|
+
count: z
|
|
537
|
+
.number()
|
|
538
|
+
.int()
|
|
539
|
+
.min(1)
|
|
540
|
+
.max(MAX_PEERS)
|
|
541
|
+
.describe(`How many peers to spawn (1-${MAX_PEERS}; ${MAX_PEERS} live peers is the ceiling)`),
|
|
542
|
+
scene: z.string().optional().describe("Optional res:// scene each peer runs (default: the project's main scene)"),
|
|
543
|
+
args: z.array(z.string()).optional().describe("Extra command-line arguments passed to every peer"),
|
|
544
|
+
role: z
|
|
545
|
+
.string()
|
|
546
|
+
.optional()
|
|
547
|
+
.describe("Label echoed back per peer and exported to each child as BREAKPOINT_PEER_ROLE (e.g. \"server\")"),
|
|
548
|
+
timeout_ms: z
|
|
549
|
+
.number()
|
|
550
|
+
.int()
|
|
551
|
+
.positive()
|
|
552
|
+
.optional()
|
|
553
|
+
.describe("How long to wait for every peer to answer on its bridge, in ms (default 15000)"),
|
|
554
|
+
},
|
|
555
|
+
}, async ({ count, scene, args, role, timeout_ms }) => {
|
|
556
|
+
try {
|
|
557
|
+
const spawned = await peers.spawn({
|
|
558
|
+
count,
|
|
559
|
+
...(scene !== undefined ? { scene } : {}),
|
|
560
|
+
...(args !== undefined ? { args } : {}),
|
|
561
|
+
...(role !== undefined ? { role } : {}),
|
|
562
|
+
...(timeout_ms !== undefined ? { timeoutMs: timeout_ms } : {}),
|
|
563
|
+
});
|
|
564
|
+
return ok({ peers: spawned, count: spawned.length });
|
|
565
|
+
}
|
|
566
|
+
catch (err) {
|
|
567
|
+
return fail(err);
|
|
568
|
+
}
|
|
569
|
+
});
|
|
570
|
+
server.registerTool("runtime_peer_stop", {
|
|
571
|
+
title: "Runtime stop peer(s)",
|
|
572
|
+
description: "Terminate a headless peer started by runtime_spawn_peers, or every one with all:true. DESTRUCTIVE (kills a " +
|
|
573
|
+
"child process). Stopping an already-stopped peer is a no-op, so this is safe to repeat; peers are also killed " +
|
|
574
|
+
"automatically when the server shuts down.",
|
|
575
|
+
inputSchema: {
|
|
576
|
+
id: z.string().optional().describe("Peer id to stop (from runtime_spawn_peers) — omit when using all"),
|
|
577
|
+
all: z.boolean().optional().describe("Stop every peer this server spawned (default false)"),
|
|
578
|
+
},
|
|
579
|
+
}, async ({ id, all }) => {
|
|
580
|
+
if (!all && !id) {
|
|
581
|
+
return { isError: true, content: [{ type: "text", text: "Pass a peer `id`, or all:true." }] };
|
|
582
|
+
}
|
|
583
|
+
try {
|
|
584
|
+
return ok({ stopped: peers.stop(id, all ?? false) });
|
|
585
|
+
}
|
|
586
|
+
catch (err) {
|
|
587
|
+
return fail(err);
|
|
588
|
+
}
|
|
589
|
+
});
|
|
590
|
+
server.registerTool("runtime_peers_digest", {
|
|
591
|
+
title: "Runtime peer state digest / convergence",
|
|
592
|
+
description: "Read runtime_state_digest from two or more peers over the SAME root and field set and report whether they " +
|
|
593
|
+
"agree (read-only). Converged means every peer's digest is byte-equal; when they differ, diverged_at names the " +
|
|
594
|
+
"node paths that disagree. The sequence that actually converges, in this order: runtime_spawn_peers, then per " +
|
|
595
|
+
"peer runtime_time_scale{scale:0} to FREEZE FIRST, runtime_set_property{peer} to equalise the starting state, " +
|
|
596
|
+
"runtime_seed_rng{seed} with the same seed, runtime_step_frames{frames:K,kind:\"physics\"}, then this. " +
|
|
597
|
+
"FOUR PRECONDITIONS, every one measured on real Godot 4.3 (convergence re-measured on 4.7) — a run that " +
|
|
598
|
+
"skips any of them diverges, and (2) is " +
|
|
599
|
+
"the one that surprises people. (1) Step the FIXED physics timestep: state advanced on the variable idle-frame " +
|
|
600
|
+
"delta is real elapsed wall-clock time in each process and never converges, so pass kind:\"physics\". " +
|
|
601
|
+
"(2) The global RNG must be consumed ONLY on frames you are stepping. runtime_seed_rng seeds one stream shared " +
|
|
602
|
+
"by the whole project, and freezing does NOT stop it being drawn — time_scale 0 zeroes delta but callbacks " +
|
|
603
|
+
"still fire, so unconditional draws burn the stream at wall-clock rate while frozen, and idle-frame draws burn " +
|
|
604
|
+
"it during the step. Guard draws on delta > 0 and give idle-frame code its own RandomNumberGenerator; " +
|
|
605
|
+
"otherwise even fixed-timestep physics state diverges. (3) Peers free-run between spawn and freeze for " +
|
|
606
|
+
"different durations, so their state already differs before you begin: freeze first, then equalise with " +
|
|
607
|
+
"runtime_set_property{peer}. (4) Same machine only — peers share one OS and one engine build, and this claims " +
|
|
608
|
+
"nothing about convergence across machines.",
|
|
609
|
+
inputSchema: {
|
|
610
|
+
root: z.string().describe("Root node path to digest in each peer (same path on every peer)"),
|
|
611
|
+
peers: z
|
|
612
|
+
.array(z.string())
|
|
613
|
+
.optional()
|
|
614
|
+
.describe("Peer ids to compare (default: every live peer; at least two are required)"),
|
|
615
|
+
fields: z
|
|
616
|
+
.array(z.string())
|
|
617
|
+
.optional()
|
|
618
|
+
.describe("Property names to capture per node (default: the runtime_state_digest defaults)"),
|
|
619
|
+
max_depth: z.number().int().nonnegative().optional().describe("Max recursion depth (default 8)"),
|
|
620
|
+
},
|
|
621
|
+
}, async ({ root, peers: ids, fields, max_depth }) => {
|
|
622
|
+
const targets = ids ?? peers.live().map((p) => p.id);
|
|
623
|
+
if (targets.length < 2) {
|
|
624
|
+
return {
|
|
625
|
+
isError: true,
|
|
626
|
+
content: [
|
|
627
|
+
{
|
|
628
|
+
type: "text",
|
|
629
|
+
text: `Convergence needs at least two peers; got ${targets.length}. ` +
|
|
630
|
+
`Spawn more with runtime_spawn_peers, or use runtime_state_digest for a single target.`,
|
|
631
|
+
},
|
|
632
|
+
],
|
|
633
|
+
};
|
|
634
|
+
}
|
|
635
|
+
const params = {
|
|
636
|
+
root,
|
|
637
|
+
...(fields !== undefined ? { fields } : {}),
|
|
638
|
+
...(max_depth !== undefined ? { max_depth } : {}),
|
|
639
|
+
};
|
|
640
|
+
let results;
|
|
641
|
+
try {
|
|
642
|
+
results = await Promise.all(targets.map(async (id) => {
|
|
643
|
+
const r = (await peers.clientFor(id).request("runtime.state_digest", params));
|
|
644
|
+
return { id, digest: r?.digest ?? {}, node_count: r?.node_count ?? 0 };
|
|
645
|
+
}));
|
|
646
|
+
}
|
|
647
|
+
catch (err) {
|
|
648
|
+
return fail(err);
|
|
649
|
+
}
|
|
650
|
+
const paths = new Set();
|
|
651
|
+
for (const r of results)
|
|
652
|
+
for (const k of Object.keys(r.digest))
|
|
653
|
+
paths.add(k);
|
|
654
|
+
const first = results[0];
|
|
655
|
+
const divergedAt = [...paths]
|
|
656
|
+
.filter((path) => {
|
|
657
|
+
const ref = canonical(first.digest[path]);
|
|
658
|
+
return results.some((r) => canonical(r.digest[path]) !== ref);
|
|
659
|
+
})
|
|
660
|
+
.sort();
|
|
661
|
+
return ok({
|
|
662
|
+
digests: results,
|
|
663
|
+
converged: divergedAt.length === 0,
|
|
664
|
+
diverged_at: divergedAt.length ? divergedAt : null,
|
|
665
|
+
});
|
|
666
|
+
});
|
|
236
667
|
}
|
|
237
668
|
//# sourceMappingURL=runtime.js.map
|
package/dist/toolsets.js
CHANGED
|
@@ -6,6 +6,7 @@ import { registerDapTools } from "./tools/dap.js";
|
|
|
6
6
|
import { registerCsDapTools } from "./tools/csdap.js";
|
|
7
7
|
import { registerRuntimeTools } from "./tools/runtime.js";
|
|
8
8
|
import { registerProcessTools } from "./tools/processes.js";
|
|
9
|
+
import { PeerRegistry } from "./peers.js";
|
|
9
10
|
import { registerKnowledgeTools } from "./tools/knowledge.js";
|
|
10
11
|
import { registerVcsTools } from "./tools/vcs.js";
|
|
11
12
|
import { registerAssetGenTools } from "./tools/assetgen.js";
|
|
@@ -23,6 +24,11 @@ export function buildToolsets(d) {
|
|
|
23
24
|
const s = d.server;
|
|
24
25
|
const c = d.config;
|
|
25
26
|
const stub = (v) => v;
|
|
27
|
+
// F6: constructed here, not in index.ts, so the registration tests drive the
|
|
28
|
+
// same wiring the live server does. Construction is inert — nothing is spawned
|
|
29
|
+
// until runtime_spawn_peers is called.
|
|
30
|
+
const peers = new PeerRegistry(c);
|
|
31
|
+
d.onPeers?.(peers);
|
|
26
32
|
return [
|
|
27
33
|
{ id: "cli", describe: "Plane B — headless CLI (no editor required)", run: () => registerCliTools(s, c) },
|
|
28
34
|
{ id: "editor", describe: "Plane A — live editor authoring (addon bridge)", run: () => registerEditorTools(s, stub(d.bridge)) },
|
|
@@ -30,7 +36,7 @@ export function buildToolsets(d) {
|
|
|
30
36
|
{ id: "cslsp", describe: "Plane D — C# language server (OmniSharp)", run: () => registerCsLspTools(s, stub(d.csLsp), c) },
|
|
31
37
|
{ id: "dap", describe: "Plane D — GDScript debug adapter (DAP)", run: () => registerDapTools(s, stub(d.dap), c) },
|
|
32
38
|
{ id: "csdap", describe: "Plane D — C# debug adapter (netcoredbg)", run: () => registerCsDapTools(s, stub(d.csDap), c) },
|
|
33
|
-
{ id: "runtime", describe: "Plane C — running-game runtime + verification family", run: () => registerRuntimeTools(s, stub(d.runtime)) },
|
|
39
|
+
{ id: "runtime", describe: "Plane C — running-game runtime + verification family (incl. F6 multi-peer)", run: () => registerRuntimeTools(s, stub(d.runtime), peers) },
|
|
34
40
|
{ id: "processes", describe: "Managed run + captured console output", run: () => { const h = registerProcessTools(s, c); d.onProcesses?.(h); } },
|
|
35
41
|
{ id: "knowledge", describe: "Group K — host-side project grep / symbol & idiom lookup", run: () => registerKnowledgeTools(s, c) },
|
|
36
42
|
{ id: "vcs", describe: "Group L — read-only version control (git) over the project", run: () => registerVcsTools(s, c) },
|