gdharness 1.1.11 → 1.1.13

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

@@ -10,6 +10,8 @@ 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 Menus = preload("runtime_menus.gd")
+const Screen = preload("runtime_screen.gd")
 const Targets = preload("runtime_targets.gd")
 const Words = preload("runtime_words.gd")
 
@@ -410,36 +412,6 @@ func inject_mouse_motion(params: Dictionary) -> Dictionary:
 	}
 
 
-## The viewport a click aimed at [param control] has to be pushed into.
-##
-## Its own, unless that is an embedded [Window]. A ConfirmationDialog is a Window, and under
-## `gui_embed_subwindows` a Window is drawn inside its parent rather than given one by the
-## desktop: pushing into its own viewport delivers nothing, measured, with the pointer reading as
-## over no control at all. What reaches it is the parent, which is what the engine does with a
-## real pointer. Walked rather than stepped once, because a dialog can open a dialog.
-static func _clicking_viewport(control: Control) -> Viewport:
-	var viewport: Viewport = control.get_viewport()
-	var window: Window = viewport as Window
-	while window != null and window.is_embedded() and window.get_parent() != null:
-		viewport = window.get_parent().get_viewport()
-		window = viewport as Window
-	return viewport
-
-
-## Where [param control]'s centre is in the viewport [method _clicking_viewport] names.
-##
-## The transform is against the control's own viewport, so every embedded window between it and
-## that one contributes its offset. The same walk, because the two answers have to agree about
-## which viewport they are describing.
-static func _centre_of(control: Control) -> Vector2:
-	var centre: Vector2 = control.get_global_transform_with_canvas() * (control.size * 0.5)
-	var window: Window = control.get_viewport() as Window
-	while window != null and window.is_embedded() and window.get_parent() != null:
-		centre += Vector2(window.position)
-		window = window.get_parent().get_viewport() as Window
-	return centre
-
-
 ## Scrolls whatever is holding [param control] until it is on screen, and answers whether
 ## anything moved.
 ##
@@ -521,8 +493,9 @@ func click(params: Dictionary) -> Dictionary:
 	if not control.is_visible_in_tree():
 		return {"type": "error", "message": "%s is not visible, so nothing can click it" % node_path}
 
-	var viewport: Viewport = _clicking_viewport(control)
-	var centre: Vector2 = _centre_of(control)
+	# In the control's own viewport first, which is the space its scrolling happens in.
+	var own: Viewport = control.get_viewport()
+	var local: Vector2 = control.get_global_transform_with_canvas() * (control.size * 0.5)
 
 	# A control out of sight inside a ScrollContainer is not out of reach, it is one scroll away,
 	# which is what a person does without thinking about it before they click. Refusing it
@@ -534,19 +507,23 @@ func click(params: Dictionary) -> Dictionary:
 	# the click went to that instead and said so. Measured on a hall whose staff panel had been
 	# scrolled past: the button was at y 69 and its container started at y 166.
 	var scrolled: bool = false
-	if not _in_sight(control, viewport, centre):
+	if not _in_sight(control, own, local):
 		scrolled = _scroll_into_view(control)
 		if scrolled:
 			# A container moves its child on the next layout pass rather than inside the call.
 			await _host.get_tree().process_frame
-			centre = control.get_global_transform_with_canvas() * (control.size * 0.5)
+			local = control.get_global_transform_with_canvas() * (control.size * 0.5)
 
+	var reached: Dictionary = Screen.reach(own, local)
+	var viewport: Viewport = reached["viewport"]
+	var centre: Vector2 = reached["point"]
 	var position: Vector2 = viewport.get_final_transform() * centre
 	# The GUI only delivers to what is inside the viewport, so a centre outside it would be a
 	# click that silently reached nothing. A game with no window has a 64 by 64 viewport
 	# whatever the project settings say, which is the usual reason to be here and is not
-	# something the caller can read off the rect on its own.
-	if not viewport.get_visible_rect().has_point(centre):
+	# something the caller can read off the rect on its own. Its own viewport as well, since a
+	# control outside its SubViewport is drawn nowhere.
+	if not viewport.get_visible_rect().has_point(centre) or not own.get_visible_rect().has_point(local):
 		var why: String = _no_window_note(viewport)
 		if scrolled:
 			why = ". It was scrolled as far as what holds it goes and is still out there"
@@ -583,20 +560,17 @@ func click(params: Dictionary) -> Dictionary:
 		hovered_path = str(hovered.get_path())
 	var landed: bool = hovered == control or (hovered != null and control.is_ancestor_of(hovered))
 
-	viewport.push_input(_button(position, button, true, double))
+	_press_button(viewport, _button(position, button, true, double))
 	await _host.get_tree().process_frame
-	viewport.push_input(_button(position, button, false, false))
+	_press_button(viewport, _button(position, button, false, false))
 	# The release is what a button acts on, and a queue_free it causes lands at the end of
 	# this frame; the frame passes so the answer describes the control as the click left it.
 	await _host.get_tree().process_frame
 
 	# What became of the control: still in the tree, taken out of it, or freed. A button that
 	# opened another screen is the second or the third, and the caller wants to hear that
-	# rather than guess it from a tree that has changed shape. A freed reference cannot be
-	# handed to anything typed, so the question is asked here.
-	var afterwards: String = "freed"
-	if is_instance_valid(control):
-		afterwards = "in_tree" if control.is_inside_tree() else "removed"
+	# rather than guess it from a tree that has changed shape.
+	var afterwards: String = _afterwards(control)
 
 	var answer: Dictionary = {
 		"type": "clicked",
@@ -655,7 +629,7 @@ func choose(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	var menu: PopupMenu = _menu_of(node)
+	var menu: PopupMenu = Menus.menu_of(node)
 	if menu == null:
 		return {
 			"type": "error",
@@ -672,15 +646,15 @@ func choose(params: Dictionary) -> Dictionary:
 			"message":
 			(
 				"%s needs the item named, by text or index. It holds: %s"
-				% [node_path, ", ".join(_items_of(menu))]
+				% [node_path, ", ".join(Menus.items_of(menu))]
 			)
 		}
 
-	var index: int = _wanted_item(menu, params)
+	var index: int = Menus.wanted_item(menu, params)
 	if index < 0:
 		return {
 			"type": "error",
-			"message": "%s has no such item. It holds: %s" % [node_path, ", ".join(_items_of(menu))]
+			"message": "%s has no such item. It holds: %s" % [node_path, ", ".join(Menus.items_of(menu))]
 		}
 	if menu.is_item_separator(index):
 		var heading: String = Words.item_says(menu, index).strip_edges()
@@ -705,9 +679,22 @@ func choose(params: Dictionary) -> Dictionary:
 	# Shown first, because a menu nobody has opened has no focus to move and Enter would go to
 	# whatever is behind it. An OptionButton opens its own; a bare PopupMenu is popped where it
 	# already sits, which leaves a menu that was already open where it is.
-	var opened: bool = _open_the_menu(node, menu)
+	var opened: bool = Menus.open_the_menu(node, menu)
 	await _host.get_tree().process_frame
 
+	# Read before the press, because the press can take the menu away: a game that rebuilds its
+	# settings screen on item_selected frees the button and its menu inside the pick, and reading
+	# the item afterwards was an engine error in the game's log and an empty answer to a pick that
+	# had taken.
+	var answer: Dictionary = {
+		"type": "chosen",
+		"path": node_path,
+		"index": index,
+		"text": Words.item_says(menu, index),
+		"id": menu.get_item_id(index),
+		"opened": opened,
+		"menu": str(menu.get_path()),
+	}
 	menu.scroll_to_item(index)
 	menu.set_focused_item(index)
 	# Through Input rather than pushed at the menu, which is how a keyboard reaches an open one: a
@@ -718,96 +705,49 @@ func choose(params: Dictionary) -> Dictionary:
 	Input.parse_input_event(_accept(false))
 	await _host.get_tree().process_frame
 
-	var answer: Dictionary = {
-		"type": "chosen",
-		"path": node_path,
-		"index": index,
-		"text": Words.item_says(menu, index),
-		"id": menu.get_item_id(index),
-		"opened": opened,
-		"menu": str(menu.get_path()),
-	}
+	answer["control_afterwards"] = _afterwards(node)
 	# What the button in front of the menu reads now, which is the answer to "did it take": a menu
-	# item that fired changes the thing holding it, and nothing else about the press says so.
-	var chooser: OptionButton = node as OptionButton
-	if chooser != null:
+	# item that fired changes the thing holding it, and nothing else about the press says so. A
+	# button the pick took away has nothing to read, and that it went is the answer.
+	if answer["control_afterwards"] == "in_tree" and node is OptionButton:
+		var chooser: OptionButton = node
 		answer["selected"] = chooser.get_selected()
 		answer["shows"] = Words.said_by(chooser)
 	return answer
 
 
-## The menu [param node] is, or the one it holds. An [OptionButton] and a [MenuButton] both keep
-## theirs as an internal child, which is a node a caller cannot name and should not have to.
-static func _menu_of(node: Node) -> PopupMenu:
-	var menu: PopupMenu = node as PopupMenu
-	if menu != null:
-		return menu
-	if node.has_method("get_popup"):
-		var held: Variant = node.call("get_popup")
-		if held is PopupMenu:
-			return held
-	return null
+## Sends a click's press or release into [param viewport], through Input when that is the game's
+## own window.
+##
+## Through Input so that Input knows a button is held, which is what a real mouse tells it. A
+## PopupMenu opened by a press asks Input whether a button is down, and when one is, it lets the
+## release that ends that press go by rather than choosing the item under it. Pushed straight into
+## the viewport, the press left Input thinking nothing was held, so a dropdown near the bottom of
+## the screen, whose menu opens over it and under the pointer, had its first item chosen by the
+## click meant to open it. Games read that state too, through Input.is_mouse_button_pressed.
+##
+## Any other viewport is pushed into directly: Input reaches only the game's window. That is a
+## viewport with no place on the screen, since `Screen.reach` carries every other one there.
+func _press_button(viewport: Viewport, event: InputEventMouseButton) -> void:
+	if viewport == _host.get_tree().root:
+		Input.parse_input_event(event)
+		# Delivered now, as a push is, rather than at the next frame: the answer is read a frame
+		# after the release, and a button that frees itself on it has to be gone by then.
+		Input.flush_buffered_events()
+	else:
+		viewport.push_input(event)
 
 
-## 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)
-		return asked if asked >= 0 and asked < menu.get_item_count() else -1
-	var wanted: String = str(params.get("text", ""))
-	if wanted.is_empty():
-		return -1
-	# 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.
-	var order: Array[int] = []
-	for separators: bool in [false, true]:
-		for index: int in menu.get_item_count():
-			if menu.is_item_separator(index) == separators:
-				order.append(index)
-	var shown: Array[String] = []
-	var held: Array[String] = []
-	for index: int in order:
-		shown.append(Words.item_says(menu, index))
-		held.append(menu.get_item_text(index))
-	for words: Array[String] in [shown, held]:
-		for at: int in words.size():
-			if words[at] == wanted:
-				return order[at]
-		for at: int in words.size():
-			if words[at].nocasecmp_to(wanted) == 0:
-				return order[at]
-	return -1
-
-
-## What the menu shows, for a refusal that names the choices rather than the miss: a titled
-## separator marked as the heading it is, and one with no title left out, since it shows nothing.
-static func _items_of(menu: PopupMenu) -> Array[String]:
-	var said: Array[String] = []
-	for index: int in menu.get_item_count():
-		var words: String = Words.item_says(menu, index)
-		if not menu.is_item_separator(index):
-			said.append("%d: %s" % [index, words])
-		elif not words.strip_edges().is_empty():
-			said.append("%d: %s (a heading)" % [index, words])
-	return said
-
-
-## Opens the menu if it is not already, and answers whether anything opened.
-static func _open_the_menu(node: Node, menu: PopupMenu) -> bool:
-	if menu.visible:
-		return false
-	if node.has_method("show_popup"):
-		node.call("show_popup")
-		return true
-	menu.popup()
-	return true
+## What became of [param node] once an input it was given has run: still in the tree, taken out
+## of it, or freed. Untyped, because a freed reference handed to a typed parameter is itself the
+## engine error this is here to avoid.
+static func _afterwards(node: Variant) -> String:
+	if not is_instance_valid(node):
+		return "freed"
+	if not node is Node:
+		return "removed"
+	var placed: Node = node
+	return "in_tree" if placed.is_inside_tree() else "removed"
 
 
 func _accept(pressed: bool) -> InputEventKey:
@@ -859,13 +799,16 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 			)
 		}
 
-	var position: Vector2 = viewport.get_final_transform() * aim
+	var reached: Dictionary = Screen.reach(viewport, aim)
+	var arriving: Viewport = reached["viewport"]
+	var reached_point: Vector2 = reached["point"]
+	var position: Vector2 = arriving.get_final_transform() * reached_point
 	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
 	if button < 0:
 		return _no_such_button(params.get("button"))
 	var double: bool = Read.as_bool(params.get("double", false))
 
-	viewport.push_input(_motion(position, _arrive(position)))
+	arriving.push_input(_motion(position, _arrive(position)))
 	# Read before the press, for the reason the Control click reads it: what the caller needs to
 	# know is whether a panel is sitting over the room, and the press is what would change it.
 	var hovered: Control = viewport.gui_get_hovered_control()
@@ -873,9 +816,9 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	if hovered != null:
 		hovered_path = str(hovered.get_path())
 
-	viewport.push_input(_button(position, button, true, double))
+	_press_button(arriving, _button(position, button, true, double))
 	await _host.get_tree().process_frame
-	viewport.push_input(_button(position, button, false, false))
+	_press_button(arriving, _button(position, button, false, false))
 	await _host.get_tree().process_frame
 
 	return {

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

@@ -0,0 +1,81 @@
+extends RefCounted
+
+## The menu a choice is made from and the item in it, for a choice made by what an item says or by
+## where it is in the list.
+
+const Read = preload("reading.gd")
+const Words = preload("runtime_words.gd")
+
+
+## The menu [param node] is, or the one it holds. An [OptionButton] and a [MenuButton] both keep
+## theirs as an internal child, which is a node a caller cannot name and should not have to.
+static func menu_of(node: Node) -> PopupMenu:
+	var menu: PopupMenu = node as PopupMenu
+	if menu != null:
+		return menu
+	if node.has_method("get_popup"):
+		var held: Variant = node.call("get_popup")
+		if held is PopupMenu:
+			return held
+	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.
+##
+## `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)
+		return asked if asked >= 0 and asked < menu.get_item_count() else -1
+	var wanted: String = str(params.get("text", ""))
+	if wanted.is_empty():
+		return -1
+	# 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.
+	var order: Array[int] = []
+	for separators: bool in [false, true]:
+		for index: int in menu.get_item_count():
+			if menu.is_item_separator(index) == separators:
+				order.append(index)
+	var shown: Array[String] = []
+	var held: Array[String] = []
+	for index: int in order:
+		shown.append(Words.item_says(menu, index))
+		held.append(menu.get_item_text(index))
+	for words: Array[String] in [shown, held]:
+		for at: int in words.size():
+			if words[at] == wanted:
+				return order[at]
+		for at: int in words.size():
+			if words[at].nocasecmp_to(wanted) == 0:
+				return order[at]
+	return -1
+
+
+## What the menu shows, for a refusal that names the choices rather than the miss: a titled
+## separator marked as the heading it is, and one with no title left out, since it shows nothing.
+static func items_of(menu: PopupMenu) -> Array[String]:
+	var said: Array[String] = []
+	for index: int in menu.get_item_count():
+		var words: String = Words.item_says(menu, index)
+		if not menu.is_item_separator(index):
+			said.append("%d: %s" % [index, words])
+		elif not words.strip_edges().is_empty():
+			said.append("%d: %s (a heading)" % [index, words])
+	return said
+
+
+## Opens the menu if it is not already, and answers whether anything opened.
+static func open_the_menu(node: Node, menu: PopupMenu) -> bool:
+	if menu.visible:
+		return false
+	if node.has_method("show_popup"):
+		node.call("show_popup")
+		return true
+	menu.popup()
+	return true

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

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

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

@@ -5,6 +5,7 @@ extends RefCounted
 
 const Paths = preload("runtime_paths.gd")
 const Read = preload("reading.gd")
+const Screen = preload("runtime_screen.gd")
 const Values = preload("runtime_values.gd")
 const Words = preload("runtime_words.gd")
 
@@ -423,21 +424,30 @@ func get_rect(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
+	# In the window's pixels, which is what a mouse event names, through every embedded window and
+	# SubViewport between the node and the window: multiplied by its own viewport's transform alone,
+	# a control in a dialog lost the dialog's offset and one in a SubViewport was given its place in
+	# the SubViewport, and a mouse event sent there missed it.
 	if node is Control:
 		var control: Control = node
-		var to_window: Transform2D = control.get_viewport().get_final_transform()
 		var canvas_rect: Rect2 = control.get_global_rect()
 		return {
 			"type": "rect",
 			"path": node_path,
 			"visible": control.is_visible_in_tree(),
 			"canvas": _values.serialize(canvas_rect),
-			"window": _values.serialize(to_window * canvas_rect),
+			"window":
+			_values.serialize(
+				Screen.rect_in_window(
+					control.get_viewport(),
+					control.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, control.size)
+				)
+			),
 		}
 	if node is Node2D:
 		var item: Node2D = node
 		var canvas_position: Vector2 = item.get_global_transform_with_canvas().origin
-		var window_position: Vector2 = item.get_viewport().get_final_transform() * canvas_position
+		var window_position: Vector2 = Screen.in_window(item.get_viewport(), canvas_position)
 		return {
 			"type": "point",
 			"path": node_path,
@@ -470,7 +480,7 @@ func _in_the_frame(node_path: String, item: Node3D) -> Dictionary:
 			"message": "%s is not in a viewport with a current Camera3D, so nothing is drawing it" % node_path
 		}
 
-	var to_window: Transform2D = item.get_viewport().get_final_transform()
+	var drawn_in: Viewport = item.get_viewport()
 	var answer: Dictionary = {
 		"type": "point",
 		"path": node_path,
@@ -481,12 +491,12 @@ func _in_the_frame(node_path: String, item: Node3D) -> Dictionary:
 	if found.has("aim"):
 		var aim: Vector2 = found["aim"]
 		answer["canvas"] = _values.serialize(aim)
-		answer["window"] = _values.serialize(to_window * aim)
+		answer["window"] = _values.serialize(Screen.in_window(drawn_in, aim))
 	if found.has("rect"):
 		var covered: Rect2 = found["rect"]
 		answer["covers"] = {
 			"canvas": _values.serialize(covered),
-			"window": _values.serialize(to_window * covered),
+			"window": _values.serialize(Screen.rect_in_window(drawn_in, covered)),
 		}
 	return answer
 

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

@@ -0,0 +1,50 @@
+extends RefCounted
+
+## Where a point in some viewport is on the game's own screen, for a click to be sent there and for
+## an answer to say where something is drawn.
+
+
+## The viewport a pointer at [param point], in [param viewport]'s own coordinates, arrives through,
+## and where it is there: {"viewport", "point"}.
+##
+## A real pointer arrives at the outermost viewport showing this one and is handed down, so that is
+## where a click is sent. An embedded [Window], a ConfirmationDialog for one, is drawn inside its
+## parent under `gui_embed_subwindows`: pushing into its own viewport delivered nothing, measured,
+## with the pointer reading as over no control at all. A [SubViewport] shown by a
+## [SubViewportContainer] is drawn inside the container, scaled by its shrink when it stretches, and
+## pushing into it read the point as the container's: the click on a dropdown inside one landed on
+## nothing. Walked rather than stepped once, because a dialog can open a dialog and a container can
+## sit inside another viewport. A SubViewport drawn some other way, onto a mesh for one, has no
+## place on the screen to carry the point to, and the point stays in it.
+static func reach(viewport: Viewport, point: Vector2) -> Dictionary:
+	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()
+			continue
+		var shown_by: SubViewportContainer = viewport.get_parent() as SubViewportContainer
+		if viewport is SubViewport and shown_by != null:
+			var scaled: Vector2 = point * float(shown_by.stretch_shrink) if shown_by.stretch else point
+			point = shown_by.get_global_transform_with_canvas() * scaled
+			viewport = shown_by.get_viewport()
+			continue
+		break
+	return {"viewport": viewport, "point": point}
+
+
+## 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:
+	var reached: Dictionary = reach(viewport, point)
+	var outermost: Viewport = reached["viewport"]
+	var there: Vector2 = reached["point"]
+	return outermost.get_final_transform() * there
+
+
+## [param rect], in [param viewport]'s own coordinates, in the window's pixels: the box its two
+## corners make once carried there, which is the rect itself for anything not turned.
+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())

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

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