breakpoint-mcp 1.21.1 → 1.24.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/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/config.js +29 -4
- package/dist/index.js +26 -4
- package/dist/peers.js +225 -0
- package/dist/ports.js +68 -0
- package/dist/recipes.js +36 -4
- package/dist/schemas.js +17 -0
- package/dist/secret.js +49 -0
- package/dist/tools/cli.js +15 -2
- package/dist/tools/processes.js +43 -4
- package/dist/tools/runtime.js +292 -67
- package/dist/toolsets.js +7 -1
- package/package.json +1 -1
package/dist/peers.js
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
import { BridgeClient, BridgeError } from "./bridge.js";
|
|
2
|
+
import { ProcessRegistry } from "./tools/processes.js";
|
|
3
|
+
import { ensureProjectSecret, readProjectSecret } from "./secret.js";
|
|
4
|
+
import { log } from "./logger.js";
|
|
5
|
+
import { portFree } from "./ports.js";
|
|
6
|
+
/**
|
|
7
|
+
* Hard ceiling on simultaneously live peers.
|
|
8
|
+
*
|
|
9
|
+
* Four, not the eight a rival offers. Four headless Godot instances is already a
|
|
10
|
+
* heavy CI runner, the convergence cases that matter are covered at four, and
|
|
11
|
+
* every extra instance multiplies the flake surface of the one feature whose
|
|
12
|
+
* entire selling point is that it does NOT flake. Raise it on evidence, never
|
|
13
|
+
* speculatively.
|
|
14
|
+
*/
|
|
15
|
+
export const MAX_PEERS = 4;
|
|
16
|
+
/** How far above the default runtime port the allocator will scan. */
|
|
17
|
+
const PORT_SCAN_SPAN = 200;
|
|
18
|
+
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
19
|
+
export class PeerRegistry {
|
|
20
|
+
cfg;
|
|
21
|
+
/** Peers get their OWN process registry, so peer ids and `godot_run_managed`
|
|
22
|
+
* ids never share a namespace and the `runtime` toolset does not depend on
|
|
23
|
+
* whether the `processes` toolset is enabled. */
|
|
24
|
+
procs = new ProcessRegistry();
|
|
25
|
+
peers = new Map();
|
|
26
|
+
counter = 0;
|
|
27
|
+
constructor(cfg) {
|
|
28
|
+
this.cfg = cfg;
|
|
29
|
+
}
|
|
30
|
+
/** Peers that have not been stopped and whose child is still running. */
|
|
31
|
+
live() {
|
|
32
|
+
const out = [];
|
|
33
|
+
for (const e of this.peers.values()) {
|
|
34
|
+
if (e.stopped)
|
|
35
|
+
continue;
|
|
36
|
+
if (this.procs.get(e.managedId)?.exited)
|
|
37
|
+
continue;
|
|
38
|
+
out.push(e.info);
|
|
39
|
+
}
|
|
40
|
+
return out;
|
|
41
|
+
}
|
|
42
|
+
/** Every peer this registry has spawned, live or not. */
|
|
43
|
+
all() {
|
|
44
|
+
return [...this.peers.values()].map((e) => e.info);
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* The bridge client addressing one peer. Throws a BridgeError the runtime
|
|
48
|
+
* tools' `fail()` renders — an unknown or dead peer must read as a clear
|
|
49
|
+
* message naming the live ids, never as a generic "cannot reach the bridge".
|
|
50
|
+
*/
|
|
51
|
+
clientFor(id) {
|
|
52
|
+
const e = this.peers.get(id);
|
|
53
|
+
if (!e) {
|
|
54
|
+
const ids = this.live().map((p) => p.id);
|
|
55
|
+
throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}. ` +
|
|
56
|
+
`Spawn peers with runtime_spawn_peers, or omit \`peer\` to address the default running game.`);
|
|
57
|
+
}
|
|
58
|
+
if (e.stopped)
|
|
59
|
+
throw new BridgeError("peer_stopped", `Peer "${id}" was stopped by runtime_peer_stop.`);
|
|
60
|
+
const m = this.procs.get(e.managedId);
|
|
61
|
+
if (m?.exited) {
|
|
62
|
+
const tail = this.procs.tail(e.managedId, 6).join(" | ");
|
|
63
|
+
throw new BridgeError("peer_exited", `Peer "${id}" exited (code ${m.exitCode})${tail ? `; last output: ${tail}` : ""}.`);
|
|
64
|
+
}
|
|
65
|
+
return e.client;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Allocate `count` free loopback ports, starting just above the default
|
|
69
|
+
* runtime port so a peer never collides with a developer's already-running
|
|
70
|
+
* game. Ports held by live peers are skipped even if the probe would pass.
|
|
71
|
+
*
|
|
72
|
+
* The probe is TOCTOU by construction (see `ports.ts`), but allocation is
|
|
73
|
+
* sequential and the window is sub-millisecond, and the failure mode is
|
|
74
|
+
* benign — the child logs "could not listen" and the readiness wait below
|
|
75
|
+
* reports it with that line attached, rather than the peer silently
|
|
76
|
+
* half-existing. The DEFAULT runtime port has no such readiness wait, which
|
|
77
|
+
* is why `godot_run_managed` and `godot_run_project` refuse a held port
|
|
78
|
+
* outright rather than reporting it after the fact.
|
|
79
|
+
*/
|
|
80
|
+
async allocatePorts(count) {
|
|
81
|
+
const taken = new Set([this.cfg.runtimePort, ...this.live().map((p) => p.port)]);
|
|
82
|
+
const ports = [];
|
|
83
|
+
const base = this.cfg.runtimePort + 1;
|
|
84
|
+
for (let port = base; port < base + PORT_SCAN_SPAN && ports.length < count; port++) {
|
|
85
|
+
if (taken.has(port))
|
|
86
|
+
continue;
|
|
87
|
+
if (!(await portFree(this.cfg.runtimeHost, port)))
|
|
88
|
+
continue;
|
|
89
|
+
taken.add(port);
|
|
90
|
+
ports.push(port);
|
|
91
|
+
}
|
|
92
|
+
if (ports.length < count) {
|
|
93
|
+
throw new BridgeError("no_free_port", `Could not find ${count} free loopback port(s) in ${base}–${base + PORT_SCAN_SPAN - 1}. ` +
|
|
94
|
+
`Stop stale peers with runtime_peer_stop{all:true}, or set BREAKPOINT_RUNTIME_PORT to a quieter range.`);
|
|
95
|
+
}
|
|
96
|
+
return ports;
|
|
97
|
+
}
|
|
98
|
+
/** Poll a peer's bridge until it answers `ping`, or the deadline passes. */
|
|
99
|
+
async waitReady(client, deadline) {
|
|
100
|
+
for (;;) {
|
|
101
|
+
const remaining = deadline - Date.now();
|
|
102
|
+
if (remaining <= 0)
|
|
103
|
+
return false;
|
|
104
|
+
try {
|
|
105
|
+
await client.request("ping", {}, Math.min(1000, remaining));
|
|
106
|
+
return true;
|
|
107
|
+
}
|
|
108
|
+
catch {
|
|
109
|
+
if (Date.now() >= deadline)
|
|
110
|
+
return false;
|
|
111
|
+
await sleep(100);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Spawn `count` headless peers and wait until each answers `ping`.
|
|
117
|
+
*
|
|
118
|
+
* Waiting is part of the contract on purpose. Godot needs ~200 ms to bind, so
|
|
119
|
+
* a tool that returned immediately would hand the caller peers its very next
|
|
120
|
+
* call cannot reach — a flake in the one feature that exists to remove flakes.
|
|
121
|
+
*/
|
|
122
|
+
async spawn(opts) {
|
|
123
|
+
const liveCount = this.live().length;
|
|
124
|
+
if (liveCount + opts.count > MAX_PEERS) {
|
|
125
|
+
throw new BridgeError("peer_limit", `${liveCount} peer(s) already live; spawning ${opts.count} more would exceed the ceiling of ${MAX_PEERS}. ` +
|
|
126
|
+
`Stop some with runtime_peer_stop{all:true} first.`);
|
|
127
|
+
}
|
|
128
|
+
// Constraint 2 — mint BEFORE the first spawn so no child reaches the addon's
|
|
129
|
+
// unlocked mint branch. Never overwrites an existing secret.
|
|
130
|
+
const secret = ensureProjectSecret(this.cfg.projectPath);
|
|
131
|
+
if (!secret) {
|
|
132
|
+
log("[peers] could not read or mint the project secret; peers will mint their own (see peers.ts)");
|
|
133
|
+
}
|
|
134
|
+
const ports = await this.allocatePorts(opts.count);
|
|
135
|
+
const deadline = Date.now() + (opts.timeoutMs ?? 15000);
|
|
136
|
+
const spawned = [];
|
|
137
|
+
for (let i = 0; i < ports.length; i++) {
|
|
138
|
+
const port = ports[i];
|
|
139
|
+
const id = `peer-${++this.counter}`;
|
|
140
|
+
const extraArgs = ["--headless", ...(opts.args ?? []), ...(opts.scene ? [opts.scene] : [])];
|
|
141
|
+
const env = {
|
|
142
|
+
BREAKPOINT_RUNTIME_PORT: String(port),
|
|
143
|
+
BREAKPOINT_PEER_ID: id,
|
|
144
|
+
BREAKPOINT_PEER_INDEX: String(i),
|
|
145
|
+
};
|
|
146
|
+
if (opts.role)
|
|
147
|
+
env.BREAKPOINT_PEER_ROLE = opts.role;
|
|
148
|
+
const managed = this.procs.run(this.cfg, extraArgs, env);
|
|
149
|
+
const client = new BridgeClient(this.cfg.runtimeHost, port, this.cfg.runtimeTimeoutMs, `runtime peer ${id}`, "Is the peer still running? Peers are headless children of this server; a project that fails to load exits immediately.",
|
|
150
|
+
// The FILE, not resolveBridgeSecret: the addon's _setup_auth() does not
|
|
151
|
+
// read BREAKPOINT_*_SECRET, so a host-launched child authenticates with
|
|
152
|
+
// whatever is on disk regardless of the host's env overrides.
|
|
153
|
+
() => readProjectSecret(this.cfg.projectPath));
|
|
154
|
+
const entry = {
|
|
155
|
+
info: { id, port, pid: managed.child.pid ?? null, role: opts.role ?? null, ready: false },
|
|
156
|
+
client,
|
|
157
|
+
managedId: managed.id,
|
|
158
|
+
stopped: false,
|
|
159
|
+
};
|
|
160
|
+
this.peers.set(id, entry);
|
|
161
|
+
spawned.push(entry);
|
|
162
|
+
}
|
|
163
|
+
await Promise.all(spawned.map(async (e) => {
|
|
164
|
+
e.info.ready = await this.waitReady(e.client, deadline);
|
|
165
|
+
}));
|
|
166
|
+
const notReady = spawned.filter((e) => !e.info.ready);
|
|
167
|
+
if (notReady.length) {
|
|
168
|
+
const detail = notReady
|
|
169
|
+
.map((e) => {
|
|
170
|
+
const m = this.procs.get(e.managedId);
|
|
171
|
+
const why = m?.exited ? `exited (code ${m.exitCode})` : "never answered ping";
|
|
172
|
+
const tail = this.procs.tail(e.managedId, 6).join(" | ");
|
|
173
|
+
return `${e.info.id} on ${e.info.port}: ${why}${tail ? ` — ${tail}` : ""}`;
|
|
174
|
+
})
|
|
175
|
+
.join("; ");
|
|
176
|
+
// Leave the failed peers registered rather than reaping them: the caller
|
|
177
|
+
// can still runtime_peer_stop{all:true}, and a half-started peer that
|
|
178
|
+
// vanished from the registry is harder to reason about than one that
|
|
179
|
+
// reports why it is not ready.
|
|
180
|
+
throw new BridgeError("peer_not_ready", `${notReady.length} of ${spawned.length} peer(s) did not become ready. ${detail}. ` +
|
|
181
|
+
`Is the Breakpoint MCP addon enabled in this project (it registers the runtime autoload)?`);
|
|
182
|
+
}
|
|
183
|
+
return spawned.map((e) => e.info);
|
|
184
|
+
}
|
|
185
|
+
/** Stop one peer (or all). Repeating is a no-op, so the tool is idempotent. */
|
|
186
|
+
stop(id, all = false) {
|
|
187
|
+
const targets = all ? [...this.peers.keys()] : id ? [id] : [];
|
|
188
|
+
if (!all && id && !this.peers.has(id)) {
|
|
189
|
+
const ids = this.live().map((p) => p.id);
|
|
190
|
+
throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}.`);
|
|
191
|
+
}
|
|
192
|
+
const stopped = [];
|
|
193
|
+
for (const t of targets) {
|
|
194
|
+
const e = this.peers.get(t);
|
|
195
|
+
if (!e)
|
|
196
|
+
continue;
|
|
197
|
+
try {
|
|
198
|
+
e.client.close();
|
|
199
|
+
}
|
|
200
|
+
catch {
|
|
201
|
+
/* ignore */
|
|
202
|
+
}
|
|
203
|
+
try {
|
|
204
|
+
this.procs.get(e.managedId)?.child.kill();
|
|
205
|
+
}
|
|
206
|
+
catch {
|
|
207
|
+
/* ignore */
|
|
208
|
+
}
|
|
209
|
+
e.stopped = true;
|
|
210
|
+
stopped.push(t);
|
|
211
|
+
}
|
|
212
|
+
return stopped;
|
|
213
|
+
}
|
|
214
|
+
/** Shutdown hook — kill every peer child and close every peer socket. */
|
|
215
|
+
stopAll() {
|
|
216
|
+
try {
|
|
217
|
+
this.stop(undefined, true);
|
|
218
|
+
}
|
|
219
|
+
catch {
|
|
220
|
+
/* ignore */
|
|
221
|
+
}
|
|
222
|
+
this.procs.killAll();
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
//# sourceMappingURL=peers.js.map
|
package/dist/ports.js
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import net from "node:net";
|
|
2
|
+
/**
|
|
3
|
+
* Loopback port probing, shared by the two callers that must not collide.
|
|
4
|
+
*
|
|
5
|
+
* It lives in its own module because `peers.ts` imports `ProcessRegistry` from
|
|
6
|
+
* `tools/processes.ts`, so `processes.ts` importing the probe back out of
|
|
7
|
+
* `peers.ts` would close an import cycle. Nothing here imports anything local.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Is `port` bindable on `host` right now?
|
|
11
|
+
*
|
|
12
|
+
* Probe-then-release is a TOCTOU window by construction: another process could
|
|
13
|
+
* take the port between this answer and whoever acts on it. Every caller here
|
|
14
|
+
* treats a `true` as "nothing is holding it as of now", never as a lease.
|
|
15
|
+
*
|
|
16
|
+
* SO_REUSEADDR (which Node sets by default) does NOT let two live listeners
|
|
17
|
+
* share an address on Linux or macOS — that needs SO_REUSEPORT, which Node does
|
|
18
|
+
* not set — so a bound port answers `false` rather than being silently joinable.
|
|
19
|
+
*/
|
|
20
|
+
export function portFree(host, port) {
|
|
21
|
+
return new Promise((resolve) => {
|
|
22
|
+
const srv = net.createServer();
|
|
23
|
+
srv.once("error", () => resolve(false));
|
|
24
|
+
srv.once("listening", () => srv.close(() => resolve(true)));
|
|
25
|
+
try {
|
|
26
|
+
srv.listen(port, host);
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
resolve(false);
|
|
30
|
+
}
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* The refusal text shared by `godot_run_managed` and `godot_run_project`.
|
|
35
|
+
*
|
|
36
|
+
* Both tools start a game whose runtime autoload binds `BREAKPOINT_RUNTIME_PORT`
|
|
37
|
+
* (`runtime_bridge.gd:74`). When that port is already held, the autoload's
|
|
38
|
+
* `listen()` returns non-OK, it `push_error`s, and **the game keeps running
|
|
39
|
+
* without a bridge** — while the host's runtime client, which dials the same
|
|
40
|
+
* fixed port, connects to whichever process got there first. Every subsequent
|
|
41
|
+
* `runtime_*` call then answers confidently about the WRONG process, and `ping`
|
|
42
|
+
* carries no pid or boot nonce that could tell them apart.
|
|
43
|
+
*
|
|
44
|
+
* That is why this refuses rather than warns: a determinism feature returning a
|
|
45
|
+
* correct-looking answer from the wrong game is worse than one that will not
|
|
46
|
+
* start.
|
|
47
|
+
*
|
|
48
|
+
* Note what is deliberately NOT offered as a remedy: stopping peers. A peer can
|
|
49
|
+
* never hold this port — `allocatePorts` seeds its `taken` set with
|
|
50
|
+
* `cfg.runtimePort` and scans from `runtimePort + 1`, so whatever holds it is
|
|
51
|
+
* something else. `runtime_spawn_peers` is named below as the way to drive
|
|
52
|
+
* several games at once, which is true; `runtime_peer_stop` as a way to free
|
|
53
|
+
* THIS port would not be, and a remedy that cannot work is worse than one fewer
|
|
54
|
+
* suggestion.
|
|
55
|
+
*/
|
|
56
|
+
export function portConflictMessage(host, port) {
|
|
57
|
+
return (`${host}:${port} is already bound, so a game started now could not host the runtime bridge. ` +
|
|
58
|
+
`Its autoload would fail to listen and keep running anyway, and every runtime_* call would ` +
|
|
59
|
+
`silently address the process that already holds the port instead of the one you just started. ` +
|
|
60
|
+
`Stop the running game first — godot_stop if godot_run_managed started it, otherwise quit it in ` +
|
|
61
|
+
`the game window or end the debug session that launched it (a detached godot_run_project game is ` +
|
|
62
|
+
`not stoppable by any tool) — or point this server at a free port with ` +
|
|
63
|
+
`BREAKPOINT_RUNTIME_PORT. Pass allow_port_conflict:true to start it anyway — reasonable only if ` +
|
|
64
|
+
`you want the process for its console output or its side effects and will not use any runtime_* ` +
|
|
65
|
+
`tool against it. To drive more than one game at once, use runtime_spawn_peers, which allocates ` +
|
|
66
|
+
`a distinct port per peer.`);
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=ports.js.map
|
package/dist/recipes.js
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* it's **free** (MIT, shipped in the server), and it sits **over typed,
|
|
8
8
|
* schema-validated, undoable tools** — so the contract is executed by the
|
|
9
9
|
* server, not merely described in prose the model might misapply. Recipes are
|
|
10
|
-
* discoverable via MCP `prompts/list`; they add **no tools** (the
|
|
10
|
+
* discoverable via MCP `prompts/list`; they add **no tools** (the 289-tool
|
|
11
11
|
* count is unchanged) and cost nothing until a client pulls one.
|
|
12
12
|
*/
|
|
13
13
|
import { z } from "zod";
|
|
@@ -28,6 +28,7 @@ export const RECIPE_NAMES = [
|
|
|
28
28
|
"recipe_type_safe_edit",
|
|
29
29
|
"recipe_csharp_fix_and_debug",
|
|
30
30
|
"recipe_deterministic_playtest",
|
|
31
|
+
"recipe_multiplayer_scaffold_and_converge",
|
|
31
32
|
];
|
|
32
33
|
export function registerRecipes(server) {
|
|
33
34
|
// 1 — 2D player controller, then verify it moves.
|
|
@@ -113,8 +114,8 @@ export function registerRecipes(server) {
|
|
|
113
114
|
return recipe("Golden-image regression check for a scene.", [
|
|
114
115
|
`Goal: lock a scene's look to a golden image at ${ref} and catch visual drift.`,
|
|
115
116
|
"",
|
|
116
|
-
`1. Establish the golden (first run only):
|
|
117
|
-
`2. Regression run (every time after):
|
|
117
|
+
`1. Establish the golden (first run only): godot_run_managed, drive the game to the state under test (runtime_inject_input / runtime_call_method), then runtime_screenshot and save the frame to ${ref}. Commit it (vcs_add) so it's the reference, then godot_stop — this recipe runs the game more than once, and a game left running holds the runtime bridge port, so the next run is refused.`,
|
|
118
|
+
`2. Regression run (every time after): godot_run_managed, reproduce the same state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} (pass a region to ignore volatile HUD areas). ok:true means no meaningful drift. godot_stop when the diff is in hand.`,
|
|
118
119
|
"3. On failure: the diff returns diff_ratio + differing_pixels — don't just eyeball it. runtime_get_tree / runtime_assert_node_state to find the node that changed, or dbg_* to break where the offending value is set. Update the golden deliberately (re-do step 1) only once you've confirmed the change is intended.",
|
|
119
120
|
"",
|
|
120
121
|
"The whole diff runs engine-side (Image), so there's no OCR/image dependency and it stays read-only and ungated.",
|
|
@@ -137,7 +138,7 @@ export function registerRecipes(server) {
|
|
|
137
138
|
`1. Understand: gd_document_symbols for the file's shape; gd_definition / gd_references before touching a symbol so you know every call site; find_usages across the project for wider blast radius.`,
|
|
138
139
|
"2. Edit with help: while writing, use gd_completion and gd_hover to get exact API names and signatures (this is where a generic 'call any method' tool hallucinates — the LSP gives you the truth). gd_rename to rename safely across the project.",
|
|
139
140
|
"3. Gate: run gd_diagnostics and do not proceed until it's clean. gd_code_action for quick-fixes it suggests.",
|
|
140
|
-
"4. Prove behavior:
|
|
141
|
+
"4. Prove behavior: godot_run_managed and a runtime_assert_* that the change did what you intended, then godot_stop — leaving it running holds the runtime bridge port and the next run of this recipe is refused. If the assert didn't pass, dbg_* into it.",
|
|
141
142
|
"",
|
|
142
143
|
"Every mutation is on the undo stack — editor_undo reverts a bad edit instantly.",
|
|
143
144
|
"",
|
|
@@ -196,5 +197,36 @@ export function registerRecipes(server) {
|
|
|
196
197
|
SAFETY,
|
|
197
198
|
].join("\n"));
|
|
198
199
|
});
|
|
200
|
+
// 8 — Multiplayer: scaffold it with mp_*, then prove independent peers converge.
|
|
201
|
+
server.registerPrompt("recipe_multiplayer_scaffold_and_converge", {
|
|
202
|
+
title: "Scaffold multiplayer with mp_*, then prove independent peers converge",
|
|
203
|
+
description: "Scaffold ENet + spawner / synchronizer / RPC netcode, then spawn real headless peers and assert they reach a byte-equal state — the scaffold verified rather than assumed.",
|
|
204
|
+
argsSchema: {
|
|
205
|
+
scene_path: z.string().optional().describe("Scene to scaffold and play-test (default res://main.tscn)"),
|
|
206
|
+
peer_count: z.string().optional().describe("Headless peers to spawn (1-4; default 3)"),
|
|
207
|
+
seed: z.string().optional().describe("RNG seed given to every peer (default 12345)"),
|
|
208
|
+
frames: z.string().optional().describe("Physics frames to step on each peer (default 30)"),
|
|
209
|
+
root_path: z.string().optional().describe("Node subtree to compare across peers (default '.', the running scene root)"),
|
|
210
|
+
},
|
|
211
|
+
}, (a) => {
|
|
212
|
+
const scene = str(a, "scene_path", "res://main.tscn");
|
|
213
|
+
const count = str(a, "peer_count", "3");
|
|
214
|
+
const seed = str(a, "seed", "12345");
|
|
215
|
+
const frames = str(a, "frames", "30");
|
|
216
|
+
const root = str(a, "root_path", ".");
|
|
217
|
+
return recipe("Multiplayer scaffolding with a multi-peer convergence check.", [
|
|
218
|
+
`Goal: scaffold multiplayer in ${scene} with the mp_* family, then prove ${count} independently-driven peers reach the SAME state.`,
|
|
219
|
+
"",
|
|
220
|
+
`1. Scaffold: scene_open ${scene}. mp_setup_enet_peer for the host/join script (mp_setup_webrtc_peer if you need WebRTC); mp_scaffold_lobby for a lobby; mp_add_spawner for nodes created at runtime and mp_add_synchronizer for replicated properties; mp_set_authority on the nodes each peer owns; mp_wire_rpc for the calls that cross the wire. Run gd_diagnostics until clean BEFORE running anything.`,
|
|
221
|
+
"2. Make it testable, or step 4 will diverge and be right to: keep replicated state on _physics_process (the FIXED timestep), guard every global randf() on `delta > 0`, and give idle-frame code its OWN RandomNumberGenerator. runtime_seed_rng seeds ONE stream for the whole project, and freezing does not stop callbacks firing — an unguarded draw burns that stream at wall-clock rate and desynchronises peers that are otherwise identical.",
|
|
222
|
+
`3. Spawn: runtime_spawn_peers{count:${count}} — real headless children of this project, each on its own loopback port (ceiling 4). Pass role:"server" to label one and branch on OS.get_environment("BREAKPOINT_PEER_ROLE"). It is code-execution-privileged, so it is absent from the default surface unless you enabled that capability group.`,
|
|
223
|
+
`4. Converge, IN THIS ORDER: runtime_time_scale{scale:0, peer} to FREEZE every peer first (they free-ran for different durations since spawn, so their state already differs); runtime_set_property{peer} to equalise the starting state; runtime_seed_rng{seed:${seed}, peer} with the SAME seed on each; runtime_step_frames{frames:${frames}, kind:"physics", peer} on each; then runtime_peers_digest{root:"${root}"}.`,
|
|
224
|
+
`5. Assert, then diagnose: converged:true is the green result. On false, diverged_at names the exact node paths that disagree — start there with runtime_get_property{peer} and runtime_get_log{peer} on the two peers that differ, runtime_assert_node_state for the value you expected, and dbg_set_breakpoints + dbg_launch when you need the frame it went wrong on. Finish with runtime_peer_stop{all:true}.`,
|
|
225
|
+
"",
|
|
226
|
+
"Scope, so a green result means what you think it does: peers are local headless children on loopback — this is testing, not hosting, and Breakpoint runs no relay, lobby or signalling server. Convergence is a same-machine claim (one OS, one engine build); it says nothing about two players on two machines.",
|
|
227
|
+
"",
|
|
228
|
+
SAFETY,
|
|
229
|
+
].join("\n"));
|
|
230
|
+
});
|
|
199
231
|
}
|
|
200
232
|
//# sourceMappingURL=recipes.js.map
|
package/dist/schemas.js
CHANGED
|
@@ -513,6 +513,23 @@ export const outputSchemas = {
|
|
|
513
513
|
runtime_step_frames: { frames_advanced: z.number(), frame_index: z.number() },
|
|
514
514
|
runtime_state_digest: { digest: z.record(z.record(encodedValue)), node_count: z.number() },
|
|
515
515
|
runtime_seed_rng: { seed: z.number() },
|
|
516
|
+
// F6 additions: multi-peer deterministic playtesting (spawn / stop / converge).
|
|
517
|
+
runtime_spawn_peers: {
|
|
518
|
+
peers: z.array(z.object({
|
|
519
|
+
id: z.string(),
|
|
520
|
+
port: z.number(),
|
|
521
|
+
pid: z.number().nullable(),
|
|
522
|
+
role: z.string().nullable(),
|
|
523
|
+
ready: z.boolean(),
|
|
524
|
+
})),
|
|
525
|
+
count: z.number(),
|
|
526
|
+
},
|
|
527
|
+
runtime_peer_stop: { stopped: z.array(z.string()) },
|
|
528
|
+
runtime_peers_digest: {
|
|
529
|
+
digests: z.array(z.object({ id: z.string(), digest: z.record(z.record(encodedValue)), node_count: z.number() })),
|
|
530
|
+
converged: z.boolean(),
|
|
531
|
+
diverged_at: z.array(z.string()).nullable(),
|
|
532
|
+
},
|
|
516
533
|
// ---- Group K: knowledge & search ----
|
|
517
534
|
// Host-side project index (tools/knowledge.ts) — no bridge/LSP; read the project files directly.
|
|
518
535
|
project_search: {
|
package/dist/secret.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import fs from "node:fs";
|
|
2
2
|
import path from "node:path";
|
|
3
|
+
import { randomBytes } from "node:crypto";
|
|
3
4
|
/**
|
|
4
5
|
* Loopback-bridge shared secret (host side).
|
|
5
6
|
*
|
|
@@ -35,4 +36,52 @@ export function resolveBridgeSecret(projectPath, envNames) {
|
|
|
35
36
|
}
|
|
36
37
|
return readProjectSecret(projectPath);
|
|
37
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* Mint the per-project secret if it does not exist yet, and return it (or the
|
|
41
|
+
* existing one). Returns null if the file can neither be read nor written — the
|
|
42
|
+
* caller then proceeds exactly as before, with the child minting its own.
|
|
43
|
+
*
|
|
44
|
+
* Why the HOST mints it, ahead of spawning peers (F6 spike, constraint 2):
|
|
45
|
+
* `BridgeSecret.load_or_mint()` in the addon is a check-then-write with no lock
|
|
46
|
+
* — `file_exists → read` ELSE `mint → write`. F6 spawns N children through one
|
|
47
|
+
* funnel, so on a COLD project every child can reach the mint branch before any
|
|
48
|
+
* of them has written. Two peers minting different secrets, each holding its own
|
|
49
|
+
* in memory while the last writer wins on disk, is a peer the host can never
|
|
50
|
+
* authenticate against — and it presents as a flaky spawn, not a clear error.
|
|
51
|
+
* Measured 6/6 clean at 3 simultaneous peers, but that is Godot's ~200 ms init
|
|
52
|
+
* versus a sub-millisecond mint, i.e. timing, not a guarantee; the window is
|
|
53
|
+
* structurally open and would surface on someone else's slower machine.
|
|
54
|
+
*
|
|
55
|
+
* Writing the file first closes it by construction: every child then takes the
|
|
56
|
+
* `file_exists` path (verified 4/4 in the spike, with the file untouched after).
|
|
57
|
+
* An EXISTING secret is never overwritten — the editor may have minted it, and
|
|
58
|
+
* all three parties must agree on one value.
|
|
59
|
+
*
|
|
60
|
+
* Format matches `addons/breakpoint_mcp/bridge_secret.gd` exactly: 32 random
|
|
61
|
+
* bytes, hex-encoded to 64 characters, at `<projectPath>/.godot/breakpoint_mcp.secret`.
|
|
62
|
+
* Note the addon's `_setup_auth()` does NOT read the env overrides — they are
|
|
63
|
+
* host-side only — so the FILE is the mechanism for a host-launched child.
|
|
64
|
+
*/
|
|
65
|
+
export function ensureProjectSecret(projectPath) {
|
|
66
|
+
const existing = readProjectSecret(projectPath);
|
|
67
|
+
if (existing)
|
|
68
|
+
return existing;
|
|
69
|
+
try {
|
|
70
|
+
const dir = path.join(projectPath, ".godot");
|
|
71
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
72
|
+
const secret = randomBytes(32).toString("hex");
|
|
73
|
+
// wx: never clobber a secret another process minted between the read above
|
|
74
|
+
// and this write — losing that race must be a no-op, not an overwrite.
|
|
75
|
+
try {
|
|
76
|
+
fs.writeFileSync(path.join(dir, "breakpoint_mcp.secret"), secret, { encoding: "utf8", flag: "wx", mode: 0o600 });
|
|
77
|
+
return secret;
|
|
78
|
+
}
|
|
79
|
+
catch {
|
|
80
|
+
return readProjectSecret(projectPath);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
catch {
|
|
84
|
+
return null;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
38
87
|
//# sourceMappingURL=secret.js.map
|
package/dist/tools/cli.js
CHANGED
|
@@ -4,6 +4,7 @@ import { z } from "zod";
|
|
|
4
4
|
import { log } from "../logger.js";
|
|
5
5
|
import { registerTaskTool } from "../tasks.js";
|
|
6
6
|
import { ok } from "./lsp-common.js";
|
|
7
|
+
import { portFree, portConflictMessage } from "../ports.js";
|
|
7
8
|
const execFileAsync = promisify(execFile);
|
|
8
9
|
/** Run the Godot binary to completion, capturing stdout/stderr. */
|
|
9
10
|
async function runCaptured(cfg, args, timeoutMs, signal) {
|
|
@@ -62,11 +63,23 @@ export function registerCliTools(server, cfg) {
|
|
|
62
63
|
});
|
|
63
64
|
server.registerTool("godot_run_project", {
|
|
64
65
|
title: "Run project",
|
|
65
|
-
description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id."
|
|
66
|
+
description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id. " +
|
|
67
|
+
"Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
|
|
68
|
+
"runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
|
|
69
|
+
"than one game at once.",
|
|
66
70
|
inputSchema: {
|
|
67
71
|
scene: z.string().optional().describe("Optional scene to run, e.g. res://levels/test.tscn"),
|
|
72
|
+
allow_port_conflict: z
|
|
73
|
+
.boolean()
|
|
74
|
+
.optional()
|
|
75
|
+
.describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
|
|
76
|
+
"bridge will NOT be reachable — use only when you want the process for its side effects and will not " +
|
|
77
|
+
"call any runtime_* tool against it."),
|
|
68
78
|
},
|
|
69
|
-
}, async ({ scene }) => {
|
|
79
|
+
}, async ({ scene, allow_port_conflict }) => {
|
|
80
|
+
if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
|
|
81
|
+
return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
|
|
82
|
+
}
|
|
70
83
|
const args = ["--path", cfg.projectPath];
|
|
71
84
|
if (scene)
|
|
72
85
|
args.push(scene);
|
package/dist/tools/processes.js
CHANGED
|
@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
|
|
|
2
2
|
import { z } from "zod";
|
|
3
3
|
import { log } from "../logger.js";
|
|
4
4
|
import { ok } from "./lsp-common.js";
|
|
5
|
+
import { portFree, portConflictMessage } from "../ports.js";
|
|
5
6
|
const LINE_CAP = 5000;
|
|
6
7
|
/**
|
|
7
8
|
* Runs Godot as a MANAGED child (piped stdio) so the host captures ALL stdout/
|
|
@@ -12,11 +13,23 @@ const LINE_CAP = 5000;
|
|
|
12
13
|
export class ProcessRegistry {
|
|
13
14
|
procs = new Map();
|
|
14
15
|
counter = 0;
|
|
15
|
-
|
|
16
|
+
/**
|
|
17
|
+
* Spawn a managed Godot child. `env` is an OVERLAY on the inherited
|
|
18
|
+
* environment, not a replacement: omitted (the `godot_run_managed` path) the
|
|
19
|
+
* child inherits exactly as before, byte-identical to pre-F6 behaviour.
|
|
20
|
+
*
|
|
21
|
+
* The overlay is what makes multi-peer work at all — the runtime autoload
|
|
22
|
+
* reads `BREAKPOINT_RUNTIME_PORT` from its environment
|
|
23
|
+
* (`runtime_bridge.gd:74`), so N addressable peers is a per-child env
|
|
24
|
+
* passthrough plus a port allocator, with no protocol, transport or handshake
|
|
25
|
+
* change. See `peers.ts`.
|
|
26
|
+
*/
|
|
27
|
+
run(cfg, extraArgs, env) {
|
|
16
28
|
const id = `godot-${++this.counter}`;
|
|
17
29
|
const child = spawn(cfg.godotBin, ["--path", cfg.projectPath, ...extraArgs], {
|
|
18
30
|
cwd: cfg.projectPath,
|
|
19
31
|
stdio: ["ignore", "pipe", "pipe"],
|
|
32
|
+
...(env ? { env: { ...process.env, ...env } } : {}),
|
|
20
33
|
});
|
|
21
34
|
const m = { id, child, lines: [], seq: 0, exited: false, exitCode: null };
|
|
22
35
|
const ingest = (stream) => (buf) => {
|
|
@@ -43,6 +56,18 @@ export class ProcessRegistry {
|
|
|
43
56
|
get(id) {
|
|
44
57
|
return this.procs.get(id);
|
|
45
58
|
}
|
|
59
|
+
/**
|
|
60
|
+
* The last `n` captured lines for a managed child, newest last. Used to
|
|
61
|
+
* explain a peer that never bound its port — a project that fails to load
|
|
62
|
+
* dies with the reason on stderr, and without this the caller only ever sees
|
|
63
|
+
* "cannot reach the runtime bridge".
|
|
64
|
+
*/
|
|
65
|
+
tail(id, n = 12) {
|
|
66
|
+
const m = this.procs.get(id);
|
|
67
|
+
if (!m)
|
|
68
|
+
return [];
|
|
69
|
+
return m.lines.slice(-n).map((l) => l.text);
|
|
70
|
+
}
|
|
46
71
|
killAll() {
|
|
47
72
|
for (const m of this.procs.values()) {
|
|
48
73
|
try {
|
|
@@ -59,9 +84,23 @@ export function registerProcessTools(server, cfg) {
|
|
|
59
84
|
server.registerTool("godot_run_managed", {
|
|
60
85
|
title: "Run project (managed, captured output)",
|
|
61
86
|
description: "Run the project as a managed child process with captured stdout/stderr, so godot_output can read ALL print()/error output. " +
|
|
62
|
-
"Returns a process id. Use this instead of godot_run_project when you want the game's console log."
|
|
63
|
-
|
|
64
|
-
|
|
87
|
+
"Returns a process id. Use this instead of godot_run_project when you want the game's console log. " +
|
|
88
|
+
"Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
|
|
89
|
+
"runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
|
|
90
|
+
"than one game at once.",
|
|
91
|
+
inputSchema: {
|
|
92
|
+
scene: z.string().optional().describe("Optional res:// scene to run"),
|
|
93
|
+
allow_port_conflict: z
|
|
94
|
+
.boolean()
|
|
95
|
+
.optional()
|
|
96
|
+
.describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
|
|
97
|
+
"bridge will NOT be reachable — use only when you want the process for its console output or side " +
|
|
98
|
+
"effects and will not call any runtime_* tool against it."),
|
|
99
|
+
},
|
|
100
|
+
}, async ({ scene, allow_port_conflict }) => {
|
|
101
|
+
if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
|
|
102
|
+
return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
|
|
103
|
+
}
|
|
65
104
|
const m = registry.run(cfg, scene ? [scene] : []);
|
|
66
105
|
return ok({ id: m.id, pid: m.child.pid ?? null, running: true, scene: scene ?? null });
|
|
67
106
|
});
|