gdharness 1.0.0 → 1.0.2

package/README.md

@@ -26,9 +26,8 @@ property reads right now, what the console printed, what broke and on which line
 Hand this to your agent:
 
 ```text
-Install gdharness into this project by following
-https://aureliolo.github.io/gdharness/agent.md, then tell me what it asked you to
-recommend back to me.
+Install gdharness here by following https://aureliolo.github.io/gdharness/agent.md,
+then tell me what it asked you to recommend back to me.
 ```
 
 Or do it yourself, and pick your harness:

package/build/cli.js

@@ -7673,6 +7673,9 @@ function cacheWrittenAt(projectPath) {
     return null;
   }
 }
+function cachedAtMissingPaths(cached, projectPath) {
+  return [...cached].filter(([, path]) => path.startsWith("res://") && !existsSync6(join6(projectPath, path.slice("res://".length)))).map(([name]) => name).sort();
+}
 function staleAgainst(cached, projectPath) {
   return [...declaredClasses(projectPath)].filter(([name, path]) => cached.get(name) !== path).map(([name]) => name);
 }
@@ -16084,7 +16087,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_rescan",
-      description: "Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure is this call on its own, with no change to the declaring script: measured against a real editor on three platforms, with idle waits of the same length ruled out so the scan is credited rather than the time it takes, and reproduced in a second project against its own reproduction in 203ms. editor_launch restart also does it and costs a window, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve goes out of that file with it. That is not a reason to refuse the scan, because on a class the editor has merely not walked yet the scan is the cure; what the answer does instead is name the loss under cacheLost and rebuild the cache from the files, naming what came back under cacheRestored, so no fresh engine, CI run or clone inherits the short file. An editor that lost classes is still holding the short list, so the note says to restart it before scanning again. Needs the editor connected.",
+      description: "Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure is this call on its own, with no change to the declaring script: measured against a real editor on three platforms, with idle waits of the same length ruled out so the scan is credited rather than the time it takes, and reproduced in a second project against its own reproduction in 203ms. editor_launch restart also does it and costs a window, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve goes out of that file with it. That is not a reason to refuse the scan, because on a class the editor has merely not walked yet the scan is the cure; what the answer does instead is name the loss under cacheLost and rebuild the cache from the files, naming what came back under cacheRestored, so no fresh engine, CI run or clone inherits the short file. An editor that lost classes is still holding the short list, so the note says to restart it before scanning again. The other direction is guarded the same way: a class the editor still holds for a script that was renamed or deleted comes back into the cache at a path that is not there, and the next engine to read it fails on \"Could not parse global class\" in whichever correct script shares the bare name, so the cache is rebuilt without it and the answer names it under cacheDropped; the editor goes on holding it until it is restarted, and every scan until then ends in that rebuild. A script or shader written outside the editor has no .uid sidecar until something imports it, and the scan writes one beside it, which a project that commits sidecars needs before the commit. Needs the editor connected.",
       parameters: {
         projectPath: PROJECT_PATH,
         timeoutMs: { type: "number", description: "How long to wait for the scan. Default 30000." },
@@ -16120,12 +16123,20 @@ var init_tool_definitions = __esm(() => {
         },
         instantiableOnly: { type: "boolean", description: "query: leave out abstract classes. Default false." },
         className: { type: "string", description: "info, inheritance: the class." },
-        includeInherited: { type: "boolean", description: "info: include inherited members. Default false." }
+        includeInherited: { type: "boolean", description: "info: include inherited members. Default false." },
+        member: {
+          type: "string",
+          ops: ["info"],
+          description: 'info: one member by name, a method, property, signal, enum or constant, with its signature and which class declares it, looked for on the class and every ancestor. The whole of Control is seventy thousand characters; the question "does this engine have it, and what does it take" is this. A name nothing declares is refused with the members whose names contain it.'
+        }
       },
       requires: ["projectPath"],
       operations: {
         query: { summary: "classes matching a filter or category", requires: [] },
-        info: { summary: "methods, properties, signals and enums of one class", requires: ["className"] },
+        info: {
+          summary: "methods, properties, signals and enums of one class, or one member of it by name",
+          requires: ["className"]
+        },
         inheritance: { summary: "ancestors and descendants of one class", requires: ["className"] }
       },
       defaultOperation: "query"
@@ -16150,7 +16161,13 @@ var init_tool_definitions = __esm(() => {
         includeProperties: {
           type: "boolean",
           ops: ["tree"],
-          description: "tree: include each node's properties. Default false."
+          description: "tree: include every stored property of each node. Default false, and one row of a form answered seventy-six thousand characters with it; properties names the few that are wanted."
+        },
+        properties: {
+          type: "array",
+          items: { type: "string" },
+          ops: ["tree"],
+          description: "tree: the properties to read off each node, by name, so the text of every label and button under a panel is one call: a node that has not got one leaves it out. Colons read through what a node holds, as property does for find."
         },
         className: {
           type: "string",
@@ -16339,12 +16356,12 @@ var init_tool_definitions = __esm(() => {
         relativeX: {
           type: "number",
           ops: ["mouse_motion"],
-          description: "mouse_motion: movement since the last event."
+          description: "mouse_motion: the movement the event carries. Left out, it is the distance from where the last injected pointer event put the pointer, and none for the first; that is what a control that drags reads. Give it to send a motion the position does not show."
         },
         relativeY: {
           type: "number",
           ops: ["mouse_motion"],
-          description: "mouse_motion: movement since the last event."
+          description: "mouse_motion: as relativeX."
         }
       },
       requires: [],
@@ -16358,13 +16375,22 @@ var init_tool_definitions = __esm(() => {
           requires: ["nodePath"]
         },
         action: { summary: "press an action, or hold it", requires: ["action"] },
-        key: { summary: "press a key, or hold it", requires: ["keycode"] },
+        key: {
+          summary: "press a key, or hold it. Not for a menu a click has opened: an OptionButton or PopupMenu pops up as a window of its own that a key sent to the game never reaches, so an arrow moves nothing in it and Enter closes it with nothing chosen. choose is what selects there. The limit is that menu's own navigation, not windows in general: an embedded dialog whose owner reads keys in _input gets them, and a binding catcher up in one takes the key first time",
+          requires: ["keycode"]
+        },
         text: {
           summary: "type a string into the field being edited, a character at a time, and say what it landed in",
           requires: ["text"]
         },
-        mouse_click: { summary: "one mouse button event at a position", requires: ["x", "y"] },
-        mouse_motion: { summary: "move the mouse to a position", requires: ["x", "y"] }
+        mouse_click: {
+          summary: "one mouse button event at a position, carrying the buttons held once it has happened. A drag is a press held with pressed true, motions, and a release with pressed false",
+          requires: ["x", "y"]
+        },
+        mouse_motion: {
+          summary: "move the mouse to a position, carrying the distance from where the last injected event put it unless relativeX and relativeY say otherwise, and the buttons held, so a control that drags moves under a run of these between a held mouse_click and its release",
+          requires: ["x", "y"]
+        }
       }
     },
     {
@@ -16385,7 +16411,12 @@ var init_tool_definitions = __esm(() => {
         says: {
           type: "string",
           ops: ["until"],
-          description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, hidden nodes included; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+          description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+        },
+        includeHidden: {
+          type: "boolean",
+          ops: ["until"],
+          description: "until, with says: count words on a hidden node too. Default false, since a wait for words is a wait for them to be shown: a button that exists hidden through a whole animation carries its words the whole time and satisfied the wait at once, and every wait on that screen fell back to counting frames."
         },
         timeoutMs: {
           type: "number",
@@ -37449,13 +37480,16 @@ function stillRunning(run) {
   }
   return true;
 }
-function runIsUp(run, editorSays) {
+function runIsUp(run, editorSays, now = Date.now()) {
   if (run?.throughEditor !== true) {
     return stillRunning(run);
   }
   if (run.announcedPid !== undefined && !alive(run.announcedPid)) {
     return false;
   }
+  if (editorSays === false && run.seenPlaying !== true && now - run.startedAt < PLAY_STARTS_WITHIN_MS) {
+    return true;
+  }
   return editorSays ?? stillRunning(run);
 }
 function endedPreviousRun(ended) {
@@ -37529,10 +37563,11 @@ function runtimeVerdict(endpoint, after) {
       heldAt: after.heldAt
     };
   }
+  const state = after.playingSeen === false ? "the editor has not yet reported the game as playing, which a restarted editor does not until its scan is over" : "the game is still running";
   return {
     listening: false,
     mayYetAnnounce: after.running,
-    note: after.running ? `nothing announced itself within ${after.budgetMs}ms and the game is still running, so it may announce a moment from now: editor_status says whether it has, and editor_run start takes runtimeWaitMs to wait longer than this${after.withArgs ? ", which a run carrying its own arguments may well need, since whatever they ask the game to do before its first frame is inside this wait" : ""}` : `nothing announced itself within ${after.budgetMs}ms and the game is no longer running, so nothing is going to: editor_output has what it printed on the way down`,
+    note: after.running ? `nothing announced itself within ${after.budgetMs}ms and ${state}, so it may announce a moment from now: editor_status says whether it has, and editor_run start takes runtimeWaitMs to wait longer than this${after.withArgs ? ", which a run carrying its own arguments may well need, since whatever they ask the game to do before its first frame is inside this wait" : ""}` : `nothing announced itself within ${after.budgetMs}ms and the game is no longer running, so nothing is going to: editor_output has what it printed on the way down`,
     heldAt: null
   };
 }
@@ -38221,7 +38256,8 @@ class GodotServer {
               ...whichGame(args),
               root: readNonEmptyString(args, "nodePath") ?? "/root",
               depth: readPositiveNumber(args, "depth") ?? 3,
-              include_properties: readBoolean(args, "includeProperties") ?? false
+              include_properties: readBoolean(args, "includeProperties") ?? false,
+              properties: readArray(args, "properties") ?? []
             });
           case "find":
             return await this.handleFindRuntimeNodes(args);
@@ -39436,7 +39472,8 @@ class GodotServer {
       budgetMs,
       heldAt: this.dapClient?.whereItStopped() ?? null,
       running: endpoint !== null || going !== null && await this.runStillGoing(going),
-      withArgs
+      withArgs,
+      ...going?.throughEditor === true ? { playingSeen: going.seenPlaying === true } : {}
     });
   }
   async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
@@ -39466,6 +39503,7 @@ class GodotServer {
     const startedAt = Date.now();
     const transcript = openTranscript(startedAt);
     closeSync(transcript.fd);
+    const playAnswer = asParams(JSON.parse(answer.content[0]?.text ?? "{}"));
     const played = {
       process: null,
       pid: null,
@@ -39477,7 +39515,8 @@ class GodotServer {
       exitCode: null,
       throughEditor: true,
       brokeOn: null,
-      announcedBefore: alreadyPlaying
+      announcedBefore: alreadyPlaying,
+      seenPlaying: readBoolean(playAnswer, "playing") === true
     };
     this.activeProcess = played;
     writeEditorRunNote({ projectPath, transcript: transcript.path, startedAt });
@@ -39487,7 +39526,7 @@ class GodotServer {
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
-      debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
+      debugPort: readNumber(playAnswer, "debugPort"),
       endedPreviousRun: endedPreviousRun(ended),
       breakpoints: breakpoints.applied.length === 0 ? undefined : this.breakpointsAsProjectSpells(projectPath, breakpoints.applied),
       breakpointsRefused: breakpoints.refused.length === 0 ? undefined : breakpoints.refused.map((one) => ({
@@ -40013,7 +40052,11 @@ class GodotServer {
     if (announced !== undefined && editorSays === undefined) {
       return stillRunning(run);
     }
-    return runIsUp(run, editorSays === undefined ? (await this.editorPlayingState())?.playing ?? null : editorSays);
+    const said = editorSays === undefined ? (await this.editorPlayingState())?.playing ?? null : editorSays;
+    if (said === true) {
+      run.seenPlaying = true;
+    }
+    return runIsUp(run, said);
   }
   async handleGetDebugOutput(args, waitedMs) {
     await this.pickUpWhatTheEditorIsPlaying();
@@ -40196,6 +40239,7 @@ class GodotServer {
     const writtenBefore = projectPath === "" ? null : cacheWrittenAt(projectPath);
     const blind = await this.classesTheEditorCannotSee(args);
     const atRisk = before === null ? [] : blind.unseen.filter((one) => before.has(one.className));
+    const ghosts = blind.stillHeld ?? [];
     const first = await this.handleViaBridge("rescan_filesystem", args);
     if (first.isError) {
       return first;
@@ -40207,7 +40251,7 @@ class GodotServer {
       const pending = Boolean(status["pending"]) && Date.now() - started < SCAN_START_MS;
       busy = Boolean(status["scanning"]) || Boolean(status["importing"]) || pending;
     }
-    if (!busy && projectPath !== "" && (atRisk.length > 0 || blind.unchecked !== undefined)) {
+    if (!busy && projectPath !== "" && (atRisk.length > 0 || ghosts.length > 0 || blind.unchecked !== undefined)) {
       const until = Date.now() + CACHE_WRITE_MS;
       while (Date.now() < until && cacheWrittenAt(projectPath) === writtenBefore) {
         await new Promise((settle) => setTimeout(settle, 100));
@@ -40215,7 +40259,11 @@ class GodotServer {
     }
     const after = projectPath === "" || busy ? null : cachedClasses(projectPath);
     const lost = before === null || after === null ? [] : [...before.keys()].filter((name) => !after.has(name));
-    const restored = lost.length > 0 ? await this.rebuildCacheAfterLoss(projectPath, lost) : [];
+    const atMissingPaths = after === null ? [] : cachedAtMissingPaths(after, projectPath);
+    const restored = lost.length > 0 || atMissingPaths.length > 0 ? await this.rebuildCacheAfterLoss(projectPath, lost) : [];
+    const rebuilt = atMissingPaths.length > 0 ? cachedClasses(projectPath) : null;
+    const dropped = rebuilt === null ? [] : atMissingPaths.filter((name) => !cachedAtMissingPaths(rebuilt, projectPath).includes(name));
+    const stillAtMissingPaths = atMissingPaths.filter((name) => !dropped.includes(name));
     const reloading = readNonEmptyString(args, "reloadScript");
     let reloaded = {};
     if (reloading !== undefined) {
@@ -40231,8 +40279,23 @@ class GodotServer {
     const checked = busy ? { unseen: [] } : await this.classesTheEditorCannotSee(args);
     const unseen = checked.unseen;
     const stillGone = lost.filter((name) => !restored.includes(name));
+    const notes = [];
+    if (busy) {
+      notes.push("The editor was still scanning or importing when the wait ran out, so new files may not be visible yet.");
+    } else if (stillGone.length > 0) {
+      notes.push("The scan wrote the class cache from the list this editor is holding, that list is shorter than the file was, and rebuilding the cache from the files did not bring these back. Every engine that reads the cache next, including a test run, will report them as unknown identifiers. Restart the editor with editor_launch restart before scanning again.");
+    } else if (lost.length > 0) {
+      notes.push("The scan wrote the class cache from the list this editor is holding, which is shorter than the file was, so the cache was rebuilt from the files and these classes are back in it. Nothing was lost, but this editor is still holding the short list: do not rescan again until it has been restarted with editor_launch restart, because it will write the same list over the file each time.");
+    } else if (unseen.length > 0) {
+      notes.push("The scan finished and these classes are still not in the list the editor resolves against, so every use of them reads as an unknown identifier. Its walk skips a file another engine has already imported. Rescan again on its own, which is the measured cure and needs no change to the declaring script, or restart the editor with editor_launch restart.");
+    }
+    if (stillAtMissingPaths.length > 0) {
+      notes.push(`The scan wrote the class cache with ${stillAtMissingPaths.join(", ")} at a path that is not on disk, and rebuilding the cache from the files did not take it out. The next engine to read the cache fails on "Could not parse global class" in whichever correct script shares the bare name. Restart the editor with editor_launch restart, then run project_import refresh_classes.`);
+    } else if (dropped.length > 0) {
+      notes.push(`The scan wrote the class cache from the list this editor is holding, and that list still has ${dropped.join(", ")} for a script that is gone, so the cache was rebuilt from the files without it. The editor goes on holding it and writes it back on every scan until it is restarted with editor_launch restart; until then a scan is followed by this same rebuild.`);
+    }
     return this.jsonTextResponse({
-      ok: !busy && unseen.length === 0 && stillGone.length === 0 && checked.unchecked === undefined,
+      ok: !busy && unseen.length === 0 && stillGone.length === 0 && stillAtMissingPaths.length === 0 && checked.unchecked === undefined,
       stillWorking: busy,
       waitedMs: Date.now() - started,
       heldBeforeReload: reloaded.heldBefore,
@@ -40241,8 +40304,10 @@ class GodotServer {
       unseenByEditor: unseen.length > 0 ? unseen : undefined,
       cacheLost: lost.length > 0 ? lost : undefined,
       cacheRestored: restored.length > 0 ? restored : undefined,
+      cacheDropped: dropped.length > 0 ? dropped : undefined,
+      cacheAtMissingPaths: stillAtMissingPaths.length > 0 ? stillAtMissingPaths : undefined,
       classesUnchecked: checked.unchecked,
-      note: busy ? "The editor was still scanning or importing when the wait ran out, so new files may not be visible yet." : stillGone.length > 0 ? "The scan wrote the class cache from the list this editor is holding, that list is shorter than the file was, and rebuilding the cache from the files did not bring these back. Every engine that reads the cache next, including a test run, will report them as unknown identifiers. Restart the editor with editor_launch restart before scanning again." : lost.length > 0 ? "The scan wrote the class cache from the list this editor is holding, which is shorter than the file was, so the cache was rebuilt from the files and these classes are back in it. Nothing was lost, but this editor is still holding the short list: do not rescan again until it has been restarted with editor_launch restart, because it will write the same list over the file each time." : unseen.length > 0 ? "The scan finished and these classes are still not in the list the editor resolves against, so every use of them reads as an unknown identifier. Its walk skips a file another engine has already imported. Rescan again on its own, which is the measured cure and needs no change to the declaring script, or restart the editor with editor_launch restart." : undefined
+      note: notes.length > 0 ? notes.join(" ") : undefined
     });
   }
   async rebuildCacheAfterLoss(projectPath, lost) {
@@ -40483,6 +40548,7 @@ class GodotServer {
       property: readString(args, "property") ?? "",
       value: args["value"],
       ...readNonEmptyString(args, "says") === undefined ? {} : { says: readNonEmptyString(args, "says") },
+      ...readBoolean(args, "includeHidden") === undefined ? {} : { include_hidden: readBoolean(args, "includeHidden") },
       timeout_ms: timeoutMs
     }, patience);
   }
@@ -40491,7 +40557,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run7, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, CONSOLE_WRAPPER, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CACHE_WRITE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run7, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, CONSOLE_WRAPPER, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CACHE_WRITE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
 var init_server3 = __esm(() => {
   init_mcp();
   init_stdio2();
@@ -42080,11 +42146,13 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | Press the next thing after a click that changed screen | \`runtime_wait until\` with \`says\` and a word the new screen shows, then the click. A click sent straight after a screen change lands on a control the new screen is about to free, answers \`landed: true\`, and does nothing; a frame count is a number nobody can pick correctly across a cold start and a warm one, and waiting for the words answered in about 130ms where twenty frames had not been enough |
 | Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\` with \`replace\`; a submitted field has to be clicked again |
 | Click somebody standing in a 3D room | \`runtime_input click\` on the Node3D, which aims at what it draws |
-| Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says |
+| Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says, rather than a click and keys: the menu opens as a window of its own that an injected key never reaches, so Enter closes it with nothing chosen |
 | Answer a dialog | \`runtime_input click\` on its button, or \`key\` Escape to dismiss it: an [AcceptDialog] reads that key itself and never asks the InputMap, so \`ui_cancel\` leaves it standing |
 | Press a bound key | \`runtime_input action\` or \`key\`, a whole press unless you hold it |
 | Where a 3D node is on screen | \`runtime_inspect\` \`rect\`, rather than unprojecting by hand |
-| Wait for something in a running game | \`runtime_wait\`, never a sleep; \`until\` with \`says\` for a panel that rebuilds its own labels |
+| Wait for something in a running game | \`runtime_wait\`, never a sleep; \`until\` with \`says\` for a panel that rebuilds its own labels. The words have to be shown: a button that exists hidden through an animation does not satisfy it until it appears, unless \`includeHidden\` says otherwise |
+| What every label on a screen says | \`runtime_inspect tree\` with \`properties\` naming \`text\`, which reads it off every node that has one; \`includeProperties\` is every stored property of every node and ran to seventy-six thousand characters for one row |
+| Whether this engine has a method or property, and what it takes | \`editor_classes info\` with \`member\`, which answers that one member and which class declares it rather than the whole class |
 | Wait for a run to finish | \`editor_run wait\`, never a sleep or a shell loop on the pid: it answers as \`editor_output\` does, once the run is over |
 | End a bench and the workers it opened | \`editor_run stop\` with \`andChildren\`, never a process listing by scene name: it ends every process under the run's, to any depth, that is a game of the project, announced as one or the project's engine run with \`--path\` on it, names them under \`endedChildren\` with what identified each, and leaves and names any other |
 | A picture, for a person who asked to see one | \`runtime_capture\` |

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

@@ -25,12 +25,31 @@ const HEADLESS_VIEWPORT: Vector2 = Vector2(64, 64)
 var _host: Node
 var _values: Values
 
+## Where the last injected pointer event put the pointer, once one has.
+##
+## Kept here rather than asked of the viewport: the root viewport answers get_mouse_position
+## from the operating system's pointer, which an injected event never moves, so on a desktop it
+## is wherever the user's mouse is, another monitor included, and every motion sent through the
+## bridge carried the distance from there. Only a headless run, with no pointer to read, followed
+## the injected events, which is why that reading measured right and a played game read it wrong.
+var _pointer: Vector2 = Vector2.ZERO
+var _pointer_placed: bool = false
+
 
 func _init(host: Node, values: Values) -> void:
 	_host = host
 	_values = values
 
 
+## The movement a pointer arriving at [param position] carries, which is the distance from where
+## the last injected event put it, and none at all for the first. The arrival is recorded.
+func _arrive(position: Vector2) -> Vector2:
+	var relative: Vector2 = position - _pointer if _pointer_placed else Vector2.ZERO
+	_pointer = position
+	_pointer_placed = true
+	return relative
+
+
 ## Presses [param params].action, and lets go of it again unless asked to hold it.
 ##
 ## The whole press by default, for the reason [method click] is the whole click: an action left
@@ -329,6 +348,9 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	var pressed: bool = Read.as_bool(params.get("pressed", true), true)
 	var double: bool = Read.as_bool(params.get("doubleClick", false))
 
+	# A button pressed somewhere puts the pointer there: the motion after a held press measures
+	# its drag from the press, which is where a real pointer would be.
+	var _moved: Vector2 = _arrive(position)
 	Input.parse_input_event(_button(position, button, pressed, double))
 
 	return {
@@ -341,15 +363,29 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	}
 
 
+## Moves the pointer to a position, with the movement the event carries taken from where the
+## last injected event put it unless the caller says otherwise.
+##
+## A real pointer never arrives without a `relative`, and a control that drags reads that field
+## rather than the position, so a motion carrying none leaves a grip where it was however far the
+## position moved. The distance from where the bridge last put the pointer is what a real move
+## would have carried. A relative the caller gives is kept, since a game may want to read a motion
+## the position does not show.
 func inject_mouse_motion(params: Dictionary) -> Dictionary:
 	var point: Variant = _read_point(params, "x", "y", "position")
 	if point is String:
 		return {"type": "error", "message": point}
 	var position: Vector2 = point
-	var movement: Variant = _read_point(params, "relativeX", "relativeY", "relative")
-	if movement is String:
-		return {"type": "error", "message": movement}
-	var relative: Vector2 = movement
+	var relative: Vector2 = _arrive(position)
+	if params.has("relativeX") or params.has("relativeY"):
+		relative = Vector2(
+			Read.as_float(params.get("relativeX", 0.0)), Read.as_float(params.get("relativeY", 0.0))
+		)
+	elif params.has("relative"):
+		var movement: Variant = _read_point(params, "relativeX", "relativeY", "relative")
+		if movement is String:
+			return {"type": "error", "message": movement}
+		relative = movement
 
 	Input.parse_input_event(_motion(position, relative))
 
@@ -502,7 +538,7 @@ func click(params: Dictionary) -> Dictionary:
 	# Pushed into the viewport rather than through Input: Input accumulates events and flushes
 	# them at the next frame, so the hovered control read below would be the one from before
 	# the pointer moved. The viewport delivers it to the GUI the same way a real one arrives.
-	viewport.push_input(_motion(position, Vector2.ZERO))
+	viewport.push_input(_motion(position, _arrive(position)))
 	# What the engine itself thinks is under the pointer, which is the answer to "did it land",
 	# read before the press so the caller learns about a control on top rather than a click
 	# that went to it. Read in full here, path included, because nothing about that control
@@ -762,7 +798,7 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 		return _no_such_button(params.get("button"))
 	var double: bool = Read.as_bool(params.get("double", false))
 
-	viewport.push_input(_motion(position, Vector2.ZERO))
+	viewport.push_input(_motion(position, _arrive(position)))
 	# Read before the press, for the reason the Control click reads it: what the caller needs to
 	# know is whether a panel is sitting over the room, and the press is what would change it.
 	var hovered: Control = viewport.gui_get_hovered_control()
@@ -790,14 +826,21 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	}
 
 
+## The buttons a real pointer event carries are the ones held as it happens, and Input keeps that
+## from every button event it is given, injected ones included, so a motion between a held click
+## and its release is a drag to a control that reads the mask rather than remembering the click.
 func _motion(position: Vector2, relative: Vector2) -> InputEventMouseMotion:
 	var event: InputEventMouseMotion = InputEventMouseMotion.new()
 	event.position = position
 	event.global_position = position
 	event.relative = relative
+	event.screen_relative = relative
+	event.button_mask = Input.get_mouse_button_mask()
 	return event
 
 
+## A button event carries the buttons held once it has happened: the pressed one among them, the
+## released one out. A wheel step is a button with no mask, as it is from a real mouse.
 func _button(position: Vector2, button: int, pressed: bool, double: bool) -> InputEventMouseButton:
 	var event: InputEventMouseButton = InputEventMouseButton.new()
 	event.position = position
@@ -805,9 +848,20 @@ func _button(position: Vector2, button: int, pressed: bool, double: bool) -> Inp
 	event.button_index = button as MouseButton
 	event.pressed = pressed
 	event.double_click = double
+	var held: int = Input.get_mouse_button_mask()
+	var own: int = _mask_of(button)
+	event.button_mask = (held | own) if pressed else (held & ~own)
 	return event
 
 
+## The mask bit for a button, which is the engine's own mapping: left 1, right 2, middle 4, the
+## two extra buttons 128 and 256. The wheel steps between have none.
+func _mask_of(button: int) -> int:
+	if button >= MOUSE_BUTTON_WHEEL_UP and button <= MOUSE_BUTTON_WHEEL_RIGHT:
+		return 0
+	return 1 << (button - 1)
+
+
 ## What to say about a name that is not a mouse button, with the ones that are.
 func _no_such_button(named: Variant) -> Dictionary:
 	return {

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

@@ -30,17 +30,33 @@ func _init(host: Node, values: Values) -> void:
 	_values = values
 
 
+## The tree under a node, to a depth, with every stored property on each node when asked for all
+## of them or the named ones when a list is given.
+##
+## The list is the shape most questions about a screen take: the `text` of every label and
+## button under a panel. All of them for one row of a form answered seventy-six thousand
+## characters, and the same question as a find with one property answered two.
 func get_tree(params: Dictionary) -> Dictionary:
 	var root_path: String = str(params.get("root", "/root"))
 	var max_depth: int = Read.as_int(params.get("depth", 3), 3)
 	var include_properties: bool = Read.as_bool(params.get("include_properties", false))
+	var named: Array[String] = []
+	var listed: Variant = params.get("properties", [])
+	if listed is Array:
+		for each: Variant in listed:
+			named.append(str(each))
+	else:
+		return {"type": "error", "message": "properties must be a list of property names"}
 
 	var reached: Dictionary = Values.node_at(_host.get_tree().root, root_path)
 	if reached.has("message"):
 		return reached
 	var root: Node = reached["node"]
 
-	return {"type": "tree", "root": _serialize_node_tree(root, 0, max_depth, include_properties)}
+	return {
+		"type": "tree",
+		"root": _serialize_node_tree(root, 0, max_depth, include_properties, named),
+	}
 
 
 ## Nodes matching every filter given, as paths, so a caller can name what it wants without
@@ -91,7 +107,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 		var node: Node = pending.pop_front()
 		var rest: bool = _matches_apart_from_name(node, wanted)
 		if rest and _named(node, wanted["name"]):
-			if not include_hidden and not _shown(node):
+			if not include_hidden and not shown(node):
 				hidden += 1
 			elif found.size() >= limit:
 				truncated = true
@@ -144,8 +160,8 @@ func find_nodes(params: Dictionary) -> Dictionary:
 ## a plain Node sitting between a hidden panel and a label has no visibility to ask about, and the
 ## label answers that it is visible while nothing of it is on screen. Walking up is what makes a
 ## row hidden because the panel holding it is hidden, which is what somebody checking a screen is
-## asking about.
-static func _shown(node: Node) -> bool:
+## asking about. A wait on words asks the same, so it reads this too.
+static func shown(node: Node) -> bool:
 	var walk: Node = node
 	while walk != null:
 		if not _drawn(walk):
@@ -846,8 +862,12 @@ func get_metrics(params: Dictionary) -> Dictionary:
 	return {"type": "metrics", "data": selected}
 
 
-func _serialize_node_tree(node: Node, depth: int, max_depth: int, include_properties: bool) -> Dictionary:
+func _serialize_node_tree(
+	node: Node, depth: int, max_depth: int, include_properties: bool, named: Array[String]
+) -> Dictionary:
 	var result: Dictionary = _serialize_node(node, include_properties)
+	if not named.is_empty():
+		result["properties"] = _named_properties_of(node, str(result["path"]), named)
 
 	if depth < max_depth:
 		var children: Array = []
@@ -856,12 +876,28 @@ func _serialize_node_tree(node: Node, depth: int, max_depth: int, include_proper
 		# it is wrong, and it is what sends somebody looking for another way to press the button.
 		# `depth` is what keeps the answer a size worth reading.
 		for child: Node in node.get_children(true):
-			children.append(_serialize_node_tree(child, depth + 1, max_depth, include_properties))
+			children.append(_serialize_node_tree(child, depth + 1, max_depth, include_properties, named))
 		result["children"] = children
 
 	return result
 
 
+## The named properties a node has, read the way a find reads its one: through a colon path as
+## well, and a name this node has not got is left out rather than answered null, since a tree
+## holds nodes of every class and a label's `text` is not a container's.
+func _named_properties_of(node: Node, path: String, named: Array[String]) -> Dictionary:
+	var properties: Dictionary = {}
+	for wanted: String in named:
+		var reached: Dictionary = _reached(node, path, wanted)
+		if reached.has("message"):
+			continue
+		var holder: Variant = reached["holder"]
+		var name: String = reached["name"]
+		if _can_read(holder, name):
+			properties[wanted] = _values.serialize(_read(holder, name))
+	return properties
+
+
 func _serialize_node(node: Node, include_properties: bool) -> Dictionary:
 	var result: Dictionary = {"name": node.name, "type": node.get_class(), "path": str(node.get_path())}
 

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

@@ -115,7 +115,8 @@ func wait_until(params: Dictionary) -> Dictionary:
 			)
 		}
 	if not says.is_empty():
-		return await _wait_until_said(node_path, says, timeout_ms)
+		var include_hidden: bool = Read.as_bool(params.get("include_hidden", false))
+		return await _wait_until_said(node_path, says, timeout_ms, include_hidden)
 	if property.is_empty():
 		return {"type": "error", "message": "A property and a value, or says, are required"}
 	if not params.has("value"):
@@ -196,34 +197,40 @@ func wait_until(params: Dictionary) -> Dictionary:
 ## on a node that was freed a frame later, and that is what it answered: the date along the top of a
 ## hall could not be waited on at all. What a caller is watching for is a word arriving on a screen,
 ## and the screen is the part that stays put.
-func _wait_until_said(node_path: String, said: String, timeout_ms: int) -> Dictionary:
+##
+## On the screen, which is to say shown: a control carrying the words while hidden satisfied the
+## wait at once, so a duel screen whose "Carry on" button exists hidden through the whole sweep
+## answered met in two milliseconds while the sweep was still animating, and every wait on that
+## screen fell back to counting frames. [param include_hidden] asks the other question, for a
+## caller waiting on words a hidden node holds.
+func _wait_until_said(node_path: String, said: String, timeout_ms: int, include_hidden: bool) -> Dictionary:
 	var started: int = Time.get_ticks_msec()
 	var words: String = Queries.as_said(said)
-	var found: bool = _anything_says(node_path, words)
+	var found: bool = _anything_says(node_path, words, include_hidden)
 	while not found and Time.get_ticks_msec() - started < timeout_ms:
 		await _host.get_tree().process_frame
-		found = _anything_says(node_path, words)
+		found = _anything_says(node_path, words, include_hidden)
 
 	return {
 		"type": "condition",
 		"path": node_path,
 		"says": said,
 		"met": found,
+		"include_hidden": include_hidden,
 		"elapsed_ms": Time.get_ticks_msec() - started,
 	}
 
 
-## Whether anything under [param node_path] says [param said], the node itself included. Hidden
-## nodes count, for the reason a find answers off them: a caller may be waiting for a dialog that
-## is built before it is shown.
-func _anything_says(node_path: String, said: String) -> bool:
+## Whether anything under [param node_path] says [param said], the node itself included, and shown
+## unless hidden ones are wanted too.
+func _anything_says(node_path: String, said: String, include_hidden: bool) -> bool:
 	var root: Node = _host.get_tree().root.get_node_or_null(node_path)
 	if root == null:
 		return false
 	var pending: Array[Node] = [root]
 	while not pending.is_empty():
 		var node: Node = pending.pop_back()
-		if Queries.said_by(node).containsn(said):
+		if Queries.said_by(node).containsn(said) and (include_hidden or Queries.shown(node)):
 			return true
 		pending.append_array(node.get_children(true))
 	return false

package/build/godot/operations/classdb_queries.gd

@@ -92,6 +92,10 @@ func query_class_info(params: Dictionary) -> Dictionary:
 	if not ClassDB.class_exists(class_name_str):
 		return _log.failure("Class not found: " + class_name_str)
 
+	var member: String = str(params.get("member", ""))
+	if not member.is_empty():
+		return _member_of(class_name_str, member)
+
 	var methods: Array[Dictionary] = _methods_of(class_name_str, include_inherited)
 	var properties: Array[Dictionary] = _properties_of(class_name_str, include_inherited)
 	var signals: Array[Dictionary] = _signals_of(class_name_str, include_inherited)
@@ -130,6 +134,77 @@ func query_class_info(params: Dictionary) -> Dictionary:
 	}
 
 
+# One member of a class by name, wherever in its ancestry it is declared.
+#
+# The question a member is asked by name for is "does this engine have it, and what does it take":
+# the whole class in answer to that ran to seventy thousand characters for Control, and the member
+# is as often an ancestor's as the class's own, so the ancestry is walked without being asked. Each
+# match says which class declares it. Nothing found names the members whose names contain the one
+# asked for, since the usual miss is a spelling.
+func _member_of(class_name_str: String, member: String) -> Dictionary:
+	var found: Array[Dictionary] = []
+	var current: String = class_name_str
+	while not current.is_empty():
+		for m: Dictionary in _methods_of(current, false):
+			if m["name"] == member:
+				found.append({"kind": "method", "declared_in": current, "member": m})
+		for p: Dictionary in _properties_of(current, false):
+			if p["name"] == member:
+				found.append({"kind": "property", "declared_in": current, "member": p})
+		for s: Dictionary in _signals_of(current, false):
+			if s["name"] == member:
+				found.append({"kind": "signal", "declared_in": current, "member": s})
+		for e: String in ClassDB.class_get_enum_list(current, true):
+			if e == member:
+				var values: Dictionary = {}
+				for c: String in ClassDB.class_get_enum_constants(current, e, true):
+					values[c] = ClassDB.class_get_integer_constant(current, c)
+				found.append(
+					{"kind": "enum", "declared_in": current, "member": {"name": e, "values": values}}
+				)
+		for c: String in ClassDB.class_get_integer_constant_list(current, true):
+			if c == member:
+				var value: int = ClassDB.class_get_integer_constant(current, c)
+				found.append(
+					{"kind": "constant", "declared_in": current, "member": {"name": c, "value": value}}
+				)
+		current = ClassDB.get_parent_class(current)
+
+	if found.is_empty():
+		var alike: Array[String] = _members_alike(class_name_str, member)
+		var hint: String = (
+			"" if alike.is_empty() else " Members with names containing it: " + ", ".join(alike) + "."
+		)
+		return _log.failure(
+			"%s and its ancestors declare no member named %s.%s" % [class_name_str, member, hint]
+		)
+
+	return {"class_name": class_name_str, "member": member, "found": found}
+
+
+# The names, across a class and its ancestors, that contain the asked-for one, case-insensitively.
+func _members_alike(class_name_str: String, member: String) -> Array[String]:
+	var alike: Array[String] = []
+	var wanted: String = member.to_lower()
+	var current: String = class_name_str
+	while not current.is_empty():
+		for m: Dictionary in _methods_of(current, false):
+			var name: String = m["name"]
+			if name.to_lower().contains(wanted) and not alike.has(name):
+				alike.append(name)
+		for p: Dictionary in _properties_of(current, false):
+			var name: String = p["name"]
+			if name.to_lower().contains(wanted) and not alike.has(name):
+				alike.append(name)
+		for s: Dictionary in _signals_of(current, false):
+			var name: String = s["name"]
+			if name.to_lower().contains(wanted) and not alike.has(name):
+				alike.append(name)
+		current = ClassDB.get_parent_class(current)
+	alike.sort()
+	return alike
+
+
 # Inspect class inheritance hierarchy
 func inspect_inheritance(params: Dictionary) -> Dictionary:
 	var class_name_str: String = str(params.get("class_name", ""))

package/build/index.js

@@ -25052,6 +25052,9 @@ function cacheWrittenAt(projectPath) {
     return null;
   }
 }
+function cachedAtMissingPaths(cached, projectPath) {
+  return [...cached].filter(([, path]) => path.startsWith("res://") && !existsSync2(join4(projectPath, path.slice("res://".length)))).map(([name]) => name).sort();
+}
 function staleAgainst(cached, projectPath) {
   return [...declaredClasses(projectPath)].filter(([name, path]) => cached.get(name) !== path).map(([name]) => name);
 }
@@ -29687,7 +29690,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_rescan",
-    description: "Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure is this call on its own, with no change to the declaring script: measured against a real editor on three platforms, with idle waits of the same length ruled out so the scan is credited rather than the time it takes, and reproduced in a second project against its own reproduction in 203ms. editor_launch restart also does it and costs a window, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve goes out of that file with it. That is not a reason to refuse the scan, because on a class the editor has merely not walked yet the scan is the cure; what the answer does instead is name the loss under cacheLost and rebuild the cache from the files, naming what came back under cacheRestored, so no fresh engine, CI run or clone inherits the short file. An editor that lost classes is still holding the short list, so the note says to restart it before scanning again. Needs the editor connected.",
+    description: "Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure is this call on its own, with no change to the declaring script: measured against a real editor on three platforms, with idle waits of the same length ruled out so the scan is credited rather than the time it takes, and reproduced in a second project against its own reproduction in 203ms. editor_launch restart also does it and costs a window, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve goes out of that file with it. That is not a reason to refuse the scan, because on a class the editor has merely not walked yet the scan is the cure; what the answer does instead is name the loss under cacheLost and rebuild the cache from the files, naming what came back under cacheRestored, so no fresh engine, CI run or clone inherits the short file. An editor that lost classes is still holding the short list, so the note says to restart it before scanning again. The other direction is guarded the same way: a class the editor still holds for a script that was renamed or deleted comes back into the cache at a path that is not there, and the next engine to read it fails on \"Could not parse global class\" in whichever correct script shares the bare name, so the cache is rebuilt without it and the answer names it under cacheDropped; the editor goes on holding it until it is restarted, and every scan until then ends in that rebuild. A script or shader written outside the editor has no .uid sidecar until something imports it, and the scan writes one beside it, which a project that commits sidecars needs before the commit. Needs the editor connected.",
     parameters: {
       projectPath: PROJECT_PATH,
       timeoutMs: { type: "number", description: "How long to wait for the scan. Default 30000." },
@@ -29723,12 +29726,20 @@ var TOOL_SPECS = [
       },
       instantiableOnly: { type: "boolean", description: "query: leave out abstract classes. Default false." },
       className: { type: "string", description: "info, inheritance: the class." },
-      includeInherited: { type: "boolean", description: "info: include inherited members. Default false." }
+      includeInherited: { type: "boolean", description: "info: include inherited members. Default false." },
+      member: {
+        type: "string",
+        ops: ["info"],
+        description: 'info: one member by name, a method, property, signal, enum or constant, with its signature and which class declares it, looked for on the class and every ancestor. The whole of Control is seventy thousand characters; the question "does this engine have it, and what does it take" is this. A name nothing declares is refused with the members whose names contain it.'
+      }
     },
     requires: ["projectPath"],
     operations: {
       query: { summary: "classes matching a filter or category", requires: [] },
-      info: { summary: "methods, properties, signals and enums of one class", requires: ["className"] },
+      info: {
+        summary: "methods, properties, signals and enums of one class, or one member of it by name",
+        requires: ["className"]
+      },
       inheritance: { summary: "ancestors and descendants of one class", requires: ["className"] }
     },
     defaultOperation: "query"
@@ -29753,7 +29764,13 @@ var TOOL_SPECS = [
       includeProperties: {
         type: "boolean",
         ops: ["tree"],
-        description: "tree: include each node's properties. Default false."
+        description: "tree: include every stored property of each node. Default false, and one row of a form answered seventy-six thousand characters with it; properties names the few that are wanted."
+      },
+      properties: {
+        type: "array",
+        items: { type: "string" },
+        ops: ["tree"],
+        description: "tree: the properties to read off each node, by name, so the text of every label and button under a panel is one call: a node that has not got one leaves it out. Colons read through what a node holds, as property does for find."
       },
       className: {
         type: "string",
@@ -29942,12 +29959,12 @@ var TOOL_SPECS = [
       relativeX: {
         type: "number",
         ops: ["mouse_motion"],
-        description: "mouse_motion: movement since the last event."
+        description: "mouse_motion: the movement the event carries. Left out, it is the distance from where the last injected pointer event put the pointer, and none for the first; that is what a control that drags reads. Give it to send a motion the position does not show."
       },
       relativeY: {
         type: "number",
         ops: ["mouse_motion"],
-        description: "mouse_motion: movement since the last event."
+        description: "mouse_motion: as relativeX."
       }
     },
     requires: [],
@@ -29961,13 +29978,22 @@ var TOOL_SPECS = [
         requires: ["nodePath"]
       },
       action: { summary: "press an action, or hold it", requires: ["action"] },
-      key: { summary: "press a key, or hold it", requires: ["keycode"] },
+      key: {
+        summary: "press a key, or hold it. Not for a menu a click has opened: an OptionButton or PopupMenu pops up as a window of its own that a key sent to the game never reaches, so an arrow moves nothing in it and Enter closes it with nothing chosen. choose is what selects there. The limit is that menu's own navigation, not windows in general: an embedded dialog whose owner reads keys in _input gets them, and a binding catcher up in one takes the key first time",
+        requires: ["keycode"]
+      },
       text: {
         summary: "type a string into the field being edited, a character at a time, and say what it landed in",
         requires: ["text"]
       },
-      mouse_click: { summary: "one mouse button event at a position", requires: ["x", "y"] },
-      mouse_motion: { summary: "move the mouse to a position", requires: ["x", "y"] }
+      mouse_click: {
+        summary: "one mouse button event at a position, carrying the buttons held once it has happened. A drag is a press held with pressed true, motions, and a release with pressed false",
+        requires: ["x", "y"]
+      },
+      mouse_motion: {
+        summary: "move the mouse to a position, carrying the distance from where the last injected event put it unless relativeX and relativeY say otherwise, and the buttons held, so a control that drags moves under a run of these between a held mouse_click and its release",
+        requires: ["x", "y"]
+      }
     }
   },
   {
@@ -29988,7 +30014,12 @@ var TOOL_SPECS = [
       says: {
         type: "string",
         ops: ["until"],
-        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, hidden nodes included; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+      },
+      includeHidden: {
+        type: "boolean",
+        ops: ["until"],
+        description: "until, with says: count words on a hidden node too. Default false, since a wait for words is a wait for them to be shown: a button that exists hidden through a whole animation carries its words the whole time and satisfied the wait at once, and every wait on that screen fell back to counting frames."
       },
       timeoutMs: {
         type: "number",
@@ -30142,13 +30173,17 @@ function stillRunning(run) {
   }
   return true;
 }
-function runIsUp(run, editorSays) {
+var PLAY_STARTS_WITHIN_MS = 30000;
+function runIsUp(run, editorSays, now = Date.now()) {
   if (run?.throughEditor !== true) {
     return stillRunning(run);
   }
   if (run.announcedPid !== undefined && !alive(run.announcedPid)) {
     return false;
   }
+  if (editorSays === false && run.seenPlaying !== true && now - run.startedAt < PLAY_STARTS_WITHIN_MS) {
+    return true;
+  }
   return editorSays ?? stillRunning(run);
 }
 function endedPreviousRun(ended) {
@@ -30223,10 +30258,11 @@ function runtimeVerdict(endpoint, after) {
       heldAt: after.heldAt
     };
   }
+  const state = after.playingSeen === false ? "the editor has not yet reported the game as playing, which a restarted editor does not until its scan is over" : "the game is still running";
   return {
     listening: false,
     mayYetAnnounce: after.running,
-    note: after.running ? `nothing announced itself within ${after.budgetMs}ms and the game is still running, so it may announce a moment from now: editor_status says whether it has, and editor_run start takes runtimeWaitMs to wait longer than this${after.withArgs ? ", which a run carrying its own arguments may well need, since whatever they ask the game to do before its first frame is inside this wait" : ""}` : `nothing announced itself within ${after.budgetMs}ms and the game is no longer running, so nothing is going to: editor_output has what it printed on the way down`,
+    note: after.running ? `nothing announced itself within ${after.budgetMs}ms and ${state}, so it may announce a moment from now: editor_status says whether it has, and editor_run start takes runtimeWaitMs to wait longer than this${after.withArgs ? ", which a run carrying its own arguments may well need, since whatever they ask the game to do before its first frame is inside this wait" : ""}` : `nothing announced itself within ${after.budgetMs}ms and the game is no longer running, so nothing is going to: editor_output has what it printed on the way down`,
     heldAt: null
   };
 }
@@ -30957,7 +30993,8 @@ class GodotServer {
               ...whichGame(args),
               root: readNonEmptyString(args, "nodePath") ?? "/root",
               depth: readPositiveNumber(args, "depth") ?? 3,
-              include_properties: readBoolean(args, "includeProperties") ?? false
+              include_properties: readBoolean(args, "includeProperties") ?? false,
+              properties: readArray(args, "properties") ?? []
             });
           case "find":
             return await this.handleFindRuntimeNodes(args);
@@ -32172,7 +32209,8 @@ class GodotServer {
       budgetMs,
       heldAt: this.dapClient?.whereItStopped() ?? null,
       running: endpoint !== null || going !== null && await this.runStillGoing(going),
-      withArgs
+      withArgs,
+      ...going?.throughEditor === true ? { playingSeen: going.seenPlaying === true } : {}
     });
   }
   async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
@@ -32202,6 +32240,7 @@ class GodotServer {
     const startedAt = Date.now();
     const transcript = openTranscript(startedAt);
     closeSync(transcript.fd);
+    const playAnswer = asParams(JSON.parse(answer.content[0]?.text ?? "{}"));
     const played = {
       process: null,
       pid: null,
@@ -32213,7 +32252,8 @@ class GodotServer {
       exitCode: null,
       throughEditor: true,
       brokeOn: null,
-      announcedBefore: alreadyPlaying
+      announcedBefore: alreadyPlaying,
+      seenPlaying: readBoolean(playAnswer, "playing") === true
     };
     this.activeProcess = played;
     writeEditorRunNote({ projectPath, transcript: transcript.path, startedAt });
@@ -32223,7 +32263,7 @@ class GodotServer {
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
-      debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
+      debugPort: readNumber(playAnswer, "debugPort"),
       endedPreviousRun: endedPreviousRun(ended),
       breakpoints: breakpoints.applied.length === 0 ? undefined : this.breakpointsAsProjectSpells(projectPath, breakpoints.applied),
       breakpointsRefused: breakpoints.refused.length === 0 ? undefined : breakpoints.refused.map((one) => ({
@@ -32749,7 +32789,11 @@ class GodotServer {
     if (announced !== undefined && editorSays === undefined) {
       return stillRunning(run);
     }
-    return runIsUp(run, editorSays === undefined ? (await this.editorPlayingState())?.playing ?? null : editorSays);
+    const said = editorSays === undefined ? (await this.editorPlayingState())?.playing ?? null : editorSays;
+    if (said === true) {
+      run.seenPlaying = true;
+    }
+    return runIsUp(run, said);
   }
   async handleGetDebugOutput(args, waitedMs) {
     await this.pickUpWhatTheEditorIsPlaying();
@@ -32932,6 +32976,7 @@ class GodotServer {
     const writtenBefore = projectPath === "" ? null : cacheWrittenAt(projectPath);
     const blind = await this.classesTheEditorCannotSee(args);
     const atRisk = before === null ? [] : blind.unseen.filter((one) => before.has(one.className));
+    const ghosts = blind.stillHeld ?? [];
     const first = await this.handleViaBridge("rescan_filesystem", args);
     if (first.isError) {
       return first;
@@ -32943,7 +32988,7 @@ class GodotServer {
       const pending = Boolean(status["pending"]) && Date.now() - started < SCAN_START_MS;
       busy = Boolean(status["scanning"]) || Boolean(status["importing"]) || pending;
     }
-    if (!busy && projectPath !== "" && (atRisk.length > 0 || blind.unchecked !== undefined)) {
+    if (!busy && projectPath !== "" && (atRisk.length > 0 || ghosts.length > 0 || blind.unchecked !== undefined)) {
       const until = Date.now() + CACHE_WRITE_MS;
       while (Date.now() < until && cacheWrittenAt(projectPath) === writtenBefore) {
         await new Promise((settle) => setTimeout(settle, 100));
@@ -32951,7 +32996,11 @@ class GodotServer {
     }
     const after = projectPath === "" || busy ? null : cachedClasses(projectPath);
     const lost = before === null || after === null ? [] : [...before.keys()].filter((name) => !after.has(name));
-    const restored = lost.length > 0 ? await this.rebuildCacheAfterLoss(projectPath, lost) : [];
+    const atMissingPaths = after === null ? [] : cachedAtMissingPaths(after, projectPath);
+    const restored = lost.length > 0 || atMissingPaths.length > 0 ? await this.rebuildCacheAfterLoss(projectPath, lost) : [];
+    const rebuilt = atMissingPaths.length > 0 ? cachedClasses(projectPath) : null;
+    const dropped = rebuilt === null ? [] : atMissingPaths.filter((name) => !cachedAtMissingPaths(rebuilt, projectPath).includes(name));
+    const stillAtMissingPaths = atMissingPaths.filter((name) => !dropped.includes(name));
     const reloading = readNonEmptyString(args, "reloadScript");
     let reloaded = {};
     if (reloading !== undefined) {
@@ -32967,8 +33016,23 @@ class GodotServer {
     const checked = busy ? { unseen: [] } : await this.classesTheEditorCannotSee(args);
     const unseen = checked.unseen;
     const stillGone = lost.filter((name) => !restored.includes(name));
+    const notes = [];
+    if (busy) {
+      notes.push("The editor was still scanning or importing when the wait ran out, so new files may not be visible yet.");
+    } else if (stillGone.length > 0) {
+      notes.push("The scan wrote the class cache from the list this editor is holding, that list is shorter than the file was, and rebuilding the cache from the files did not bring these back. Every engine that reads the cache next, including a test run, will report them as unknown identifiers. Restart the editor with editor_launch restart before scanning again.");
+    } else if (lost.length > 0) {
+      notes.push("The scan wrote the class cache from the list this editor is holding, which is shorter than the file was, so the cache was rebuilt from the files and these classes are back in it. Nothing was lost, but this editor is still holding the short list: do not rescan again until it has been restarted with editor_launch restart, because it will write the same list over the file each time.");
+    } else if (unseen.length > 0) {
+      notes.push("The scan finished and these classes are still not in the list the editor resolves against, so every use of them reads as an unknown identifier. Its walk skips a file another engine has already imported. Rescan again on its own, which is the measured cure and needs no change to the declaring script, or restart the editor with editor_launch restart.");
+    }
+    if (stillAtMissingPaths.length > 0) {
+      notes.push(`The scan wrote the class cache with ${stillAtMissingPaths.join(", ")} at a path that is not on disk, and rebuilding the cache from the files did not take it out. The next engine to read the cache fails on "Could not parse global class" in whichever correct script shares the bare name. Restart the editor with editor_launch restart, then run project_import refresh_classes.`);
+    } else if (dropped.length > 0) {
+      notes.push(`The scan wrote the class cache from the list this editor is holding, and that list still has ${dropped.join(", ")} for a script that is gone, so the cache was rebuilt from the files without it. The editor goes on holding it and writes it back on every scan until it is restarted with editor_launch restart; until then a scan is followed by this same rebuild.`);
+    }
     return this.jsonTextResponse({
-      ok: !busy && unseen.length === 0 && stillGone.length === 0 && checked.unchecked === undefined,
+      ok: !busy && unseen.length === 0 && stillGone.length === 0 && stillAtMissingPaths.length === 0 && checked.unchecked === undefined,
       stillWorking: busy,
       waitedMs: Date.now() - started,
       heldBeforeReload: reloaded.heldBefore,
@@ -32977,8 +33041,10 @@ class GodotServer {
       unseenByEditor: unseen.length > 0 ? unseen : undefined,
       cacheLost: lost.length > 0 ? lost : undefined,
       cacheRestored: restored.length > 0 ? restored : undefined,
+      cacheDropped: dropped.length > 0 ? dropped : undefined,
+      cacheAtMissingPaths: stillAtMissingPaths.length > 0 ? stillAtMissingPaths : undefined,
       classesUnchecked: checked.unchecked,
-      note: busy ? "The editor was still scanning or importing when the wait ran out, so new files may not be visible yet." : stillGone.length > 0 ? "The scan wrote the class cache from the list this editor is holding, that list is shorter than the file was, and rebuilding the cache from the files did not bring these back. Every engine that reads the cache next, including a test run, will report them as unknown identifiers. Restart the editor with editor_launch restart before scanning again." : lost.length > 0 ? "The scan wrote the class cache from the list this editor is holding, which is shorter than the file was, so the cache was rebuilt from the files and these classes are back in it. Nothing was lost, but this editor is still holding the short list: do not rescan again until it has been restarted with editor_launch restart, because it will write the same list over the file each time." : unseen.length > 0 ? "The scan finished and these classes are still not in the list the editor resolves against, so every use of them reads as an unknown identifier. Its walk skips a file another engine has already imported. Rescan again on its own, which is the measured cure and needs no change to the declaring script, or restart the editor with editor_launch restart." : undefined
+      note: notes.length > 0 ? notes.join(" ") : undefined
     });
   }
   async rebuildCacheAfterLoss(projectPath, lost) {
@@ -33219,6 +33285,7 @@ class GodotServer {
       property: readString(args, "property") ?? "",
       value: args["value"],
       ...readNonEmptyString(args, "says") === undefined ? {} : { says: readNonEmptyString(args, "says") },
+      ...readBoolean(args, "includeHidden") === undefined ? {} : { include_hidden: readBoolean(args, "includeHidden") },
       timeout_ms: timeoutMs
     }, patience);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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",