gdharness 1.2.17 → 1.2.19

package/build/cli.js

@@ -642,6 +642,36 @@ function resolveSilent(requested, variables) {
   const said = envValue("GDHARNESS_SILENT", variables)?.toLowerCase();
   return said !== undefined && said !== "0" && said !== "false";
 }
+function engineFlags(given) {
+  const offered = Object.keys(ENGINE_FLAGS).join(", ");
+  for (let at = 0;at < given.length; at += 1) {
+    const flag = given[at] ?? "";
+    const takes = Object.hasOwn(ENGINE_FLAGS, flag) ? ENGINE_FLAGS[flag] : undefined;
+    if (takes === undefined) {
+      const setBy = Object.hasOwn(SET_BY_ARGUMENT, flag) ? SET_BY_ARGUMENT[flag] : undefined;
+      return {
+        ok: false,
+        reason: setBy !== undefined ? `${flag} is set by this tool's own argument, ${setBy}, rather than through engineArgs.` : `${flag} is not one of the engine flags engineArgs takes, which are those that change what the engine logs, draws for debugging, checks on the GPU or how it times frames: ${offered}. A value goes as the next entry, as in ["--fixed-fps", "60"].`
+      };
+    }
+    if (takes === "none") {
+      continue;
+    }
+    const value = given[at + 1];
+    const fits = value !== undefined && (takes === "number" ? /^\d+(?:\.\d+)?$/.test(value) : /^\d+x\d+$/.test(value));
+    if (!fits) {
+      return {
+        ok: false,
+        reason: `${flag} takes ${takes === "number" ? "a number" : "a size such as 1280x720"} as the next entry, and ${value === undefined ? "nothing followed it" : `${JSON.stringify(value)} is not one`}.`
+      };
+    }
+    at += 1;
+  }
+  return { ok: true };
+}
+function engineFlagsAmongGameArgs(args) {
+  return args.filter((one) => Object.hasOwn(ENGINE_FLAGS, one) || Object.hasOwn(SET_BY_ARGUMENT, one));
+}
 function runArguments(options) {
   const args = options.headless ? ["--headless", "--path", options.projectPath] : ["--path", options.projectPath];
   if (options.silent === true && !options.headless) {
@@ -650,6 +680,9 @@ function runArguments(options) {
   if (options.quitAfter !== undefined && options.quitAfter !== null) {
     args.push("--quit-after", String(options.quitAfter));
   }
+  if (options.engineArgs !== undefined) {
+    args.push(...options.engineArgs);
+  }
   if (options.scene !== null) {
     args.push(`res://${options.scene}`);
   }
@@ -692,7 +725,35 @@ function environmentFor(options, variables = process.env) {
   const base = options.savesIn === undefined ? { ...variables } : userDataIn(options.savesIn, variables);
   return { ...base, ...options.env, GDHARNESS_RUNTIME_DIR: options.runtimeDirectory };
 }
-var OPENED_BY_A_SERVER = "GDHARNESS_OPENED_BY_A_SERVER", EDITOR_PID_VARIABLE = "GDHARNESS_EDITOR_PID", RESERVED_VARIABLE_PREFIX = "GDHARNESS_", SAVES_NOT_MOVED_NOTE = "On macOS the engine reads user:// off HOME and ignores the variables that move it elsewhere, measured on Godot 4.7.2, so this run wrote its saves where the player keeps theirs. A suite that saves a game has written into the same folder as the copy being played, and one that tidies up after itself may have removed real saves.";
+var ENGINE_FLAGS, SET_BY_ARGUMENT, OPENED_BY_A_SERVER = "GDHARNESS_OPENED_BY_A_SERVER", EDITOR_PID_VARIABLE = "GDHARNESS_EDITOR_PID", RESERVED_VARIABLE_PREFIX = "GDHARNESS_", SAVES_NOT_MOVED_NOTE = "On macOS the engine reads user:// off HOME and ignores the variables that move it elsewhere, measured on Godot 4.7.2, so this run wrote its saves where the player keeps theirs. A suite that saves a game has written into the same folder as the copy being played, and one that tidies up after itself may have removed real saves.";
+var init_launch = __esm(() => {
+  ENGINE_FLAGS = Object.freeze({
+    "--verbose": "none",
+    "--quiet": "none",
+    "--debug-collisions": "none",
+    "--debug-paths": "none",
+    "--debug-navigation": "none",
+    "--debug-avoidance": "none",
+    "--debug-stringnames": "none",
+    "--debug-canvas-item-redraw": "none",
+    "--debug-mute-audio": "none",
+    "--print-fps": "none",
+    "--gpu-profile": "none",
+    "--gpu-validation": "none",
+    "--gpu-abort": "none",
+    "--disable-vsync": "none",
+    "--frame-delay": "number",
+    "--time-scale": "number",
+    "--fixed-fps": "number",
+    "--max-fps": "number",
+    "--resolution": "size"
+  });
+  SET_BY_ARGUMENT = Object.freeze({
+    "--headless": "headless",
+    "--audio-driver": "silent",
+    "--quit-after": "frames, on editor_run check"
+  });
+});
 
 // src/godot-path.ts
 import { execFile as execFile2 } from "node:child_process";
@@ -769,6 +830,7 @@ var run2;
 var init_godot_path = __esm(() => {
   init_detection();
   init_errors();
+  init_launch();
   run2 = promisify2(execFile2);
 });
 
@@ -10793,6 +10855,10 @@ function describeOperations(spec) {
   const fallback = spec.defaultOperation ? ` Default ${spec.defaultOperation}.` : "";
   return ` Operations: ${lines.join("; ")}.${fallback}`;
 }
+function servedDescription(spec) {
+  const answer = spec.answer === undefined ? "" : " The tool reference in the gdharness skill, and the site, say what every field of the answer means.";
+  return `${spec.description}${describeOperations(spec)}${answer}`;
+}
 function buildToolDefinitions() {
   return TOOL_SPECS.map((spec) => {
     const properties = {};
@@ -10814,7 +10880,7 @@ function buildToolDefinitions() {
     return {
       name: spec.name,
       title: spec.title,
-      description: `${spec.description}${describeOperations(spec)}`,
+      description: servedDescription(spec),
       inputSchema: {
         type: "object",
         properties,
@@ -10836,6 +10902,7 @@ function annotationsOf(spec) {
 }
 var PROJECT_INFO_SECTIONS, PROJECT_PATH, RUNNING_PROJECT_PATH, RUNNING_PID, SCENE_PATH, SCRIPT_PATH, RESOURCE_PATH, NODE_PATH, PROPERTIES, XY, ANIMATION_TRACK, SCRIPT_MODIFICATIONS, INPUT_EVENTS, TILESET_SOURCES, TILEMAP_CELLS, COLOUR, TOOL_SPECS, SPECS_BY_NAME;
 var init_tool_definitions = __esm(() => {
+  init_launch();
   PROJECT_INFO_SECTIONS = [
     "autoloads",
     "plugins",
@@ -11754,7 +11821,13 @@ var init_tool_definitions = __esm(() => {
           type: "array",
           items: { type: "string" },
           ops: ["start", "check"],
-          description: `The game's own arguments, what OS.get_cmdline_user_args() answers, such as ["--level=2"]. The separator is added here. A run with any is started by this server rather than by the editor, which fixes the game's command line when it opens the project, so the debug_* tools do not answer for it.`
+          description: `The game's own arguments, what OS.get_cmdline_user_args() answers, such as ["--level=2"]. The separator is added here, so a flag the engine reads goes to the game instead, and the answer says so under argsNote. A run with any is started by this server rather than by the editor, which fixes the game's command line when it opens the project, so the debug_* tools do not answer for it.`
+        },
+        engineArgs: {
+          type: "array",
+          items: { type: "string" },
+          ops: ["start", "check"],
+          description: `The engine's own flags, before the separator, such as ["--verbose"] or ["--fixed-fps", "60"], a value going as the next entry. Only those that change what the engine logs, draws for debugging, checks on the GPU or how it times frames: ${Object.keys(ENGINE_FLAGS).join(", ")}. Any other is refused, since the engine's command line can also run scripts, open other projects and write files. A run with any is started by this server, as one with args is. A check given --verbose answers with everything printed rather than only errors and warnings, since what verbose adds, the instances leaked at exit among it, is printed as ordinary lines.`
         },
         headless: { type: "boolean", ops: ["start"], description: "start: force a window or no window." },
         visible: {
@@ -11832,12 +11905,12 @@ var init_tool_definitions = __esm(() => {
         },
         stop: {
           effect: "destructive",
-          summary: "end the run and answer with the errors and warnings it printed under entries (editor_output has everything else it printed), naming the process ended under endedPid: for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. A game that started processes of its own keeps them unless andChildren says to end those too. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, the note naming which property it failed on, and false with the number under stillGoing when what was told to end was still running ten seconds later. endedThrough says how the stop ended a run that was going: keeper (the process that started the game ended it through the handle it holds), signal (its pid was signalled once shown to still be the run), or editor (the editor playing it was asked). A start that ends the run before it says how under endedPreviousRunThrough, with the same values, and one that refused to signal that run names the property it failed on under previousRunLeftBecause",
+          summary: "end the run, naming the process ended under endedPid, and answer with the errors and warnings it printed under entries (editor_output has the rest); a game that started processes of its own keeps them unless andChildren says to end those too",
           requires: []
         },
         check: {
           effect: "additive",
-          summary: "boot headless, quit after a few frames, and report the verdict. booted is that verdict rather than whether the game came up: true only for a run that quit on its own within timeoutMs, exited 0 and printed no error, so a game that reached _ready and then raised an error answers false. hung is a run killed at timeoutMs, and errors and warnings count what it printed, which comes back under entries with repeats folded together",
+          summary: "boot headless, quit after a few frames, and report the verdict: booted is true only for a run that quit on its own within timeoutMs, exited 0 and printed no error, so a game that reached _ready and then raised an error answers false",
           requires: ["projectPath"]
         },
         wait: {
@@ -11847,10 +11920,11 @@ var init_tool_definitions = __esm(() => {
         },
         profile: {
           effect: "read",
-          summary: "where the run spends its time by GDScript function, while it runs or after it ended: per function its script, the function (Class.name when the script declares a class_name), the line its body's first statement is on, for a lambda the named function it is written in (within), calls, and self and total milliseconds, sorted by self time, with functionsCounted, scriptMs (the self time of them all) and coveredMs. complete is true when the engine's own totals arrived, which it sends only when the profiler is switched off: the runtime addon does that as a game quits, so a scene that does its work in _ready and quits is covered whole; otherwise the answer is the frames summed so far and the note says what that misses. Self time counts a call into the engine's own methods as the caller's, and a call through super too, while the overridden function's row counts it again: such a row carries selfIncludesSuper, so self times along an override chain overlap. The profiler's own cost of timing a call lands in the self time of the function called; with the runtime addon it is measured each run on an empty function, as perCallOverheadUs, and a row with at least half its selfMs in it carries overheadMs, since a small function called often costs that much less without the profiler. A function the profiler started inside is left out, since its time would be counted from the engine's start. The milliseconds are time passed while the function ran, not processor time given to it, so they grow when other processes compete for the processor: compare two profiles taken under the same load. They are also summed over every thread: a function run by WorkerThreadPool or a Thread on several threads at once counts each thread's time, the engine does not say which thread a call ran on, and a function waiting for them has the wait in its own self time, so selfMs is not time taken from frames, and scriptMs can exceed coveredMs, which the note then says. A property's get and set blocks are named Class.@name_getter and Class.@name_setter, as the engine names them, and their rows carry property, the property's name. A run started with profile: true is profiled from its start. A game the editor plays that was not is profiled from the moment this is asked, and the answer says so; a run this server started without it is refused, since its debugger is fixed as it starts",
+          summary: "where the run spends its time by GDScript function, while it runs or after it ended, sorted by self time. A run started with profile: true is profiled from its start; a game the editor plays that was not is profiled from the moment this is asked; a run this server started without it is refused, since its debugger is fixed as it starts",
           requires: []
         }
       },
+      answer: "stop: endedPid is, for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, the note naming which property it failed on, and false with the number under stillGoing when what was told to end was still running ten seconds later. endedThrough says how the stop ended a run that was going: keeper (the process that started the game ended it through the handle it holds), signal (its pid was signalled once shown to still be the run), or editor (the editor playing it was asked). A start that ends the run before it says how under endedPreviousRunThrough, with the same values, and one that refused to signal that run names the property it failed on under previousRunLeftBecause. check: hung is a run killed at timeoutMs, and errors and warnings count what it printed, which comes back under entries with repeats folded together. profile: per function its script, the function (Class.name when the script declares a class_name), the line its body's first statement is on, for a lambda the named function it is written in (within), calls, and self and total milliseconds, with functionsCounted, scriptMs (the self time of them all) and coveredMs. complete is true when the engine's own totals arrived, which it sends only when the profiler is switched off: the runtime addon does that as a game quits, so a scene that does its work in _ready and quits is covered whole; otherwise the answer is the frames summed so far and the note says what that misses. Self time counts a call into the engine's own methods as the caller's, and a call through super too, while the overridden function's row counts it again: such a row carries selfIncludesSuper, so self times along an override chain overlap. The profiler's own cost of timing a call lands in the self time of the function called; with the runtime addon it is measured each run on an empty function, as perCallOverheadUs, and a row with at least half its selfMs in it carries overheadMs, since a small function called often costs that much less without the profiler. A function the profiler started inside is left out, since its time would be counted from the engine's start. The milliseconds are time passed while the function ran, not processor time given to it, so they grow when other processes compete for the processor: compare two profiles taken under the same load. They are also summed over every thread: a function run by WorkerThreadPool or a Thread on several threads at once counts each thread's time, the engine does not say which thread a call ran on, and a function waiting for them has the wait in its own self time, so selfMs is not time taken from frames, and scriptMs can exceed coveredMs, which the note then says. A property's get and set blocks are named Class.@name_getter and Class.@name_setter, as the engine names them, and their rows carry property, the property's name. A game the editor plays that was not started with profile: true says, in the answer, that it was profiled from the moment it was asked.",
       defaultOperation: "start"
     },
     {
@@ -11908,7 +11982,8 @@ var init_tool_definitions = __esm(() => {
       name: "editor_status",
       title: "Editor status",
       effect: "read",
-      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. It stays named after the run ends, beside processActive false, so editor_output can still read what that run printed; null when there is no run at all. startedAt says when it began, and endedAt when it ended, wherever something saw the end: a run adopted from a note another server wrote can have ended hours before this server started. editor.lspListening and editor.dapListening say whether anything accepts connections on the ports the editor names, lspPort and dapPort: Godot binds each once, as the editor starts, and reports a failure only in the log panel of the editor itself, so a false comes with serversNote, and editor_launch restart binds it again. 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. Any editor of this project running and not yet connected, whoever opened it, makes it true as well and is named under editorsNotYetConnected with its pid and start time, so a restart a reconnect interrupted after its launch is not read as nothing being there. 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. Every other call made while an editor is arriving, before its greeting or while it is looked up, waits up to ten seconds for it to settle rather than acting on connected as it reads in that window.",
+      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and which games with the runtime addon are reachable, of this project and of every other on the machine. Read connected with mayYetConnect: the editor dials this server and backs off between tries, so for the first half-minute after a server starts false means not reached yet as often as no editor; mayYetConnect true is worth waiting out, false is final, and restartInterrupted, restartUnderway, closedHere and editorsNotYetConnected say why. An editor that has connected and not yet greeted reports nothing about itself, and every other call made in that window waits up to ten seconds for it to settle. playingInEditor null means unanswered rather than nothing playing: processActive and runtimes do not depend on the editor answering. game.run names the run editor_output and editor_run stop answer for, and stays named after it ends. addonIsStale, on the editor and on each game, says it runs addon code other than what this server ships, and staleNote says which half moves: gdharness upgrade in the project, a restart, or a reconnect of this server. A false editor.lspListening or editor.dapListening comes with serversNote, and editor_launch restart binds the port again. editor.scan says whether the editor is scanning, which editor_run waits out before starting a game. A game announced in a protocol this server does not speak is listed under unreadable, during an upgrade that moves the protocol, until the halves match.",
+      answer: "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. It stays named after the run ends, beside processActive false, so editor_output can still read what that run printed; null when there is no run at all. startedAt says when it began, and endedAt when it ended, wherever something saw the end: a run adopted from a note another server wrote can have ended hours before this server started. editor.lspListening and editor.dapListening say whether anything accepts connections on the ports the editor names, lspPort and dapPort: Godot binds each once, as the editor starts, and reports a failure only in the log panel of the editor itself, so a false comes with serversNote, and editor_launch restart binds it again. 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. Any editor of this project running and not yet connected, whoever opened it, makes it true as well and is named under editorsNotYetConnected with its pid and start time, so a restart a reconnect interrupted after its launch is not read as nothing being there. 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. Every other call made while an editor is arriving, before its greeting or while it is looked up, waits up to ten seconds for it to settle rather than acting on connected as it reads in that window.",
       parameters: {},
       requires: []
     },
@@ -12215,6 +12290,7 @@ var init_tool_definitions = __esm(() => {
       name: "runtime_input",
       title: "Send input to the game",
       description: "Input to the running game: a whole click on a Control or a 3D node named by path or on a control named by the words on it, an item chosen out of a menu, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it. On gdharness's own desktop, where a windowed run goes, Windows refuses to say where the pointer is: every pointer answer there carries pointer_on_hidden_desktop, and the first of the run pointer_note saying why it matters: get_mouse_position() on the root window, and the mouse positions derived from it, read a meaningless position, while what reads the event itself (the control under it, hover, tooltips, input handlers) gets the injected position.",
+      answer: 'click: what was under the pointer, and what became of the control: in_tree, removed or freed. Named by says, found says which match it was, and found.pressedOn says "the words" for words in a RichTextLabel pressed where they are drawn, or "the middle of the label" with a note saying why they could not be placed; on a rich label link_pressed says whether the press reached a link, with link_meta giving the meta the label reports clicked, an empty one included. A control scrolled into view first is scrolled each container out from it a frame after the one inside, and scrolled_into_view says whether a scroll value changed. A button in toggle mode, a CheckBox or CheckButton included, answers pressed with before and after, its button_pressed either side of the click: the same value twice is a click the game undid, and after is null when the click freed it. A refusal for a pointer turned off names where mouse_behavior_recursive was set. On a 3D node landed says the interface did not swallow the press: no control under the pointer stopped it, a control letting the pointer pass included, and every viewport on the way out from the room had the pointer over what shows the room. choose: what was chosen, read before the press, which is heard rather than assumed; what became of the control named (in_tree, removed or freed, since a game can rebuild its screen on the pick); and what the button in front of the menu shows now when it is still there. A menu is opened rather than clicked because its items are drawn rather than built, and the item is looked for as the menu stands once open, since a game can fill a menu as it opens.',
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         pid: RUNNING_PID,
@@ -12304,12 +12380,12 @@ var init_tool_definitions = __esm(() => {
       operations: {
         click: {
           effect: "additive",
-          summary: `press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed. The control is named by nodePath, or by says with the words on it, found under nodePath when both are given, and the answer then says under found which match it was. Words that are part of a RichTextLabel are pressed where they are drawn rather than at the label's middle, so a link among them is the one pressed: found.pressedOn says "the words", or "the middle of the label" with a note saying why they could not be placed, and on a rich label link_pressed says whether the press reached a link, with link_meta giving the meta the label reports clicked, an empty one included. A control out of sight inside a ScrollContainer is scrolled to first, each container out from it a frame after the one inside, and scrolled_into_view says whether a scroll value changed. A button in toggle mode, a CheckBox or CheckButton included, answers pressed with before and after, its button_pressed either side of the click: the same value twice is a click the game undid, and after is null when the click freed it. A disabled button, and a control that does not process (the game paused, say), are refused: the pointer reaches them and the press does nothing. So is a control whose pointer a mouse_behavior_recursive set to disabled on it or above it has turned off, naming where it was set; by says, one the pointer can reach is picked over it. A 3D node is clicked where it is drawn, and landed then says the interface did not swallow the press: no control under the pointer stopped it, a control letting the pointer pass included, and every viewport on the way out from the room had the pointer over what shows the room`,
+          summary: "press and release on a Control, a frame apart, named by nodePath or by says with the words on it (found under nodePath when both are given), or on a 3D node where it is drawn. A control out of sight inside a ScrollContainer is scrolled to first, and a link in a RichTextLabel is pressed where its words are drawn. A disabled button, a control that does not process and one whose pointer mouse_behavior_recursive turned off are refused, since the press would do nothing; by says, one the pointer can reach is picked over it",
           requires: []
         },
         choose: {
           effect: "additive",
-          summary: "take an item out of a menu, by what it says or by where it is in the list. A menu's items are drawn rather than built, so there is nothing to click: the menu is opened, the item is looked for in it as it stands then, since a game can fill a menu as it opens, and the item takes the focus and ui_accept presses it, which is the engine's own path, needs no window, and does not depend on what ui_accept is bound to. A disabled or hidden button in front of the menu is refused, and so is a press the menu did not take, which is heard rather than assumed. Answers with what was chosen, read before the press, what became of the control named (in_tree, removed or freed, since a game can rebuild its screen on the pick), and what the button in front of it shows now when it is still there",
+          summary: "take an item out of a menu, by what it says or by where it is in the list: the menu is opened, the item found in it as it stands then, and pressed through the engine's own path, which needs no window and does not depend on what ui_accept is bound to. A disabled or hidden button in front of the menu is refused, and so is a press the menu did not take",
           requires: ["nodePath"]
         },
         action: { effect: "additive", summary: "press an action, or hold it", requires: ["action"] },
@@ -12585,6 +12661,9 @@ function renderToolsMarkdown() {
   ];
   for (const tool of TOOL_SPECS) {
     lines.push(`## ${tool.name}`, "", `${tool.title}. ${whatItCanChange(tool)}`, "", tool.description, "");
+    if (tool.answer !== undefined) {
+      lines.push(`The answer: ${tool.answer}`, "");
+    }
     const operations = Object.entries(tool.operations ?? {});
     if (operations.length > 0) {
       for (const [op, spec] of operations) {
@@ -34724,6 +34803,7 @@ function runtimeRequest(endpoint, command, params, timeoutMs, keepListening = fa
 var RUNTIME_PROTOCOL = 2, ANNOUNCEMENT_PATTERN, ERROR_REPORT_PATTERN, CONSOLE_BOUNDARY = "[gdharness] runtime listening on ", ERROR_REPORT_KEEP_MS, GONE_WINDOW_MS = 120000, GONE_KEPT = 32, gone, STARTED_AFTER_ANNOUNCING_MS = 2000, CONFIRMED_FOR_MS = 60000, JUDGED_AFTER_MS = 60000, verdicts, judging = null, ENDED_WITHIN_MS = 3000, LOOK_EVERY_MS = 50, ANNOUNCE_BUDGET_MS = 5000, nextRequestId = 1, LATE_ANSWER_MS, LATE_KEPT = 50, lateAnswers;
 var init_runtime_client = __esm(() => {
   init_alive();
+  init_launch();
   init_paths();
   init_process_children();
   ANNOUNCEMENT_PATTERN = /^runtime-(\d+)\.json$/;
@@ -40736,6 +40816,7 @@ var init_lsp_client = __esm(() => {
   init_answer_json();
   init_errors();
   init_framing();
+  init_launch();
   init_paths();
   init_ports();
   LSPTimeout = class LSPTimeout extends Error {
@@ -43608,6 +43689,19 @@ function scanWaitAnswer(scanned, started = "game") {
     scanNote: !scanned.stillScanning ? undefined : started === "game" ? `${still} this game started during the scan and may have read a class cache being rewritten. If ` + 'editor_output shows "Could not find type" for a class that is declared, editor_rescan ' + "waits for the scan to finish, and a start after it reads the finished cache." : `${still} the engine answering this started during the scan and may have read a class cache being ` + "rewritten, and a class cache it wrote can be written over when the scan finishes. If " + 'engine_messages shows "Could not find type" for a class that is declared, editor_rescan waits ' + "for the scan to finish, and the same call after it reads the finished cache."
   };
 }
+function engineFlagsNote(args) {
+  const among = engineFlagsAmongGameArgs(args);
+  if (among.length === 0) {
+    return;
+  }
+  const named = among.join(", ");
+  return `${named} ${among.length === 1 ? "is a flag" : "are flags"} the engine reads, and args goes to the game after --, where the engine does not read ${among.length === 1 ? "it" : "them"}. engineArgs hands the engine its own flags; ${among.length === 1 ? "leave it" : "leave them"} in args only for a game that reads ${among.length === 1 ? "that flag" : "those flags"} itself.`;
+}
+function opElsewhere(tool, requested) {
+  const ops = Object.hasOwn(OPS_ELSEWHERE, tool) ? OPS_ELSEWHERE[tool] : undefined;
+  const where = ops !== undefined && typeof requested === "string" && Object.hasOwn(ops, requested) ? ops[requested] : undefined;
+  return where === undefined ? "" : ` A value is read with ${where}.`;
+}
 function changedSettings(before, after) {
   if (before === null || after === null) {
     return null;
@@ -43984,9 +44078,9 @@ function callersAnswer(totals, asked) {
     note: found.sites.length === 0 ? `No script in the project names ${asked.name} in code, outside its declaration: a call made through a string, such as call("name"), is not found by name.` : found.property ? `${byName} ${PROPERTY_PLACES}` : byName
   };
 }
-function foldedEntriesAnswer(log) {
+function foldedEntriesAnswer(log, floor = "warning") {
   const problems = log.selectFolded({
-    severity: "warning",
+    severity: floor,
     sinceLastCall: false,
     limit: MOST_ENGINE_ENTRIES
   });
@@ -44662,7 +44756,7 @@ class GodotServer {
       } else {
         return {
           ok: false,
-          response: this.createErrorResponse(`${spec.name} has no op ${JSON.stringify(requested)}. Valid ops: ${valid.join(", ")}.`)
+          response: this.createErrorResponse(`${spec.name} has no op ${JSON.stringify(requested)}. Valid ops: ${valid.join(", ")}.${opElsewhere(spec.name, requested)}`)
         };
       }
     }
@@ -45011,6 +45105,25 @@ class GodotServer {
     }
     return { ok: true, value: given };
   }
+  engineArguments(args) {
+    if (args["engineArgs"] === undefined) {
+      return { ok: true, value: [] };
+    }
+    const given = readStringArray(args, "engineArgs");
+    if (given === undefined) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("engineArgs must be a list of strings.", [
+          'Pass engine flags, such as ["--verbose"] or ["--fixed-fps", "60"]'
+        ])
+      };
+    }
+    const checked = engineFlags(given);
+    if (!checked.ok) {
+      return { ok: false, response: this.createErrorResponse(checked.reason) };
+    }
+    return { ok: true, value: given };
+  }
   runEnvironment(args) {
     const savesIn = readNonEmptyString(args, "savesIn");
     if (savesIn !== undefined && !isAbsolute3(savesIn)) {
@@ -46827,6 +46940,10 @@ class GodotServer {
     if (!given.ok) {
       return given.response;
     }
+    const flags = this.engineArguments(args);
+    if (!flags.ok) {
+      return flags.response;
+    }
     const asked = this.runEnvironment(args);
     if (!asked.ok) {
       return asked.response;
@@ -46848,7 +46965,7 @@ class GodotServer {
     }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
-      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, scanned, asked.value);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, scanned, asked.value, flags.value);
     }
     await this.pickUpWhatTheEditorIsPlaying();
     let ended = null;
@@ -46875,7 +46992,7 @@ class GodotServer {
     const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
     const silent = resolveSilent(args["silent"], process.env) && !headless;
     const profiled = readBoolean(args, "profile") === true;
-    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && !needsItsOwnProcess(asked.value) && !silent) {
+    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && flags.value.length === 0 && !needsItsOwnProcess(asked.value) && !silent) {
       return await this.playThroughEditor(sceneArgument, refreshed.value, scanned, project.value.path, alreadyPlaying, runtimeWaitMs, ended, profiled);
     }
     const cmdArgs = runArguments({
@@ -46883,6 +47000,7 @@ class GodotServer {
       headless,
       scene: sceneArgument,
       userArgs: given.value,
+      engineArgs: flags.value,
       silent
     });
     this.logDebug(`Running Godot project: ${engine.value} ${cmdArgs.join(" ")}`);
@@ -46895,7 +47013,7 @@ class GodotServer {
     started.announcedBefore = alreadyPlaying;
     started.bootScene = runtimeWaitMs.scene;
     this.activeProcess = started;
-    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && given.value.length > 0 ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && needsItsOwnProcess(asked.value) ? " The editor plays a game with its own environment, so a run given one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && silent ? " The editor cannot play a game silent, which takes an engine flag, so this one was " + `started here${args["silent"] === true ? "" : ", silent because GDHARNESS_SILENT says so"}: the debug_* tools answer only for a game the editor is playing, and silent: false plays it through the editor.` : "";
+    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && (given.value.length > 0 || flags.value.length > 0) ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && needsItsOwnProcess(asked.value) ? " The editor plays a game with its own environment, so a run given one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && silent ? " The editor cannot play a game silent, which takes an engine flag, so this one was " + `started here${args["silent"] === true ? "" : ", silent because GDHARNESS_SILENT says so"}: the debug_* tools answer only for a game the editor is playing, and silent: false plays it through the editor.` : "";
     const endedForThis = endedToStartThis(ended);
     const stranded = wereHereFirst.filter((one) => one.pid !== ended?.pid && alive(one.pid));
     const alsoRunning = leftRunningNote(stranded);
@@ -46905,6 +47023,7 @@ class GodotServer {
       alsoRunning: stranded.length === 0 ? undefined : stranded.map((one) => one.pid),
       pid: started.pid,
       arguments: cmdArgs,
+      argsNote: engineFlagsNote(given.value),
       transcript: started.transcript,
       profile: profileOnStart(profiled, "gdharness", runtimeAddonRegistered(project.value.path)),
       refreshedClasses: refreshed.value,
@@ -47807,10 +47926,17 @@ class GodotServer {
   async currentRun() {
     return this.activeProcess ?? await this.adoptRecordedRun();
   }
-  async checkBoot(godotPath, projectPath, scene, args, userArgs, scanned, asked = {}) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs, scanned, asked = {}, engineArgs = []) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
-    const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
+    const cmdArgs = runArguments({
+      projectPath,
+      headless: true,
+      scene,
+      quitAfter: frames,
+      userArgs,
+      engineArgs
+    });
     const boot = this.spawnGame(godotPath, cmdArgs, needsItsOwnProcess(asked) ? environmentFor({ ...asked, runtimeDirectory: runtimeDirectory() }) : undefined);
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {
@@ -47838,9 +47964,10 @@ class GodotServer {
       frames,
       errors,
       warnings,
+      argsNote: engineFlagsNote(userArgs),
       ...scanWaitAnswer(scanned),
       savesNote: asked.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
-      ...foldedEntriesAnswer(boot.log)
+      ...foldedEntriesAnswer(boot.log, engineArgs.includes("--verbose") ? "info" : "warning")
     });
   }
   async handleRunProfile(args) {
@@ -49218,7 +49345,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run4, __dirname2, EDITOR_SERVERS_START_MS = 20000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, KEEPER_ANSWER_MS = 15000, EXIT_REPORTED_WITHIN_MS = 2000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, PROFILE_SEND_MS = 5000, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CONSOLE_WATCH_MS = 250, BOUNDARY_WAIT_MS = 2000, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, STREAMS_GRACE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, SCAN_SETTLED_MS = 500, REIMPORT_TIMEOUT_MS = 300000, AUDIO_BUS_OPS, STALLED_AFTER_MS = 30000, TEST_HEARTBEAT_MS = 20000, DEPENDED_FAILED = "Failed to compile depended scripts", WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/", PROFILE_FUNCTIONS = 30, PROFILER_ON_MS = 3000, PROPERTY_PLACES = "It is a property, so each place says whether it writes it (access write), which runs its set block, or reads it (access read), which runs its get block: withinCalls on a read says nothing of the set block, nor on a write of the get block unless the write is a compound one such as +=. Inside the property's own blocks its name is the value stored, which the engine reads and writes without running them, so those lines are not listed.", CALLERS_FOUND_BY_NAME = "Found by name in the project's scripts, since the engine's profiler counts calls and time per function and records nothing about who made them: a method of the same name on another class is listed too, unless one class was asked about and it is called through another class by name or through a variable declared as one. Each place carries the profile's numbers for the function it is written in.", MOST_ENGINE_ENTRIES = 200, ERROR_ASSERT = "GdUnitGodotErrorAssertImpl.gd", EXTERNAL_MEMBER = 'Could not resolve external class member "', STATIC_LIST_HINT;
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run4, __dirname2, EDITOR_SERVERS_START_MS = 20000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, KEEPER_ANSWER_MS = 15000, EXIT_REPORTED_WITHIN_MS = 2000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, PROFILE_SEND_MS = 5000, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CONSOLE_WATCH_MS = 250, BOUNDARY_WAIT_MS = 2000, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, STREAMS_GRACE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, SCAN_SETTLED_MS = 500, REIMPORT_TIMEOUT_MS = 300000, OPS_ELSEWHERE, AUDIO_BUS_OPS, STALLED_AFTER_MS = 30000, TEST_HEARTBEAT_MS = 20000, DEPENDED_FAILED = "Failed to compile depended scripts", WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/", PROFILE_FUNCTIONS = 30, PROFILER_ON_MS = 3000, PROPERTY_PLACES = "It is a property, so each place says whether it writes it (access write), which runs its set block, or reads it (access read), which runs its get block: withinCalls on a read says nothing of the set block, nor on a write of the get block unless the write is a compound one such as +=. Inside the property's own blocks its name is the value stored, which the engine reads and writes without running them, so those lines are not listed.", CALLERS_FOUND_BY_NAME = "Found by name in the project's scripts, since the engine's profiler counts calls and time per function and records nothing about who made them: a method of the same name on another class is listed too, unless one class was asked about and it is called through another class by name or through a variable declared as one. Each place carries the profile's numbers for the function it is written in.", MOST_ENGINE_ENTRIES = 200, ERROR_ASSERT = "GdUnitGodotErrorAssertImpl.gd", EXTERNAL_MEMBER = 'Could not resolve external class member "', STATIC_LIST_HINT;
 var init_server = __esm(() => {
   init_dist();
   init_stdio();
@@ -49246,6 +49373,7 @@ var init_server = __esm(() => {
   init_issues();
   init_junit();
   init_keeper_channel();
+  init_launch();
   init_lsp_client();
   init_outside();
   init_paths();
@@ -49281,6 +49409,9 @@ var init_server = __esm(() => {
     object: "an object"
   };
   HANDOVER_MS = SUCCESSOR_CHECK_MS + 5000;
+  OPS_ELSEWHERE = {
+    runtime_invoke: { get: "runtime_inspect property", property: "runtime_inspect property" }
+  };
   AUDIO_BUS_OPS = new Set([
     "add_audio_bus",
     "remove_audio_bus",

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

@@ -135,6 +135,24 @@ static func make_folder_for(file_path: String) -> String:
 	return "" if made == OK else "Could not make the folder %s: %s" % [folder, error_string(made)]
 
 
+## Why [param script], loaded from [param script_path], cannot be attached because the editor could not
+## compile it, or "". A script that did not compile has no base type, and the refusal built from that
+## said "start.gd extends , so it cannot be on a Control root" about a script that was fine, whose
+## failure was a class it called being behind in the editor.
+static func uncompiled(script: Script, script_path: String) -> String:
+	if not str(script.get_instance_base_type()).is_empty():
+		return ""
+	return (
+		(
+			"%s does not compile in the editor, so it cannot be attached. script_diagnostics on it gives "
+			+ "the parser's errors. If they deny a member that another class's file declares, the "
+			+ "editor's copy of that class is behind: editor_rescan with reloadScript on that class, then "
+			+ "ask again."
+		)
+		% script_path
+	)
+
+
 ## Why no node can be called [param node_name], wherever it sits, or "".
 static func unfit_name(node_name: String) -> String:
 	if node_name.is_empty():

package/build/godot/addons/gdharness_editor/tools/resource_tools.gd

@@ -174,6 +174,9 @@ func create_resource(args: Dictionary) -> Dictionary:
 		var script: Script = load(script_file) as Script
 		if script == null:
 			return {"ok": false, "error": "No script loads from " + script_file}
+		var uncompiled: String = SceneFile.uncompiled(script, script_file)
+		if not uncompiled.is_empty():
+			return {"ok": false, "error": uncompiled}
 		var base: String = str(script.get_instance_base_type())
 		if not ClassDB.is_parent_class(resource_type, base):
 			return {

package/build/godot/addons/gdharness_editor/tools/scene_tools.gd

@@ -313,6 +313,10 @@ func create_scene(args: Dictionary) -> Dictionary:
 		if script == null:
 			root.free()
 			return {"ok": false, "error": "No script loads from " + full_script_path}
+		var uncompiled: String = SceneFile.uncompiled(script, full_script_path)
+		if not uncompiled.is_empty():
+			root.free()
+			return {"ok": false, "error": uncompiled}
 		var base: String = str(script.get_instance_base_type())
 		if not ClassDB.is_parent_class(root_node_type, base):
 			root.free()

package/build/index.js

@@ -24913,6 +24913,62 @@ function resolveSilent(requested, variables) {
   const said = envValue("GDHARNESS_SILENT", variables)?.toLowerCase();
   return said !== undefined && said !== "0" && said !== "false";
 }
+var ENGINE_FLAGS = Object.freeze({
+  "--verbose": "none",
+  "--quiet": "none",
+  "--debug-collisions": "none",
+  "--debug-paths": "none",
+  "--debug-navigation": "none",
+  "--debug-avoidance": "none",
+  "--debug-stringnames": "none",
+  "--debug-canvas-item-redraw": "none",
+  "--debug-mute-audio": "none",
+  "--print-fps": "none",
+  "--gpu-profile": "none",
+  "--gpu-validation": "none",
+  "--gpu-abort": "none",
+  "--disable-vsync": "none",
+  "--frame-delay": "number",
+  "--time-scale": "number",
+  "--fixed-fps": "number",
+  "--max-fps": "number",
+  "--resolution": "size"
+});
+var SET_BY_ARGUMENT = Object.freeze({
+  "--headless": "headless",
+  "--audio-driver": "silent",
+  "--quit-after": "frames, on editor_run check"
+});
+function engineFlags(given) {
+  const offered = Object.keys(ENGINE_FLAGS).join(", ");
+  for (let at = 0;at < given.length; at += 1) {
+    const flag = given[at] ?? "";
+    const takes = Object.hasOwn(ENGINE_FLAGS, flag) ? ENGINE_FLAGS[flag] : undefined;
+    if (takes === undefined) {
+      const setBy = Object.hasOwn(SET_BY_ARGUMENT, flag) ? SET_BY_ARGUMENT[flag] : undefined;
+      return {
+        ok: false,
+        reason: setBy !== undefined ? `${flag} is set by this tool's own argument, ${setBy}, rather than through engineArgs.` : `${flag} is not one of the engine flags engineArgs takes, which are those that change what the engine logs, draws for debugging, checks on the GPU or how it times frames: ${offered}. A value goes as the next entry, as in ["--fixed-fps", "60"].`
+      };
+    }
+    if (takes === "none") {
+      continue;
+    }
+    const value = given[at + 1];
+    const fits = value !== undefined && (takes === "number" ? /^\d+(?:\.\d+)?$/.test(value) : /^\d+x\d+$/.test(value));
+    if (!fits) {
+      return {
+        ok: false,
+        reason: `${flag} takes ${takes === "number" ? "a number" : "a size such as 1280x720"} as the next entry, and ${value === undefined ? "nothing followed it" : `${JSON.stringify(value)} is not one`}.`
+      };
+    }
+    at += 1;
+  }
+  return { ok: true };
+}
+function engineFlagsAmongGameArgs(args) {
+  return args.filter((one) => Object.hasOwn(ENGINE_FLAGS, one) || Object.hasOwn(SET_BY_ARGUMENT, one));
+}
 function runArguments(options) {
   const args = options.headless ? ["--headless", "--path", options.projectPath] : ["--path", options.projectPath];
   if (options.silent === true && !options.headless) {
@@ -24921,6 +24977,9 @@ function runArguments(options) {
   if (options.quitAfter !== undefined && options.quitAfter !== null) {
     args.push("--quit-after", String(options.quitAfter));
   }
+  if (options.engineArgs !== undefined) {
+    args.push(...options.engineArgs);
+  }
   if (options.scene !== null) {
     args.push(`res://${options.scene}`);
   }
@@ -34767,7 +34826,13 @@ var TOOL_SPECS = [
         type: "array",
         items: { type: "string" },
         ops: ["start", "check"],
-        description: `The game's own arguments, what OS.get_cmdline_user_args() answers, such as ["--level=2"]. The separator is added here. A run with any is started by this server rather than by the editor, which fixes the game's command line when it opens the project, so the debug_* tools do not answer for it.`
+        description: `The game's own arguments, what OS.get_cmdline_user_args() answers, such as ["--level=2"]. The separator is added here, so a flag the engine reads goes to the game instead, and the answer says so under argsNote. A run with any is started by this server rather than by the editor, which fixes the game's command line when it opens the project, so the debug_* tools do not answer for it.`
+      },
+      engineArgs: {
+        type: "array",
+        items: { type: "string" },
+        ops: ["start", "check"],
+        description: `The engine's own flags, before the separator, such as ["--verbose"] or ["--fixed-fps", "60"], a value going as the next entry. Only those that change what the engine logs, draws for debugging, checks on the GPU or how it times frames: ${Object.keys(ENGINE_FLAGS).join(", ")}. Any other is refused, since the engine's command line can also run scripts, open other projects and write files. A run with any is started by this server, as one with args is. A check given --verbose answers with everything printed rather than only errors and warnings, since what verbose adds, the instances leaked at exit among it, is printed as ordinary lines.`
       },
       headless: { type: "boolean", ops: ["start"], description: "start: force a window or no window." },
       visible: {
@@ -34845,12 +34910,12 @@ var TOOL_SPECS = [
       },
       stop: {
         effect: "destructive",
-        summary: "end the run and answer with the errors and warnings it printed under entries (editor_output has everything else it printed), naming the process ended under endedPid: for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. A game that started processes of its own keeps them unless andChildren says to end those too. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, the note naming which property it failed on, and false with the number under stillGoing when what was told to end was still running ten seconds later. endedThrough says how the stop ended a run that was going: keeper (the process that started the game ended it through the handle it holds), signal (its pid was signalled once shown to still be the run), or editor (the editor playing it was asked). A start that ends the run before it says how under endedPreviousRunThrough, with the same values, and one that refused to signal that run names the property it failed on under previousRunLeftBecause",
+        summary: "end the run, naming the process ended under endedPid, and answer with the errors and warnings it printed under entries (editor_output has the rest); a game that started processes of its own keeps them unless andChildren says to end those too",
         requires: []
       },
       check: {
         effect: "additive",
-        summary: "boot headless, quit after a few frames, and report the verdict. booted is that verdict rather than whether the game came up: true only for a run that quit on its own within timeoutMs, exited 0 and printed no error, so a game that reached _ready and then raised an error answers false. hung is a run killed at timeoutMs, and errors and warnings count what it printed, which comes back under entries with repeats folded together",
+        summary: "boot headless, quit after a few frames, and report the verdict: booted is true only for a run that quit on its own within timeoutMs, exited 0 and printed no error, so a game that reached _ready and then raised an error answers false",
         requires: ["projectPath"]
       },
       wait: {
@@ -34860,10 +34925,11 @@ var TOOL_SPECS = [
       },
       profile: {
         effect: "read",
-        summary: "where the run spends its time by GDScript function, while it runs or after it ended: per function its script, the function (Class.name when the script declares a class_name), the line its body's first statement is on, for a lambda the named function it is written in (within), calls, and self and total milliseconds, sorted by self time, with functionsCounted, scriptMs (the self time of them all) and coveredMs. complete is true when the engine's own totals arrived, which it sends only when the profiler is switched off: the runtime addon does that as a game quits, so a scene that does its work in _ready and quits is covered whole; otherwise the answer is the frames summed so far and the note says what that misses. Self time counts a call into the engine's own methods as the caller's, and a call through super too, while the overridden function's row counts it again: such a row carries selfIncludesSuper, so self times along an override chain overlap. The profiler's own cost of timing a call lands in the self time of the function called; with the runtime addon it is measured each run on an empty function, as perCallOverheadUs, and a row with at least half its selfMs in it carries overheadMs, since a small function called often costs that much less without the profiler. A function the profiler started inside is left out, since its time would be counted from the engine's start. The milliseconds are time passed while the function ran, not processor time given to it, so they grow when other processes compete for the processor: compare two profiles taken under the same load. They are also summed over every thread: a function run by WorkerThreadPool or a Thread on several threads at once counts each thread's time, the engine does not say which thread a call ran on, and a function waiting for them has the wait in its own self time, so selfMs is not time taken from frames, and scriptMs can exceed coveredMs, which the note then says. A property's get and set blocks are named Class.@name_getter and Class.@name_setter, as the engine names them, and their rows carry property, the property's name. A run started with profile: true is profiled from its start. A game the editor plays that was not is profiled from the moment this is asked, and the answer says so; a run this server started without it is refused, since its debugger is fixed as it starts",
+        summary: "where the run spends its time by GDScript function, while it runs or after it ended, sorted by self time. A run started with profile: true is profiled from its start; a game the editor plays that was not is profiled from the moment this is asked; a run this server started without it is refused, since its debugger is fixed as it starts",
         requires: []
       }
     },
+    answer: "stop: endedPid is, for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, the note naming which property it failed on, and false with the number under stillGoing when what was told to end was still running ten seconds later. endedThrough says how the stop ended a run that was going: keeper (the process that started the game ended it through the handle it holds), signal (its pid was signalled once shown to still be the run), or editor (the editor playing it was asked). A start that ends the run before it says how under endedPreviousRunThrough, with the same values, and one that refused to signal that run names the property it failed on under previousRunLeftBecause. check: hung is a run killed at timeoutMs, and errors and warnings count what it printed, which comes back under entries with repeats folded together. profile: per function its script, the function (Class.name when the script declares a class_name), the line its body's first statement is on, for a lambda the named function it is written in (within), calls, and self and total milliseconds, with functionsCounted, scriptMs (the self time of them all) and coveredMs. complete is true when the engine's own totals arrived, which it sends only when the profiler is switched off: the runtime addon does that as a game quits, so a scene that does its work in _ready and quits is covered whole; otherwise the answer is the frames summed so far and the note says what that misses. Self time counts a call into the engine's own methods as the caller's, and a call through super too, while the overridden function's row counts it again: such a row carries selfIncludesSuper, so self times along an override chain overlap. The profiler's own cost of timing a call lands in the self time of the function called; with the runtime addon it is measured each run on an empty function, as perCallOverheadUs, and a row with at least half its selfMs in it carries overheadMs, since a small function called often costs that much less without the profiler. A function the profiler started inside is left out, since its time would be counted from the engine's start. The milliseconds are time passed while the function ran, not processor time given to it, so they grow when other processes compete for the processor: compare two profiles taken under the same load. They are also summed over every thread: a function run by WorkerThreadPool or a Thread on several threads at once counts each thread's time, the engine does not say which thread a call ran on, and a function waiting for them has the wait in its own self time, so selfMs is not time taken from frames, and scriptMs can exceed coveredMs, which the note then says. A property's get and set blocks are named Class.@name_getter and Class.@name_setter, as the engine names them, and their rows carry property, the property's name. A game the editor plays that was not started with profile: true says, in the answer, that it was profiled from the moment it was asked.",
     defaultOperation: "start"
   },
   {
@@ -34921,7 +34987,8 @@ var TOOL_SPECS = [
     name: "editor_status",
     title: "Editor status",
     effect: "read",
-    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. It stays named after the run ends, beside processActive false, so editor_output can still read what that run printed; null when there is no run at all. startedAt says when it began, and endedAt when it ended, wherever something saw the end: a run adopted from a note another server wrote can have ended hours before this server started. editor.lspListening and editor.dapListening say whether anything accepts connections on the ports the editor names, lspPort and dapPort: Godot binds each once, as the editor starts, and reports a failure only in the log panel of the editor itself, so a false comes with serversNote, and editor_launch restart binds it again. 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. Any editor of this project running and not yet connected, whoever opened it, makes it true as well and is named under editorsNotYetConnected with its pid and start time, so a restart a reconnect interrupted after its launch is not read as nothing being there. 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. Every other call made while an editor is arriving, before its greeting or while it is looked up, waits up to ten seconds for it to settle rather than acting on connected as it reads in that window.",
+    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and which games with the runtime addon are reachable, of this project and of every other on the machine. Read connected with mayYetConnect: the editor dials this server and backs off between tries, so for the first half-minute after a server starts false means not reached yet as often as no editor; mayYetConnect true is worth waiting out, false is final, and restartInterrupted, restartUnderway, closedHere and editorsNotYetConnected say why. An editor that has connected and not yet greeted reports nothing about itself, and every other call made in that window waits up to ten seconds for it to settle. playingInEditor null means unanswered rather than nothing playing: processActive and runtimes do not depend on the editor answering. game.run names the run editor_output and editor_run stop answer for, and stays named after it ends. addonIsStale, on the editor and on each game, says it runs addon code other than what this server ships, and staleNote says which half moves: gdharness upgrade in the project, a restart, or a reconnect of this server. A false editor.lspListening or editor.dapListening comes with serversNote, and editor_launch restart binds the port again. editor.scan says whether the editor is scanning, which editor_run waits out before starting a game. A game announced in a protocol this server does not speak is listed under unreadable, during an upgrade that moves the protocol, until the halves match.",
+    answer: "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. It stays named after the run ends, beside processActive false, so editor_output can still read what that run printed; null when there is no run at all. startedAt says when it began, and endedAt when it ended, wherever something saw the end: a run adopted from a note another server wrote can have ended hours before this server started. editor.lspListening and editor.dapListening say whether anything accepts connections on the ports the editor names, lspPort and dapPort: Godot binds each once, as the editor starts, and reports a failure only in the log panel of the editor itself, so a false comes with serversNote, and editor_launch restart binds it again. 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. Any editor of this project running and not yet connected, whoever opened it, makes it true as well and is named under editorsNotYetConnected with its pid and start time, so a restart a reconnect interrupted after its launch is not read as nothing being there. 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. Every other call made while an editor is arriving, before its greeting or while it is looked up, waits up to ten seconds for it to settle rather than acting on connected as it reads in that window.",
     parameters: {},
     requires: []
   },
@@ -35228,6 +35295,7 @@ var TOOL_SPECS = [
     name: "runtime_input",
     title: "Send input to the game",
     description: "Input to the running game: a whole click on a Control or a 3D node named by path or on a control named by the words on it, an item chosen out of a menu, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it. On gdharness's own desktop, where a windowed run goes, Windows refuses to say where the pointer is: every pointer answer there carries pointer_on_hidden_desktop, and the first of the run pointer_note saying why it matters: get_mouse_position() on the root window, and the mouse positions derived from it, read a meaningless position, while what reads the event itself (the control under it, hover, tooltips, input handlers) gets the injected position.",
+    answer: 'click: what was under the pointer, and what became of the control: in_tree, removed or freed. Named by says, found says which match it was, and found.pressedOn says "the words" for words in a RichTextLabel pressed where they are drawn, or "the middle of the label" with a note saying why they could not be placed; on a rich label link_pressed says whether the press reached a link, with link_meta giving the meta the label reports clicked, an empty one included. A control scrolled into view first is scrolled each container out from it a frame after the one inside, and scrolled_into_view says whether a scroll value changed. A button in toggle mode, a CheckBox or CheckButton included, answers pressed with before and after, its button_pressed either side of the click: the same value twice is a click the game undid, and after is null when the click freed it. A refusal for a pointer turned off names where mouse_behavior_recursive was set. On a 3D node landed says the interface did not swallow the press: no control under the pointer stopped it, a control letting the pointer pass included, and every viewport on the way out from the room had the pointer over what shows the room. choose: what was chosen, read before the press, which is heard rather than assumed; what became of the control named (in_tree, removed or freed, since a game can rebuild its screen on the pick); and what the button in front of the menu shows now when it is still there. A menu is opened rather than clicked because its items are drawn rather than built, and the item is looked for as the menu stands once open, since a game can fill a menu as it opens.',
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       pid: RUNNING_PID,
@@ -35317,12 +35385,12 @@ var TOOL_SPECS = [
     operations: {
       click: {
         effect: "additive",
-        summary: `press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed. The control is named by nodePath, or by says with the words on it, found under nodePath when both are given, and the answer then says under found which match it was. Words that are part of a RichTextLabel are pressed where they are drawn rather than at the label's middle, so a link among them is the one pressed: found.pressedOn says "the words", or "the middle of the label" with a note saying why they could not be placed, and on a rich label link_pressed says whether the press reached a link, with link_meta giving the meta the label reports clicked, an empty one included. A control out of sight inside a ScrollContainer is scrolled to first, each container out from it a frame after the one inside, and scrolled_into_view says whether a scroll value changed. A button in toggle mode, a CheckBox or CheckButton included, answers pressed with before and after, its button_pressed either side of the click: the same value twice is a click the game undid, and after is null when the click freed it. A disabled button, and a control that does not process (the game paused, say), are refused: the pointer reaches them and the press does nothing. So is a control whose pointer a mouse_behavior_recursive set to disabled on it or above it has turned off, naming where it was set; by says, one the pointer can reach is picked over it. A 3D node is clicked where it is drawn, and landed then says the interface did not swallow the press: no control under the pointer stopped it, a control letting the pointer pass included, and every viewport on the way out from the room had the pointer over what shows the room`,
+        summary: "press and release on a Control, a frame apart, named by nodePath or by says with the words on it (found under nodePath when both are given), or on a 3D node where it is drawn. A control out of sight inside a ScrollContainer is scrolled to first, and a link in a RichTextLabel is pressed where its words are drawn. A disabled button, a control that does not process and one whose pointer mouse_behavior_recursive turned off are refused, since the press would do nothing; by says, one the pointer can reach is picked over it",
         requires: []
       },
       choose: {
         effect: "additive",
-        summary: "take an item out of a menu, by what it says or by where it is in the list. A menu's items are drawn rather than built, so there is nothing to click: the menu is opened, the item is looked for in it as it stands then, since a game can fill a menu as it opens, and the item takes the focus and ui_accept presses it, which is the engine's own path, needs no window, and does not depend on what ui_accept is bound to. A disabled or hidden button in front of the menu is refused, and so is a press the menu did not take, which is heard rather than assumed. Answers with what was chosen, read before the press, what became of the control named (in_tree, removed or freed, since a game can rebuild its screen on the pick), and what the button in front of it shows now when it is still there",
+        summary: "take an item out of a menu, by what it says or by where it is in the list: the menu is opened, the item found in it as it stands then, and pressed through the engine's own path, which needs no window and does not depend on what ui_accept is bound to. A disabled or hidden button in front of the menu is refused, and so is a press the menu did not take",
         requires: ["nodePath"]
       },
       action: { effect: "additive", summary: "press an action, or hold it", requires: ["action"] },
@@ -35486,6 +35554,10 @@ function describeOperations(spec) {
   const fallback = spec.defaultOperation ? ` Default ${spec.defaultOperation}.` : "";
   return ` Operations: ${lines.join("; ")}.${fallback}`;
 }
+function servedDescription(spec) {
+  const answer = spec.answer === undefined ? "" : " The tool reference in the gdharness skill, and the site, say what every field of the answer means.";
+  return `${spec.description}${describeOperations(spec)}${answer}`;
+}
 function buildToolDefinitions() {
   return TOOL_SPECS.map((spec) => {
     const properties = {};
@@ -35507,7 +35579,7 @@ function buildToolDefinitions() {
     return {
       name: spec.name,
       title: spec.title,
-      description: `${spec.description}${describeOperations(spec)}`,
+      description: servedDescription(spec),
       inputSchema: {
         type: "object",
         properties,
@@ -36310,6 +36382,22 @@ var PLAYING_STATUS_MS = 1000;
 var SCAN_START_MS = 2000;
 var SCAN_SETTLED_MS = 500;
 var REIMPORT_TIMEOUT_MS = 300000;
+function engineFlagsNote(args) {
+  const among = engineFlagsAmongGameArgs(args);
+  if (among.length === 0) {
+    return;
+  }
+  const named = among.join(", ");
+  return `${named} ${among.length === 1 ? "is a flag" : "are flags"} the engine reads, and args goes to the game after --, where the engine does not read ${among.length === 1 ? "it" : "them"}. engineArgs hands the engine its own flags; ${among.length === 1 ? "leave it" : "leave them"} in args only for a game that reads ${among.length === 1 ? "that flag" : "those flags"} itself.`;
+}
+var OPS_ELSEWHERE = {
+  runtime_invoke: { get: "runtime_inspect property", property: "runtime_inspect property" }
+};
+function opElsewhere(tool, requested) {
+  const ops = Object.hasOwn(OPS_ELSEWHERE, tool) ? OPS_ELSEWHERE[tool] : undefined;
+  const where = ops !== undefined && typeof requested === "string" && Object.hasOwn(ops, requested) ? ops[requested] : undefined;
+  return where === undefined ? "" : ` A value is read with ${where}.`;
+}
 var AUDIO_BUS_OPS = new Set([
   "add_audio_bus",
   "remove_audio_bus",
@@ -36732,9 +36820,9 @@ function callersAnswer(totals, asked) {
   };
 }
 var MOST_ENGINE_ENTRIES = 200;
-function foldedEntriesAnswer(log) {
+function foldedEntriesAnswer(log, floor = "warning") {
   const problems = log.selectFolded({
-    severity: "warning",
+    severity: floor,
     sinceLastCall: false,
     limit: MOST_ENGINE_ENTRIES
   });
@@ -37413,7 +37501,7 @@ class GodotServer {
       } else {
         return {
           ok: false,
-          response: this.createErrorResponse(`${spec.name} has no op ${JSON.stringify(requested)}. Valid ops: ${valid.join(", ")}.`)
+          response: this.createErrorResponse(`${spec.name} has no op ${JSON.stringify(requested)}. Valid ops: ${valid.join(", ")}.${opElsewhere(spec.name, requested)}`)
         };
       }
     }
@@ -37762,6 +37850,25 @@ class GodotServer {
     }
     return { ok: true, value: given };
   }
+  engineArguments(args) {
+    if (args["engineArgs"] === undefined) {
+      return { ok: true, value: [] };
+    }
+    const given = readStringArray(args, "engineArgs");
+    if (given === undefined) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("engineArgs must be a list of strings.", [
+          'Pass engine flags, such as ["--verbose"] or ["--fixed-fps", "60"]'
+        ])
+      };
+    }
+    const checked = engineFlags(given);
+    if (!checked.ok) {
+      return { ok: false, response: this.createErrorResponse(checked.reason) };
+    }
+    return { ok: true, value: given };
+  }
   runEnvironment(args) {
     const savesIn = readNonEmptyString(args, "savesIn");
     if (savesIn !== undefined && !isAbsolute3(savesIn)) {
@@ -39578,6 +39685,10 @@ class GodotServer {
     if (!given.ok) {
       return given.response;
     }
+    const flags = this.engineArguments(args);
+    if (!flags.ok) {
+      return flags.response;
+    }
     const asked = this.runEnvironment(args);
     if (!asked.ok) {
       return asked.response;
@@ -39599,7 +39710,7 @@ class GodotServer {
     }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
-      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, scanned, asked.value);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, scanned, asked.value, flags.value);
     }
     await this.pickUpWhatTheEditorIsPlaying();
     let ended = null;
@@ -39626,7 +39737,7 @@ class GodotServer {
     const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
     const silent = resolveSilent(args["silent"], process.env) && !headless;
     const profiled = readBoolean(args, "profile") === true;
-    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && !needsItsOwnProcess(asked.value) && !silent) {
+    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && flags.value.length === 0 && !needsItsOwnProcess(asked.value) && !silent) {
       return await this.playThroughEditor(sceneArgument, refreshed.value, scanned, project.value.path, alreadyPlaying, runtimeWaitMs, ended, profiled);
     }
     const cmdArgs = runArguments({
@@ -39634,6 +39745,7 @@ class GodotServer {
       headless,
       scene: sceneArgument,
       userArgs: given.value,
+      engineArgs: flags.value,
       silent
     });
     this.logDebug(`Running Godot project: ${engine.value} ${cmdArgs.join(" ")}`);
@@ -39646,7 +39758,7 @@ class GodotServer {
     started.announcedBefore = alreadyPlaying;
     started.bootScene = runtimeWaitMs.scene;
     this.activeProcess = started;
-    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && given.value.length > 0 ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && needsItsOwnProcess(asked.value) ? " The editor plays a game with its own environment, so a run given one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && silent ? " The editor cannot play a game silent, which takes an engine flag, so this one was " + `started here${args["silent"] === true ? "" : ", silent because GDHARNESS_SILENT says so"}: the debug_* tools answer only for a game the editor is playing, and silent: false plays it through the editor.` : "";
+    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && (given.value.length > 0 || flags.value.length > 0) ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && needsItsOwnProcess(asked.value) ? " The editor plays a game with its own environment, so a run given one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && silent ? " The editor cannot play a game silent, which takes an engine flag, so this one was " + `started here${args["silent"] === true ? "" : ", silent because GDHARNESS_SILENT says so"}: the debug_* tools answer only for a game the editor is playing, and silent: false plays it through the editor.` : "";
     const endedForThis = endedToStartThis(ended);
     const stranded = wereHereFirst.filter((one) => one.pid !== ended?.pid && alive(one.pid));
     const alsoRunning = leftRunningNote(stranded);
@@ -39656,6 +39768,7 @@ class GodotServer {
       alsoRunning: stranded.length === 0 ? undefined : stranded.map((one) => one.pid),
       pid: started.pid,
       arguments: cmdArgs,
+      argsNote: engineFlagsNote(given.value),
       transcript: started.transcript,
       profile: profileOnStart(profiled, "gdharness", runtimeAddonRegistered(project.value.path)),
       refreshedClasses: refreshed.value,
@@ -40558,10 +40671,17 @@ class GodotServer {
   async currentRun() {
     return this.activeProcess ?? await this.adoptRecordedRun();
   }
-  async checkBoot(godotPath, projectPath, scene, args, userArgs, scanned, asked = {}) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs, scanned, asked = {}, engineArgs = []) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
-    const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
+    const cmdArgs = runArguments({
+      projectPath,
+      headless: true,
+      scene,
+      quitAfter: frames,
+      userArgs,
+      engineArgs
+    });
     const boot = this.spawnGame(godotPath, cmdArgs, needsItsOwnProcess(asked) ? environmentFor({ ...asked, runtimeDirectory: runtimeDirectory() }) : undefined);
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {
@@ -40589,9 +40709,10 @@ class GodotServer {
       frames,
       errors,
       warnings,
+      argsNote: engineFlagsNote(userArgs),
       ...scanWaitAnswer(scanned),
       savesNote: asked.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
-      ...foldedEntriesAnswer(boot.log)
+      ...foldedEntriesAnswer(boot.log, engineArgs.includes("--verbose") ? "info" : "warning")
     });
   }
   async handleRunProfile(args) {

package/build/keeper.js

@@ -364,6 +364,32 @@ function envValue(name, variables = process.env) {
   const value = variables[name];
   return value === undefined || value === "" ? undefined : value;
 }
+var ENGINE_FLAGS = Object.freeze({
+  "--verbose": "none",
+  "--quiet": "none",
+  "--debug-collisions": "none",
+  "--debug-paths": "none",
+  "--debug-navigation": "none",
+  "--debug-avoidance": "none",
+  "--debug-stringnames": "none",
+  "--debug-canvas-item-redraw": "none",
+  "--debug-mute-audio": "none",
+  "--print-fps": "none",
+  "--gpu-profile": "none",
+  "--gpu-validation": "none",
+  "--gpu-abort": "none",
+  "--disable-vsync": "none",
+  "--frame-delay": "number",
+  "--time-scale": "number",
+  "--fixed-fps": "number",
+  "--max-fps": "number",
+  "--resolution": "size"
+});
+var SET_BY_ARGUMENT = Object.freeze({
+  "--headless": "headless",
+  "--audio-driver": "silent",
+  "--quit-after": "frames, on editor_run check"
+});
 
 // src/runtime-client.ts
 function runtimeDirectory(variables = process.env) {

package/package.json

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