gdharness 1.0.27 → 1.0.28

package/build/cli.js

@@ -16538,7 +16538,7 @@ var init_tool_definitions = __esm(() => {
         says: {
           type: "string",
           ops: ["find"],
-          description: "find: part of what the node has written on it, case-insensitively, which is how a button is reached by the word on it rather than by a generated path. Its own text, so a row is found by the label in it, and hidden nodes match. A bare word is a contains; write a glob and it is one, matched against the whole of what the node says, the same as namePattern. A label with a line break is matched with the break in the words, and a backslash followed by n counts as one."
+          description: "find: part of what the node has written on it as drawn, the way the text op reads it, case-insensitively, which is how a button is reached by the word on it rather than by a generated path. Its own text, so a row is found by the label in it, and hidden nodes match. A bare word is a contains; write a glob and it is one, matched against the whole of what the node says, the same as namePattern. A label with a line break is matched with the break in the words, and a backslash followed by n counts as one."
         },
         limit: {
           type: "integer",
@@ -16567,7 +16567,7 @@ var init_tool_definitions = __esm(() => {
       operations: {
         tree: { summary: "the live scene tree", requires: [] },
         text: {
-          summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+          summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it. Every line reads as drawn: rich text without its tags, text only as far as it has been typed out, a translation rather than its key, an upper-case label in capitals and a secret field as its mask. Tab titles, menu bar titles, list items, a tree's column titles and rows, and an open menu's items read a line each",
           requires: []
         },
         find: {
@@ -16716,7 +16716,7 @@ var init_tool_definitions = __esm(() => {
           type: "string",
           ops: ["text", "choose"],
           blank: true,
-          description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says.'
+          description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says as drawn, which in a game with translations is the translation; the key it holds is matched after that.'
         },
         replace: {
           type: "boolean",
@@ -16778,7 +16778,7 @@ var init_tool_definitions = __esm(() => {
           requires: ["keycode"]
         },
         text: {
-          summary: "type a string into the field being edited, a character at a time, and say what it landed in",
+          summary: "type a string into the field being edited, a character at a time, and say what it landed in and what it holds afterwards, a secret field as its mask",
           requires: ["text"]
         },
         mouse_click: {

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

@@ -10,6 +10,7 @@ const Values = preload("runtime_values.gd")
 ## reports are the same place by construction rather than by agreement.
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
+const Words = preload("runtime_words.gd")
 
 ## The distance from a capital letter to its small one in Unicode. A keycode holds the capital.
 const TO_SMALL: int = 32
@@ -239,11 +240,12 @@ static func _select_everything(focused: Control) -> bool:
 ## What the field says now, or null where the focus is not a field at all.
 ##
 ## A spin box rewrites its own text out of the number it parsed, so this is the only thing that
-## says whether what was typed became what the field means.
+## says whether what was typed became what the field means. A secret field answers with its mask,
+## which still says how many characters it took.
 static func _what_it_holds(focused: Control) -> Variant:
 	var field: LineEdit = focused as LineEdit
 	if field != null:
-		return field.text
+		return Words.masked(field) if field.secret else field.text
 	var box: TextEdit = focused as TextEdit
 	if box == null:
 		return null
@@ -666,7 +668,7 @@ func choose(params: Dictionary) -> Dictionary:
 	if menu.is_item_disabled(index):
 		return {
 			"type": "error",
-			"message": "%s item %d, %s, is disabled" % [node_path, index, menu.get_item_text(index)]
+			"message": "%s item %d, %s, is disabled" % [node_path, index, Words.item_says(menu, index)]
 		}
 
 	# Shown first, because a menu nobody has opened has no focus to move and Enter would go to
@@ -689,7 +691,7 @@ func choose(params: Dictionary) -> Dictionary:
 		"type": "chosen",
 		"path": node_path,
 		"index": index,
-		"text": menu.get_item_text(index),
+		"text": Words.item_says(menu, index),
 		"id": menu.get_item_id(index),
 		"opened": opened,
 		"menu": str(menu.get_path()),
@@ -699,7 +701,7 @@ func choose(params: Dictionary) -> Dictionary:
 	var chooser: OptionButton = node as OptionButton
 	if chooser != null:
 		answer["selected"] = chooser.get_selected()
-		answer["shows"] = chooser.text
+		answer["shows"] = Words.said_by(chooser)
 	return answer
 
 
@@ -718,6 +720,11 @@ static func _menu_of(node: Node) -> PopupMenu:
 
 ## Which item was asked for: `text`, matched exactly and then case-insensitively, or `index`.
 ## Minus one when neither names one that is there.
+##
+## `text` is matched against the words the item shows before the ones it holds. In a game with
+## translations they differ, and the shown ones are what a caller has read off the screen: an item
+## held as `ACT_ENGAGE` and shown as "Hire" refused "Hire" and listed the keys. The held words
+## still count after them, for a caller that has the key from the source.
 static func _wanted_item(menu: PopupMenu, params: Dictionary) -> int:
 	if params.has("index"):
 		var asked: int = Read.as_int(params.get("index", -1), -1)
@@ -725,20 +732,26 @@ static func _wanted_item(menu: PopupMenu, params: Dictionary) -> int:
 	var wanted: String = str(params.get("text", ""))
 	if wanted.is_empty():
 		return -1
+	var shown: Array[String] = []
+	var held: Array[String] = []
 	for index: int in menu.get_item_count():
-		if menu.get_item_text(index) == wanted:
-			return index
-	for index: int in menu.get_item_count():
-		if menu.get_item_text(index).nocasecmp_to(wanted) == 0:
-			return index
+		shown.append(Words.item_says(menu, index))
+		held.append(menu.get_item_text(index))
+	for words: Array[String] in [shown, held]:
+		for index: int in words.size():
+			if words[index] == wanted:
+				return index
+		for index: int in words.size():
+			if words[index].nocasecmp_to(wanted) == 0:
+				return index
 	return -1
 
 
-## What the menu says, for a refusal that names the choices rather than the miss.
+## What the menu shows, for a refusal that names the choices rather than the miss.
 static func _items_of(menu: PopupMenu) -> Array[String]:
 	var said: Array[String] = []
 	for index: int in menu.get_item_count():
-		said.append("%d: %s" % [index, menu.get_item_text(index)])
+		said.append("%d: %s" % [index, Words.item_says(menu, index)])
 	return said
 
 

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

@@ -6,6 +6,7 @@ extends RefCounted
 const Paths = preload("runtime_paths.gd")
 const Read = preload("reading.gd")
 const Values = preload("runtime_values.gd")
+const Words = preload("runtime_words.gd")
 
 ## The most nodes one find answers with, unless asked for fewer: enough for any real query and
 ## far short of the tree dump a query exists to avoid.
@@ -251,7 +252,7 @@ func _matches_apart_from_name(node: Node, wanted: Dictionary[String, String]) ->
 	# What this node says, rather than everything said underneath it. A row is then found by the
 	# label in it, and the path answered is that label's, which is where the words a caller is
 	# looking at actually are: matching every container above it would answer with the screen.
-	if not wanted["says"].is_empty() and not _says(said_by(node), wanted["says"]):
+	if not wanted["says"].is_empty() and not _says(Words.said_by(node), wanted["says"]):
 		return false
 	var script: Variant = node.get_script()
 	if not wanted["script"].is_empty():
@@ -346,8 +347,7 @@ func _read_into(node: Node, include_hidden: bool, most: int, into: Array[String]
 	if not include_hidden and not _drawn(node):
 		return 0
 	var left_out: int = 0
-	var said: String = said_by(node)
-	if not said.is_empty():
+	for said: String in Words.lines_said_by(node):
 		if into.size() < most:
 			into.append(said)
 		else:
@@ -373,25 +373,6 @@ static func _drawn(node: Node) -> bool:
 	return window == null or window.visible
 
 
-## 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.
-##
-## Public because three questions are the same question: what a screen reads as, which nodes say a
-## given word, and whether anything has come to say it yet. Two copies of what a node says is how
-## the three of them come to disagree about a SpinBox.
-##
-## Read rather than looked up in the property list, which the engine builds afresh on every call: a
-## wait asks this of every node on the screen every frame, and on a hall of 3,500 nodes the lookup
-## took the game it was watching from 60 frames a second to 11. A node without the property reads
-## as null, which is not a string.
-static func said_by(node: Node) -> String:
-	var text: Variant = node.get("text")
-	if not text is String:
-		return ""
-	var words: String = text
-	return words.strip_edges()
-
-
 func get_rect(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	if node_path.is_empty():

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

@@ -7,6 +7,7 @@ const Paths = preload("runtime_paths.gd")
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
 const Values = preload("runtime_values.gd")
+const Words = preload("runtime_words.gd")
 
 ## The longest one wait may last, whatever the request says: past this the server has long
 ## since given up on the reply.
@@ -291,7 +292,7 @@ func _anything_says(node_path: String, said: String, include_hidden: bool) -> bo
 	var pending: Array[Node] = [root]
 	while not pending.is_empty():
 		var node: Node = pending.pop_back()
-		if Queries.said_by(node).containsn(said) and (include_hidden or Queries.shown(node)):
+		if Words.said_by(node).containsn(said) and (include_hidden or Queries.shown(node)):
 			return true
 		pending.append_array(node.get_children(true))
 	return false

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

@@ -0,0 +1,163 @@
+extends RefCounted
+
+## What a node says to a player, read the way it is drawn: the parsed words of rich text, as much of
+## a line as is typed out so far, the translation rather than its key, a mask over a secret, and the
+## items of the controls that draw a list.
+##
+## One module because three questions are the same question: what a screen reads as, which nodes say
+## a given word, and whether anything has come to say it yet. Two copies of what a node says is how
+## the three of them come to disagree about a SpinBox.
+
+
+## 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.
+##
+## Read rather than looked up in the property list, which the engine builds afresh on every call: a
+## wait asks this of every node on the screen every frame, and on a hall of 3,500 nodes the lookup
+## took the game it was watching from 60 frames a second to 11. A node without the property reads
+## as null, which is not a string.
+##
+## A label is asked about first and read directly, because a screen is mostly labels and this runs
+## for each of them on every look a wait takes.
+static func said_by(node: Node) -> String:
+	var label: Label = node as Label
+	if label != null:
+		return _label_says(label)
+	if _draws_a_list(node):
+		return "\n".join(lines_said_by(node))
+	return _text_of(node)
+
+
+## Every line [param node] draws for a player to read, one to an entry: a label's one line, or each
+## item of a control that draws a list of them. Tab titles, list items, tree rows, menu titles and
+## the items of an open menu are held by the control rather than in any `text`, so a screen read as
+## every label on it and none of those, and a wait for a tab's title or a list item was never met.
+static func lines_said_by(node: Node) -> Array[String]:
+	var lines: Array[String] = []
+	if node is TabBar:
+		var bar: TabBar = node
+		for tab: int in bar.tab_count:
+			if not bar.is_tab_hidden(tab):
+				_keep(node.atr(bar.get_tab_title(tab)), lines)
+	elif node is MenuBar:
+		var menus: MenuBar = node
+		for menu: int in menus.get_menu_count():
+			if not menus.is_menu_hidden(menu):
+				_keep(node.atr(menus.get_menu_title(menu)), lines)
+	elif node is ItemList:
+		var list: ItemList = node
+		for item: int in list.item_count:
+			_keep(_as_drawn(node, list.get_item_text(item), list.get_item_auto_translate_mode(item)), lines)
+	elif node is PopupMenu:
+		var menu: PopupMenu = node
+		for item: int in menu.item_count:
+			if not menu.is_item_separator(item):
+				_keep(item_says(menu, item), lines)
+	elif node is Tree:
+		var tree: Tree = node
+		if tree.column_titles_visible:
+			var titles: Array[String] = []
+			for column: int in tree.columns:
+				_keep(node.atr(tree.get_column_title(column)), titles)
+			_keep("  ".join(titles), lines)
+		_tree_rows(tree, tree.get_root(), tree.hide_root, lines)
+	else:
+		_keep(_text_of(node), lines)
+	return lines
+
+
+## What item [param index] of [param menu] shows: the translation where the item has one. A menu is
+## chosen from by these words, since they are the ones a caller has read off the screen.
+static func item_says(menu: PopupMenu, index: int) -> String:
+	return _as_drawn(menu, menu.get_item_text(index), menu.get_item_auto_translate_mode(index))
+
+
+## What a secret [param field] draws: one mask character for each character it holds. Reading the
+## words back would hand a password to whoever reads the answer, which the player cannot see either.
+static func masked(field: LineEdit) -> String:
+	return field.secret_character.repeat(field.text.length())
+
+
+static func _draws_a_list(node: Node) -> bool:
+	return node is TabBar or node is MenuBar or node is ItemList or node is PopupMenu or node is Tree
+
+
+static func _keep(line: String, into: Array[String]) -> void:
+	var trimmed: String = line.strip_edges()
+	if not trimmed.is_empty():
+		into.append(trimmed)
+
+
+## [param words] as [param node] draws them, which for a game with translations is the translation
+## rather than the key it holds: a control set to `UI_HIRE` shows "Hire", and a wait for "Hire" was
+## never met. [param mode] is an item's own setting, which the engine reads before the node's.
+static func _as_drawn(
+	node: Node, words: String, mode: Node.AutoTranslateMode = Node.AUTO_TRANSLATE_MODE_INHERIT
+) -> String:
+	match mode:
+		Node.AUTO_TRANSLATE_MODE_ALWAYS:
+			return node.tr(words)
+		Node.AUTO_TRANSLATE_MODE_DISABLED:
+			return words
+	return node.atr(words)
+
+
+## The rows of a tree from [param item] down, a row being its columns' text side by side, and
+## nothing under a collapsed row or a hidden one, since neither is drawn. A hidden root is only the
+## place its children hang from.
+static func _tree_rows(tree: Tree, item: TreeItem, skip: bool, into: Array[String]) -> void:
+	if item == null or not item.visible:
+		return
+	if not skip:
+		var cells: Array[String] = []
+		for column: int in tree.columns:
+			_keep(_as_drawn(tree, item.get_text(column), item.get_auto_translate_mode(column)), cells)
+		_keep("  ".join(cells), into)
+		if item.collapsed:
+			return
+	var child: TreeItem = item.get_first_child()
+	while child != null:
+		_tree_rows(tree, child, false, into)
+		child = child.get_next()
+
+
+## What a node with a `text` says, as it is drawn.
+static func _text_of(node: Node) -> String:
+	var label: Label = node as Label
+	if label != null:
+		return _label_says(label)
+	# A RichTextLabel's text is its markup when it reads BBCode, and nobody reads the tags: a
+	# dossier line came back as "[b][color=#4fc2d4]Mollum Telken[/color], [/b]..." and a phrase
+	# running across a tag could not be found or waited for. The parsed text is what is drawn, and
+	# it also holds what a game added with append_text(), which the property never shows. It is
+	# parsed from the translation already.
+	if node is RichTextLabel:
+		var rich: RichTextLabel = node
+		return _shown_part(rich.get_parsed_text(), rich.visible_characters)
+	var text: Variant = node.get("text")
+	if not text is String:
+		return ""
+	var words: String = text
+	# What somebody typed is drawn as typed, never translated.
+	if node is LineEdit:
+		var field: LineEdit = node
+		return masked(field) if field.secret else words.strip_edges()
+	if node is TextEdit:
+		return words.strip_edges()
+	words = node.atr(words)
+	if node is Label3D:
+		var sign_text: Label3D = node
+		return (words.to_upper() if sign_text.uppercase else words).strip_edges()
+	return words.strip_edges()
+
+
+static func _label_says(label: Label) -> String:
+	var words: String = label.atr(label.text)
+	return _shown_part(words.to_upper() if label.uppercase else words, label.visible_characters)
+
+
+## As much of [param words] as is drawn: a label typing a line out shows [param drawn] characters
+## of it, and -1 is all of them. Read whole, a words wait was met on the first frame of a line being
+## typed out, before the player could read any of it.
+static func _shown_part(words: String, drawn: int) -> String:
+	return (words if drawn < 0 else words.substr(0, drawn)).strip_edges()

package/build/godot/addons/gdharness_runtime/runtime_words.gd.uid

@@ -0,0 +1 @@
+uid://u3ml7sk81frh

package/build/index.js

@@ -30545,7 +30545,7 @@ var TOOL_SPECS = [
       says: {
         type: "string",
         ops: ["find"],
-        description: "find: part of what the node has written on it, case-insensitively, which is how a button is reached by the word on it rather than by a generated path. Its own text, so a row is found by the label in it, and hidden nodes match. A bare word is a contains; write a glob and it is one, matched against the whole of what the node says, the same as namePattern. A label with a line break is matched with the break in the words, and a backslash followed by n counts as one."
+        description: "find: part of what the node has written on it as drawn, the way the text op reads it, case-insensitively, which is how a button is reached by the word on it rather than by a generated path. Its own text, so a row is found by the label in it, and hidden nodes match. A bare word is a contains; write a glob and it is one, matched against the whole of what the node says, the same as namePattern. A label with a line break is matched with the break in the words, and a backslash followed by n counts as one."
       },
       limit: {
         type: "integer",
@@ -30574,7 +30574,7 @@ var TOOL_SPECS = [
     operations: {
       tree: { summary: "the live scene tree", requires: [] },
       text: {
-        summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+        summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it. Every line reads as drawn: rich text without its tags, text only as far as it has been typed out, a translation rather than its key, an upper-case label in capitals and a secret field as its mask. Tab titles, menu bar titles, list items, a tree's column titles and rows, and an open menu's items read a line each",
         requires: []
       },
       find: {
@@ -30723,7 +30723,7 @@ var TOOL_SPECS = [
         type: "string",
         ops: ["text", "choose"],
         blank: true,
-        description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says.'
+        description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says as drawn, which in a game with translations is the translation; the key it holds is matched after that.'
       },
       replace: {
         type: "boolean",
@@ -30785,7 +30785,7 @@ var TOOL_SPECS = [
         requires: ["keycode"]
       },
       text: {
-        summary: "type a string into the field being edited, a character at a time, and say what it landed in",
+        summary: "type a string into the field being edited, a character at a time, and say what it landed in and what it holds afterwards, a secret field as its mask",
         requires: ["text"]
       },
       mouse_click: {

package/package.json

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