gdharness 1.2.31 → 1.2.32

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

@@ -11,8 +11,10 @@ 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 Hover = preload("runtime_hover.gd")
 const Screen = preload("runtime_screen.gd")
 const Targets = preload("runtime_targets.gd")
+const Mouse = preload("runtime_mouse.gd")
 
 ## The distance from a capital letter to its small one in Unicode. A keycode holds the capital.
 const TO_SMALL: int = 32
@@ -33,8 +35,12 @@ const PROCESS_MODES: Dictionary[int, String] = {
 ## Whether this run has had the pointer note in full; the game process is the run.
 static var _pointer_explained: bool = false
 
+## Whether this run has had the note on a supplied hover in full.
+static var _hover_explained: bool = false
+
 var _host: Node
 var _values: Values
+var _hover: Hover = Hover.new()
 
 ## Where the last injected pointer event put the pointer, once one has.
 ##
@@ -87,6 +93,32 @@ static func _pointer_noted(answer: Dictionary) -> Dictionary:
 	return answer
 
 
+## [param answer], saying that the hover it reports was supplied here, when [param supplied]: see
+## runtime_hover.gd.
+static func _hover_noted(answer: Dictionary, supplied: bool) -> Dictionary:
+	if not supplied:
+		return answer
+	answer["hover_supplied"] = true
+	if not _hover_explained:
+		_hover_explained = true
+		answer["hover_note"] = (
+			"This window has had no pointer enter from the operating system, and with subwindow"
+			+ " embedding off Godot hovers nothing in a native window until it has, so a Button there"
+			+ " takes no press. The runtime gave the controls under the pointer the hover the engine"
+			+ " would have: their mouse_entered and mouse_exited, and the hover a Button presses on."
+			+ " Viewport.gui_get_hovered_control() still answers null in this window. Said once a run;"
+			+ " hover_supplied marks every answer it applies to."
+		)
+	return answer
+
+
+## Hovers what is under [param position] in the game's window, where the pointer events Input is
+## given go, when the engine cannot: see runtime_hover.gd.
+func _follow_in_the_window(position: Vector2) -> bool:
+	var root: Window = _host.get_tree().root
+	return _hover.follow(root, root.get_final_transform().affine_inverse() * position)
+
+
 ## 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
@@ -242,22 +274,6 @@ func _glyph_of(keycode: Key, shifted: bool) -> int:
 	return keycode
 
 
-## A point the tool schema sends as two flat numbers, or the older form of one [x, y] value.
-## Answers a Vector2, or the String that says what was wrong with it.
-func _read_point(params: Dictionary, x_key: String, y_key: String, pair_key: String) -> Variant:
-	if params.has(x_key) and params.has(y_key):
-		return Vector2(Read.as_float(params[x_key]), Read.as_float(params[y_key]))
-	var raw: Variant = params.get(pair_key, Vector2.ZERO)
-	if raw is Vector2:
-		return raw
-	if raw is Array:
-		var pair: Array = raw
-		if pair.size() < 2:
-			return "%s array must contain [x, y]" % pair_key
-		return Vector2(Read.as_float(pair[0]), Read.as_float(pair[1]))
-	return "%s must be Vector2 or [x, y]" % pair_key
-
-
 ## Clicks a mouse button at a position, and lets go of it again unless asked to hold it.
 ##
 ## The whole click by default, for the reason [method inject_action] is the whole press, and
@@ -267,20 +283,20 @@ func _read_point(params: Dictionary, x_key: String, y_key: String, pair_key: Str
 ## `pressed` is how a caller asks for one half, the way a drag is made: true holds the button down,
 ## false lets go of one being held.
 func inject_mouse_click(params: Dictionary) -> Dictionary:
-	var point: Variant = _read_point(params, "x", "y", "position")
+	var point: Variant = Mouse.read_point(params, "x", "y", "position")
 	if point is String:
 		return {"type": "error", "message": point}
 	var position: Vector2 = point
-	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
+	var button: int = Mouse.button_of(params.get("button", MOUSE_BUTTON_LEFT))
 	if button < 0:
-		return _no_such_button(params.get("button"))
+		return Mouse.no_such_button(params.get("button"))
 	var held: bool = Read.as_bool(params.get("pressed", true), true)
 	var double: bool = Read.as_bool(params.get("doubleClick", false))
 	# A wheel step is a press and a release together, as a mouse sends one: there is no holding a
 	# wheel. A lone wheel press left the viewport's mouse focus on the control that took it, with
 	# the wheel's bit in the focus mask, and every click after it landed on that control rather
 	# than under the pointer, landing true and doing nothing, until a release was sent by hand.
-	var notch: bool = held and _mask_of(button) == 0
+	var notch: bool = held and Mouse.mask_of(button) == 0
 	var whole: bool = notch or not params.has("pressed")
 	var holding: Variant = Values.held_for(params)
 	if holding is String:
@@ -295,6 +311,7 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	# A button pressed somewhere puts the pointer there: the motion after a held press measures
 	# 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)
 	Input.parse_input_event(_button(position, button, whole or held, double))
 	if notch:
 		Input.parse_input_event(_button(position, button, false, false))
@@ -306,16 +323,19 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 		await _host.get_tree().process_frame
 
 	return _pointer_noted(
-		{
-			"type": "input_injected",
-			"input_type": "mouse_click",
-			"held_frames": Values.held_answer(whole and not notch, frames),
-			"position": [position.x, position.y],
-			"button": button,
-			"pressed": held and not whole,
-			"whole": whole,
-			"double": double
-		}
+		_hover_noted(
+			{
+				"type": "input_injected",
+				"input_type": "mouse_click",
+				"held_frames": Values.held_answer(whole and not notch, frames),
+				"position": [position.x, position.y],
+				"button": button,
+				"pressed": held and not whole,
+				"whole": whole,
+				"double": double
+			},
+			supplied
+		)
 	)
 
 
@@ -328,7 +348,7 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 ## would have carried. A relative the caller gives is kept, since a game may want to read a motion
 ## the position does not show.
 func inject_mouse_motion(params: Dictionary) -> Dictionary:
-	var point: Variant = _read_point(params, "x", "y", "position")
+	var point: Variant = Mouse.read_point(params, "x", "y", "position")
 	if point is String:
 		return {"type": "error", "message": point}
 	var position: Vector2 = point
@@ -338,20 +358,87 @@ func inject_mouse_motion(params: Dictionary) -> Dictionary:
 			Read.as_float(params.get("relativeX", 0.0)), Read.as_float(params.get("relativeY", 0.0))
 		)
 	elif params.has("relative"):
-		var movement: Variant = _read_point(params, "relativeX", "relativeY", "relative")
+		var movement: Variant = Mouse.read_point(params, "relativeX", "relativeY", "relative")
 		if movement is String:
 			return {"type": "error", "message": movement}
 		relative = movement
 
+	var supplied: bool = _follow_in_the_window(position)
 	Input.parse_input_event(_motion(position, relative))
 
 	return _pointer_noted(
-		{
-			"type": "input_injected",
-			"input_type": "mouse_motion",
-			"position": [position.x, position.y],
-			"relative": [relative.x, relative.y]
+		_hover_noted(
+			{
+				"type": "input_injected",
+				"input_type": "mouse_motion",
+				"position": [position.x, position.y],
+				"relative": [relative.x, relative.y]
+			},
+			supplied
+		)
+	)
+
+
+## Drags with a mouse button from one point to another, through any points between, as a hand does:
+## the press, one motion each process frame along the stroke, and the release where the last motion
+## left the pointer, a frame after it. A game acting on every motion it gets sees as many as a real
+## stroke over that many frames sends. Made of calls, a stroke cost a round trip a motion, so the
+## one a caller could afford was three or four motions where a hand sends dozens, and a stir that
+## moves a few cells a motion moved two for a stroke.
+##
+## Each motion goes in a frame of its own because the engine merges the motions it is given within
+## one frame into a single event, as it does a real mouse's, and a game counting motions counts one.
+func inject_mouse_drag(params: Dictionary) -> Dictionary:
+	var stroke: Variant = Mouse.stroke_of(params)
+	if stroke is String:
+		return {"type": "error", "message": stroke}
+	var points: Array[Vector2] = stroke
+	var button: int = Mouse.button_of(params.get("button", MOUSE_BUTTON_LEFT))
+	if button < 0:
+		return Mouse.no_such_button(params.get("button"))
+	var own: int = Mouse.mask_of(button)
+	if own == 0:
+		return {
+			"type": "error",
+			"message": "A wheel step has no held position to drag from: give left, right or middle."
+		}
+	var frames: int = Read.as_int(params.get("frames", 0), 0)
+	if frames < 1 or frames > Values.MOST_HELD:
+		return {
+			"type": "error", "message": "frames is %d, and it takes 1 to %d." % [frames, Values.MOST_HELD]
 		}
+
+	var lengths: Array[float] = Mouse.lengths_of(points)
+	var start: Vector2 = points[0]
+	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))
+	var travelled: Vector2 = Vector2.ZERO
+	for step: int in range(1, frames + 1):
+		await _host.get_tree().process_frame
+		var at: Vector2 = Mouse.along(points, lengths, float(step) / frames)
+		var relative: Vector2 = _arrive(at)
+		travelled += relative
+		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))
+	await _host.get_tree().process_frame
+
+	return _pointer_noted(
+		_hover_noted(
+			{
+				"type": "input_injected",
+				"input_type": "mouse_drag",
+				"from": [start.x, start.y],
+				"to": [end.x, end.y],
+				"button": button,
+				"motions": frames,
+				"relative_total": [travelled.x, travelled.y],
+			},
+			supplied
+		)
 	)
 
 
@@ -507,15 +594,16 @@ func click(params: Dictionary) -> Dictionary:
 	var out_there: String = _out_of_reach(control, node_path, local, reached, scrolled)
 	if not out_there.is_empty():
 		return {"type": "error", "message": out_there}
-	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
+	var button: int = Mouse.button_of(params.get("button", MOUSE_BUTTON_LEFT))
 	if button < 0:
-		return _no_such_button(params.get("button"))
+		return Mouse.no_such_button(params.get("button"))
 	var double: bool = Read.as_bool(params.get("double", false))
 
 	# Pushed into the viewport rather than through Input: Input accumulates events and flushes
 	# them at the next frame, so the hovered control read below would be the one from before
 	# the pointer moved. The viewport delivers it to the GUI the same way a real one arrives.
 	viewport.push_input(_motion(position, _arrive(position)))
+	var supplied: bool = _hover.follow(viewport, centre)
 	# What the engine itself thinks is under the pointer, which is the answer to "did it land",
 	# read before the press so the caller learns about a control on top rather than a click
 	# that went to it. Read in full here, path included, because nothing about that control
@@ -526,7 +614,7 @@ func click(params: Dictionary) -> Dictionary:
 	# and the window keeps the GUI state. Reading the parent reported every dialog as not landed
 	# while the button it was aimed at pressed perfectly well, which is the worst shape an answer
 	# can have, since the caller believes the miss over what the game just did.
-	var hovered: Control = control.get_viewport().gui_get_hovered_control()
+	var hovered: Control = _hover.hovered_in(control.get_viewport())
 	var hovered_path: Variant = null
 	if hovered != null:
 		hovered_path = str(hovered.get_path())
@@ -584,7 +672,7 @@ func click(params: Dictionary) -> Dictionary:
 		answer["link_pressed"] = not links.is_empty()
 		if not links.is_empty():
 			answer["link_meta"] = _values.serialize(links.back())
-	return _pointer_noted(answer)
+	return _pointer_noted(_hover_noted(answer, supplied))
 
 
 ## Why [param control] would take no click a player gave it, or "" when it would.
@@ -761,12 +849,13 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 			)
 		}
 	var position: Vector2 = arriving.get_final_transform() * reached_point
-	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
+	var button: int = Mouse.button_of(params.get("button", MOUSE_BUTTON_LEFT))
 	if button < 0:
-		return _no_such_button(params.get("button"))
+		return Mouse.no_such_button(params.get("button"))
 	var double: bool = Read.as_bool(params.get("double", false))
 
 	arriving.push_input(_motion(position, _arrive(position)))
+	var supplied: bool = _hover.follow(arriving, reached_point)
 	# 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 through: Dictionary = _through_the_interface(out)
@@ -778,19 +867,22 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	await _host.get_tree().process_frame
 
 	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"],
-		}
+		_hover_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"],
+			},
+			supplied
+		)
 	)
 
 
@@ -803,12 +895,12 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 ## over what shows the one inside: the SubViewportContainer, with nothing drawn over it, or inside
 ## the embedded window. Read in the first viewport alone, a click beside a container that is smaller
 ## than what it shows, or under a panel drawn over the container, answered landed.
-static func _through_the_interface(out: Array[Dictionary]) -> Dictionary:
+func _through_the_interface(out: Array[Dictionary]) -> Dictionary:
 	var first_under: Variant = null
 	for step: Dictionary in out:
 		var viewport: Viewport = step["viewport"]
 		var through: Variant = step["through"]
-		var hovered: Control = viewport.gui_get_hovered_control()
+		var hovered: Control = _hover.hovered_in(viewport)
 		if through is Window:
 			var window: Window = through
 			var point: Vector2 = step["point"]
@@ -879,53 +971,6 @@ func _button(position: Vector2, button: int, pressed: bool, double: bool) -> Inp
 	event.pressed = pressed
 	event.double_click = double
 	var held: int = Input.get_mouse_button_mask()
-	var own: int = _mask_of(button)
+	var own: int = Mouse.mask_of(button)
 	event.button_mask = (held | own) if pressed else (held & ~own)
 	return event
-
-
-## The mask bit for a button, which is the engine's own mapping: left 1, right 2, middle 4, the
-## two extra buttons 128 and 256. The wheel steps between have none.
-func _mask_of(button: int) -> int:
-	if button >= MOUSE_BUTTON_WHEEL_UP and button <= MOUSE_BUTTON_WHEEL_RIGHT:
-		return 0
-	return 1 << (button - 1)
-
-
-## What to say about a name that is not a mouse button, with the ones that are.
-func _no_such_button(named: Variant) -> Dictionary:
-	return {
-		"type": "error",
-		"message":
-		(
-			"%s is not a mouse button. It takes: left, right, middle, wheel_up, wheel_down, or the number of one."
-			% JSON.stringify(named)
-		)
-	}
-
-
-## The button [param raw] names, or -1 for a name that is not one of them.
-##
-## A name nobody recognises used to come back as the left button, so a right click asked for by a
-## spelling this does not know went to the left button and reported the left button. The caller
-## reads the answer and believes it, which is the whole reason nothing here guesses.
-func _resolve_mouse_button(raw: Variant) -> int:
-	if raw is String:
-		var named: String = raw
-		match named.to_lower():
-			"left":
-				return MOUSE_BUTTON_LEFT
-			"right":
-				return MOUSE_BUTTON_RIGHT
-			"middle":
-				return MOUSE_BUTTON_MIDDLE
-			"wheel_up", "wheelup":
-				return MOUSE_BUTTON_WHEEL_UP
-			"wheel_down", "wheeldown":
-				return MOUSE_BUTTON_WHEEL_DOWN
-			_:
-				return -1
-	# The engine's buttons run from 1 to 9: 0 is MOUSE_BUTTON_NONE, which no event carries, and a
-	# number past the two extra buttons names nothing a mask bit can be made for.
-	var number: int = Read.as_int(raw, -1)
-	return number if number >= MOUSE_BUTTON_LEFT and number <= MOUSE_BUTTON_XBUTTON2 else -1

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

@@ -0,0 +1,112 @@
+extends RefCounted
+
+## What a pointer call names: a point, the stroke of a drag, a mouse button and its mask bit. Read
+## here and sent from runtime_input.gd, which keeps where the pointer is.
+
+const Read = preload("reading.gd")
+
+
+## A point the tool schema sends as two flat numbers, or the older form of one [x, y] value.
+## Answers a Vector2, or the String that says what was wrong with it.
+static func read_point(params: Dictionary, x_key: String, y_key: String, pair_key: String) -> Variant:
+	if params.has(x_key) and params.has(y_key):
+		return Vector2(Read.as_float(params[x_key]), Read.as_float(params[y_key]))
+	var raw: Variant = params.get(pair_key, Vector2.ZERO)
+	if raw is Vector2:
+		return raw
+	if raw is Array:
+		var pair: Array = raw
+		if pair.size() < 2:
+			return "%s array must contain [x, y]" % pair_key
+		return Vector2(Read.as_float(pair[0]), Read.as_float(pair[1]))
+	return "%s must be Vector2 or [x, y]" % pair_key
+
+
+## The points of a drag: x, y, then each of via, then toX, toY. Answers the String saying what is
+## wrong instead, since a point left out would otherwise read as the window's corner.
+static func stroke_of(params: Dictionary) -> Variant:
+	for key: String in ["x", "y", "toX", "toY"]:
+		if not params.has(key):
+			return "mouse_drag needs x, y, toX and toY: %s is missing." % key
+	var points: Array[Vector2] = [Vector2(Read.as_float(params["x"]), Read.as_float(params["y"]))]
+	var via: Variant = params.get("via", [])
+	if not via is Array:
+		return "via must be a list of [x, y] points."
+	var between: Array = via
+	for point: Variant in between:
+		var pair: Array = point if point is Array else []
+		if pair.size() < 2:
+			return "via must be a list of [x, y] points, and holds %s." % JSON.stringify(point)
+		points.append(Vector2(Read.as_float(pair[0]), Read.as_float(pair[1])))
+	points.append(Vector2(Read.as_float(params["toX"]), Read.as_float(params["toY"])))
+	return points
+
+
+## The distance along [param points] to each of them from the first.
+static func lengths_of(points: Array[Vector2]) -> Array[float]:
+	var lengths: Array[float] = [0.0]
+	for at: int in range(1, points.size()):
+		lengths.append(lengths[at - 1] + points[at - 1].distance_to(points[at]))
+	return lengths
+
+
+## The point [param share] of the way along the stroke through [param points], by distance, with
+## [param lengths] from [method lengths_of].
+static func along(points: Array[Vector2], lengths: Array[float], share: float) -> Vector2:
+	var total: float = lengths[lengths.size() - 1]
+	if total == 0.0:
+		return points[0]
+	var wanted: float = total * share
+	for at: int in range(1, points.size()):
+		if lengths[at] >= wanted:
+			var span: float = lengths[at] - lengths[at - 1]
+			var part: float = 0.0 if span == 0.0 else (wanted - lengths[at - 1]) / span
+			return points[at - 1].lerp(points[at], part)
+	return points[points.size() - 1]
+
+
+## The mask bit for a button, which is the engine's own mapping: left 1, right 2, middle 4, the
+## two extra buttons 128 and 256. The wheel steps between have none.
+static func mask_of(button: int) -> int:
+	if button >= MOUSE_BUTTON_WHEEL_UP and button <= MOUSE_BUTTON_WHEEL_RIGHT:
+		return 0
+	return 1 << (button - 1)
+
+
+## What to say about a name that is not a mouse button, with the ones that are.
+static func no_such_button(named: Variant) -> Dictionary:
+	return {
+		"type": "error",
+		"message":
+		(
+			"%s is not a mouse button. It takes: left, right, middle, wheel_up, wheel_down, or the number of one."
+			% JSON.stringify(named)
+		)
+	}
+
+
+## The button [param raw] names, or -1 for a name that is not one of them.
+##
+## A name nobody recognises used to come back as the left button, so a right click asked for by a
+## spelling this does not know went to the left button and reported the left button. The caller
+## reads the answer and believes it, which is the whole reason nothing here guesses.
+static func button_of(raw: Variant) -> int:
+	if raw is String:
+		var named: String = raw
+		match named.to_lower():
+			"left":
+				return MOUSE_BUTTON_LEFT
+			"right":
+				return MOUSE_BUTTON_RIGHT
+			"middle":
+				return MOUSE_BUTTON_MIDDLE
+			"wheel_up", "wheelup":
+				return MOUSE_BUTTON_WHEEL_UP
+			"wheel_down", "wheeldown":
+				return MOUSE_BUTTON_WHEEL_DOWN
+			_:
+				return -1
+	# The engine's buttons run from 1 to 9: 0 is MOUSE_BUTTON_NONE, which no event carries, and a
+	# number past the two extra buttons names nothing a mask bit can be made for.
+	var number: int = Read.as_int(raw, -1)
+	return number if number >= MOUSE_BUTTON_LEFT and number <= MOUSE_BUTTON_XBUTTON2 else -1

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

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