gdharness 1.1.29 → 1.1.31

package/build/cli.js

@@ -384,9 +384,18 @@ function readCommandLine(command) {
   return {
     executable,
     projectPath,
-    editor: words.some((word) => word === "-e" || word === "--editor")
+    editor: words.some((word) => word === "-e" || word === "--editor"),
+    oneShot: words.find((word) => ONE_SHOT_OPTIONS.includes(word)) ?? null
   };
 }
+async function oneShotOptionOf(pid) {
+  const tree = await processTree();
+  const listed = tree?.get(pid);
+  if (listed === undefined || listed.command === "") {
+    return;
+  }
+  return readCommandLine(listed.command).oneShot;
+}
 function commandWords(command) {
   const words = [];
   let word = "";
@@ -422,10 +431,31 @@ async function askPosix() {
   });
   return stdout;
 }
-var run, ASK_TIMEOUT_MS = 15000, lastListingFailure;
+var run, ASK_TIMEOUT_MS = 15000, lastListingFailure, ONE_SHOT_OPTIONS;
 var init_process_children = __esm(() => {
   init_windows_ask();
   run = promisify(execFile);
+  ONE_SHOT_OPTIONS = [
+    "--import",
+    "--quit",
+    "--quit-after",
+    "--export-release",
+    "--export-debug",
+    "--export-pack",
+    "--export-patch",
+    "--doctool",
+    "--gdscript-docs",
+    "--script",
+    "-s",
+    "--check-only",
+    "--build-solutions",
+    "--dump-gdextension-interface",
+    "--dump-extension-api",
+    "--dump-extension-api-with-docs",
+    "--validate-extension-api",
+    "--convert-3to4",
+    "--validate-conversion-3to4"
+  ];
 });
 
 // src/bridge-announce.ts
@@ -17617,7 +17647,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_status",
-      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. game.run names the run processActive is about, the one editor_output and editor_run stop answer for: its pid, its project, and adopted true when this server read it back from another server rather than starting it; null when there is none. editor.scan says whether the editor is scanning or importing and how many milliseconds ago its last scan finished (finishedMsAgo), or is null when it did not answer: the editor rewrites the class cache just after a scan, and editor_run waits that out before starting a game, saying so under waitedForEditorScanMs. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. Each game also says which runtime addon it loaded, under addonVersion (null when it cannot say); addonIsStale is true when that code is not what this server ships, and staleNote says whether the project needs gdharness upgrade, the game a restart, or this server a reconnect. A second checkout of a project, such as a git worktree, carries addons of its own and is where this shows. Every runtime_* answer from such a game carries addonIsStale and staleNote too. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. True beside restartUnderway is a restart still in progress, its server alive and within the wait for the old editor to go: the editor is coming, and opening another would put two on one project. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait. An editor that has connected and not yet greeted, which lasts a frame and longer while it imports, reports nothing about itself: greeting says so, addonIsStale is absent rather than guessed, and a restart asked then waits for the greeting to learn who opened it. startedByAnEditor is an editor another editor started, by Godot's own restart or the project manager, which has none of the arguments a server gave the one before it; startedByAnEditorNote says what that costs.",
+      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. game.run names the run processActive is about, the one editor_output and editor_run stop answer for: its pid, its project, and adopted true when this server read it back from another server rather than starting it; null when there is none. editor.scan says whether the editor is scanning or importing and how many milliseconds ago its last scan finished (finishedMsAgo), or is null when it did not answer: the editor rewrites the class cache just after a scan, and editor_run waits that out before starting a game, saying so under waitedForEditorScanMs. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. Each game also says which runtime addon it loaded, under addonVersion (null when it cannot say); addonIsStale is true when that code is not what this server ships, and staleNote says whether the project needs gdharness upgrade, the game a restart, or this server a reconnect. A second checkout of a project, such as a git worktree, carries addons of its own and is where this shows. Every runtime_* answer from such a game carries addonIsStale and staleNote too. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. True beside restartUnderway is a restart still in progress, its server alive and within the wait for the old editor to go: the editor is coming, and opening another would put two on one project. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait. An editor that has connected and not yet greeted, which lasts a frame and longer while it imports, reports nothing about itself: greeting says so, addonIsStale is absent rather than guessed, and a restart asked then waits for the greeting to learn who opened it. startedByAnEditor is an editor another editor started, by Godot's own restart or the project manager, which has none of the arguments a server gave the one before it; startedByAnEditorNote says what that costs. An engine run that loads the editor addon to do one job and quit, such as a gate's godot --headless --import, an export or a script, is not taken as the editor: a process that greets without a server's mark has its command line read first, and while that is read identifying is true and connected false; one started with such an option is turned away, and turnedAway names the last one, its pid and the option.",
       parameters: {},
       requires: []
     },
@@ -17841,7 +17871,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "runtime_capture",
-      description: "A picture of the running game: the whole screen or one viewport, as an image. The whole screen includes the game's own dialogs and popups where they sit, also when a project opens them as windows of their own (subwindows not embedded). Needs the game running with a window. A capture asked for before the game's first frame is drawn waits for that frame, since the game announces itself before it and the viewport holds nothing it drew until then.",
+      description: "A picture of the running game: the whole screen, one region or node of it at full resolution, or one viewport, as an image. The whole screen includes the game's own dialogs and popups where they sit, also when a project opens them as windows of their own (subwindows not embedded). Needs the game running with a window. A capture asked for before the game's first frame is drawn waits for that frame, since the game announces itself before it and the viewport holds nothing it drew until then.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         pid: RUNNING_PID,
@@ -17860,6 +17890,22 @@ var init_tool_definitions = __esm(() => {
           minimum: 1,
           description: "Scale the image to this height. Given alone, the width keeps the picture's proportions."
         },
+        region: {
+          type: "object",
+          ops: ["screenshot"],
+          description: "screenshot: capture only this rectangle of the window, at the game's own pixels: x, y, width and height in window pixels, or the window rectangle runtime_inspect rect answers, passed as it came. A region partly outside the window is cut to it and the answer says clipped; one wholly outside is refused. The answer names the region captured in window pixels, and drawnAt when the project draws at its own size and stretches that to the window, since the picture then has the game's pixels rather than the window's."
+        },
+        nodePath: {
+          type: "string",
+          ops: ["screenshot"],
+          description: "screenshot: capture only where this node is drawn, as runtime_inspect rect answers it: a Control's rectangle, what a 3D node's geometry covers, or what a Sprite2D draws. A node with a position and no extent is refused; give region around it instead. Not with region."
+        },
+        zoom: {
+          type: "integer",
+          minimum: 1,
+          maximum: 16,
+          description: "Enlarge the picture this many times, each pixel made a square of pixels rather than blended with its neighbours, so a thin line or a corner can be read. Not with width or height. Default 1."
+        },
         outputPath: {
           type: "string",
           description: "Also save the picture as a PNG at this absolute path, for somebody to open later; the answer says where. Refused unless it ends in .png, its directory exists, it is outside the project, and no file is there already."
@@ -37461,7 +37507,7 @@ function getDefaultBridge(ownProject = null) {
   defaultBridge ??= new GodotBridge(resolveDefaultBridgePort(), resolveDefaultBridgeHost(), DEFAULT_TIMEOUT_MS, ownProject);
   return defaultBridge;
 }
-var DEFAULT_PORT = 6505, DEFAULT_HOST = "127.0.0.1", DEFAULT_TIMEOUT_MS = 30000, KEEPALIVE_INTERVAL_MS = 1e4, SECOND_CONNECTION_CLOSE_CODE = 4000, OTHER_PROJECT_CLOSE_CODE = 4001, CONNECT_WINDOW_MS = 35000, GodotBridge, defaultBridge = null;
+var DEFAULT_PORT = 6505, DEFAULT_HOST = "127.0.0.1", DEFAULT_TIMEOUT_MS = 30000, KEEPALIVE_INTERVAL_MS = 1e4, SECOND_CONNECTION_CLOSE_CODE = 4000, OTHER_PROJECT_CLOSE_CODE = 4001, ONE_SHOT_CLOSE_CODE = 4002, CONNECT_WINDOW_MS = 35000, GodotBridge, defaultBridge = null;
 var init_godot_bridge = __esm(() => {
   init_wrapper();
   init_errors();
@@ -37474,6 +37520,9 @@ var init_godot_bridge = __esm(() => {
     socket = null;
     pingInterval = null;
     connectionInfo = null;
+    oneShotReader = null;
+    oneShots = new Map;
+    turnedAway = null;
     pendingRequests = new Map;
     resourceQueues = new Map;
     wantedPort;
@@ -37488,6 +37537,9 @@ var init_godot_bridge = __esm(() => {
       this.timeoutMs = timeoutMs;
       this.ownProject = ownProject;
     }
+    identifyEditorsWith(reader) {
+      this.oneShotReader = reader;
+    }
     get mayMove() {
       return this.ownProject !== null;
     }
@@ -37594,25 +37646,29 @@ var init_godot_bridge = __esm(() => {
       this.log("info", "WebSocket bridge stopped");
     }
     isConnected() {
-      return this.socket?.readyState === import_websocket.default.OPEN;
+      return this.socket?.readyState === import_websocket.default.OPEN && this.connectionInfo?.identifying !== true;
     }
     getStatus() {
+      const identifying = this.connectionInfo?.identifying === true;
+      const editor = identifying ? null : this.connectionInfo;
       return {
         host: this.host,
         port: this.port,
         connected: this.isConnected(),
-        projectPath: this.connectionInfo?.projectPath,
-        connectedAt: this.connectionInfo?.connectedAt,
-        lastPongAt: this.connectionInfo?.lastPongAt,
-        addonVersion: this.connectionInfo?.addonVersion,
-        addonDigest: this.connectionInfo?.addonDigest,
-        editorPid: this.connectionInfo?.editorPid,
-        lspPort: this.connectionInfo?.lspPort,
-        dapPort: this.connectionInfo?.dapPort,
-        debugPort: this.connectionInfo?.debugPort,
-        openedByAServer: this.connectionInfo?.openedByAServer,
-        startedByAnEditor: this.connectionInfo?.startedByAnEditor,
-        syncsBreakpoints: this.connectionInfo?.syncsBreakpoints,
+        projectPath: editor?.projectPath,
+        connectedAt: editor?.connectedAt,
+        lastPongAt: editor?.lastPongAt,
+        addonVersion: editor?.addonVersion,
+        addonDigest: editor?.addonDigest,
+        editorPid: editor?.editorPid,
+        lspPort: editor?.lspPort,
+        dapPort: editor?.dapPort,
+        debugPort: editor?.debugPort,
+        openedByAServer: editor?.openedByAServer,
+        startedByAnEditor: editor?.startedByAnEditor,
+        syncsBreakpoints: editor?.syncsBreakpoints,
+        turnedAway: this.turnedAway ?? undefined,
+        identifying: identifying ? true : undefined,
         pendingRequests: this.pendingRequests.size,
         queuedResources: this.resourceQueues.size,
         listeningSince: this.listeningSince ?? undefined,
@@ -37760,6 +37816,11 @@ var init_godot_bridge = __esm(() => {
             this.connectionInfo.startedByAnEditor = typeof message.started_by_an_editor === "boolean" ? message.started_by_an_editor : undefined;
             this.connectionInfo.syncsBreakpoints = typeof message.syncs_breakpoints === "boolean" ? message.syncs_breakpoints : undefined;
             this.log("info", `Godot ready: ${message.project_path}`);
+            const pid = this.connectionInfo.editorPid;
+            if (!this.connectionInfo.openedByAServer && pid !== undefined && this.oneShotReader !== null) {
+              this.identify(pid);
+              return;
+            }
             this.emitBridgeEvent("godot_connected", { projectPath: message.project_path });
           }
           return;
@@ -37850,6 +37911,45 @@ var init_godot_bridge = __esm(() => {
       this.stopKeepalive();
       stranger?.close(OTHER_PROJECT_CLOSE_CODE, said);
     }
+    identify(pid) {
+      const known = this.oneShots.get(pid);
+      if (known !== undefined) {
+        this.turnAway(pid, known);
+        return;
+      }
+      const info = this.connectionInfo;
+      const socket = this.socket;
+      const reader = this.oneShotReader;
+      if (info === null || reader === null) {
+        return;
+      }
+      info.identifying = true;
+      reader(pid).catch(() => {
+        return;
+      }).then((option) => {
+        if (this.socket !== socket || this.connectionInfo !== info) {
+          return;
+        }
+        if (typeof option === "string") {
+          this.oneShots.set(pid, option);
+          this.turnAway(pid, option);
+          return;
+        }
+        info.identifying = false;
+        this.log("info", `Godot editor identified: pid ${pid}`);
+        this.emitBridgeEvent("godot_connected", { projectPath: info.projectPath });
+      });
+    }
+    turnAway(pid, option) {
+      const said = `pid ${pid} was started with ${option}, which does one job and quits, so it is not an editor`;
+      this.log("info", `Turning away an engine run: ${said}`);
+      this.turnedAway = { pid, option, at: new Date };
+      const run = this.socket;
+      this.socket = null;
+      this.connectionInfo = null;
+      this.stopKeepalive();
+      run?.close(ONE_SHOT_CLOSE_CODE, said);
+    }
     handleDisconnect(disconnectedSocket, reason) {
       if (disconnectedSocket && this.socket && disconnectedSocket !== this.socket) {
         this.log("debug", "Ignoring stale Godot socket disconnect event");
@@ -39645,6 +39745,25 @@ function captureDestinationRefusal(outputPath, projects) {
   }
   return null;
 }
+function captureDetail(payload) {
+  const parts = [];
+  const region = payload["region"];
+  if (region !== null && typeof region === "object") {
+    const named = region;
+    const at = (key) => String(Math.round(Number(named[key]) * 100) / 100);
+    parts.push(`of the window region at ${at("x")},${at("y")}, ${at("width")}x${at("height")} window pixels${payload["clipped"] === true ? ", clipped to the window" : ""}`);
+  }
+  const drawnAt = payload["drawnAt"];
+  if (drawnAt !== null && typeof drawnAt === "object") {
+    const drawn = drawnAt;
+    parts.push(`at the game's own pixels: it draws at ${String(drawn["width"])}x${String(drawn["height"])} and stretches that to its window`);
+  }
+  if (typeof payload["zoom"] === "number") {
+    parts.push(`enlarged ${payload["zoom"]} times`);
+  }
+  const note = typeof payload["note"] === "string" ? `. ${payload["note"]}` : "";
+  return parts.length === 0 ? note : `, ${parts.join(", ")}${note}`;
+}
 function patienceForFrames(frames, atLeast) {
   return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
 }
@@ -40224,6 +40343,7 @@ class GodotServer {
   constructor() {
     this.ownProject = envValue("GDHARNESS_PROJECT") ?? null;
     this.godotBridge = getDefaultBridge(this.ownProject);
+    this.godotBridge.identifyEditorsWith(oneShotOptionOf);
     this.godotBridge.on("godot_connected", () => {
       this.settleTheLaunchReading();
     });
@@ -42483,6 +42603,10 @@ class GodotServer {
     const dap = portFromEnvOrNull("GDHARNESS_DAP_PORT") ?? await freePort(DEFAULT_DAP_PORT);
     return { lsp, dap };
   }
+  editorOnTheBridge() {
+    const pid = this.godotBridge.getStatus().editorPid;
+    return pid === undefined ? "the editor on this bridge" : `the editor on this bridge (pid ${pid})`;
+  }
   async handleRunProject(args, op) {
     const project = this.project(args);
     if (!project.ok) {
@@ -42490,7 +42614,7 @@ class GodotServer {
     }
     const open = this.godotBridge.isConnected() ? this.godotBridge.getStatus().projectPath : undefined;
     if (op !== "check" && open !== undefined && open !== "" && !isSameDirectory(open, project.value.path)) {
-      return this.createErrorResponse(`This start names ${project.value.path}, and the editor on this bridge has ${open} open.`, [
+      return this.createErrorResponse(`This start names ${project.value.path}, and ${this.editorOnTheBridge()} has ${open} open.`, [
         "editor_status names the project this server's editor is showing",
         "One server serves one editor: start a second server for the other project"
       ]);
@@ -44207,7 +44331,7 @@ class GodotServer {
     const open = this.godotBridge.getStatus().projectPath;
     const meant = readNonEmptyString(args, "projectPath");
     if (open !== undefined && open !== "" && meant !== undefined && !isSameDirectory(open, meant)) {
-      return this.createErrorResponse(`This call names ${meant}, and the editor on this bridge has ${open} open.`, [
+      return this.createErrorResponse(`This call names ${meant}, and ${this.editorOnTheBridge()} has ${open} open.`, [
         "editor_status names the project this server's editor is showing",
         "One server serves one editor: start a second server for the other project"
       ]);
@@ -44398,7 +44522,7 @@ ${staleNote}`);
         content: [
           {
             type: "text",
-            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${saveTo === null ? "" : `. Saved to ${saveTo}`}${staleNote === undefined ? "" : `
+            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${captureDetail(payload)}${saveTo === null ? "" : `. Saved to ${saveTo}`}${staleNote === undefined ? "" : `
 
 ${staleNote}`}`
           },

package/build/godot/addons/gdharness_editor/bridge_client.gd

@@ -25,6 +25,10 @@ const MAX_RECONNECT_DELAY: float = 30.0
 ## What a server closes with when the editor that said hello belongs to another project. Kept in
 ## step with `OTHER_PROJECT_CLOSE_CODE` in src/godot-bridge.ts.
 const ELSEWHERE_CLOSE_CODE: int = 4001
+## What a server closes with when this process is one job that quits, such as a gate's `--import`,
+## rather than an editor: dialling in again changes nothing for the rest of the run. Kept in step
+## with `ONE_SHOT_CLOSE_CODE` in src/godot-bridge.ts.
+const ONE_SHOT_CLOSE_CODE: int = 4002
 
 ## Where Godot keeps the three ports an editor serves. None of them is per editor: the settings
 ## file is one for every editor of this engine version on the machine, so two open at once want the
@@ -447,6 +451,8 @@ func _read_marker(path: String) -> String:
 func _handle_disconnect() -> void:
 	_is_connected = false
 	_said_elsewhere()
+	if socket.get_close_code() == ONE_SHOT_CLOSE_CODE:
+		_should_reconnect = false
 	disconnected.emit()
 
 	if _should_reconnect:

package/build/godot/addons/gdharness_runtime/runtime_autoload.gd

@@ -58,7 +58,7 @@ var _queries: Queries = Queries.new(self, values)
 var _changes: Changes = Changes.new(self, values)
 var _input: InputCommands = InputCommands.new(self, values)
 var _typing: Typing = Typing.new(self)
-var _capture: Capture = Capture.new(self)
+var _capture: Capture = Capture.new(self, values)
 var _waits: Waits = Waits.new(self, values)
 
 var _server: TCPServer

package/build/godot/addons/gdharness_runtime/runtime_capture.gd

@@ -4,12 +4,20 @@ extends RefCounted
 
 const Read = preload("reading.gd")
 const Values = preload("runtime_values.gd")
+const Queries = preload("runtime_queries.gd")
+const Screen = preload("runtime_screen.gd")
+
+## How far zoom enlarges at most. Sixteen makes a 3-pixel ring 48 pixels across, past any need to
+## see it, and a 200-pixel region 3200, past the size anybody reads a picture at.
+const ZOOM_MOST: int = 16
 
 var _host: Node
+var _values: Values
 
 
-func _init(host: Node) -> void:
+func _init(host: Node, values: Values) -> void:
 	_host = host
+	_values = values
 
 
 func capture_screenshot(params: Dictionary) -> Dictionary:
@@ -88,12 +96,155 @@ static func scaled_to(drawn: Vector2i, width: int, height: int) -> Vector2i:
 	return drawn
 
 
+## What part of the picture a capture is cut to and how far it is enlarged, from what was asked, or
+## a refusal saying what is wrong with the asking. Read before a frame is waited for, so a call that
+## cannot be answered costs no wait.
+##
+## A region and a node are asked for because width and height scale the whole picture, and a
+## question about a 3-pixel ring in a 1600-pixel window was answered by capturing the window, saving
+## it and cropping it with a script of the caller's own, three calls for every look.
+func _cut_asked(params: Dictionary, in_window: bool) -> Dictionary:
+	var region_given: Variant = params.get("region")
+	var node_path: String = str(params.get("nodePath", ""))
+	var zoom: int = Read.as_int(params.get("zoom", 1), 1)
+	var sized: bool = Read.as_int(params.get("width", 0)) > 0 or Read.as_int(params.get("height", 0)) > 0
+	if region_given != null and not node_path.is_empty():
+		return _refused("region and nodePath each name the part to capture; give one of them")
+	if (region_given != null or not node_path.is_empty()) and not in_window:
+		return _refused(
+			(
+				"region and nodePath are in the window's pixels, and this viewport's texture is in its "
+				+ "own: capture the screen with them, or this viewport whole"
+			)
+		)
+	if zoom < 1 or zoom > ZOOM_MOST:
+		return _refused("zoom is a whole factor from 1 to %d, and %d was asked for" % [ZOOM_MOST, zoom])
+	if zoom > 1 and sized:
+		return _refused(
+			(
+				"zoom enlarges by a whole factor and keeps every pixel square, and width and height "
+				+ "scale to a size; give one or the other"
+			)
+		)
+	var asked: Dictionary = {"zoom": zoom}
+	if region_given != null:
+		var region: Variant = region_of(_values, region_given)
+		if region == null:
+			var shape: String = (
+				"region is a rectangle in window pixels with an area: x, y, width and height, or the "
+				+ "window rectangle runtime_inspect rect answers, passed back as it came. %s is neither"
+			)
+			return _refused(shape % JSON.stringify(region_given))
+		asked["region"] = region
+	if not node_path.is_empty():
+		asked["node_path"] = node_path
+	return asked
+
+
+static func _refused(message: String) -> Dictionary:
+	return {"type": "error", "message": message}
+
+
+## The rectangle [param given] names: the four numbers x, y, width and height, or a rectangle as the
+## runtime answers one, its two corners tagged with their type, passed back as it came. Null when it
+## is neither or has no area.
+static func region_of(values: Values, given: Variant) -> Variant:
+	if not given is Dictionary:
+		return null
+	var fields: Dictionary = given
+	fields = fields.duplicate()
+	if not fields.has("_type"):
+		fields["_type"] = "Rect2"
+	var rebuilt: Variant = values.deserialize(fields)
+	var region: Rect2
+	if rebuilt is Rect2:
+		region = rebuilt
+	elif rebuilt is Rect2i:
+		var whole: Rect2i = rebuilt
+		region = Rect2(whole)
+	else:
+		return null
+	if not region.has_area():
+		return null
+	return region
+
+
+## Where [param node] is drawn, in window pixels, as runtime_inspect rect answers it: a Control's
+## rectangle, what a 3D node's geometry covers, or what a 2D node that knows its own rectangle draws.
+## A refusal's message when it has no extent on screen.
+static func drawn_rect_of(node: Node) -> Variant:
+	if node is Control:
+		var control: Control = node
+		return Screen.rect_in_window(
+			control.get_viewport(),
+			control.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, control.size)
+		)
+	if node is Node3D:
+		var spatial: Node3D = node
+		var found: Dictionary = Queries.in_frame(spatial)
+		if not found.has("rect"):
+			return "%s is not drawn by any current camera, so it covers nothing on screen" % node.get_path()
+		var covered: Rect2 = found["rect"]
+		return Screen.rect_in_window(spatial.get_viewport(), covered)
+	if node is Node2D and node.has_method("get_rect"):
+		var item: Node2D = node
+		var own: Rect2 = item.call("get_rect")
+		return Screen.rect_in_window(item.get_viewport(), item.get_global_transform_with_canvas() * own)
+	var no_extent: String = (
+		"%s is a %s, which has a position on screen and no extent; give region around the point "
+		+ "runtime_inspect rect answers for it"
+	)
+	return no_extent % [node.get_path(), node.get_class()]
+
+
+## [param region], in window pixels, as pixels of a picture drawn at [param drawn] in a window
+## [param window] pixels across: the same rectangle when the two match, scaled when the project draws
+## at its own size and stretches that to the window. Widened to whole pixels, so an edge falling
+## inside a pixel keeps that pixel, and cut to the picture. Without area when none of it is in it.
+static func in_picture(region: Rect2, window: Vector2i, drawn: Vector2i) -> Rect2i:
+	return widened(region, window, drawn).intersection(Rect2i(Vector2i.ZERO, drawn))
+
+
+## [param region] in the picture's pixels as [method in_picture] takes it, before it is cut to the
+## picture, which is what tells a region that was clipped from one that fitted.
+static func widened(region: Rect2, window: Vector2i, drawn: Vector2i) -> Rect2i:
+	var scale: Vector2 = Vector2.ONE
+	if window.x > 0 and window.y > 0:
+		scale = Vector2(drawn) / Vector2(window)
+	var start: Vector2 = (region.position * scale).floor()
+	var end: Vector2 = (region.end * scale).ceil()
+	return Rect2i(Vector2i(start), Vector2i(end - start))
+
+
+## [param picture], pixels of a picture drawn at [param drawn], as the window pixels it covers in a
+## window [param window] pixels across: what an answer names, since the region was asked for in them.
+static func in_window_pixels(picture: Rect2i, window: Vector2i, drawn: Vector2i) -> Dictionary:
+	var scale: Vector2 = Vector2.ONE
+	if drawn.x > 0 and drawn.y > 0 and window.x > 0 and window.y > 0:
+		scale = Vector2(window) / Vector2(drawn)
+	var start: Vector2 = Vector2(picture.position) * scale
+	var size: Vector2 = Vector2(picture.size) * scale
+	return {"x": start.x, "y": start.y, "width": size.x, "height": size.y}
+
+
+## [param image] cut to [param picture] and enlarged [param zoom] times, each pixel made a square of
+## them rather than blended with its neighbours, so a pixel in the answer is a pixel the game drew.
+static func cut(image: Image, picture: Rect2i, zoom: int) -> Image:
+	var part: Image = image.get_region(picture)
+	if zoom > 1:
+		part.resize(part.get_width() * zoom, part.get_height() * zoom, Image.INTERPOLATE_NEAREST)
+	return part
+
+
 ## The server names the file, so a game cannot point it at a path of its own choosing; a call
 ## with no path is a call the server did not make.
 func _capture(viewport: Viewport, params: Dictionary, with_windows: bool = false) -> Dictionary:
 	var requested_path: String = str(params.get("output_path", ""))
 	if requested_path.is_empty():
 		return {"type": "error", "message": "output_path required"}
+	var asked: Dictionary = _cut_asked(params, with_windows)
+	if asked.has("message"):
+		return asked
 
 	# Godot draws nothing to a minimised window and nothing at all without one, and the
 	# texture keeps whatever was drawn last. A capture then comes back byte for byte the same
@@ -127,12 +278,57 @@ func _capture(viewport: Viewport, params: Dictionary, with_windows: bool = false
 	if with_windows:
 		_lay_native_windows(image)
 
-	var drawn: Vector2i = Vector2i(image.get_width(), image.get_height())
-	var target: Vector2i = scaled_to(
-		drawn, Read.as_int(params.get("width", 0)), Read.as_int(params.get("height", 0))
-	)
-	if target != drawn:
-		image.resize(target.x, target.y)
+	var described: Dictionary = {}
+	var region: Variant = asked.get("region")
+	if asked.has("node_path"):
+		var node_path: String = asked["node_path"]
+		var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+		if standing.has("message"):
+			return standing
+		var node: Node = standing["node"]
+		var placed: Variant = drawn_rect_of(node)
+		if placed is String:
+			var why: String = placed
+			return _refused(why)
+		region = placed
+		# A hidden node's rectangle is still a place, and what is drawn there is whatever is behind it.
+		if not Queries.shown(node):
+			described["note"] = (
+				"%s is hidden, so this is what is drawn where it would be rather than the node" % node_path
+			)
+	if region != null:
+		var asked_region: Rect2 = region
+		var window: Vector2i = _host.get_tree().root.size
+		var picture_size: Vector2i = image.get_size()
+		var whole: Rect2i = widened(asked_region, window, picture_size)
+		var picture: Rect2i = whole.intersection(Rect2i(Vector2i.ZERO, picture_size))
+		if not picture.has_area():
+			return _refused(
+				(
+					"The region at %s, %s pixels across, is outside the window, which is %dx%d pixels"
+					% [asked_region.position, asked_region.size, window.x, window.y]
+				)
+			)
+		image = cut(image, picture, 1)
+		described["region"] = in_window_pixels(picture, window, picture_size)
+		if picture != whole:
+			described["clipped"] = true
+		# The project draws at its own size and stretches that to the window, so the picture's pixels
+		# are not the window's: said, because a caller sizing a region by window pixels gets fewer.
+		if picture_size != window:
+			described["drawnAt"] = {"width": picture_size.x, "height": picture_size.y}
+
+	var zoom: int = asked["zoom"]
+	if zoom > 1:
+		image = cut(image, Rect2i(Vector2i.ZERO, image.get_size()), zoom)
+		described["zoom"] = zoom
+	else:
+		var drawn: Vector2i = Vector2i(image.get_width(), image.get_height())
+		var target: Vector2i = scaled_to(
+			drawn, Read.as_int(params.get("width", 0)), Read.as_int(params.get("height", 0))
+		)
+		if target != drawn:
+			image.resize(target.x, target.y)
 
 	var screenshot_path: String = requested_path
 	if screenshot_path.begins_with("user://") or screenshot_path.begins_with("res://"):
@@ -141,10 +337,12 @@ func _capture(viewport: Viewport, params: Dictionary, with_windows: bool = false
 	if save_error != OK:
 		return {"type": "error", "message": "Failed to save screenshot as PNG: " + str(save_error)}
 
-	return {
+	var answer: Dictionary = {
 		"type": "screenshot_file",
 		"format": "png",
 		"width": image.get_width(),
 		"height": image.get_height(),
 		"path": screenshot_path
 	}
+	answer.merge(described)
+	return answer

package/build/index.js

@@ -25284,6 +25284,27 @@ function ancestorsIn(tree, pid, root) {
   }
   return chain;
 }
+var ONE_SHOT_OPTIONS = [
+  "--import",
+  "--quit",
+  "--quit-after",
+  "--export-release",
+  "--export-debug",
+  "--export-pack",
+  "--export-patch",
+  "--doctool",
+  "--gdscript-docs",
+  "--script",
+  "-s",
+  "--check-only",
+  "--build-solutions",
+  "--dump-gdextension-interface",
+  "--dump-extension-api",
+  "--dump-extension-api-with-docs",
+  "--validate-extension-api",
+  "--convert-3to4",
+  "--validate-conversion-3to4"
+];
 function readCommandLine(command) {
   const all = commandWords(command);
   const separator = all.findIndex((word) => word === "--" || word === "++");
@@ -25304,9 +25325,18 @@ function readCommandLine(command) {
   return {
     executable,
     projectPath,
-    editor: words.some((word) => word === "-e" || word === "--editor")
+    editor: words.some((word) => word === "-e" || word === "--editor"),
+    oneShot: words.find((word) => ONE_SHOT_OPTIONS.includes(word)) ?? null
   };
 }
+async function oneShotOptionOf(pid) {
+  const tree = await processTree();
+  const listed = tree?.get(pid);
+  if (listed === undefined || listed.command === "") {
+    return;
+  }
+  return readCommandLine(listed.command).oneShot;
+}
 function commandWords(command) {
   const words = [];
   let word = "";
@@ -27664,6 +27694,7 @@ var DEFAULT_TIMEOUT_MS = 30000;
 var KEEPALIVE_INTERVAL_MS = 1e4;
 var SECOND_CONNECTION_CLOSE_CODE = 4000;
 var OTHER_PROJECT_CLOSE_CODE = 4001;
+var ONE_SHOT_CLOSE_CODE = 4002;
 function resolveDefaultBridgePort() {
   return portFromEnv("GDHARNESS_BRIDGE_PORT", DEFAULT_PORT);
 }
@@ -27695,6 +27726,9 @@ class GodotBridge extends EventEmitter {
   socket = null;
   pingInterval = null;
   connectionInfo = null;
+  oneShotReader = null;
+  oneShots = new Map;
+  turnedAway = null;
   pendingRequests = new Map;
   resourceQueues = new Map;
   wantedPort;
@@ -27709,6 +27743,9 @@ class GodotBridge extends EventEmitter {
     this.timeoutMs = timeoutMs;
     this.ownProject = ownProject;
   }
+  identifyEditorsWith(reader) {
+    this.oneShotReader = reader;
+  }
   get mayMove() {
     return this.ownProject !== null;
   }
@@ -27815,25 +27852,29 @@ class GodotBridge extends EventEmitter {
     this.log("info", "WebSocket bridge stopped");
   }
   isConnected() {
-    return this.socket?.readyState === import_websocket.default.OPEN;
+    return this.socket?.readyState === import_websocket.default.OPEN && this.connectionInfo?.identifying !== true;
   }
   getStatus() {
+    const identifying = this.connectionInfo?.identifying === true;
+    const editor = identifying ? null : this.connectionInfo;
     return {
       host: this.host,
       port: this.port,
       connected: this.isConnected(),
-      projectPath: this.connectionInfo?.projectPath,
-      connectedAt: this.connectionInfo?.connectedAt,
-      lastPongAt: this.connectionInfo?.lastPongAt,
-      addonVersion: this.connectionInfo?.addonVersion,
-      addonDigest: this.connectionInfo?.addonDigest,
-      editorPid: this.connectionInfo?.editorPid,
-      lspPort: this.connectionInfo?.lspPort,
-      dapPort: this.connectionInfo?.dapPort,
-      debugPort: this.connectionInfo?.debugPort,
-      openedByAServer: this.connectionInfo?.openedByAServer,
-      startedByAnEditor: this.connectionInfo?.startedByAnEditor,
-      syncsBreakpoints: this.connectionInfo?.syncsBreakpoints,
+      projectPath: editor?.projectPath,
+      connectedAt: editor?.connectedAt,
+      lastPongAt: editor?.lastPongAt,
+      addonVersion: editor?.addonVersion,
+      addonDigest: editor?.addonDigest,
+      editorPid: editor?.editorPid,
+      lspPort: editor?.lspPort,
+      dapPort: editor?.dapPort,
+      debugPort: editor?.debugPort,
+      openedByAServer: editor?.openedByAServer,
+      startedByAnEditor: editor?.startedByAnEditor,
+      syncsBreakpoints: editor?.syncsBreakpoints,
+      turnedAway: this.turnedAway ?? undefined,
+      identifying: identifying ? true : undefined,
       pendingRequests: this.pendingRequests.size,
       queuedResources: this.resourceQueues.size,
       listeningSince: this.listeningSince ?? undefined,
@@ -27981,6 +28022,11 @@ class GodotBridge extends EventEmitter {
           this.connectionInfo.startedByAnEditor = typeof message.started_by_an_editor === "boolean" ? message.started_by_an_editor : undefined;
           this.connectionInfo.syncsBreakpoints = typeof message.syncs_breakpoints === "boolean" ? message.syncs_breakpoints : undefined;
           this.log("info", `Godot ready: ${message.project_path}`);
+          const pid = this.connectionInfo.editorPid;
+          if (!this.connectionInfo.openedByAServer && pid !== undefined && this.oneShotReader !== null) {
+            this.identify(pid);
+            return;
+          }
           this.emitBridgeEvent("godot_connected", { projectPath: message.project_path });
         }
         return;
@@ -28071,6 +28117,45 @@ class GodotBridge extends EventEmitter {
     this.stopKeepalive();
     stranger?.close(OTHER_PROJECT_CLOSE_CODE, said);
   }
+  identify(pid) {
+    const known = this.oneShots.get(pid);
+    if (known !== undefined) {
+      this.turnAway(pid, known);
+      return;
+    }
+    const info = this.connectionInfo;
+    const socket = this.socket;
+    const reader = this.oneShotReader;
+    if (info === null || reader === null) {
+      return;
+    }
+    info.identifying = true;
+    reader(pid).catch(() => {
+      return;
+    }).then((option) => {
+      if (this.socket !== socket || this.connectionInfo !== info) {
+        return;
+      }
+      if (typeof option === "string") {
+        this.oneShots.set(pid, option);
+        this.turnAway(pid, option);
+        return;
+      }
+      info.identifying = false;
+      this.log("info", `Godot editor identified: pid ${pid}`);
+      this.emitBridgeEvent("godot_connected", { projectPath: info.projectPath });
+    });
+  }
+  turnAway(pid, option) {
+    const said = `pid ${pid} was started with ${option}, which does one job and quits, so it is not an editor`;
+    this.log("info", `Turning away an engine run: ${said}`);
+    this.turnedAway = { pid, option, at: new Date };
+    const run = this.socket;
+    this.socket = null;
+    this.connectionInfo = null;
+    this.stopKeepalive();
+    run?.close(ONE_SHOT_CLOSE_CODE, said);
+  }
   handleDisconnect(disconnectedSocket, reason) {
     if (disconnectedSocket && this.socket && disconnectedSocket !== this.socket) {
       this.log("debug", "Ignoring stale Godot socket disconnect event");
@@ -31601,7 +31686,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_status",
-    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. game.run names the run processActive is about, the one editor_output and editor_run stop answer for: its pid, its project, and adopted true when this server read it back from another server rather than starting it; null when there is none. editor.scan says whether the editor is scanning or importing and how many milliseconds ago its last scan finished (finishedMsAgo), or is null when it did not answer: the editor rewrites the class cache just after a scan, and editor_run waits that out before starting a game, saying so under waitedForEditorScanMs. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. Each game also says which runtime addon it loaded, under addonVersion (null when it cannot say); addonIsStale is true when that code is not what this server ships, and staleNote says whether the project needs gdharness upgrade, the game a restart, or this server a reconnect. A second checkout of a project, such as a git worktree, carries addons of its own and is where this shows. Every runtime_* answer from such a game carries addonIsStale and staleNote too. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. True beside restartUnderway is a restart still in progress, its server alive and within the wait for the old editor to go: the editor is coming, and opening another would put two on one project. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait. An editor that has connected and not yet greeted, which lasts a frame and longer while it imports, reports nothing about itself: greeting says so, addonIsStale is absent rather than guessed, and a restart asked then waits for the greeting to learn who opened it. startedByAnEditor is an editor another editor started, by Godot's own restart or the project manager, which has none of the arguments a server gave the one before it; startedByAnEditorNote says what that costs.",
+    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. game.run names the run processActive is about, the one editor_output and editor_run stop answer for: its pid, its project, and adopted true when this server read it back from another server rather than starting it; null when there is none. editor.scan says whether the editor is scanning or importing and how many milliseconds ago its last scan finished (finishedMsAgo), or is null when it did not answer: the editor rewrites the class cache just after a scan, and editor_run waits that out before starting a game, saying so under waitedForEditorScanMs. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. Each game also says which runtime addon it loaded, under addonVersion (null when it cannot say); addonIsStale is true when that code is not what this server ships, and staleNote says whether the project needs gdharness upgrade, the game a restart, or this server a reconnect. A second checkout of a project, such as a git worktree, carries addons of its own and is where this shows. Every runtime_* answer from such a game carries addonIsStale and staleNote too. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. True beside restartUnderway is a restart still in progress, its server alive and within the wait for the old editor to go: the editor is coming, and opening another would put two on one project. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait. An editor that has connected and not yet greeted, which lasts a frame and longer while it imports, reports nothing about itself: greeting says so, addonIsStale is absent rather than guessed, and a restart asked then waits for the greeting to learn who opened it. startedByAnEditor is an editor another editor started, by Godot's own restart or the project manager, which has none of the arguments a server gave the one before it; startedByAnEditorNote says what that costs. An engine run that loads the editor addon to do one job and quit, such as a gate's godot --headless --import, an export or a script, is not taken as the editor: a process that greets without a server's mark has its command line read first, and while that is read identifying is true and connected false; one started with such an option is turned away, and turnedAway names the last one, its pid and the option.",
     parameters: {},
     requires: []
   },
@@ -31825,7 +31910,7 @@ var TOOL_SPECS = [
   },
   {
     name: "runtime_capture",
-    description: "A picture of the running game: the whole screen or one viewport, as an image. The whole screen includes the game's own dialogs and popups where they sit, also when a project opens them as windows of their own (subwindows not embedded). Needs the game running with a window. A capture asked for before the game's first frame is drawn waits for that frame, since the game announces itself before it and the viewport holds nothing it drew until then.",
+    description: "A picture of the running game: the whole screen, one region or node of it at full resolution, or one viewport, as an image. The whole screen includes the game's own dialogs and popups where they sit, also when a project opens them as windows of their own (subwindows not embedded). Needs the game running with a window. A capture asked for before the game's first frame is drawn waits for that frame, since the game announces itself before it and the viewport holds nothing it drew until then.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       pid: RUNNING_PID,
@@ -31844,6 +31929,22 @@ var TOOL_SPECS = [
         minimum: 1,
         description: "Scale the image to this height. Given alone, the width keeps the picture's proportions."
       },
+      region: {
+        type: "object",
+        ops: ["screenshot"],
+        description: "screenshot: capture only this rectangle of the window, at the game's own pixels: x, y, width and height in window pixels, or the window rectangle runtime_inspect rect answers, passed as it came. A region partly outside the window is cut to it and the answer says clipped; one wholly outside is refused. The answer names the region captured in window pixels, and drawnAt when the project draws at its own size and stretches that to the window, since the picture then has the game's pixels rather than the window's."
+      },
+      nodePath: {
+        type: "string",
+        ops: ["screenshot"],
+        description: "screenshot: capture only where this node is drawn, as runtime_inspect rect answers it: a Control's rectangle, what a 3D node's geometry covers, or what a Sprite2D draws. A node with a position and no extent is refused; give region around it instead. Not with region."
+      },
+      zoom: {
+        type: "integer",
+        minimum: 1,
+        maximum: 16,
+        description: "Enlarge the picture this many times, each pixel made a square of pixels rather than blended with its neighbours, so a thin line or a corner can be read. Not with width or height. Default 1."
+      },
       outputPath: {
         type: "string",
         description: "Also save the picture as a PNG at this absolute path, for somebody to open later; the answer says where. Refused unless it ends in .png, its directory exists, it is outside the project, and no file is there already."
@@ -32161,6 +32262,25 @@ function captureDestinationRefusal(outputPath, projects) {
   }
   return null;
 }
+function captureDetail(payload) {
+  const parts = [];
+  const region = payload["region"];
+  if (region !== null && typeof region === "object") {
+    const named = region;
+    const at = (key) => String(Math.round(Number(named[key]) * 100) / 100);
+    parts.push(`of the window region at ${at("x")},${at("y")}, ${at("width")}x${at("height")} window pixels${payload["clipped"] === true ? ", clipped to the window" : ""}`);
+  }
+  const drawnAt = payload["drawnAt"];
+  if (drawnAt !== null && typeof drawnAt === "object") {
+    const drawn = drawnAt;
+    parts.push(`at the game's own pixels: it draws at ${String(drawn["width"])}x${String(drawn["height"])} and stretches that to its window`);
+  }
+  if (typeof payload["zoom"] === "number") {
+    parts.push(`enlarged ${payload["zoom"]} times`);
+  }
+  const note = typeof payload["note"] === "string" ? `. ${payload["note"]}` : "";
+  return parts.length === 0 ? note : `, ${parts.join(", ")}${note}`;
+}
 function patienceForFrames(frames, atLeast) {
   return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
 }
@@ -32804,6 +32924,7 @@ class GodotServer {
   constructor() {
     this.ownProject = envValue("GDHARNESS_PROJECT") ?? null;
     this.godotBridge = getDefaultBridge(this.ownProject);
+    this.godotBridge.identifyEditorsWith(oneShotOptionOf);
     this.godotBridge.on("godot_connected", () => {
       this.settleTheLaunchReading();
     });
@@ -35063,6 +35184,10 @@ class GodotServer {
     const dap = portFromEnvOrNull("GDHARNESS_DAP_PORT") ?? await freePort(DEFAULT_DAP_PORT);
     return { lsp, dap };
   }
+  editorOnTheBridge() {
+    const pid = this.godotBridge.getStatus().editorPid;
+    return pid === undefined ? "the editor on this bridge" : `the editor on this bridge (pid ${pid})`;
+  }
   async handleRunProject(args, op) {
     const project = this.project(args);
     if (!project.ok) {
@@ -35070,7 +35195,7 @@ class GodotServer {
     }
     const open = this.godotBridge.isConnected() ? this.godotBridge.getStatus().projectPath : undefined;
     if (op !== "check" && open !== undefined && open !== "" && !isSameDirectory(open, project.value.path)) {
-      return this.createErrorResponse(`This start names ${project.value.path}, and the editor on this bridge has ${open} open.`, [
+      return this.createErrorResponse(`This start names ${project.value.path}, and ${this.editorOnTheBridge()} has ${open} open.`, [
         "editor_status names the project this server's editor is showing",
         "One server serves one editor: start a second server for the other project"
       ]);
@@ -36787,7 +36912,7 @@ class GodotServer {
     const open = this.godotBridge.getStatus().projectPath;
     const meant = readNonEmptyString(args, "projectPath");
     if (open !== undefined && open !== "" && meant !== undefined && !isSameDirectory(open, meant)) {
-      return this.createErrorResponse(`This call names ${meant}, and the editor on this bridge has ${open} open.`, [
+      return this.createErrorResponse(`This call names ${meant}, and ${this.editorOnTheBridge()} has ${open} open.`, [
         "editor_status names the project this server's editor is showing",
         "One server serves one editor: start a second server for the other project"
       ]);
@@ -36978,7 +37103,7 @@ ${staleNote}`);
         content: [
           {
             type: "text",
-            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${saveTo === null ? "" : `. Saved to ${saveTo}`}${staleNote === undefined ? "" : `
+            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${captureDetail(payload)}${saveTo === null ? "" : `. Saved to ${saveTo}`}${staleNote === undefined ? "" : `
 
 ${staleNote}`}`
           },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.1.29",
+  "version": "1.1.31",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",