gdharness 0.10.1 → 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. 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.",
+      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: {
@@ -36776,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) {
@@ -37436,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",
@@ -37452,7 +37479,7 @@ 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");
@@ -37463,17 +37490,20 @@ class GodotServer {
       platform: process.platform,
       variables: process.env
     });
-    if (this.godotBridge.isConnected() && (!headless || editorPlaysHeadless(project.value.file))) {
+    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",
@@ -37481,7 +37511,7 @@ class GodotServer {
       arguments: cmdArgs,
       refreshedClasses: refreshed.value,
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying),
-      message: "Use editor_output for what it prints and editor_run stop to end it."
+      message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}`
     });
   }
   async runtimeUp(projectPath, before) {
@@ -37598,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

@@ -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) {
@@ -28313,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. 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.",
+    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: {
@@ -29558,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) {
@@ -30218,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",
@@ -30234,7 +30261,7 @@ 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");
@@ -30245,17 +30272,20 @@ class GodotServer {
       platform: process.platform,
       variables: process.env
     });
-    if (this.godotBridge.isConnected() && (!headless || editorPlaysHeadless(project.value.file))) {
+    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",
@@ -30263,7 +30293,7 @@ class GodotServer {
       arguments: cmdArgs,
       refreshedClasses: refreshed.value,
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying),
-      message: "Use editor_output for what it prints and editor_run stop to end it."
+      message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}`
     });
   }
   async runtimeUp(projectPath, before) {
@@ -30380,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.1",
+  "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",