gdharness 0.6.0 → 0.6.2

package/build/cli.js

@@ -15785,7 +15785,7 @@ var init_tool_definitions = __esm(() => {
           requires: []
         },
         rect: {
-          summary: "one node's rectangle or position, in canvas and in window pixels",
+          summary: "one node's rectangle or position, in canvas and in window pixels. A 3D node answers with the point to aim at, which is the middle of what it draws rather than the origin it stands on, the rectangle it covers under covers, the camera that drew it, and behind_camera when it is not in front of one",
           requires: ["nodePath"]
         },
         property: {
@@ -15834,10 +15834,13 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "runtime_input",
-      description: "Input to the running game: a whole click on a Control named by path, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.",
+      description: "Input to the running game: a whole click on a Control or a 3D node named by path, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
-        nodePath: { type: "string", description: "click: the Control to click, at its centre." },
+        nodePath: {
+          type: "string",
+          description: "click: the Control to click, at its centre, or the 3D node to click, where it is drawn."
+        },
         action: { type: "string", description: "action: the InputMap action name." },
         pressed: { type: "boolean", description: "Press or release. Default true." },
         strength: { type: "number", description: "action: 0 to 1. Default 1." },
@@ -15863,7 +15866,7 @@ var init_tool_definitions = __esm(() => {
       requires: [],
       operations: {
         click: {
-          summary: "press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed. A control out of sight inside a ScrollContainer is scrolled to first, and scrolled_into_view says whether the view moved",
+          summary: "press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed. A control out of sight inside a ScrollContainer is scrolled to first, and scrolled_into_view says whether the view moved. A 3D node is clicked where it is drawn, and landed then says the interface did not swallow the press",
           requires: ["nodePath"]
         },
         action: { summary: "press or release an action", requires: ["action"] },
@@ -38641,6 +38644,8 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | What a property reads right now | \`runtime_inspect\` \`property\`, \`runtime_invoke\` |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |
 | Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\` |
+| Click somebody standing in a 3D room | \`runtime_input click\` on the Node3D, which aims at what it draws |
+| Where a 3D node is on screen | \`runtime_inspect\` \`rect\`, rather than unprojecting by hand |
 | Wait for something | \`runtime_wait\`, never a sleep |
 | A picture, for a person who asked to see one | \`runtime_capture\` |
 

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

@@ -1,10 +1,15 @@
 extends RefCounted
 
 ## Input handed to the running game as if a player had given it: actions, keys, the mouse, and
-## a whole click on a Control found by path.
+## a whole click on a Control or a 3D node found by path.
 
 const Values = preload("runtime_values.gd")
 
+## Where a 3D node is drawn, which is what a click aimed at one has to work out first. Asked of the
+## query module rather than worked out again here, so the place this aims at and the place a rect
+## reports are the same place by construction rather than by agreement.
+const Queries = preload("runtime_queries.gd")
+
 ## The distance from a capital letter to its small one in Unicode. A keycode holds the capital.
 const TO_SMALL: int = 32
 
@@ -220,6 +225,36 @@ 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.
 ##
@@ -255,14 +290,19 @@ func click(params: Dictionary) -> Dictionary:
 	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
 	if node == null:
 		return {"type": "error", "message": "Node not found: " + node_path}
+	if node is Node3D:
+		return await _click_in_the_world(node_path, node, params)
 	if not node is Control:
-		return {"type": "error", "message": "%s is a %s, not a Control" % [node_path, node.get_class()]}
+		return {
+			"type": "error",
+			"message": "%s is a %s, not a Control or a Node3D" % [node_path, node.get_class()]
+		}
 	var control: Control = node
 	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 = control.get_viewport()
-	var centre: Vector2 = control.get_global_transform_with_canvas() * (control.size * 0.5)
+	var viewport: Viewport = _clicking_viewport(control)
+	var centre: Vector2 = _centre_of(control)
 
 	# A control below the fold of 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
@@ -282,18 +322,9 @@ func click(params: Dictionary) -> Dictionary:
 	# 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):
-		var why: String = ""
+		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"
-		elif not _host.get_tree().root.can_draw():
-			why = ". This game has no window: run it with a window to reach this control"
-			# Only where it is true. The rect is printed just above, so claiming 64 by 64 over a
-			# viewport somebody has resized says two different things in one sentence.
-			if viewport.get_visible_rect().size == HEADLESS_VIEWPORT:
-				why = (
-					". This game has no window, and a game with no window has a 64 by 64 viewport "
-					+ "whatever the project settings say: run it with a window to reach this control"
-				)
 		return {
 			"type": "error",
 			"message":
@@ -314,7 +345,12 @@ func click(params: Dictionary) -> Dictionary:
 	# that went to it. Read in full here, path included, because nothing about that control
 	# is guaranteed to survive the release: a button that opens the next screen takes the
 	# whole menu out of the tree, and a node that has left the tree has no path to give.
-	var hovered: Control = viewport.gui_get_hovered_control()
+	# Asked of the control's own viewport rather than the one the event went into, and for an
+	# embedded window those are two different objects: the parent takes the event and hands it on,
+	# 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_path: Variant = null
 	if hovered != null:
 		hovered_path = str(hovered.get_path())
@@ -348,6 +384,94 @@ func click(params: Dictionary) -> Dictionary:
 	}
 
 
+## What to add to a refusal about a point outside the viewport, when the reason is that nobody
+## gave this game a window. The rect on its own does not say it, and it is the usual reason.
+##
+## The size is only claimed where it is true: the rect is printed beside this, so naming 64 by 64
+## over a viewport somebody has resized says two different things in one sentence.
+func _no_window_note(viewport: Viewport) -> String:
+	if _host.get_tree().root.can_draw():
+		return ""
+	if viewport.get_visible_rect().size == HEADLESS_VIEWPORT:
+		return (
+			". This game has no window, and a game with no window has a 64 by 64 viewport whatever "
+			+ "the project settings say: run it with a window to reach this control"
+		)
+	return ". This game has no window: run it with a window to reach this control"
+
+
+## A whole click aimed at where a 3D node is drawn, for a game that picks with a ray out of the
+## cursor rather than with a Control.
+##
+## The alternative was three calls: read the node's position, find the camera, unproject it, then
+## push raw mouse events at the answer. Anything that walks has walked by the third, so the click
+## lands where it used to be, which is a miss that looks exactly like a game that ignored it.
+##
+## What this can honestly say is where the click went and whether the interface took it: a Control
+## under the pointer swallows the press and the room never hears it, and that is the failure worth
+## naming. Whether the game's own picking then chose this node is the game's rule rather than
+## anything the engine can be asked, so it is not claimed.
+func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) -> Dictionary:
+	if not item.is_visible_in_tree():
+		return {"type": "error", "message": "%s is not visible, so nothing can click it" % node_path}
+
+	var found: Dictionary = Queries.in_frame(item)
+	if found.is_empty():
+		return {
+			"type": "error",
+			"message":
+			"%s is not in a viewport with a current Camera3D, so there is nowhere to click it" % node_path
+		}
+	if not found.has("aim"):
+		return {
+			"type": "error",
+			"message": "%s is behind the camera drawing it, so it is not on screen to click" % node_path
+		}
+
+	var viewport: Viewport = item.get_viewport()
+	var aim: Vector2 = found["aim"]
+	if not viewport.get_visible_rect().has_point(aim):
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s is drawn at %s, outside the viewport %s, so nothing can click it%s"
+				% [node_path, aim, viewport.get_visible_rect(), _no_window_note(viewport)]
+			)
+		}
+
+	var position: Vector2 = viewport.get_final_transform() * aim
+	var button: int = _resolve_mouse_button(params.get("button", MOUSE_BUTTON_LEFT))
+	var double: bool = bool(params.get("double", false))
+
+	viewport.push_input(_motion(position, Vector2.ZERO))
+	# 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()
+	var hovered_path: Variant = null
+	if hovered != null:
+		hovered_path = str(hovered.get_path())
+
+	viewport.push_input(_button(position, button, true, double))
+	await _host.get_tree().process_frame
+	viewport.push_input(_button(position, button, false, false))
+	await _host.get_tree().process_frame
+
+	return {
+		"type": "clicked",
+		"path": node_path,
+		"position": _values.serialize(position),
+		"button": button,
+		"double": double,
+		"hovered": hovered_path,
+		# The interface did not take it, so it reached the game's own input. As close to "it
+		# landed" as anything outside the game can get, and said in the same word the Control
+		# click says it in.
+		"landed": hovered == null,
+		"camera": found["camera"],
+	}
+
+
 func _motion(position: Vector2, relative: Vector2) -> InputEventMouseMotion:
 	var event: InputEventMouseMotion = InputEventMouseMotion.new()
 	event.position = position

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

@@ -75,7 +75,13 @@ func find_nodes(params: Dictionary) -> Dictionary:
 				truncated = true
 				break
 			found.append(_found(node, wanted_property))
-		var children: Array[Node] = node.get_children()
+		# Internal children included, which they were not. A ConfirmationDialog builds its Yes and
+		# its No as internal nodes, and a ScrollContainer its bars, so a find over a screen for
+		# every Button came back without the two buttons the player is being asked to press:
+		# nothing here could see the dialog at all, and the way past it was to emit `confirmed`.
+		# A filtered query carries no cost for including them, because they only appear when they
+		# are what was asked for.
+		var children: Array[Node] = node.get_children(true)
 		for index: int in range(children.size() - 1, -1, -1):
 			pending.push_front(children[index])
 
@@ -128,9 +134,10 @@ func _matches(
 	return true
 
 
-## Where a node is on screen: a Control's rectangle, or a Node2D's position, in both the
-## canvas coordinates the node reports and the window pixels input arrives in. The two differ
-## whenever the project stretches its viewport, which is what made a rect unusable for a click.
+## Where a node is on screen: a Control's rectangle, a Node2D's position, or the place a 3D node
+## is drawn in, in both the canvas coordinates the node reports and the window pixels input
+## arrives in. The two differ whenever the project stretches its viewport, which is what made a
+## rect unusable for a click.
 func get_rect(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	if node_path.is_empty():
@@ -162,11 +169,124 @@ func get_rect(params: Dictionary) -> Dictionary:
 			"canvas": _values.serialize(canvas_position),
 			"window": _values.serialize(window_position),
 		}
+	if node is Node3D:
+		return _in_the_frame(node_path, node)
 	return {
 		"type": "error", "message": "%s is a %s, which has no place on screen" % [node_path, node.get_class()]
 	}
 
 
+## 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.
+##
+## A 3D node had no answer here at all, so placing one meant reading its position, finding the
+## camera and calling unproject_position by hand. Three calls, and anything that walks has walked
+## between the first and the third: the aim lands where the thing used to be.
+##
+## The camera is named in the answer, because "where is it on screen" is a question about a camera
+## and a game with two of them has two answers.
+func _in_the_frame(node_path: String, item: Node3D) -> Dictionary:
+	var found: Dictionary = in_frame(item)
+	if found.is_empty():
+		return {
+			"type": "error",
+			"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 answer: Dictionary = {
+		"type": "point",
+		"path": node_path,
+		"visible": item.is_visible_in_tree(),
+		"camera": found["camera"],
+		"behind_camera": found["behind"],
+	}
+	if found.has("aim"):
+		var aim: Vector2 = found["aim"]
+		answer["canvas"] = _values.serialize(aim)
+		answer["window"] = _values.serialize(to_window * aim)
+	if found.has("rect"):
+		var covered: Rect2 = found["rect"]
+		answer["covers"] = {
+			"canvas": _values.serialize(covered),
+			"window": _values.serialize(to_window * covered),
+		}
+	return answer
+
+
+## What anything aiming at a 3D node needs: the camera that draws it, whether it is behind that
+## camera, the point on screen to aim at, and the rectangle it covers. Empty when no camera is
+## drawing it at all.
+##
+## The aim is the middle of what the node draws rather than its origin, because a person clicking
+## a character clicks the character and a character's origin is on the floor under their feet. A
+## node that draws nothing has no middle and falls back to the origin, which is still a place.
+##
+## Absent keys rather than nulls: nothing drawn, or behind the camera, and each of those is a
+## different answer from a coordinate that happens to be zero. Public and static because the click
+## has to aim at the same point this reports, and two copies of the arithmetic would be two places
+## on screen for one node the first time either changed.
+static func in_frame(item: Node3D) -> Dictionary:
+	var viewport: Viewport = item.get_viewport()
+	if viewport == null:
+		return {}
+	var camera: Camera3D = viewport.get_camera_3d()
+	if camera == null:
+		return {}
+
+	var origin: Vector3 = item.global_transform.origin
+	var found: Dictionary = {"camera": str(camera.get_path()), "behind": camera.is_position_behind(origin)}
+	var box: AABB = drawn_box(item)
+	var draws: bool = box.size != Vector3.ZERO
+	var middle: Vector3 = box.get_center() if draws else origin
+	if not camera.is_position_behind(middle):
+		found["aim"] = camera.unproject_position(middle)
+	if draws:
+		found.merge(_around(box, camera))
+	return found
+
+
+## The rectangle [param box] covers on screen, under the key `rect`, or nothing when any of it is
+## behind the camera.
+##
+## All eight corners, because a box in space is not a box in the frame: an orthographic camera
+## looking down a diagonal draws a cube as a hexagon, and the rectangle worth answering is the one
+## around every corner of it. Nothing rather than a guess when a corner is behind the camera,
+## because [method Camera3D.unproject_position] mirrors those back into view and a rectangle built
+## from one is a rectangle somewhere else entirely.
+static func _around(box: AABB, camera: Camera3D) -> Dictionary:
+	var seen: Rect2 = Rect2()
+	for index: int in 8:
+		var corner: Vector3 = box.get_endpoint(index)
+		if camera.is_position_behind(corner):
+			return {}
+		var point: Vector2 = camera.unproject_position(corner)
+		seen = Rect2(point, Vector2.ZERO) if index == 0 else seen.expand(point)
+	return {"rect": seen}
+
+
+## The box everything drawn under [param item] fits in, in world space, or a box with no size when
+## nothing under it draws.
+##
+## Walked rather than asked of [param item] itself, because the node a caller names is the one that
+## moves and the thing on screen is the mesh hanging off it: a character is a Node3D with a
+## skeleton and a mesh under it, and the Node3D has no extent of its own at all.
+static func drawn_box(item: Node3D) -> AABB:
+	var merged: AABB = AABB()
+	var found: bool = false
+	var pending: Array[Node] = [item]
+	while not pending.is_empty():
+		var node: Node = pending.pop_back()
+		var visual: VisualInstance3D = node as VisualInstance3D
+		if visual != null and visual.is_visible_in_tree():
+			var box: AABB = visual.global_transform * visual.get_aabb()
+			merged = box if not found else merged.merge(box)
+			found = true
+		for child: Node in node.get_children(true):
+			pending.push_back(child)
+	return merged
+
+
 func get_property(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
@@ -286,7 +406,11 @@ func _serialize_node_tree(node: Node, depth: int, max_depth: int, include_proper
 
 	if depth < max_depth:
 		var children: Array = []
-		for child: Node in node.get_children():
+		# Internal ones too, for the reason `find` takes them: a tree that answers "no children"
+		# over a ConfirmationDialog holding a Yes and a No is not tidier than one that says so,
+		# it is wrong, and it is what sends somebody looking for another way to press the button.
+		# `depth` is what keeps the answer a size worth reading.
+		for child: Node in node.get_children(true):
 			children.append(_serialize_node_tree(child, depth + 1, max_depth, include_properties))
 		result["children"] = children
 

package/build/index.js

@@ -28299,7 +28299,7 @@ var TOOL_SPECS = [
         requires: []
       },
       rect: {
-        summary: "one node's rectangle or position, in canvas and in window pixels",
+        summary: "one node's rectangle or position, in canvas and in window pixels. A 3D node answers with the point to aim at, which is the middle of what it draws rather than the origin it stands on, the rectangle it covers under covers, the camera that drew it, and behind_camera when it is not in front of one",
         requires: ["nodePath"]
       },
       property: {
@@ -28348,10 +28348,13 @@ var TOOL_SPECS = [
   },
   {
     name: "runtime_input",
-    description: "Input to the running game: a whole click on a Control named by path, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.",
+    description: "Input to the running game: a whole click on a Control or a 3D node named by path, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
-      nodePath: { type: "string", description: "click: the Control to click, at its centre." },
+      nodePath: {
+        type: "string",
+        description: "click: the Control to click, at its centre, or the 3D node to click, where it is drawn."
+      },
       action: { type: "string", description: "action: the InputMap action name." },
       pressed: { type: "boolean", description: "Press or release. Default true." },
       strength: { type: "number", description: "action: 0 to 1. Default 1." },
@@ -28377,7 +28380,7 @@ var TOOL_SPECS = [
     requires: [],
     operations: {
       click: {
-        summary: "press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed. A control out of sight inside a ScrollContainer is scrolled to first, and scrolled_into_view says whether the view moved",
+        summary: "press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed. A control out of sight inside a ScrollContainer is scrolled to first, and scrolled_into_view says whether the view moved. A 3D node is clicked where it is drawn, and landed then says the interface did not swallow the press",
         requires: ["nodePath"]
       },
       action: { summary: "press or release an action", requires: ["action"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",