gdharness 0.10.0 → 0.10.2

package/build/cli.js

@@ -155,6 +155,9 @@ function runArguments(options) {
   if (options.scene !== null) {
     args.push(`res://${options.scene}`);
   }
+  if (options.userArgs !== undefined && options.userArgs.length > 0) {
+    args.push("--", ...options.userArgs);
+  }
   return args;
 }
 function editorArguments(projectPath, ports) {
@@ -15680,10 +15683,15 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_run",
-      description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way.",
+      description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice.",
       parameters: {
         projectPath: PROJECT_PATH,
         scene: { type: "string", description: "A scene to run instead of the main scene." },
+        args: {
+          type: "array",
+          items: { type: "string" },
+          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.`
+        },
         headless: { type: "boolean", description: "start: force a window or no window." },
         frames: { type: "number", description: "check: frames to run before quitting. Default 3." },
         timeoutMs: {
@@ -35780,6 +35788,7 @@ import { existsSync as existsSync10, readdirSync as readdirSync5, readFileSync a
 import { createConnection as createConnection3 } from "node:net";
 import { tmpdir as tmpdir4 } from "node:os";
 import { join as join13, resolve as resolve4 } from "node:path";
+import { setTimeout as delay2 } from "node:timers/promises";
 function runtimeDirectory(variables = process.env) {
   const explicit = envValue("GDHARNESS_RUNTIME_DIR", variables);
   if (explicit) {
@@ -35868,6 +35877,22 @@ function announcedIn(directory) {
   }
   return found;
 }
+async function announcedSince(projectPath, before, waiting = {}) {
+  const wanted = resolve4(projectPath);
+  const directories = waiting.directories ?? runtimeDirectories();
+  const until = Date.now() + Math.max(waiting.budgetMs ?? ANNOUNCE_BUDGET_MS, 0);
+  for (;; ) {
+    const fresh = discoverRuntimes(directories).find((endpoint) => !before.has(endpoint.pid) && resolve4(endpoint.project.path) === wanted);
+    if (fresh !== undefined) {
+      return fresh;
+    }
+    const left = until - Date.now();
+    if (left <= 0 || waiting.giveUp?.() === true) {
+      return null;
+    }
+    await delay2(Math.min(LOOK_EVERY_MS, left));
+  }
+}
 function describe2(endpoint) {
   return `pid ${endpoint.pid} on ${endpoint.address}:${endpoint.port} (${endpoint.project.name || "unnamed"} at ${endpoint.project.path})`;
 }
@@ -35994,7 +36019,7 @@ function runtimeRequest(endpoint, command, params, timeoutMs) {
     });
   });
 }
-var RUNTIME_PROTOCOL = 2, ANNOUNCEMENT_PATTERN, nextRequestId = 1;
+var RUNTIME_PROTOCOL = 2, ANNOUNCEMENT_PATTERN, LOOK_EVERY_MS = 50, ANNOUNCE_BUDGET_MS = 5000, nextRequestId = 1;
 var init_runtime_client = __esm(() => {
   ANNOUNCEMENT_PATTERN = /^runtime-(\d+)\.json$/;
 });
@@ -36010,13 +36035,17 @@ function installedAddonVersion(projectPath) {
   const said = readFileSync12(marker, "utf8").trim();
   return said === "" ? null : said;
 }
-var ADDONS2, VERSION_MARKER2 = ".gdharness-version";
+var ADDONS2, RUNTIME_AUTOLOAD2, VERSION_MARKER2 = ".gdharness-version";
 var init_setup = __esm(() => {
   init_class_cache();
   init_headless();
   init_resources();
   init_server_version();
   ADDONS2 = ["gdharness_editor", "gdharness_runtime", "auto_reload"];
+  RUNTIME_AUTOLOAD2 = {
+    name: "GdharnessRuntime",
+    path: "addons/gdharness_runtime/runtime_autoload.gd"
+  };
 });
 
 // src/server.ts
@@ -36024,7 +36053,7 @@ import { execFile as execFile5, spawn } from "node:child_process";
 import { existsSync as existsSync12, mkdirSync as mkdirSync7, mkdtempSync as mkdtempSync3, readdirSync as readdirSync6, readFileSync as readFileSync13, realpathSync as realpathSync2, rmSync as rmSync8 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
 import { basename as basename2, dirname as dirname9, join as join15, normalize as normalize3 } from "node:path";
-import { setTimeout as delay2 } from "node:timers/promises";
+import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { promisify as promisify5 } from "node:util";
 function patienceForFrames(frames, atLeast) {
@@ -36755,6 +36784,21 @@ class GodotServer {
     }
     return { ok: true, value: { path, file } };
   }
+  gameArguments(args) {
+    if (args["args"] === undefined) {
+      return { ok: true, value: [] };
+    }
+    const given = readStringArray(args, "args");
+    if (given === undefined) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("args must be a list of strings.", [
+          `Pass the game's own flags, such as ["--level=2"]`
+        ])
+      };
+    }
+    return { ok: true, value: given };
+  }
   async debuggedGame() {
     const game = this.activeProcess;
     if (game !== null && game.exitCode !== null) {
@@ -37341,7 +37385,7 @@ class GodotServer {
       if (Date.now() >= deadline) {
         return false;
       }
-      await delay2(250);
+      await delay3(250);
     }
   }
   async handleLaunchEditor(args) {
@@ -37415,6 +37459,10 @@ class GodotServer {
     if (sceneToRun && !sceneToRun.ok) {
       return this.createErrorResponse(sceneToRun.reason, PATH_SOLUTIONS);
     }
+    const given = this.gameArguments(args);
+    if (!given.ok) {
+      return given.response;
+    }
     if (!sceneToRun && !hasMainScene(project.value.file)) {
       return this.createErrorResponse("The project sets no main scene, so there is nothing to run.", [
         "Pass scene to run one scene",
@@ -37431,37 +37479,62 @@ class GodotServer {
     }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
-      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value);
     }
     if (this.activeProcess?.exitCode === null) {
       this.logDebug("Ending the running game before starting another");
       await this.endActiveGame();
     }
+    const alreadyPlaying = new Set(discoverRuntimes().map((endpoint) => endpoint.pid));
     const headless = resolveHeadless(args["headless"], {
       platform: process.platform,
       variables: process.env
     });
-    if (this.godotBridge.isConnected() && (!headless || editorPlaysHeadless(project.value.file))) {
-      return await this.playThroughEditor(sceneArgument, refreshed.value);
+    const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
+    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0) {
+      return await this.playThroughEditor(sceneArgument, refreshed.value, project.value.path, alreadyPlaying);
     }
     const cmdArgs = runArguments({
       projectPath: project.value.path,
       headless,
-      scene: sceneArgument
+      scene: sceneArgument,
+      userArgs: given.value
     });
     this.logDebug(`Running Godot project: ${engine.value} ${cmdArgs.join(" ")}`);
     const started = this.spawnGame(engine.value, cmdArgs);
     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." : "";
     return this.jsonTextResponse({
       started: true,
       through: "gdharness",
       pid: started.process.pid ?? null,
       arguments: cmdArgs,
       refreshedClasses: refreshed.value,
-      message: "Use editor_output for what it prints and editor_run stop to end it."
+      runtime: await this.runtimeUp(project.value.path, alreadyPlaying),
+      message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}`
+    });
+  }
+  async runtimeUp(projectPath, before) {
+    if (!existsSync12(join15(projectPath, RUNTIME_AUTOLOAD2.path))) {
+      return {
+        listening: false,
+        note: "this project has no gdharness_runtime addon, so the runtime_* tools have nothing to talk to"
+      };
+    }
+    const endpoint = await announcedSince(projectPath, before, {
+      giveUp: () => this.dapClient?.isStopped() === true
     });
+    if (endpoint === null) {
+      const held = this.dapClient?.whereItStopped() ?? null;
+      return {
+        listening: false,
+        note: held === null ? `nothing announced itself within ${ANNOUNCE_BUDGET_MS}ms: the game may be slow to boot, or its runtime is not coming up` : "the game stopped before its runtime came up, so the runtime_* tools have nothing to talk to yet: debug_control continue lets it carry on",
+        heldAt: held
+      };
+    }
+    return { listening: true, pid: endpoint.pid, port: endpoint.port };
   }
-  async playThroughEditor(scene, refreshedClasses) {
+  async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying) {
     const log = new GameLog;
     try {
       await this.dap().connect();
@@ -37490,6 +37563,7 @@ class GodotServer {
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
       debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
+      runtime: await this.runtimeUp(projectPath, alreadyPlaying),
       message: "The editor is playing it, so its debugger holds it: the debug_* tools can reach it, " + "editor_output reads its console through the debug adapter, and editor_run stop ends it."
     });
   }
@@ -37554,10 +37628,10 @@ class GodotServer {
     });
     return started;
   }
-  async checkBoot(godotPath, projectPath, scene, args) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
-    const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames });
+    const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
     const boot = this.spawnGame(godotPath, cmdArgs);
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {

package/build/index.js

@@ -10129,7 +10129,7 @@ import { execFile as execFile3, spawn } from "node:child_process";
 import { existsSync as existsSync7, mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync2, readdirSync as readdirSync5, readFileSync as readFileSync9, realpathSync as realpathSync2, rmSync as rmSync4 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
 import { basename, dirname as dirname4, join as join9, normalize as normalize2 } from "node:path";
-import { setTimeout as delay2 } from "node:timers/promises";
+import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify as promisify3 } from "node:util";
 
@@ -26154,6 +26154,9 @@ function runArguments(options) {
   if (options.scene !== null) {
     args.push(`res://${options.scene}`);
   }
+  if (options.userArgs !== undefined && options.userArgs.length > 0) {
+    args.push("--", ...options.userArgs);
+  }
   return args;
 }
 function editorArguments(projectPath, ports) {
@@ -27417,6 +27420,7 @@ import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as
 import { createConnection as createConnection3 } from "node:net";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join7, resolve as resolve4 } from "node:path";
+import { setTimeout as delay2 } from "node:timers/promises";
 
 // src/tool-args.ts
 function asParams(value) {
@@ -27560,6 +27564,24 @@ function announcedIn(directory) {
   }
   return found;
 }
+var LOOK_EVERY_MS = 50;
+var ANNOUNCE_BUDGET_MS = 5000;
+async function announcedSince(projectPath, before, waiting = {}) {
+  const wanted = resolve4(projectPath);
+  const directories = waiting.directories ?? runtimeDirectories();
+  const until = Date.now() + Math.max(waiting.budgetMs ?? ANNOUNCE_BUDGET_MS, 0);
+  for (;; ) {
+    const fresh = discoverRuntimes(directories).find((endpoint) => !before.has(endpoint.pid) && resolve4(endpoint.project.path) === wanted);
+    if (fresh !== undefined) {
+      return fresh;
+    }
+    const left = until - Date.now();
+    if (left <= 0 || waiting.giveUp?.() === true) {
+      return null;
+    }
+    await delay2(Math.min(LOOK_EVERY_MS, left));
+  }
+}
 function describe2(endpoint) {
   return `pid ${endpoint.pid} on ${endpoint.address}:${endpoint.port} (${endpoint.project.name || "unnamed"} at ${endpoint.project.path})`;
 }
@@ -27692,6 +27714,10 @@ function runtimeRequest(endpoint, command, params, timeoutMs) {
 import { cpSync, existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync8, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname3, join as join8 } from "node:path";
 var ADDONS = ["gdharness_editor", "gdharness_runtime", "auto_reload"];
+var RUNTIME_AUTOLOAD = {
+  name: "GdharnessRuntime",
+  path: "addons/gdharness_runtime/runtime_autoload.gd"
+};
 var VERSION_MARKER = ".gdharness-version";
 function installedAddonVersion(projectPath) {
   const marker = join8(projectPath, "addons", ADDONS[0], VERSION_MARKER);
@@ -28290,10 +28316,15 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_run",
-    description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way.",
+    description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice.",
     parameters: {
       projectPath: PROJECT_PATH,
       scene: { type: "string", description: "A scene to run instead of the main scene." },
+      args: {
+        type: "array",
+        items: { type: "string" },
+        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.`
+      },
       headless: { type: "boolean", description: "start: force a window or no window." },
       frames: { type: "number", description: "check: frames to run before quitting. Default 3." },
       timeoutMs: {
@@ -29535,6 +29566,21 @@ class GodotServer {
     }
     return { ok: true, value: { path, file } };
   }
+  gameArguments(args) {
+    if (args["args"] === undefined) {
+      return { ok: true, value: [] };
+    }
+    const given = readStringArray(args, "args");
+    if (given === undefined) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("args must be a list of strings.", [
+          `Pass the game's own flags, such as ["--level=2"]`
+        ])
+      };
+    }
+    return { ok: true, value: given };
+  }
   async debuggedGame() {
     const game = this.activeProcess;
     if (game !== null && game.exitCode !== null) {
@@ -30121,7 +30167,7 @@ class GodotServer {
       if (Date.now() >= deadline) {
         return false;
       }
-      await delay2(250);
+      await delay3(250);
     }
   }
   async handleLaunchEditor(args) {
@@ -30195,6 +30241,10 @@ class GodotServer {
     if (sceneToRun && !sceneToRun.ok) {
       return this.createErrorResponse(sceneToRun.reason, PATH_SOLUTIONS);
     }
+    const given = this.gameArguments(args);
+    if (!given.ok) {
+      return given.response;
+    }
     if (!sceneToRun && !hasMainScene(project.value.file)) {
       return this.createErrorResponse("The project sets no main scene, so there is nothing to run.", [
         "Pass scene to run one scene",
@@ -30211,37 +30261,62 @@ class GodotServer {
     }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
-      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value);
     }
     if (this.activeProcess?.exitCode === null) {
       this.logDebug("Ending the running game before starting another");
       await this.endActiveGame();
     }
+    const alreadyPlaying = new Set(discoverRuntimes().map((endpoint) => endpoint.pid));
     const headless = resolveHeadless(args["headless"], {
       platform: process.platform,
       variables: process.env
     });
-    if (this.godotBridge.isConnected() && (!headless || editorPlaysHeadless(project.value.file))) {
-      return await this.playThroughEditor(sceneArgument, refreshed.value);
+    const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
+    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0) {
+      return await this.playThroughEditor(sceneArgument, refreshed.value, project.value.path, alreadyPlaying);
     }
     const cmdArgs = runArguments({
       projectPath: project.value.path,
       headless,
-      scene: sceneArgument
+      scene: sceneArgument,
+      userArgs: given.value
     });
     this.logDebug(`Running Godot project: ${engine.value} ${cmdArgs.join(" ")}`);
     const started = this.spawnGame(engine.value, cmdArgs);
     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." : "";
     return this.jsonTextResponse({
       started: true,
       through: "gdharness",
       pid: started.process.pid ?? null,
       arguments: cmdArgs,
       refreshedClasses: refreshed.value,
-      message: "Use editor_output for what it prints and editor_run stop to end it."
+      runtime: await this.runtimeUp(project.value.path, alreadyPlaying),
+      message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}`
+    });
+  }
+  async runtimeUp(projectPath, before) {
+    if (!existsSync7(join9(projectPath, RUNTIME_AUTOLOAD.path))) {
+      return {
+        listening: false,
+        note: "this project has no gdharness_runtime addon, so the runtime_* tools have nothing to talk to"
+      };
+    }
+    const endpoint = await announcedSince(projectPath, before, {
+      giveUp: () => this.dapClient?.isStopped() === true
     });
+    if (endpoint === null) {
+      const held = this.dapClient?.whereItStopped() ?? null;
+      return {
+        listening: false,
+        note: held === null ? `nothing announced itself within ${ANNOUNCE_BUDGET_MS}ms: the game may be slow to boot, or its runtime is not coming up` : "the game stopped before its runtime came up, so the runtime_* tools have nothing to talk to yet: debug_control continue lets it carry on",
+        heldAt: held
+      };
+    }
+    return { listening: true, pid: endpoint.pid, port: endpoint.port };
   }
-  async playThroughEditor(scene, refreshedClasses) {
+  async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying) {
     const log = new GameLog;
     try {
       await this.dap().connect();
@@ -30270,6 +30345,7 @@ class GodotServer {
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
       debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
+      runtime: await this.runtimeUp(projectPath, alreadyPlaying),
       message: "The editor is playing it, so its debugger holds it: the debug_* tools can reach it, " + "editor_output reads its console through the debug adapter, and editor_run stop ends it."
     });
   }
@@ -30334,10 +30410,10 @@ class GodotServer {
     });
     return started;
   }
-  async checkBoot(godotPath, projectPath, scene, args) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
-    const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames });
+    const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
     const boot = this.spawnGame(godotPath, cmdArgs);
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {

package/package.json

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