gdharness 0.6.4 → 0.6.5

package/build/cli.js

@@ -8962,7 +8962,7 @@ var init_versions = __esm(() => {
   version = {
     major: 4,
     minor: 6,
-    patch: 4
+    patch: 5
   };
 });
 
@@ -15744,12 +15744,12 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "runtime_inspect",
-      description: "Questions about the running game: the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
+      description: "Questions about the running game: what is written on the screen, the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         nodePath: {
           type: "string",
-          description: "tree, find: where to start, default /root. rect: the node to place. property: the node to read."
+          description: "tree, find, text: where to start, default /root. rect: the node to place. property: the node to read."
         },
         property: {
           type: "string",
@@ -15771,6 +15771,10 @@ var init_tool_definitions = __esm(() => {
         },
         group: { type: "string", description: "find: a group the node is in." },
         limit: { type: "number", description: "find: the most nodes to answer with. Default 100." },
+        includeHidden: {
+          type: "boolean",
+          description: "text: read hidden nodes as well, for checking that something is not showing. Default false."
+        },
         metrics: {
           type: "array",
           items: { type: "string" },
@@ -15780,6 +15784,10 @@ var init_tool_definitions = __esm(() => {
       requires: [],
       operations: {
         tree: { summary: "the live scene tree", requires: [] },
+        text: {
+          summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+          requires: []
+        },
         find: {
           summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
           requires: []
@@ -35844,6 +35852,9 @@ import { basename as basename2, dirname as dirname9, join as join15, normalize a
 import { setTimeout as delay2 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { promisify as promisify5 } from "node:util";
+function patienceForFrames(frames, atLeast) {
+  return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
+}
 function escapingPropertyValue(properties) {
   if (typeof properties !== "object" || properties === null) {
     return;
@@ -36323,6 +36334,12 @@ class GodotServer {
             });
           case "find":
             return await this.handleFindRuntimeNodes(args);
+          case "text":
+            return await this.handleRuntimeCommand("read_text", {
+              projectPath: args["projectPath"],
+              root: readNonEmptyString(args, "nodePath") ?? "/root",
+              include_hidden: readBoolean(args, "includeHidden") ?? false
+            });
           case "rect":
             return await this.handleRuntimeCommand("get_rect", {
               projectPath: args["projectPath"],
@@ -37367,8 +37384,11 @@ class GodotServer {
     const nodePath = readNonEmptyString(args, "nodePath") ?? "";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     switch (op) {
-      case "frames":
-        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames: readPositiveNumber(args, "frames") ?? 1 }, patience);
+      case "frames": {
+        const frames = readPositiveNumber(args, "frames") ?? 1;
+        const waited = patienceForFrames(frames, patience);
+        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
+      }
       case "signal":
         return await this.handleRuntimeCommand("wait_signal", {
           projectPath: args["projectPath"],
@@ -37391,7 +37411,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run5, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, BRIDGE_RETRY_MS = 2000, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, HEADLESS_OPERATIONS, PROJECT_INFO_SECTIONS;
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run5, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, SLOWEST_FRAME_RATE = 20, BRIDGE_RETRY_MS = 2000, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, HEADLESS_OPERATIONS, PROJECT_INFO_SECTIONS;
 var init_server3 = __esm(() => {
   init_mcp();
   init_stdio2();
@@ -38740,6 +38760,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 
 | Ask | Tool |
 | --- | --- |
+| What a screen says | \`runtime_inspect text\`, which reads what is drawn and leaves out what is hidden |
 | Where a control is, and whether it is visible | \`runtime_inspect\` \`find\`, \`rect\` |
 | What a property reads right now | \`runtime_inspect\` \`property\`, \`runtime_invoke\` |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |

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

@@ -57,6 +57,7 @@ func _init() -> void:
 		"ping": _ping,
 		"get_tree": _queries.get_tree,
 		"find_nodes": _queries.find_nodes,
+		"read_text": _queries.read_text,
 		"get_rect": _queries.get_rect,
 		"get_property": _queries.get_property,
 		"set_property": _queries.set_property,

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

@@ -10,6 +10,10 @@ const Values = preload("runtime_values.gd")
 const FIND_LIMIT: int = 100
 const FIND_LIMIT_CEILING: int = 1000
 
+## The most lines one read answers with. A screen is a few dozen; a thousand is a tree somebody
+## pointed this at by mistake.
+const READ_LIMIT: int = 500
+
 var _host: Node
 var _values: Values
 
@@ -138,6 +142,60 @@ func _matches(
 ## is drawn in, in both the canvas coordinates the node reports and the window pixels input
 ## arrives in. The two differ whenever the project stretches its viewport, which is what made a
 ## rect unusable for a click.
+## Every line of text under a node, in the order somebody reads the screen.
+##
+## The question a caller asks most often, and the one that cost the most to answer: reading a panel
+## was a find for every label with the path of each beside it, a few hundred characters apiece to
+## carry a sentence of six words. Long is the smaller half of it. A find answers off nodes nobody
+## can see, and a panel keeps its empty state in the tree beside its rows, so "Nothing posted" came
+## back next to the three things posted and was believed twice in one session.
+##
+## A hidden node is left out and so is everything under it, because what a player reads is what is
+## drawn. [param include_hidden] asks for the lot instead, which is what a caller checking that
+## something is not showing wants.
+func read_text(params: Dictionary) -> Dictionary:
+	var root_path: String = str(params.get("root", "/root"))
+	var include_hidden: bool = bool(params.get("include_hidden", false))
+
+	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
+	if root == null:
+		return {"type": "error", "message": "Node not found: " + root_path}
+
+	var lines: PackedStringArray = PackedStringArray()
+	_read_into(root, include_hidden, lines)
+	return {
+		"type": "text",
+		"root": root_path,
+		"lines": lines,
+		"count": lines.size(),
+		"truncated": lines.size() >= READ_LIMIT,
+	}
+
+
+## Walks [param node] depth first, which is the order the screen is laid out in and the order a
+## person reads it.
+func _read_into(node: Node, include_hidden: bool, into: PackedStringArray) -> void:
+	if into.size() >= READ_LIMIT:
+		return
+	var control: CanvasItem = node as CanvasItem
+	if not include_hidden and control != null and not control.visible:
+		return
+	var said: String = _said_by(node)
+	if not said.is_empty():
+		into.append(said)
+	for child: Node in node.get_children():
+		_read_into(child, include_hidden, into)
+
+
+## What one node says, or "" for a node that says nothing. Anything with a `text` property, which
+## is every label, button and field the interface is built out of.
+static func _said_by(node: Node) -> String:
+	for property: Dictionary in node.get_property_list():
+		if str(property.get("name", "")) == "text" and int(property.get("type", 0)) == TYPE_STRING:
+			return str(node.get("text")).strip_edges()
+	return ""
+
+
 func get_rect(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	if node_path.is_empty():

package/build/index.js

@@ -15311,7 +15311,7 @@ ${content.join(`
 var version = {
   major: 4,
   minor: 6,
-  patch: 4
+  patch: 5
 };
 
 // node_modules/zod/v4/core/schemas.js
@@ -28298,12 +28298,12 @@ var TOOL_SPECS = [
   },
   {
     name: "runtime_inspect",
-    description: "Questions about the running game: the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
+    description: "Questions about the running game: what is written on the screen, the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       nodePath: {
         type: "string",
-        description: "tree, find: where to start, default /root. rect: the node to place. property: the node to read."
+        description: "tree, find, text: where to start, default /root. rect: the node to place. property: the node to read."
       },
       property: {
         type: "string",
@@ -28325,6 +28325,10 @@ var TOOL_SPECS = [
       },
       group: { type: "string", description: "find: a group the node is in." },
       limit: { type: "number", description: "find: the most nodes to answer with. Default 100." },
+      includeHidden: {
+        type: "boolean",
+        description: "text: read hidden nodes as well, for checking that something is not showing. Default false."
+      },
       metrics: {
         type: "array",
         items: { type: "string" },
@@ -28334,6 +28338,10 @@ var TOOL_SPECS = [
     requires: [],
     operations: {
       tree: { summary: "the live scene tree", requires: [] },
+      text: {
+        summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+        requires: []
+      },
       find: {
         summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
         requires: []
@@ -28563,6 +28571,10 @@ var FEEDBACK_NOTICE_EVERY = 250;
 var run3 = promisify3(execFile3);
 var __dirname2 = dirname4(fileURLToPath2(import.meta.url));
 var EDITOR_RESTART_TIMEOUT_MS = 90000;
+var SLOWEST_FRAME_RATE = 20;
+function patienceForFrames(frames, atLeast) {
+  return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
+}
 var BRIDGE_RETRY_MS = 2000;
 var PATH_SOLUTIONS = [
   'Give the path relative to the project, such as "scenes/main.tscn" or "res://scenes/main.tscn"',
@@ -29096,6 +29108,12 @@ class GodotServer {
             });
           case "find":
             return await this.handleFindRuntimeNodes(args);
+          case "text":
+            return await this.handleRuntimeCommand("read_text", {
+              projectPath: args["projectPath"],
+              root: readNonEmptyString(args, "nodePath") ?? "/root",
+              include_hidden: readBoolean(args, "includeHidden") ?? false
+            });
           case "rect":
             return await this.handleRuntimeCommand("get_rect", {
               projectPath: args["projectPath"],
@@ -30140,8 +30158,11 @@ class GodotServer {
     const nodePath = readNonEmptyString(args, "nodePath") ?? "";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     switch (op) {
-      case "frames":
-        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames: readPositiveNumber(args, "frames") ?? 1 }, patience);
+      case "frames": {
+        const frames = readPositiveNumber(args, "frames") ?? 1;
+        const waited = patienceForFrames(frames, patience);
+        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
+      }
       case "signal":
         return await this.handleRuntimeCommand("wait_signal", {
           projectPath: args["projectPath"],

package/package.json

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