gdharness 1.3.8 → 1.3.10

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

@@ -125,6 +125,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	var root: Node = reached["node"]
 
 	var found: Array[Dictionary] = []
+	var found_nodes: Array[Node] = []
 	var pending: Array[Node] = [root]
 	var truncated: bool = false
 	# Counted while the tree is already being walked, for the answer below: how many nodes this
@@ -148,24 +149,28 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	var nearly_hidden: int = 0
 	var nearly_said_hidden: int = 0
 	var hidden: int = 0
+	var out_of_view: int = 0
 	while not pending.is_empty():
 		var node: Node = pending.pop_front()
 		var rest: bool = _matches_apart_from_name(node, wanted)
 		if rest and _named(node, names):
 			if not include_hidden and not shown(node):
 				hidden += 1
+			elif not include_hidden and not GdhScreen.in_view(node):
+				out_of_view += 1
 			elif found.size() >= limit:
 				truncated = true
 				break
 			else:
 				found.append(_found(node, wanted_property))
+				found_nodes.append(node)
 		elif rest and _contains_any(str(node.name), plain_names):
-			if include_hidden or shown(node):
+			if include_hidden or readable(node):
 				nearly += 1
 			else:
 				nearly_hidden += 1
 		elif not widened_says.is_empty() and _named(node, names) and _matches_apart_from_name(node, widened):
-			if include_hidden or shown(node):
+			if include_hidden or readable(node):
 				nearly_said += 1
 			else:
 				nearly_said_hidden += 1
@@ -181,6 +186,39 @@ func find_nodes(params: Dictionary) -> Dictionary:
 
 	var answer: Dictionary = {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
 	var notes: Array[String] = []
+	# Each still listed, since a caller may mean one of them, and marked, so one sign drawn as a label
+	# and its outline copies is not read as four signs. The outermost match it copies, since a find
+	# under one of the copies has left the label they all copy outside it.
+	var copies: int = 0
+	for index: int in range(found_nodes.size()):
+		var at: int = -1
+		for original: Node in GdhWords.copied_through(found_nodes[index]):
+			var matched: int = found_nodes.find(original)
+			if matched != -1:
+				at = matched
+		if at != -1:
+			found[index]["copyOf"] = found[at]["path"]
+			copies += 1
+	if copies > 0:
+		answer["distinct"] = found.size() - copies
+		(
+			notes
+			. append(
+				(
+					(
+						"%d of the %d matches %s drawn under a match saying the same words, as an outline or a"
+						+ " glow is drawn, and %s it under copyOf: %d distinct"
+					)
+					% [
+						copies,
+						found.size(),
+						"is a copy" if copies == 1 else "are copies",
+						"names" if copies == 1 else "name",
+						found.size() - copies,
+					]
+				)
+			)
+		)
 	# Nothing found is the one answer that cannot be told apart from having asked the wrong
 	# question, and a name written without a wildcard is the way an agent writes "contains".
 	# Said only when it changes the answer, so a genuine nothing stays a plain nothing.
@@ -200,7 +238,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 					'name is matched as a glob against the whole name; %d %snode %s %s, which "%s"%s would find'
 					% [
 						named_near,
-						"" if nearly > 0 else "hidden ",
+						"" if nearly > 0 else "hidden or out-of-view ",
 						holding,
 						" or ".join(PackedStringArray(near_words)),
 						GdhSays.joined_at_bars(opened),
@@ -220,7 +258,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 						widened_says,
 						"" if nearly_said > 0 else " with includeHidden true",
 						said_near,
-						"" if nearly_said > 0 else "hidden ",
+						"" if nearly_said > 0 else "hidden or out-of-view ",
 						"" if said_near == 1 else "s",
 					]
 				)
@@ -236,6 +274,17 @@ func find_nodes(params: Dictionary) -> Dictionary:
 				% [hidden, "" if hidden == 1 else "s"]
 			)
 		)
+	if out_of_view > 0:
+		answer["out_of_view"] = out_of_view
+		notes.append(
+			(
+				(
+					"%d matching node%s drawn outside the viewport or scrolled out of a ScrollContainer"
+					+ " and left out; includeHidden true answers with them too"
+				)
+				% [out_of_view, "" if out_of_view == 1 else "s"]
+			)
+		)
 	if not notes.is_empty():
 		answer["note"] = " ".join(notes)
 	return answer
@@ -268,6 +317,13 @@ static func shown(node: Node) -> bool:
 	return parent == null or shown(parent)
 
 
+## Whether the player can read [param node]: [method shown], and drawn inside its viewport and every
+## ScrollContainer holding it, see [method GdhScreen.in_view]. A click by words asks [method shown]
+## alone, since it scrolls what it presses into view.
+static func readable(node: Node) -> bool:
+	return shown(node) and GdhScreen.in_view(node)
+
+
 ## Whether the canvas [param item] is drawn on is showing: its layer, and the windows around it.
 static func _on_a_shown_canvas(item: CanvasItem) -> bool:
 	var walk: Node = item.get_parent()
@@ -426,15 +482,46 @@ func read_text(params: Dictionary) -> Dictionary:
 	# and a bare `truncated: true` was looked straight past twice before the limit was suspected.
 	# A number is what sends somebody back.
 	var lines: Array[String] = []
-	var left_out: int = _read_into(root, include_hidden, limit, lines)
-	return {
+	var tally: Dictionary[String, int] = {"omitted": 0, "out_of_view": 0, "copies": 0}
+	_read_into(root, include_hidden, limit, lines, tally)
+	var answer: Dictionary = {
 		"type": "text",
 		"root": root_path,
 		"lines": lines,
 		"count": lines.size(),
-		"truncated": left_out > 0,
-		"omitted": left_out,
+		"truncated": tally["omitted"] > 0,
+		"omitted": tally["omitted"],
 	}
+	var notes: Array[String] = []
+	if tally["out_of_view"] > 0:
+		answer["out_of_view"] = tally["out_of_view"]
+		notes.append(
+			(
+				(
+					"%d line%s drawn outside the viewport or scrolled out of a ScrollContainer, where the"
+					+ " player cannot read them, left out; includeHidden true answers with them too"
+				)
+				% [tally["out_of_view"], "" if tally["out_of_view"] == 1 else "s"]
+			)
+		)
+	if tally["copies"] > 0:
+		answer["copies"] = tally["copies"]
+		notes.append(
+			(
+				(
+					"%d line%s drawn as a copy under a node saying the same words, as an outline or a glow"
+					+ " is drawn, read once with the words %s"
+				)
+				% [
+					tally["copies"],
+					"" if tally["copies"] == 1 else "s",
+					"it copies" if tally["copies"] == 1 else "they copy"
+				]
+			)
+		)
+	if not notes.is_empty():
+		answer["note"] = " ".join(notes)
+	return answer
 
 
 ## Walks [param node] depth first, which is the order the screen is laid out in and the order a
@@ -445,22 +532,33 @@ func read_text(params: Dictionary) -> Dictionary:
 ## screen full of forms answered with every label on it and none of the values in it. The hidden
 ## check covers a [Window] for the same walk: a dropdown's popup is a child that is not drawn
 ## until it is opened, and reading a closed menu would put every item on the screen.
-## Fills [param into] up to [param most] lines and answers with how many further lines the rest of
-## the subtree says, which is what the caller is told rather than left to infer.
+## Fills [param into] up to [param most] lines and counts in [param tally] how many further lines the
+## rest of the subtree says, under omitted, and how many it says out of view, under out_of_view, which
+## is what the caller is told rather than left to infer.
 ##
 ## Asked of each node rather than cut off at the first hidden one, since a hidden panel does not
 ## hide a label reached through a plain Node: see [method shown].
-func _read_into(node: Node, include_hidden: bool, most: int, into: Array[String]) -> int:
-	var left_out: int = 0
+func _read_into(
+	node: Node, include_hidden: bool, most: int, into: Array[String], tally: Dictionary[String, int]
+) -> void:
 	if include_hidden or shown(node):
-		for said: String in GdhWords.lines_said_by(node):
-			if into.size() < most:
-				into.append(said)
-			else:
-				left_out += 1
+		var said: Array[String] = GdhWords.lines_said_by(node)
+		# A copy drawn under the words it copies, as an outline or a glow is, reads once. Only while
+		# what it copies is itself read, so an original hidden or drawn out of view does not take the
+		# words with it.
+		var original: Node = GdhWords.copied_from(node) if not said.is_empty() else null
+		if original != null and (include_hidden or readable(original)):
+			tally["copies"] += said.size()
+		elif not include_hidden and not GdhScreen.in_view(node):
+			tally["out_of_view"] += said.size()
+		else:
+			for line: String in said:
+				if into.size() < most:
+					into.append(line)
+				else:
+					tally["omitted"] += 1
 	for child: Node in node.get_children(true):
-		left_out += _read_into(child, include_hidden, most, into)
-	return left_out
+		_read_into(child, include_hidden, most, into, tally)
 
 
 ## Where a node is on screen: a Control's rectangle, a Node2D's position, or the place a 3D node
@@ -488,6 +586,7 @@ func get_rect(params: Dictionary) -> Dictionary:
 			"type": "rect",
 			"path": node_path,
 			"visible": control.is_visible_in_tree(),
+			"in_view": GdhScreen.in_view(control),
 			"canvas": _values.serialize(canvas_rect),
 			"window":
 			_values.serialize(
@@ -501,13 +600,20 @@ func get_rect(params: Dictionary) -> Dictionary:
 		var item: Node2D = node
 		var canvas_position: Vector2 = item.get_global_transform_with_canvas().origin
 		var window_position: Vector2 = GdhScreen.in_window(item.get_viewport(), canvas_position)
-		return {
+		var at: Dictionary = {
 			"type": "point",
 			"path": node_path,
 			"visible": item.is_visible_in_tree(),
 			"canvas": _values.serialize(canvas_position),
 			"window": _values.serialize(window_position),
 		}
+		for local: Rect2 in _drawn_rect(item):
+			var covered: Rect2 = item.get_global_transform_with_canvas() * local
+			at["covers"] = {
+				"canvas": _values.serialize(covered),
+				"window": _values.serialize(GdhScreen.rect_in_window(item.get_viewport(), covered)),
+			}
+		return at
 	if node is Node3D:
 		var spatial: Node3D = node
 		return _in_the_frame(node_path, spatial)
@@ -516,6 +622,43 @@ func get_rect(params: Dictionary) -> Dictionary:
 	}
 
 
+## The rectangle a 2D node's own geometry takes up in its own coordinates, as the one entry of the
+## list, which is empty for a node that has none of its own: a sprite's texture, a collision shape's
+## shape, the points of a polygon or a line. A Node2D answered only where it stands, so the extent of
+## a floor or a sprite to aim inside was a read of its shape and some arithmetic.
+static func _drawn_rect(item: Node2D) -> Array[Rect2]:
+	var drawn: Array[Rect2] = []
+	var sprite: Sprite2D = item as Sprite2D
+	if sprite != null:
+		if sprite.texture != null:
+			drawn.append(sprite.get_rect())
+		return drawn
+	var shaped: CollisionShape2D = item as CollisionShape2D
+	if shaped != null:
+		if shaped.shape != null:
+			drawn.append(shaped.shape.get_rect())
+		return drawn
+	var points: PackedVector2Array = []
+	var offset: Vector2 = Vector2.ZERO
+	if item is Polygon2D:
+		var polygon: Polygon2D = item
+		points = polygon.polygon
+		offset = polygon.offset
+	elif item is CollisionPolygon2D:
+		var outline: CollisionPolygon2D = item
+		points = outline.polygon
+	elif item is Line2D:
+		var line: Line2D = item
+		points = line.points
+	if points.is_empty():
+		return drawn
+	var bounds: Rect2 = Rect2(points[0] + offset, Vector2.ZERO)
+	for point: Vector2 in points:
+		bounds = bounds.expand(point + offset)
+	drawn.append(bounds)
+	return drawn
+
+
 ## Where a 3D node is in the frame drawing it: the point to aim at, and the rectangle its own
 ## geometry covers, each in canvas coordinates and in window pixels.
 ##
@@ -723,6 +866,8 @@ func get_metrics(params: Dictionary) -> Dictionary:
 		"frame_time": frame_time,
 		"frame_time_max": frame_time_max,
 		"frames_timed": timed,
+		"process_frames": Engine.get_process_frames(),
+		"physics_frames": Engine.get_physics_frames(),
 		"physics_steps_per_second": physics_steps_per_second,
 		"physics_ticks_per_second": Engine.physics_ticks_per_second,
 		"max_physics_steps_per_frame": Engine.max_physics_steps_per_frame,

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

@@ -29,9 +29,13 @@ static func steps_out(viewport: Viewport, point: Vector2) -> Array[Dictionary]:
 	var out: Array[Dictionary] = [{"viewport": viewport, "point": point, "through": null}]
 	while true:
 		var window: Window = viewport as Window
-		if window != null and window.is_embedded() and window.get_parent() != null:
-			point += Vector2(window.position)
-			viewport = window.get_parent().get_viewport()
+		var host: Viewport = embedder_of(window) if window != null and window.is_embedded() else null
+		if host != null:
+			# A window's canvas is drawn into its embedder through its own final transform, which is
+			# where a content scale goes: one at 4 drew a button at four times the point it was clicked
+			# at, and the click missed it.
+			point = Vector2(window.position) + window.get_final_transform() * point
+			viewport = host
 			out.append({"viewport": viewport, "point": point, "through": window})
 			continue
 		var shown_by: SubViewportContainer = viewport.get_parent() as SubViewportContainer
@@ -45,6 +49,19 @@ static func steps_out(viewport: Viewport, point: Vector2) -> Array[Dictionary]:
 	return out
 
 
+## The viewport [param window] is embedded in and placed by, found as the engine finds it, which
+## does not offer it to scripts: the nearest viewport above that embeds subwindows. That is not
+## always its parent's: a window under a window that does not embed is embedded in the one above.
+static func embedder_of(window: Window) -> Viewport:
+	var above: Node = window.get_parent()
+	# A viewport's get_viewport is itself, so a window's parent that is one is asked first.
+	var viewport: Viewport = above.get_viewport() if above != null else null
+	while viewport != null and not viewport.is_embedding_subwindows():
+		above = viewport.get_parent()
+		viewport = above.get_viewport() if above != null else null
+	return viewport
+
+
 ## Where [param point], in [param viewport]'s own coordinates, is in the pixels of the window the
 ## game is shown in, which is what a mouse event names.
 static func in_window(viewport: Viewport, point: Vector2) -> Vector2:
@@ -60,3 +77,32 @@ static func rect_in_window(viewport: Viewport, rect: Rect2) -> Rect2:
 	var start: Vector2 = in_window(viewport, rect.position)
 	var end: Vector2 = in_window(viewport, rect.end)
 	return Rect2(start.min(end), (end - start).abs())
+
+
+## Whether any of [param node] is drawn where the player can see it: inside its viewport, and inside
+## every ScrollContainer between it and the viewport, each of which clips what it holds. A label
+## placed past the window's edge was read out as written on the screen. Only a Control has a box to
+## ask about, so anything else is in view.
+static func in_view(node: Node) -> bool:
+	var control: Control = node as Control
+	return control == null or shown_part(control) != null
+
+
+## The part of [param control] the player can see, in its viewport's canvas, or null when there is
+## none: its drawn box cut to the viewport and to every ScrollContainer between, each cut taken from
+## what the last one left. A control in view of an inner list and of the outer one can still sit
+## where the two do not overlap.
+static func shown_part(control: Control) -> Variant:
+	var part: Rect2 = control.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, control.size)
+	var clips: Array[Rect2] = [control.get_viewport().get_visible_rect()]
+	var walking: Node = control.get_parent()
+	while walking != null and not (walking is Viewport):
+		var holder: ScrollContainer = walking as ScrollContainer
+		if holder != null:
+			clips.append(holder.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, holder.size))
+		walking = walking.get_parent()
+	for clip: Rect2 in clips:
+		if not part.intersects(clip, true):
+			return null
+		part = part.intersection(clip)
+	return part

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

@@ -13,6 +13,15 @@ const GdhWords = preload("runtime_words.gd")
 ## How many of the controls saying the same words a refusal names, with the index for each.
 const LISTED_CANDIDATES: int = 10
 
+## Node.ProcessMode as its names, for a refusal to say which one is in force.
+const PROCESS_MODES: Dictionary[int, String] = {
+	Node.PROCESS_MODE_INHERIT: "INHERIT",
+	Node.PROCESS_MODE_PAUSABLE: "PAUSABLE",
+	Node.PROCESS_MODE_WHEN_PAUSED: "WHEN_PAUSED",
+	Node.PROCESS_MODE_ALWAYS: "ALWAYS",
+	Node.PROCESS_MODE_DISABLED: "DISABLED",
+}
+
 ## What a game started without a window gets whatever the project settings say, and the usual
 ## reason a control is out of reach. Only worth telling somebody when it is what they have.
 const HEADLESS_VIEWPORT: Vector2 = Vector2(64, 64)
@@ -753,9 +762,12 @@ static func _moved_by(node: Node, moves: Dictionary[ScrollContainer, Vector2]) -
 ## target's own viewport, a confirmation over a settings dialog did not cover the dialog's OK, and
 ## a click by words tied it with the confirmation's own.
 static func _window_over(target: Control, point: Vector2, window: Window) -> bool:
-	if window.get_parent() == null or window.is_ancestor_of(target):
+	# Not passed over for holding the target in the tree: a window under an embedded window is
+	# embedded beside it, not in it, so the one holding it can be stacked over it. The target's own
+	# window is the step out below, and is never over it.
+	if window.get_parent() == null:
 		return false
-	var host: Viewport = window.get_parent().get_viewport()
+	var host: Viewport = GdhScreen.embedder_of(window)
 	for step: Dictionary in GdhScreen.steps_out(target.get_viewport(), point):
 		if step["viewport"] != host:
 			continue
@@ -954,3 +966,20 @@ static func _out_of_reach_exactly(nodes: Array[Node], why: Array[String]) -> Str
 	if nodes.size() == 1:
 		return "1 control says exactly that and cannot be clicked: %s" % first
 	return "%d controls say exactly that and cannot be clicked, such as %s" % [nodes.size(), first]
+
+
+## Which node's process_mode keeps [param control] from processing, and what it is. A node set to
+## inherit takes its parent's, so the one deciding can be any node above it: the game turning a
+## whole screen off while a menu shows over it reads, on the button, as a button turned off.
+static func why_it_does_not_process(control: Control, node_path: String) -> String:
+	var deciding: Node = control
+	while deciding.process_mode == Node.PROCESS_MODE_INHERIT and deciding.get_parent() != null:
+		deciding = deciding.get_parent()
+	# The root inherits from nothing, which processes as pausable.
+	var value: int = deciding.process_mode
+	if value == Node.PROCESS_MODE_INHERIT:
+		value = Node.PROCESS_MODE_PAUSABLE
+	var mode: String = PROCESS_MODES.get(value, str(value))
+	if deciding == control:
+		return "its process_mode is %s" % mode
+	return "%s inherits process_mode %s from %s" % [node_path, mode, deciding.get_path()]