gdharness 1.3.9 → 1.3.10

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

@@ -78,12 +78,16 @@ func set_property(params: Dictionary) -> Dictionary:
 		var unwritable: String = GdhPaths.unwritable_copy(chain)
 		if not unwritable.is_empty():
 			return {"type": "error", "message": unwritable}
-	# The write alone, setter included, which is where a property's cost is.
+	# The write alone, setter included, which is where a property's cost is. Listened to as a call
+	# is, since a setter refusing a value says why only in what it reports.
+	var caught: GdhCallErrors = GdhCallErrors.new()
+	OS.add_logger(caught)
 	var began: int = Time.get_ticks_usec()
 	var written: Variant = GdhPaths.write(holder, named, given)
 	if copied:
 		GdhPaths.write_back(chain, written)
 	var elapsed: int = Time.get_ticks_usec() - began
+	OS.remove_logger(caught)
 	var now: Variant = GdhPaths.read_under(holder, named)
 	if copied:
 		var again: Dictionary = GdhPaths.walk_to(target, node_path, property)
@@ -122,20 +126,20 @@ func set_property(params: Dictionary) -> Dictionary:
 				)
 				% [named, str(slot["class"]), GdhValues.class_of(refused_object)]
 			)
-		return {
-			"type": "error",
-			"message":
-			(
-				"%s.%s was given %s and reads %s afterwards, as it did before: %s."
-				% [
-					reached["called"],
-					named,
-					JSON.stringify(_values.serialize(given), "", false),
-					JSON.stringify(_values.serialize(now), "", false),
-					why,
-				]
-			)
-		}
+		var refused: String = (
+			"%s.%s was given %s and reads %s afterwards, as it did before: %s."
+			% [
+				reached["called"],
+				named,
+				JSON.stringify(_values.serialize(given), "", false),
+				JSON.stringify(_values.serialize(now), "", false),
+				why,
+			]
+		)
+		if not caught.raised.is_empty():
+			var reported: PackedStringArray = PackedStringArray(caught.raised.slice(0, ERRORS_KEPT))
+			refused += " While it was written the game reported: %s" % "; ".join(reported)
+		return {"type": "error", "message": refused}
 
 	var answer: Dictionary = {
 		"type": "property_set",
@@ -147,6 +151,8 @@ func set_property(params: Dictionary) -> Dictionary:
 	}
 	if already and unmoved:
 		answer["unchanged"] = true
+	_keep_reported(answer, "errors", caught.raised)
+	_keep_reported(answer, "warnings", caught.warned)
 	# The engine stores a number past an export range, or one no enum value has, as given; only the
 	# inspector holds a property to them, so the game now holds a value its own script never expected.
 	if holder is Object:
@@ -169,6 +175,33 @@ func _argument_for(
 	var holder: Object = reached["holder"]
 	var called: String = reached["called"]
 	var wants: int = _values.parameter_type(holder, named, index)
+	var choices: Dictionary = _values.parameter_enum(holder, named, index)
+	var values: Dictionary = choices.get("values", {})
+	if not choices.is_empty() and sent is String and not str(sent).strip_edges().is_valid_int():
+		var chosen: Variant = GdhDeclared.enum_named(values, str(sent))
+		if chosen == null:
+			return {
+				"type": "error",
+				"message":
+				GdhDeclared.enum_argument_refusal(
+					"%s.%s" % [called, named], index, str(choices["enum"]), str(sent), values
+				)
+			}
+		return {"value": chosen}
+	# A packed list's elements are fitted one by one, and one that cannot become what the list holds
+	# is named: converted whole, a word or a fraction among them became 0 or was cut, and the call ran.
+	var packed: Variant = GdhValues.packed_template(wants)
+	if packed != null and sent is Array:
+		var elements: Dictionary = _values.typed_like(sent, packed, _element_object.bind(node, node_path))
+		if elements.has("message"):
+			return {
+				"type": "error",
+				"message":
+				(
+					"%s.%s takes %s as argument %d: %s"
+					% [called, named, type_string(wants), index + 1, elements["message"]]
+				)
+			}
 	if GdhValues.cuts(sent, wants):
 		return {
 			"type": "error",
@@ -259,6 +292,14 @@ func _value_for(
 			return {"value": by_name[1]}
 		if not str(by_name[1]).is_empty():
 			return {"type": "error", "message": by_name[1]}
+	var packed: Variant = GdhValues.packed_template(wanted)
+	if packed != null and value is Array:
+		var elements: Dictionary = _values.typed_like(value, packed, _element_object.bind(node, node_path))
+		if elements.has("message"):
+			return {
+				"type": "error",
+				"message": "%s.%s holds %s: %s" % [called, named, type_string(wanted), elements["message"]]
+			}
 	var holds_objects: bool = (
 		declared == TYPE_OBJECT or (declared == TYPE_NIL and (old_value == null or old_value is Object))
 	)
@@ -335,6 +376,52 @@ static func held_already(given: Variant, held: Variant) -> bool:
 	return PackedFloat32Array([given])[0] == PackedFloat32Array([held])[0]
 
 
+## What to do instead of the call [param method] makes on [param sort], the list or map [param
+## reached] ends on, which a path does not make. A method of the list itself is the likelier aim
+## than one of what it holds when the list has it: told to call append() on an element, a caller
+## adding to a list has nowhere to go.
+static func _instead_of_a_call(reached: Dictionary, method: String, sort: String) -> String:
+	var own: String = GdhPaths.method_of(str(reached["name"]))
+	if own.is_empty():
+		own = str(reached["name"])
+	var steps: PackedStringArray = GdhPaths.steps_of(method)
+	var _shortened: int = steps.resize(steps.size() - 1)
+	var holding: String = ":".join(steps)
+	var through_a_call: bool = false
+	for step: String in steps:
+		through_a_call = through_a_call or not GdhPaths.method_of(step).is_empty()
+	var the: String = "the " + sort.trim_prefix("a ")
+	match GdhPaths.container_method(reached["holder"], own):
+		"changes":
+			if through_a_call:
+				return (
+					(
+						"%s() changes %s: to change it, call a method of the game that changes it, since %s"
+						+ " is returned by a call, and runtime_invoke set does not write into what a call returns"
+					)
+					% [own, the, reached["called"]]
+				)
+			return (
+				(
+					"%s() changes %s: to change it, give %s its new value whole with runtime_invoke set,"
+					+ " property %s, or call a method of the game that changes it"
+				)
+				% [own, the, reached["called"], holding]
+			)
+		"reads":
+			return (
+				(
+					"To look in %s with %s(), read %s whole with runtime_inspect property, property %s, and"
+					+ " look in what comes back"
+				)
+				% [the, own, reached["called"], holding]
+			)
+	return (
+		"A method of what %s holds is called on the element, as in %s:0:%s"
+		% [sort, reached["called"], reached["name"]]
+	)
+
+
 func call_method(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var method: String = str(params.get("method", ""))
@@ -343,7 +430,33 @@ func call_method(params: Dictionary) -> Dictionary:
 	if node_path.is_empty() or method.is_empty():
 		return {"type": "error", "message": "Node path and method required"}
 
-	var standing: Dictionary = GdhValues.target_at(_host.get_tree().root, node_path)
+	var root: Node = _host.get_tree().root
+	var standing: Dictionary = GdhValues.class_at(root, node_path)
+	if standing.is_empty():
+		standing = GdhValues.target_at(root, node_path)
+		if standing.has("message") and node_path.is_valid_ascii_identifier():
+			var classes: Array[String] = []
+			for declared: Dictionary in ProjectSettings.get_global_class_list():
+				classes.append(str(declared.get("class", "")))
+			var close: PackedStringArray = GdhRead.nearest(node_path, PackedStringArray(classes))
+			standing["message"] = (
+				(
+					"%s. No global class is called %s either%s; a static function is called with its"
+					+ " class's name or its script's res:// path as the path."
+				)
+				% [
+					str(standing["message"]).trim_suffix("."),
+					node_path,
+					(
+						""
+						if close.is_empty()
+						else (
+							", and the nearest %s %s"
+							% ["is" if close.size() == 1 else "are", ", ".join(close)]
+						)
+					),
+				]
+			)
 	if standing.has("message"):
 		return standing
 	var node: Node = standing["node"]
@@ -368,13 +481,24 @@ func call_method(params: Dictionary) -> Dictionary:
 		var spelled: String = str(reached["name"])
 		if GdhPaths.method_of(spelled).is_empty():
 			spelled += "()"
-		# A vector or a transform has no element to call a method on: it is read by its components.
-		if GdhPaths.composite(reached["holder"]):
+		# A vector or a transform has no element to call a method on, so a call it does not answer is
+		# refused without the advice about elements below.
+		var answers: bool = GdhPaths.can_read(reached["holder"], spelled)
+		var called_on: Variant = reached["holder"]
+		if (
+			(GdhPaths.composite(called_on) or GdhPaths.textual(called_on))
+			and not (args.is_empty() and answers)
+		):
 			return {
 				"type": "error",
-				"message": GdhPaths.nothing_there(reached["holder"], spelled, str(reached["called"]))
+				"message":
+				(
+					"%s:%s takes no arguments" % [reached["called"], spelled]
+					if answers
+					else GdhPaths.nothing_there(reached["holder"], spelled, str(reached["called"]))
+				)
 			}
-		if args.is_empty() and GdhPaths.can_read(reached["holder"], spelled):
+		if args.is_empty() and answers:
 			var read_from: int = Time.get_ticks_usec()
 			var answered: Variant = GdhPaths.read_under(reached["holder"], spelled)
 			var read_for: int = Time.get_ticks_usec() - read_from
@@ -394,20 +518,19 @@ func call_method(params: Dictionary) -> Dictionary:
 			if GdhPaths.can_read(reached["holder"], spelled)
 			else GdhPaths.nothing_there(reached["holder"], spelled, str(reached["called"]))
 		)
-		return {
-			"type": "error",
-			"message":
-			(
-				"%s. A method of what %s holds is called on the element, as in %s:0:%s"
-				% [why, sort, reached["called"], reached["name"]]
-			)
-		}
+		return {"type": "error", "message": "%s. %s" % [why, _instead_of_a_call(reached, method, sort)]}
 	var holder: Object = reached["holder"]
 	var named: String = reached["name"]
 	# The method a call ends on is the one being called whether or not it carries the brackets a
 	# step along the way would: "get_viewport():gui_get_focus_owner()" is the same call as without
 	# the last pair.
-	var not_called: String = _not_a_method_to_call(holder, named, str(reached["called"]))
+	var not_called: String = _instance_method(
+		holder,
+		named if GdhPaths.method_of(named).is_empty() else GdhPaths.method_of(named),
+		str(reached["called"])
+	)
+	if not_called.is_empty():
+		not_called = _not_a_method_to_call(holder, named, str(reached["called"]))
 	if not not_called.is_empty():
 		return {"type": "error", "message": not_called}
 	if not GdhPaths.method_of(named).is_empty():
@@ -424,6 +547,9 @@ func call_method(params: Dictionary) -> Dictionary:
 	# The object arguments checked only against the engine class, by position from 1, for the refusal
 	# the engine may still make: see [method GdhValues.slot_declared].
 	var by_engine_class: Dictionary = {}
+	# The enum arguments given a number none of their values has, said beside the answer: the engine
+	# passes any number on, and a write of the same number to a property already said so.
+	var outside: PackedStringArray = []
 	for index: int in args.size():
 		var wants: int = _values.parameter_type(holder, named, index)
 		if wants == TYPE_OBJECT and (args[index] is String or args[index] is Dictionary):
@@ -444,6 +570,14 @@ func call_method(params: Dictionary) -> Dictionary:
 		if argument.has("message"):
 			return argument
 		deserialized_args.append(argument["value"])
+		var choices: Dictionary = _values.parameter_enum(holder, named, index)
+		if not choices.is_empty():
+			var values: Dictionary = choices["values"]
+			var stray: String = GdhDeclared.outside_enum_argument(
+				index, str(choices["enum"]), argument["value"], values
+			)
+			if not stray.is_empty():
+				var _noted: bool = outside.append(stray)
 
 	# Timed around the call alone, since the bridge's round trip is a second or more and swamps what
 	# one click's work costs; the frame metrics read whichever frame is last, which is not this one.
@@ -491,6 +625,8 @@ func call_method(params: Dictionary) -> Dictionary:
 	}
 	if awaited:
 		answer["awaited"] = true
+	if not outside.is_empty():
+		answer["outside_declared"] = " ".join(outside)
 	_keep_reported(answer, "errors", caught.raised)
 	_keep_reported(answer, "warnings", caught.warned)
 	# Main.explode, ended at a null it called into, answered result 0 as if it had counted something.
@@ -532,6 +668,25 @@ static func _not_a_method_to_call(holder: Object, named: String, called: String)
 	return GdhPaths.with_methods_offered("%s has no method %s" % [called, method], holder, method)
 
 
+## Why [param method] cannot be called on [param holder], a script named by its class or its path,
+## or "": a function that is not static runs on an instance of the class, which the script is not.
+static func _instance_method(holder: Object, method: String, called: String) -> String:
+	if not holder is Script:
+		return ""
+	var script: Script = holder
+	for entry: Dictionary in script.get_script_method_list():
+		if str(entry.get("name", "")) != method or GdhRead.as_int(entry.get("flags", 0)) & METHOD_FLAG_STATIC:
+			continue
+		return (
+			(
+				"%s.%s is not static, so it runs on an instance of the class: call it on a node carrying %s,"
+				+ " or on an object a path from one reaches"
+			)
+			% [called, method, script.resource_path]
+		)
+	return ""
+
+
 ## Whether a call's `properties` asks for its result to be read: true, or a list of names.
 static func _reads_the_result(asked: Variant) -> bool:
 	return asked is Array or (asked is bool and asked)
@@ -613,7 +768,7 @@ static func _argument_count_refused(holder: Object, method: String, given: int)
 	# of the game's frame; a call giving exactly the arguments the method declares needs no walk.
 	if given == holder.get_method_argument_count(method):
 		return ""
-	for entry: Dictionary in holder.get_method_list():
+	for entry: Dictionary in GdhValues.methods_of(holder):
 		if str(entry.get("name", "")) != method:
 			continue
 		var parameters: Array = entry.get("args", [])

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

@@ -148,7 +148,7 @@ func inject_action(params: Dictionary) -> Dictionary:
 		return {"type": "error", "message": holding}
 	var frames: int = holding
 
-	var focused: String = _focus_owner()
+	var focused: String = GdhValues.focus_path(_host)
 	_say_action(action, whole or held, strength)
 	var shortcuts: Dictionary = {"shortcuts": [], "shortcut_pressed": null}
 	if whole or held:
@@ -159,38 +159,21 @@ func inject_action(params: Dictionary) -> Dictionary:
 		# a listener that acts on the release both get their own frame to do it in.
 		lasted = await GdhValues.hold(_host.get_tree(), frames)
 		_say_action(action, false, strength)
-		await _host.get_tree().process_frame
-
-	return _focus_noted(
-		{
-			"type": "input_injected",
-			"input_type": "action",
-			"action": action,
-			"shortcuts": shortcuts["shortcuts"],
-			"shortcut_pressed": shortcuts["shortcut_pressed"],
-			"pressed": held and not whole,
-			"whole": whole,
-			"held_frames": GdhValues.held_answer(whole, frames),
-			"held_for": lasted,
-		},
-		focused
-	)
-
-
-## The path of the Control holding the keyboard focus, or "" when none does. Read before a key or an
-## action goes in, since pressing a focused button can move the focus.
-func _focus_owner() -> String:
-	var holding: Control = _host.get_viewport().gui_get_focus_owner()
-	return "" if holding == null else str(holding.get_path())
-
+	# The engine hands a parsed event on at the next frame, so the focus is read after one.
+	await _host.get_tree().process_frame
 
-## [param said] with [param focused], the Control that had the focus, under focused. A key or an action
-## reaches that Control before the game's _unhandled_input, so Space on a focused Button pressed it
-## and the game's own handler counted the key as well, with nothing in the answer saying why.
-static func _focus_noted(said: Dictionary, focused: String) -> Dictionary:
-	if not focused.is_empty():
-		said["focused"] = focused
-	return said
+	var answer: Dictionary = {
+		"type": "input_injected",
+		"input_type": "action",
+		"action": action,
+		"shortcuts": shortcuts["shortcuts"],
+		"shortcut_pressed": shortcuts["shortcut_pressed"],
+		"pressed": held and not whole,
+		"whole": whole,
+		"held_frames": GdhValues.held_answer(whole, frames),
+		"held_for": lasted,
+	}
+	return GdhValues.focus_noted(answer, focused, _host)
 
 
 func _say_action(action: String, down: bool, strength: float) -> void:
@@ -246,7 +229,7 @@ func inject_key(params: Dictionary) -> Dictionary:
 	# keys are the code points themselves, which is what makes this a mapping and not a table.
 	event.unicode = GdhValues.glyph_of(event.keycode, event.shift_pressed)
 
-	var focused: String = _focus_owner()
+	var focused: String = GdhValues.focus_path(_host)
 	Input.parse_input_event(event)
 	var lasted: Variant = null
 	if whole:
@@ -254,26 +237,24 @@ func inject_key(params: Dictionary) -> Dictionary:
 		var up: InputEventKey = event.duplicate()
 		up.pressed = false
 		Input.parse_input_event(up)
-		await _host.get_tree().process_frame
+	await _host.get_tree().process_frame
 
-	return _focus_noted(
-		{
-			"type": "input_injected",
-			"input_type": "key",
-			"held_frames": GdhValues.held_answer(whole, frames),
-			"held_for": lasted,
-			"keycode": event.keycode,
-			"physical_keycode": event.physical_keycode,
-			"shift": event.shift_pressed,
-			"ctrl": event.ctrl_pressed,
-			"alt": event.alt_pressed,
-			"unicode": event.unicode,
-			"actions": GdhValues.actions_of(event),
-			"pressed": held and not whole,
-			"whole": whole,
-		},
-		focused
-	)
+	var answer: Dictionary = {
+		"type": "input_injected",
+		"input_type": "key",
+		"held_frames": GdhValues.held_answer(whole, frames),
+		"held_for": lasted,
+		"keycode": event.keycode,
+		"physical_keycode": event.physical_keycode,
+		"shift": event.shift_pressed,
+		"ctrl": event.ctrl_pressed,
+		"alt": event.alt_pressed,
+		"unicode": event.unicode,
+		"actions": GdhValues.actions_of(event),
+		"pressed": held and not whole,
+		"whole": whole,
+	}
+	return GdhValues.focus_noted(answer, focused, _host)
 
 
 ## Clicks a mouse button at a position, and lets go of it again unless asked to hold it.
@@ -314,16 +295,22 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	# its drag from the press, which is where a real pointer would be.
 	var _moved: Vector2 = _arrive(position)
 	var supplied: bool = _follow_in_the_window(position)
-	var press: InputEventMouseButton = _button(position, button, whole or held, double)
+	# A double click's first click goes whole before it, as [method _click_button] sends one.
+	if double and held and not notch:
+		Input.parse_input_event(GdhMouse.button_event(position, button, true, false))
+		await _host.get_tree().process_frame
+		Input.parse_input_event(GdhMouse.button_event(position, button, false, false))
+		await _host.get_tree().process_frame
+	var press: InputEventMouseButton = GdhMouse.button_event(position, button, whole or held, double)
 	Input.parse_input_event(press)
 	var lasted: Variant = null
 	if notch:
-		Input.parse_input_event(_button(position, button, false, false))
+		Input.parse_input_event(GdhMouse.button_event(position, button, false, false))
 	elif whole:
 		# A frame between the halves at least, as inject_action has, so a control that acts on the
 		# press and one that acts on the release each get a frame to do it in.
 		lasted = await GdhValues.hold(_host.get_tree(), frames)
-		Input.parse_input_event(_button(position, button, false, false))
+		Input.parse_input_event(GdhMouse.button_event(position, button, false, false))
 	# Input hands the events on at the next frame, so the control under the pointer is read after it.
 	await _host.get_tree().process_frame
 	var hovered: Control = _hover.hovered_in(_host.get_viewport())
@@ -424,7 +411,7 @@ func inject_mouse_drag(params: Dictionary) -> Dictionary:
 	var end: Vector2 = points[points.size() - 1]
 	var _moved: Vector2 = _arrive(start)
 	var supplied: bool = _follow_in_the_window(start)
-	Input.parse_input_event(_button(start, button, true, false))
+	Input.parse_input_event(GdhMouse.button_event(start, button, true, false))
 	var travelled: Vector2 = Vector2.ZERO
 	for step: int in range(1, frames + 1):
 		await _host.get_tree().process_frame
@@ -434,7 +421,7 @@ func inject_mouse_drag(params: Dictionary) -> Dictionary:
 		supplied = _follow_in_the_window(at) or supplied
 		Input.parse_input_event(_motion(at, relative))
 	await _host.get_tree().process_frame
-	Input.parse_input_event(_button(end, button, false, false))
+	Input.parse_input_event(GdhMouse.button_event(end, button, false, false))
 	await _host.get_tree().process_frame
 
 	var said: Dictionary = _pointer_noted(
@@ -555,6 +542,7 @@ func click(params: Dictionary) -> Dictionary:
 	# other words, a link among them. Said either way, so a press on the middle is never read as one
 	# on the words.
 	var aim: Vector2 = control.size * 0.5
+	var at_centre: bool = true
 	var item_scrolled: bool = false
 	if item != null:
 		var found_by_words: Dictionary = found
@@ -564,6 +552,7 @@ func click(params: Dictionary) -> Dictionary:
 		if placed_item.has("message"):
 			return placed_item
 		aim = placed_item["point"]
+		at_centre = false
 		item_scrolled = placed_item["scrolled"]
 	var rich: RichTextLabel = control as RichTextLabel
 	if found != null and rich != null:
@@ -571,6 +560,7 @@ func click(params: Dictionary) -> Dictionary:
 		var found_here: Dictionary = found
 		if placed.has("point"):
 			aim = placed["point"]
+			at_centre = false
 			found_here["pressedOn"] = "the words"
 		elif placed.has("unplaced"):
 			found_here["pressedOn"] = "the middle of the label"
@@ -607,6 +597,20 @@ func click(params: Dictionary) -> Dictionary:
 			}
 		local = control.get_global_transform_with_canvas() * aim
 
+	# A control taller or wider than what shows it has its centre out of sight at every scroll, and
+	# a player clicks the part they can see. Refused, it was called a control nothing could click.
+	var on_part: bool = false
+	if at_centre and not _in_sight(control, own, local):
+		var part: Variant = GdhScreen.shown_part(control)
+		if part is Rect2:
+			var seen: Rect2 = part
+			var middle: Vector2 = seen.get_center()
+			# The box of a turned control is wider than the control, so its middle may be off it.
+			var back: Vector2 = control.get_global_transform_with_canvas().affine_inverse() * middle
+			if seen.has_area() and Rect2(Vector2.ZERO, control.size).has_point(back):
+				local = middle
+				on_part = true
+
 	var reached: Dictionary = GdhScreen.reach(own, local)
 	var viewport: Viewport = reached["viewport"]
 	var centre: Vector2 = reached["point"]
@@ -643,6 +647,8 @@ func click(params: Dictionary) -> Dictionary:
 	if hovered != null:
 		hovered_path = str(hovered.get_path())
 	var landed: bool = hovered == control or (hovered != null and control.is_ancestor_of(hovered))
+	# Asked only of a miss, before the press restacks windows: hovered missed a window over it.
+	var cover: Node = null if landed else GdhTargets.drawn_over(control)
 
 	# The link a rich label says was pressed, which is its own word for what the press reached.
 	var links: Array = []
@@ -658,10 +664,7 @@ func click(params: Dictionary) -> Dictionary:
 	var was_pressed: Variant = null
 	if toggle != null and toggle.toggle_mode:
 		was_pressed = toggle.button_pressed
-	var press: InputEventMouseButton = _button(position, button, true, double)
-	_press_button(viewport, press)
-	await _host.get_tree().process_frame
-	_press_button(viewport, _button(position, button, false, false))
+	var press: InputEventMouseButton = await _click_button(viewport, position, button, double)
 	# 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
@@ -685,12 +688,16 @@ func click(params: Dictionary) -> Dictionary:
 		"control_afterwards": afterwards,
 		"scrolled_into_view": scrolled,
 	}
+	if on_part:
+		answer["pressed_on"] = "the middle of the part on screen, since no scroll brings its centre into view"
 	# A Label and a TextureRect ignore the pointer unless told otherwise, so the click goes to what is
 	# under them, and landed false with that control as hovered said nothing of why.
 	if not landed and control.mouse_filter == Control.MOUSE_FILTER_IGNORE:
 		answer["why_not_landed"] = (
 			"%s's mouse_filter is ignore, so the pointer passes through it to what is under it" % node_path
 		)
+	elif cover != null:
+		answer["why_not_landed"] = "%s is drawn over it at the point clicked" % cover.get_path()
 	if found != null:
 		answer["found"] = found
 	if was_pressed != null:
@@ -795,6 +802,23 @@ func _no_window_note(viewport: Viewport) -> String:
 ##
 ## 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 `GdhScreen.reach` carries every other one there.
+## A press and its release a frame apart, answering with the press. A double click arrives as the
+## engine gets one from the system: a whole click, then a second press marked as a double click and
+## its release. Sent as the marked press alone, it pressed a button once where a player's presses it
+## twice.
+func _click_button(viewport: Viewport, position: Vector2, button: int, double: bool) -> InputEventMouseButton:
+	if double:
+		_press_button(viewport, GdhMouse.button_event(position, button, true, false))
+		await _host.get_tree().process_frame
+		_press_button(viewport, GdhMouse.button_event(position, button, false, false))
+		await _host.get_tree().process_frame
+	var press: InputEventMouseButton = GdhMouse.button_event(position, button, true, double)
+	_press_button(viewport, press)
+	await _host.get_tree().process_frame
+	_press_button(viewport, GdhMouse.button_event(position, button, false, false))
+	return press
+
+
 func _press_button(viewport: Viewport, event: InputEventMouseButton) -> void:
 	if viewport == _host.get_tree().root:
 		Input.parse_input_event(event)
@@ -877,9 +901,7 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	var through: Dictionary = _through_the_interface(out)
 	var hovered_path: Variant = through["hovered"]
 
-	_press_button(arriving, _button(position, button, true, double))
-	await _host.get_tree().process_frame
-	_press_button(arriving, _button(position, button, false, false))
+	var _press: InputEventMouseButton = await _click_button(arriving, position, button, double)
 	await _host.get_tree().process_frame
 
 	return _pointer_noted(
@@ -975,18 +997,3 @@ func _motion(position: Vector2, relative: Vector2) -> InputEventMouseMotion:
 	event.screen_velocity = event.velocity
 	event.button_mask = Input.get_mouse_button_mask()
 	return event
-
-
-## A button event carries the buttons held once it has happened: the pressed one among them, the
-## released one out. A wheel step is a button with no mask, as it is from a real mouse.
-func _button(position: Vector2, button: int, pressed: bool, double: bool) -> InputEventMouseButton:
-	var event: InputEventMouseButton = InputEventMouseButton.new()
-	event.position = position
-	event.global_position = position
-	event.button_index = button as MouseButton
-	event.pressed = pressed
-	event.double_click = double
-	var held: int = Input.get_mouse_button_mask()
-	var own: int = GdhMouse.mask_of(button)
-	event.button_mask = (held | own) if pressed else (held & ~own)
-	return event

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

@@ -65,6 +65,23 @@ static func mask_of(button: int) -> int:
 	return 1 << (button - 1)
 
 
+## A button event carries the buttons held once it has happened: the pressed one among them, the
+## released one out. A wheel step is a button with no mask, as it is from a real mouse.
+static func button_event(
+	position: Vector2, button: int, pressed: bool, double: bool
+) -> InputEventMouseButton:
+	var event: InputEventMouseButton = InputEventMouseButton.new()
+	event.position = position
+	event.global_position = position
+	event.button_index = button as MouseButton
+	event.pressed = pressed
+	event.double_click = double
+	var held: int = Input.get_mouse_button_mask()
+	var own: int = mask_of(button)
+	event.button_mask = (held | own) if pressed else (held & ~own)
+	return event
+
+
 ## [param answer], saying so when one of [param points] lies outside [param viewport]: the GUI picks
 ## what is under the pointer only inside it, so such a press or motion reaches no control, and its
 ## answer read the same as one that landed.