gdharness 0.6.1 → 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
 
@@ -285,8 +290,13 @@ 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}
@@ -312,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":
@@ -383,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

@@ -134,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():
@@ -168,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", ""))

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.1",
+  "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",