gdharness 1.1.23 → 1.1.25

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

@@ -44,6 +44,11 @@ const EDITOR_PID_VARIABLE: String = "GDHARNESS_EDITOR_PID"
 ## `errorReportPath` in src/runtime-client.ts.
 const ERROR_REPORT_NAME: String = "runtime-%d.log"
 
+## Written beside this addon by setup and upgrade. Kept in step with `VERSION_MARKER` and
+## `DIGEST_MARKER` in src/setup.ts.
+const VERSION_MARKER: String = "res://addons/gdharness_runtime/.gdharness-version"
+const DIGEST_MARKER: String = "res://addons/gdharness_runtime/.gdharness-digest"
+
 var values: Values = Values.new()
 
 # The modules are members and not locals of _init, because a Callable holds its object by id
@@ -76,6 +81,11 @@ var _announcement: String = ""
 var _errors: ErrorReport
 ## Every command, by the name a request uses, as the module method that answers it.
 var _commands: Dictionary = {}
+## The addon this game loaded, read once at start: an upgrade rewrites the markers under a running
+## game, whose code stays what it loaded, and reading them later would call that code current.
+## Empty when the markers cannot be read, as in a copy made by hand.
+var _loaded_version: String = _read_marker(VERSION_MARKER)
+var _loaded_digest: String = _read_marker(DIGEST_MARKER)
 
 
 func _init() -> void:
@@ -336,6 +346,8 @@ func _identity(bind_address: String) -> Dictionary:
 			"path": ProjectSettings.globalize_path("res://").rstrip("/")
 		},
 		"godot": Engine.get_version_info().get("string", ""),
+		"addon_version": _loaded_version,
+		"addon_digest": _loaded_digest,
 	}
 	var played_by: String = OS.get_environment(EDITOR_PID_VARIABLE)
 	if played_by.is_valid_int():
@@ -343,6 +355,17 @@ func _identity(bind_address: String) -> Dictionary:
 	return identity
 
 
+static func _read_marker(path: String) -> String:
+	if not FileAccess.file_exists(path):
+		return ""
+	var file: FileAccess = FileAccess.open(path, FileAccess.READ)
+	if file == null:
+		return ""
+	var text: String = file.get_as_text().strip_edges()
+	file.close()
+	return text
+
+
 func _send_welcome(client: StreamPeerTCP) -> void:
 	var welcome: Dictionary = _identity(
 		str(ProjectSettings.get_setting(BIND_ADDRESS_SETTING, DEFAULT_BIND_ADDRESS))

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

@@ -21,6 +21,10 @@ const TO_SMALL: int = 32
 ## reason a control is out of reach. Only worth telling somebody when it is what they have.
 const HEADLESS_VIEWPORT: Vector2 = Vector2(64, 64)
 
+## Set, to the desktop's name, for a process gdharness started on a desktop of its own and for
+## everything that process starts. Kept in step with `DESKTOP_VARIABLE` in src/desktop.ts.
+const DESKTOP_VARIABLE: String = "GDHARNESS_DESKTOP"
+
 var _host: Node
 var _values: Values
 
@@ -45,6 +49,28 @@ func _init(host: Node, values: Values) -> void:
 	_values = values
 
 
+## [param answer], saying what a desktop of gdharness's own does to the game's own reading of the
+## pointer when the game is on one.
+##
+## For the root window the engine asks Windows where the pointer is, and GetCursorPos refuses a
+## process on a desktop that is not in use: measured on one of gdharness's own, it answered false
+## with access denied and left the point unwritten. The engine does not check, so a game driven
+## there read get_mouse_position() as x 836852416 after a motion to 1310, 314. Nothing here can
+## put a pointer on that desktop: Windows moves one only on the desktop in use, and making this one
+## that would take the screen. What reads the injected event is right, tooltips included, since the
+## engine places a tooltip from the motion that reached the control.
+static func _pointer_noted(answer: Dictionary) -> Dictionary:
+	if OS.get_environment(DESKTOP_VARIABLE) != "":
+		answer["pointer_note"] = (
+			"This game is on gdharness's own desktop, where Windows refuses to say where the"
+			+ " pointer is, so get_mouse_position() on the root window, and get_global_mouse_position()"
+			+ " and get_local_mouse_position() on what is drawn there, read a meaningless position"
+			+ " rather than where this put it. What reads the event itself gets this position: the"
+			+ " control under the pointer, its hover and tooltip, and the game's input handlers."
+		)
+	return answer
+
+
 ## The movement a pointer arriving at [param position] carries, which is the distance from where
 ## the last injected event put it, and none at all for the first. The arrival is recorded, with how
 ## long it took: at least a frame, since two motions sent in one frame did not cross the screen in
@@ -238,15 +264,17 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 		Input.parse_input_event(_button(position, button, false, false))
 		await _host.get_tree().process_frame
 
-	return {
-		"type": "input_injected",
-		"input_type": "mouse_click",
-		"position": [position.x, position.y],
-		"button": button,
-		"pressed": held and not whole,
-		"whole": whole,
-		"double": double
-	}
+	return _pointer_noted(
+		{
+			"type": "input_injected",
+			"input_type": "mouse_click",
+			"position": [position.x, position.y],
+			"button": button,
+			"pressed": held and not whole,
+			"whole": whole,
+			"double": double
+		}
+	)
 
 
 ## Moves the pointer to a position, with the movement the event carries taken from where the
@@ -275,12 +303,14 @@ func inject_mouse_motion(params: Dictionary) -> Dictionary:
 
 	Input.parse_input_event(_motion(position, relative))
 
-	return {
-		"type": "input_injected",
-		"input_type": "mouse_motion",
-		"position": [position.x, position.y],
-		"relative": [relative.x, relative.y]
-	}
+	return _pointer_noted(
+		{
+			"type": "input_injected",
+			"input_type": "mouse_motion",
+			"position": [position.x, position.y],
+			"relative": [relative.x, relative.y]
+		}
+	)
 
 
 ## Whether [param centre] is somewhere a click can reach it: inside the viewport, and inside every
@@ -289,11 +319,11 @@ static func _in_sight(control: Control, viewport: Viewport, centre: Vector2) ->
 	return viewport.get_visible_rect().has_point(centre) and _clipped_by(control, centre) == null
 
 
-## The ScrollContainer between [param control] and the root that clips [param centre] away from it,
-## or null when none does.
+## The ScrollContainer between [param control] and its viewport that clips [param centre] away from
+## it, or null when none does. Not past the viewport: one holding a dialog is in another space.
 static func _clipped_by(control: Control, centre: Vector2) -> ScrollContainer:
 	var walking: Node = control.get_parent()
-	while walking != null:
+	while walking != null and not (walking is Viewport):
 		var holder: ScrollContainer = walking as ScrollContainer
 		# Carried into the same space the centre is in, which is the canvas rather than the
 		# container's own: the two are only the same while nothing above it is transformed.
@@ -312,11 +342,12 @@ static func _clipped_by(control: Control, centre: Vector2) -> ScrollContainer:
 ## next layout pass rather than inside the call, and the next one out works out where the control is
 ## from where it is drawn, so asked in the same frame it scrolled to where the control had been.
 ## Moved means a scroll value changed: a container asked to show what it already shows moves
-## nothing, and answering true for it said the view had moved when it had not.
+## nothing, and answering true for it said the view had moved when it had not. Only the containers in
+## the control's own viewport: one holding a dialog scrolls the page behind it, not the dialog.
 func _scroll_into_view(control: Control) -> bool:
 	var moved: bool = false
 	var walking: Variant = control.get_parent()
-	while walking != null:
+	while walking != null and not (walking is Viewport):
 		var step: Node = walking
 		var holder: ScrollContainer = step as ScrollContainer
 		if holder != null:
@@ -466,7 +497,7 @@ func click(params: Dictionary) -> Dictionary:
 	}
 	if found != null:
 		answer["found"] = found
-	return answer
+	return _pointer_noted(answer)
 
 
 ## Why [param control] would take no click a player gave it, or "" when it would.
@@ -636,19 +667,21 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	_press_button(arriving, _button(position, button, false, false))
 	await _host.get_tree().process_frame
 
-	return {
-		"type": "clicked",
-		"path": node_path,
-		"position": _values.serialize(position),
-		"button": button,
-		"double": double,
-		"hovered": hovered_path,
-		# The interface did not take it, so it reached the game's own input. As close to "it
-		# landed" as anything outside the game can get, and said in the same word the Control
-		# click says it in.
-		"landed": through["landed"],
-		"camera": found["camera"],
-	}
+	return _pointer_noted(
+		{
+			"type": "clicked",
+			"path": node_path,
+			"position": _values.serialize(position),
+			"button": button,
+			"double": double,
+			"hovered": hovered_path,
+			# The interface did not take it, so it reached the game's own input. As close to "it
+			# landed" as anything outside the game can get, and said in the same word the Control
+			# click says it in.
+			"landed": through["landed"],
+			"camera": found["camera"],
+		}
+	)
 
 
 ## Whether a pointer on its way out through [param out], the steps [method Screen.steps_out]

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

@@ -4,6 +4,7 @@ extends RefCounted
 ## where it is in the list.
 
 const Read = preload("reading.gd")
+const Says = preload("runtime_says.gd")
 const Words = preload("runtime_words.gd")
 
 
@@ -20,20 +21,28 @@ static func menu_of(node: Node) -> PopupMenu:
 	return null
 
 
-## Which item was asked for: `text`, matched exactly and then case-insensitively, or `index`.
-## Minus one when neither names one that is there.
+## The items asked for, best first: the one at `index`; else the one whose whole words are `text`,
+## exactly and then case-insensitively; else every item `text` matches by the rules `says` has, a
+## plain word as a contains, a glob, and alternatives split at `|`, the enabled ones when any are.
+## Empty when nothing matches, and more than one when several match equally well, which the caller
+## refuses rather than guesses between.
+##
+## By the same rules as `says` because a caller who has learnt them from a click, a find and a wait
+## writes the same pattern here: "Leave*" was refused against a menu holding "Leave the hall", and
+## the item had to be written out in full on a second call. The whole words still come first, so an
+## item named in full is chosen over another whose words contain it.
 ##
 ## `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:
+static func wanted_items(menu: PopupMenu, params: Dictionary) -> Array[int]:
 	if params.has("index"):
 		var asked: int = Read.as_int(params.get("index", -1), -1)
-		return asked if asked >= 0 and asked < menu.get_item_count() else -1
+		return _items([asked] if asked >= 0 and asked < menu.get_item_count() else [])
 	var wanted: String = str(params.get("text", ""))
 	if wanted.is_empty():
-		return -1
+		return _items([])
 	# The items before the separators, because a heading can carry the same words as an item under
 	# it, and finding the heading first refused the choice the caller meant. A separator is still
 	# looked for after, so a heading asked for by name is refused as one rather than as missing.
@@ -50,11 +59,33 @@ static func wanted_item(menu: PopupMenu, params: Dictionary) -> int:
 	for words: Array[String] in [shown, held]:
 		for at: int in words.size():
 			if words[at] == wanted:
-				return order[at]
+				return _items([order[at]])
 		for at: int in words.size():
 			if words[at].nocasecmp_to(wanted) == 0:
-				return order[at]
-	return -1
+				return _items([order[at]])
+	# Separators are left out here: a heading is refused when named in full, and a pattern that
+	# matched one beside the item it heads would tie the two.
+	for words: Array[String] in [shown, held]:
+		var matched: Array[int] = []
+		var enabled: Array[int] = []
+		for at: int in words.size():
+			var index: int = order[at]
+			if menu.is_item_separator(index) or not Says.matches(words[at], wanted):
+				continue
+			matched.append(index)
+			if not menu.is_item_disabled(index):
+				enabled.append(index)
+		if not matched.is_empty():
+			return enabled if not enabled.is_empty() else matched
+	return _items([])
+
+
+## [param indices] as a list of item numbers: a literal list is untyped, and handed back where a
+## typed one is declared it is refused when the call is made, not when the script is read.
+static func _items(indices: Array) -> Array[int]:
+	var typed: Array[int] = []
+	typed.assign(indices)
+	return typed
 
 
 ## What the menu shows, for a refusal that names the choices rather than the miss: a titled

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

@@ -216,13 +216,21 @@ static func can_read(holder: Variant, named: String) -> bool:
 ## A step is text, and a map is keyed by whatever the game put in it: text, a StringName, or a
 ## number, which a map of units by id is. Keyed by 3, "3" is not a key of it, measured on 4.7.2, so a
 ## step that reads as a number is tried as one after the two spellings of text.
+##
+## A map typed by its key is asked only in that type. It checks every key it is asked about and
+## reports an engine error for one of another type, so a step into a map typed by an enum read the
+## right entry and left four errors in the game's log for each of the two walks, and the run was
+## counted as unclean for a read.
 static func _key_in(map: Dictionary, named: String) -> Array:
 	var spellings: Array = [named, StringName(named)]
 	if named.is_valid_int():
 		spellings.append(int(named))
 	if named.is_valid_float():
 		spellings.append(float(named))
+	var typed: int = map.get_typed_key_builtin() if map.is_typed_key() else TYPE_NIL
 	for key: Variant in spellings:
+		if typed != TYPE_NIL and typeof(key) != typed:
+			continue
 		if map.has(key):
 			return [key]
 	return []

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

@@ -229,7 +229,7 @@ static func _covered_note(covered: int, cover: Node) -> String:
 ## its words means.
 static func _pressed_through(control: Control) -> Control:
 	var walk: Node = control
-	while walk != null:
+	while walk != null and not (walk is Viewport):
 		if walk is BaseButton:
 			var pressed: BaseButton = walk
 			return pressed
@@ -376,7 +376,7 @@ static func _where_it_lands(target: Control, point: Vector2) -> Vector2:
 	var half: Vector2 = (drawn * Rect2(Vector2.ZERO, target.size)).size * 0.5
 	var landed: Vector2 = point
 	var walk: Node = target.get_parent()
-	while walk != null:
+	while walk != null and not (walk is Viewport):
 		var holder: ScrollContainer = walk as ScrollContainer
 		if holder != null:
 			var shown: Rect2 = holder.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, holder.size)
@@ -405,9 +405,13 @@ static func _off_screen(target: Control) -> bool:
 
 
 ## Whether a container clipping what it holds cuts [param point] off from [param control].
+##
+## Only up to the viewport [param control] is in. A dialog is a window, and the containers the game
+## added it under are in another space: judged against a clipping one of those, every button of a
+## confirmation was refused as off the screen while it sat in plain view.
 static func _clipped_away(control: Control, point: Vector2) -> bool:
 	var walk: Node = control.get_parent()
-	while walk != null:
+	while walk != null and not (walk is Viewport):
 		var holder: Control = walk as Control
 		if holder != null and holder.clip_contents and not _holds(holder, point):
 			return true

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

@@ -261,11 +261,24 @@ func choose(params: Dictionary) -> Dictionary:
 	var opened: bool = Menus.open_the_menu(node, menu)
 	await _host.get_tree().process_frame
 
-	var index: int = Menus.wanted_item(menu, params)
+	var found: Array[int] = Menus.wanted_items(menu, params)
+	if found.size() > 1:
+		await _shut(menu, opened)
+		var tied: Array[String] = []
+		for at: int in found:
+			tied.append("%d: %s" % [at, Words.item_says(menu, at)])
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s has %d items that say %s, so nothing was chosen: %s. Name one by its whole text or by index"
+				% [node_path, found.size(), JSON.stringify(str(params.get("text", ""))), ", ".join(tied)]
+			)
+		}
+	var index: int = found[0] if found.size() == 1 else -1
 	var refused: String = _not_a_choice(node_path, menu, index)
 	if not refused.is_empty():
-		if opened and is_instance_valid(menu):
-			menu.hide()
+		await _shut(menu, opened)
 		return {"type": "error", "message": refused}
 
 	# Read before the press, because the press can take the menu away: a game that rebuilds its
@@ -298,8 +311,7 @@ func choose(params: Dictionary) -> Dictionary:
 		menu.index_pressed.disconnect(hear)
 
 	if not fired.has(index):
-		if opened and is_instance_valid(menu) and menu.visible:
-			menu.hide()
+		await _shut(menu, opened)
 		return {
 			"type": "error",
 			"message":
@@ -322,6 +334,16 @@ func choose(params: Dictionary) -> Dictionary:
 	return answer
 
 
+## Shuts a menu this call opened, and lets the frame pass in which the engine finishes shutting it.
+## A choice asked for in the frame a refusal shut the menu found it half shut, and the press it sent
+## went nowhere: measured on 4.7.2, a MenuButton refused and at once asked again answered that the
+## menu did not take the item.
+func _shut(menu: PopupMenu, opened: bool) -> void:
+	if opened and is_instance_valid(menu) and menu.visible:
+		menu.hide()
+		await _host.get_tree().process_frame
+
+
 ## Why item [param index] of [param menu] is not something to choose, or "" when it is.
 static func _not_a_choice(node_path: String, menu: PopupMenu, index: int) -> String:
 	if index < 0: