ravensight-playtest 0.1.0

package/addons/ravensight_driver/driver.gd

@@ -0,0 +1,836 @@
+# Ravensight Playtest driver: newline delimited JSON-RPC 2.0 over TCP.
+#
+# This autoload is injected into a temporary copy of the customer's project by
+# the ravensight-playtest CLI (src/run/drivers/godot.js). It is never added to
+# the customer's own project directory, and it refuses to run at all unless
+# every activation condition in spec 07 holds:
+#
+#   1. The build is not an export template, OR it was exported with the custom
+#      feature tag "ravensight_driver". A release export without that tag never
+#      activates the driver even if the flag below is passed.
+#   2. AND either "--ravensight-driver" is present in the user args (after the
+#      "--" separator) or RAVENSIGHT_DRIVER=1 is in the environment.
+#   3. It binds 127.0.0.1 only, never 0.0.0.0.
+#   4. If RAVENSIGHT_DRIVER_TOKEN is set, the first request on a connection
+#      must be hello{token} or the connection is closed.
+#   5. One client at a time. A second connection is refused with -32001.
+#   6. When any of this fails, the node calls queue_free() on itself, so an
+#      inactive driver costs nothing per frame.
+#
+# Requests are drained in _process, at most 8 per frame, so the scene tree is
+# read at a consistent point between frames.
+extends Node
+
+const DRIVER_VERSION := "1.0.0"
+const DEFAULT_PORT := 47800
+const FEATURE_TAG := "ravensight_driver"
+const ADDON_DIR := "ravensight_driver"
+
+const MAX_REQUEST_BYTES := 1048576
+const MAX_REQUESTS_PER_FRAME := 8
+const MAX_NODES := 2000
+const MAX_TEXT_CHARS := 500
+const MAX_TREE_DEPTH := 32
+const DEFAULT_TREE_DEPTH := 6
+const MAX_PRESS_MS := 10000
+const MAX_WAIT_FRAMES := 3600
+const MAX_STATE_DEPTH := 8
+const MAX_HOOK_BYTES := 65536
+const STATE_GROUP := "ravensight_state"
+
+const ERR_PARSE := -32700
+const ERR_INVALID_REQUEST := -32600
+const ERR_METHOD_NOT_FOUND := -32601
+const ERR_INVALID_PARAMS := -32602
+const ERR_BUSY := -32001
+const ERR_UNAUTHORIZED := -32002
+const ERR_HEADLESS := -32010
+const ERR_NODE_NOT_FOUND := -32011
+const ERR_ACTION_NOT_DEFINED := -32012
+const ERR_HOOK := -32020
+
+var _server: TCPServer
+var _peer: StreamPeerTCP
+var _buffer := PackedByteArray()
+var _inbox: Array[String] = []
+var _authed := false
+var _token := ""
+var _pending_waits: Array = []
+var _last_scene_path := ""
+var _extra_methods := {}
+
+## --- Lifecycle ----------------------------------------------------------------
+
+func _ready() -> void:
+	process_mode = Node.PROCESS_MODE_ALWAYS
+	if not _should_enable():
+		# Inert build: remove the node entirely rather than idling in _process.
+		queue_free()
+		return
+
+	_token = OS.get_environment("RAVENSIGHT_DRIVER_TOKEN")
+	_authed = _token.is_empty()
+
+	_server = TCPServer.new()
+	var port := _resolve_port()
+	var err := _server.listen(port, "127.0.0.1")
+	if err != OK:
+		push_error("[ravensight-driver] listen failed on 127.0.0.1:%d: %s" % [port, error_string(err)])
+		_server = null
+		queue_free()
+		return
+
+	var scene := get_tree().current_scene
+	_last_scene_path = scene.scene_file_path if scene != null else ""
+	_connect_sdk_mirror()
+	# The CLI waits for this line in godot.log before it dials the socket.
+	print("[ravensight-driver] listening on 127.0.0.1:%d version %s" % [port, DRIVER_VERSION])
+
+
+func _exit_tree() -> void:
+	_close_client()
+	if _server != null:
+		_server.stop()
+		_server = null
+
+
+## Every activation condition from spec 07, evaluated once in _ready().
+func _should_enable() -> bool:
+	# An export template only ever runs the driver when the export itself was
+	# built with the ravensight_driver custom feature tag.
+	if OS.has_feature("template") and not OS.has_feature(FEATURE_TAG):
+		return false
+	if "--ravensight-driver" in OS.get_cmdline_user_args():
+		return true
+	return OS.get_environment("RAVENSIGHT_DRIVER") == "1"
+
+
+func _resolve_port() -> int:
+	var prefix := "--ravensight-driver-port="
+	for arg in OS.get_cmdline_user_args():
+		if arg.begins_with(prefix):
+			var value := arg.substr(prefix.length())
+			if value.is_valid_int():
+				return value.to_int()
+	var env_port := OS.get_environment("RAVENSIGHT_DRIVER_PORT")
+	if env_port.is_valid_int():
+		return env_port.to_int()
+	return DEFAULT_PORT
+
+
+## Mirrors the Ravensight SDK's tracked events as "ravensight_event"
+## notifications when the SDK autoload is present. Absent SDK is not an error:
+## most projects under test do not ship it.
+func _connect_sdk_mirror() -> void:
+	for autoload_name in ["Ravensight", "GameTracker"]:
+		var sdk := get_node_or_null("/root/" + autoload_name)
+		if sdk != null and sdk.has_signal("event_tracked"):
+			sdk.connect("event_tracked", _on_sdk_event)
+			return
+	# The SDK autoload does not have to be called Ravensight: a project is free
+	# to register it under any name, so fall back to whichever autoload actually
+	# exposes the signal.
+	for child in get_tree().root.get_children():
+		if child == self:
+			continue
+		if child.has_signal("event_tracked"):
+			child.connect("event_tracked", _on_sdk_event)
+			return
+
+
+func _on_sdk_event(event_name: String, data: Dictionary) -> void:
+	_notify("ravensight_event", {"name": str(event_name), "data": data})
+
+
+## --- Socket pump --------------------------------------------------------------
+
+func _process(_delta: float) -> void:
+	_accept_connections()
+	_read_client()
+	_drain_inbox()
+	_tick_waits()
+	_check_scene_change()
+
+
+func _accept_connections() -> void:
+	while _server != null and _server.is_connection_available():
+		var incoming := _server.take_connection()
+		incoming.set_no_delay(true)
+		if _peer != null and _peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+			# Single client at a time: tell the newcomer why, then hang up.
+			var body := JSON.stringify({
+				"jsonrpc": "2.0",
+				"id": null,
+				"error": {"code": ERR_BUSY, "message": "busy: another client is connected"},
+			}) + "\n"
+			incoming.put_data(body.to_utf8_buffer())
+			incoming.poll()
+			incoming.disconnect_from_host()
+			continue
+		_peer = incoming
+		_buffer = PackedByteArray()
+		_inbox.clear()
+		_authed = _token.is_empty()
+
+
+func _read_client() -> void:
+	if _peer == null:
+		return
+	_peer.poll()
+	var status := _peer.get_status()
+	if status != StreamPeerTCP.STATUS_CONNECTED:
+		if status == StreamPeerTCP.STATUS_NONE or status == StreamPeerTCP.STATUS_ERROR:
+			_close_client()
+		return
+	var available := _peer.get_available_bytes()
+	if available > 0:
+		var res := _peer.get_data(available)
+		if res[0] == OK:
+			_buffer.append_array(res[1])
+	while true:
+		var idx := _buffer.find(10)  # "\n"
+		if idx == -1:
+			if _buffer.size() > MAX_REQUEST_BYTES:
+				# An oversized line can never become a valid request, and
+				# buffering it further is how a driver runs a machine out of
+				# memory. Refuse and drop the connection.
+				_reject_oversized_request()
+			return
+		if idx > MAX_REQUEST_BYTES:
+			# The cap applies to a line that did arrive complete just as much as
+			# to one still growing: a 4 MB request that ends in a newline is
+			# still a 4 MB request.
+			_reject_oversized_request()
+			return
+		var line := _buffer.slice(0, idx).get_string_from_utf8().strip_edges()
+		_buffer = _buffer.slice(idx + 1)
+		if not line.is_empty():
+			_inbox.append(line)
+
+
+func _reject_oversized_request() -> void:
+	_send_error(null, ERR_INVALID_REQUEST, "request line exceeds %d bytes" % MAX_REQUEST_BYTES)
+	_close_client()
+
+
+func _drain_inbox() -> void:
+	var handled := 0
+	while handled < MAX_REQUESTS_PER_FRAME and not _inbox.is_empty():
+		var line: String = _inbox.pop_front()
+		handled += 1
+		_handle_line(line)
+
+
+func _close_client() -> void:
+	if _peer != null:
+		_peer.disconnect_from_host()
+		_peer = null
+	_buffer = PackedByteArray()
+	_inbox.clear()
+	_pending_waits.clear()
+	_authed = _token.is_empty()
+
+
+## --- Dispatch ----------------------------------------------------------------
+
+func _handle_line(line: String) -> void:
+	# JSON.parse_string() cannot tell "null" (valid JSON, wrong shape) from
+	# malformed input, and those are two different JSON-RPC errors, so the
+	# instance API is used for its error code.
+	var json := JSON.new()
+	if json.parse(line) != OK:
+		_send_error(null, ERR_PARSE, "parse error")
+		return
+	var parsed: Variant = json.data
+	if typeof(parsed) != TYPE_DICTIONARY:
+		_send_error(null, ERR_INVALID_REQUEST, "request must be a JSON object")
+		return
+	var request: Dictionary = parsed
+	var id: Variant = request.get("id")
+	var method := str(request.get("method", ""))
+	if method.is_empty():
+		_send_error(id, ERR_INVALID_REQUEST, "missing method")
+		return
+	var params: Dictionary = {}
+	if typeof(request.get("params")) == TYPE_DICTIONARY:
+		params = request.get("params")
+
+	if method == "hello":
+		_handle_hello(id, params)
+		return
+	if not _authed:
+		# Token auth is on and this connection has not said hello yet.
+		_send_error(id, ERR_UNAUTHORIZED, "unauthorized: send hello{token} first")
+		_close_client()
+		return
+
+	if _extra_methods.has(method):
+		var out: Variant = (_extra_methods[method] as Callable).call(params)
+		_send_result(id, out)
+		return
+
+	match method:
+		"ping": _rpc_ping(id)
+		"get_state": _rpc_get_state(id, params)
+		"get_game_state": _rpc_get_game_state(id)
+		"press_action": _rpc_press_action(id, params)
+		"key": _rpc_key(id, params)
+		"click": _rpc_click(id, params)
+		"wait_frames": _rpc_wait_frames(id, params)
+		"screenshot": _rpc_screenshot(id, params)
+		"set_time_scale": _rpc_set_time_scale(id, params)
+		"list_actions": _send_result(id, {"actions": _action_names()})
+		"quit": _rpc_quit(id, params)
+		_: _send_error(id, ERR_METHOD_NOT_FOUND, "method not found: %s" % method)
+
+
+func _handle_hello(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"token": "string"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	if _token.is_empty():
+		_authed = true
+		_send_result(id, {"ok": true, "driver_version": DRIVER_VERSION, "auth": false})
+		return
+	if str(params.get("token", "")) != _token:
+		_send_error(id, ERR_UNAUTHORIZED, "unauthorized")
+		_close_client()
+		return
+	_authed = true
+	_send_result(id, {"ok": true, "driver_version": DRIVER_VERSION, "auth": true})
+
+
+## Lets a project or an extension script add its own method, e.g. a debug
+## "skip_to_level". Only reachable when the job config allows custom methods,
+## which the CLI decides, not the game.
+func register_method(method_name: String, callable: Callable) -> void:
+	_extra_methods[method_name] = callable
+
+
+## --- Parameter guards ---------------------------------------------------------
+
+## A param of the wrong type is a client bug, and answering -32602 with the name
+## of the offending key is far easier to act on than a silent int(null) == 0.
+const PARAM_TYPES := {
+	"number": [TYPE_INT, TYPE_FLOAT],
+	"string": [TYPE_STRING, TYPE_STRING_NAME],
+	"boolean": [TYPE_BOOL],
+	"array": [TYPE_ARRAY],
+	"keycode": [TYPE_INT, TYPE_FLOAT, TYPE_STRING, TYPE_STRING_NAME],
+}
+
+
+## Returns "" when every present param matches its declared kind, otherwise the
+## message to send back with -32602.
+func _check_params(params: Dictionary, spec: Dictionary) -> String:
+	for key in spec:
+		if not params.has(key):
+			continue
+		var label := str(spec[key])
+		if typeof(params[key]) in PARAM_TYPES[label]:
+			continue
+		if label == "keycode":
+			return "keycode must be a key name or an integer Key value"
+		return "%s must be a %s" % [key, label]
+	return ""
+
+
+## --- Methods -----------------------------------------------------------------
+
+func _rpc_ping(id: Variant) -> void:
+	var scene := get_tree().current_scene
+	_send_result(id, {
+		"ok": true,
+		"godot_version": Engine.get_version_info().get("string", ""),
+		"driver_version": DRIVER_VERSION,
+		"headless": _is_headless(),
+		"frame": Engine.get_process_frames(),
+		"time_scale": Engine.time_scale,
+		"main_scene": scene.scene_file_path if scene != null else "",
+	})
+
+
+func _rpc_get_state(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"max_depth": "number", "root": "string", "visible_only": "boolean"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	var max_depth: int = clampi(int(params.get("max_depth", DEFAULT_TREE_DEPTH)), 1, MAX_TREE_DEPTH)
+	var visible_only := bool(params.get("visible_only", true))
+	var root: Node = get_tree().root
+	if params.has("root"):
+		root = get_node_or_null(NodePath(str(params.get("root"))))
+		if root == null:
+			_send_error(id, ERR_NODE_NOT_FOUND, "node not found: %s" % str(params.get("root")))
+			return
+	var budget := {"left": MAX_NODES, "truncated": false}
+	var tree := _node_to_dict(root, 0, max_depth, visible_only, budget)
+	var scene := get_tree().current_scene
+	_send_result(id, {
+		"frame": Engine.get_process_frames(),
+		"current_scene": str(scene.get_path()) if scene != null else "",
+		"current_scene_file": scene.scene_file_path if scene != null else "",
+		"truncated": budget["truncated"],
+		"tree": tree,
+	})
+
+
+func _rpc_get_game_state(id: Variant) -> void:
+	var states := {}
+	for node in get_tree().get_nodes_in_group(STATE_GROUP):
+		if not node.has_method("_ravensight_state"):
+			continue
+		var path := str(node.get_path())
+		var raw: Variant = node.call("_ravensight_state")
+		if typeof(raw) != TYPE_DICTIONARY:
+			_send_error(id, ERR_HOOK, "_ravensight_state() did not return a Dictionary", {"path": path})
+			return
+		var value: Variant = _jsonify(raw, 0)
+		if JSON.stringify(value).to_utf8_buffer().size() > MAX_HOOK_BYTES:
+			_send_error(id, ERR_HOOK, "_ravensight_state() result exceeds %d bytes" % MAX_HOOK_BYTES, {"path": path})
+			return
+		states[path] = value
+	_send_result(id, {"frame": Engine.get_process_frames(), "states": states})
+
+
+func _rpc_press_action(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"action": "string", "duration_ms": "number"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	if not params.has("action"):
+		_send_error(id, ERR_INVALID_PARAMS, "action is required")
+		return
+	var action := str(params.get("action", ""))
+	if not InputMap.has_action(action):
+		_send_error(id, ERR_ACTION_NOT_DEFINED, "input action not defined: %s" % action, {
+			"available_actions": _action_names(),
+		})
+		return
+	var duration_ms: int = clampi(int(params.get("duration_ms", 50)), 0, MAX_PRESS_MS)
+	Input.action_press(action)
+	var event := InputEventAction.new()
+	event.action = action
+	event.pressed = true
+	Input.parse_input_event(event)
+
+	# The hold is measured in game time so it scales with time_scale, per spec.
+	# A frozen clock (time_scale 0, how the CLI parks the game between turns)
+	# would never fire that timer and the call would hang, so the timer
+	# ignores the scale in exactly that case and the result says so.
+	var frozen := Engine.time_scale <= 0.0
+	if duration_ms > 0:
+		await get_tree().create_timer(duration_ms / 1000.0, true, false, frozen).timeout
+	Input.action_release(action)
+	var release := InputEventAction.new()
+	release.action = action
+	release.pressed = false
+	Input.parse_input_event(release)
+	_send_result(id, {
+		"ok": true,
+		"released_at_frame": Engine.get_process_frames(),
+		"ignored_time_scale": frozen,
+	})
+
+
+func _rpc_key(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"keycode": "keycode", "pressed": "boolean", "unicode": "number"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	var keycode := _resolve_keycode(params.get("keycode"))
+	if keycode == KEY_NONE:
+		_send_error(id, ERR_INVALID_PARAMS, "unknown keycode: %s" % str(params.get("keycode")))
+		return
+	var event := InputEventKey.new()
+	event.keycode = keycode
+	event.physical_keycode = keycode
+	event.pressed = bool(params.get("pressed", true))
+	var unicode := int(params.get("unicode", 0))
+	if unicode == 0:
+		unicode = _unicode_for(params.get("keycode"))
+	if unicode != 0:
+		event.unicode = unicode
+	Input.parse_input_event(event)
+	_send_result(id, {"ok": true, "keycode": keycode, "pressed": event.pressed})
+
+
+func _rpc_click(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {
+		"x": "number",
+		"y": "number",
+		"node_path": "string",
+		"button": "string",
+		"double": "boolean",
+	})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	var pos := Vector2.ZERO
+	if params.has("node_path"):
+		var target := get_node_or_null(NodePath(str(params.get("node_path"))))
+		if target == null or not (target is Control):
+			_send_error(id, ERR_NODE_NOT_FOUND, "clickable node not found: %s" % str(params.get("node_path")))
+			return
+		pos = (target as Control).get_global_rect().get_center()
+	else:
+		pos = Vector2(float(params.get("x", 0.0)), float(params.get("y", 0.0)))
+
+	var button := MOUSE_BUTTON_LEFT
+	match str(params.get("button", "left")):
+		"right": button = MOUSE_BUTTON_RIGHT
+		"middle": button = MOUSE_BUTTON_MIDDLE
+
+	var motion := InputEventMouseMotion.new()
+	motion.position = pos
+	motion.global_position = pos
+	Input.parse_input_event(motion)
+
+	for pressed in [true, false]:
+		var click := InputEventMouseButton.new()
+		click.button_index = button
+		click.position = pos
+		click.global_position = pos
+		click.pressed = pressed
+		click.double_click = pressed and bool(params.get("double", false))
+		Input.parse_input_event(click)
+	_send_result(id, {"ok": true, "position": [pos.x, pos.y]})
+
+
+func _rpc_wait_frames(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"n": "number"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	var frames: int = clampi(int(params.get("n", 1)), 1, MAX_WAIT_FRAMES)
+	_pending_waits.append({"id": id, "left": frames})
+
+
+func _rpc_screenshot(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"max_width": "number", "region": "array"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	if params.has("region") and not _is_number_quad(params.get("region")):
+		_send_error(id, ERR_INVALID_PARAMS, "region must be four numbers: [x, y, width, height]")
+		return
+	if _is_headless():
+		_send_error(id, ERR_HEADLESS, "screenshot unavailable in headless mode")
+		return
+	await RenderingServer.frame_post_draw
+	var image := get_viewport().get_texture().get_image()
+	if image == null:
+		_send_error(id, ERR_HEADLESS, "viewport produced no image")
+		return
+	if params.has("region"):
+		var region: Array = params.get("region")
+		image = image.get_region(Rect2i(int(region[0]), int(region[1]), int(region[2]), int(region[3])))
+	var max_width: int = maxi(int(params.get("max_width", 1280)), 1)
+	if image.get_width() > max_width:
+		var height := maxi(1, int(round(image.get_height() * float(max_width) / image.get_width())))
+		image.resize(max_width, height, Image.INTERPOLATE_BILINEAR)
+	_send_result(id, {
+		"format": "png",
+		"width": image.get_width(),
+		"height": image.get_height(),
+		"data": Marshalls.raw_to_base64(image.save_png_to_buffer()),
+	})
+
+
+func _rpc_set_time_scale(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"scale": "number", "adjust_physics": "boolean"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	var previous := Engine.time_scale
+	var scale := clampf(float(params.get("scale", 1.0)), 0.0, 16.0)
+	Engine.time_scale = scale
+	if bool(params.get("adjust_physics", false)) and scale > 0.0:
+		Engine.physics_ticks_per_second = maxi(1, int(round(60.0 * scale)))
+	_send_result(id, {"time_scale": scale, "previous": previous})
+
+
+func _rpc_quit(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"code": "number"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	var code := int(params.get("code", 0))
+	_send_result(id, {"ok": true})
+	if _peer != null:
+		_peer.poll()
+	await get_tree().process_frame
+	get_tree().quit(code)
+
+
+func _is_number_quad(value: Variant) -> bool:
+	if typeof(value) != TYPE_ARRAY:
+		return false
+	var list: Array = value
+	if list.size() != 4:
+		return false
+	for item in list:
+		if typeof(item) != TYPE_INT and typeof(item) != TYPE_FLOAT:
+			return false
+	return true
+
+
+func _action_names() -> Array:
+	var game: Array = []
+	var builtin: Array = []
+	for action in InputMap.get_actions():
+		var action_name := str(action)
+		if action_name.begins_with("ui_"):
+			builtin.append(action_name)
+		else:
+			game.append(action_name)
+	game.sort()
+	builtin.sort()
+	return game + builtin
+
+
+## --- Scene tree snapshot ------------------------------------------------------
+
+## Serializes one node and its children. Every entry carries "path", plus
+## "scene" and "script" whenever the node owns a scene file or a script, so a
+## finding in the report can cite the file a developer has to open.
+func _node_to_dict(node: Node, depth: int, max_depth: int, visible_only: bool, budget: Dictionary) -> Dictionary:
+	var out := {
+		"name": str(node.name),
+		"type": node.get_class(),
+		"path": str(node.get_path()),
+	}
+	if not node.scene_file_path.is_empty():
+		out["scene"] = node.scene_file_path
+	var script: Variant = node.get_script()
+	if script != null and script is Script and not (script as Script).resource_path.is_empty():
+		out["script"] = (script as Script).resource_path
+
+	if node is CanvasItem:
+		out["visible"] = (node as CanvasItem).is_visible_in_tree()
+	elif node is Node3D:
+		out["visible"] = (node as Node3D).is_visible_in_tree()
+
+	var text := _text_of(node)
+	if not text.is_empty():
+		out["text"] = text.substr(0, MAX_TEXT_CHARS)
+
+	if node is Node2D:
+		var p2: Vector2 = (node as Node2D).global_position
+		out["position"] = [p2.x, p2.y]
+	elif node is Node3D:
+		var p3: Vector3 = (node as Node3D).global_position
+		out["position"] = [p3.x, p3.y, p3.z]
+	elif node is Control:
+		var rect: Rect2 = (node as Control).get_global_rect()
+		out["position"] = [rect.position.x, rect.position.y]
+		out["rect"] = [rect.position.x, rect.position.y, rect.size.x, rect.size.y]
+		out["focus"] = (node as Control).has_focus()
+	if node is BaseButton:
+		out["disabled"] = (node as BaseButton).disabled
+
+	var groups: Array = []
+	for group in node.get_groups():
+		var group_name := str(group)
+		if not group_name.begins_with("_"):
+			groups.append(group_name)
+	out["groups"] = groups
+
+	var children: Array = []
+	if depth < max_depth:
+		for child in node.get_children():
+			if budget["left"] <= 0:
+				budget["truncated"] = true
+				break
+			if _is_driver_node(child):
+				continue
+			if visible_only and not _is_visible_candidate(child):
+				continue
+			budget["left"] = int(budget["left"]) - 1
+			children.append(_node_to_dict(child, depth + 1, max_depth, visible_only, budget))
+	elif node.get_child_count() > 0:
+		# A depth cut is not truncation: the caller chose max_depth and gets
+		# child_count so it knows what it chose not to see. "truncated" is
+		# reserved for the node budget running out, which the caller did not ask
+		# for and has to react to.
+		out["child_count"] = node.get_child_count()
+	out["children"] = children
+	return out
+
+
+## The driver's own autoload is not part of the game. Leaving it in the snapshot
+## would put the driver's script path in the list of scripts a report cites.
+func _is_driver_node(node: Node) -> bool:
+	var script: Variant = node.get_script()
+	if script == null or not (script is Script):
+		return false
+	return (script as Script).resource_path.begins_with("res://addons/" + ADDON_DIR + "/")
+
+
+func _is_visible_candidate(node: Node) -> bool:
+	if node is CanvasItem:
+		return (node as CanvasItem).is_visible_in_tree()
+	if node is Node3D:
+		return (node as Node3D).is_visible_in_tree()
+	return true
+
+
+func _text_of(node: Node) -> String:
+	if node is RichTextLabel:
+		return (node as RichTextLabel).get_parsed_text()
+	if node is Label:
+		return (node as Label).text
+	if node is Button:
+		return (node as Button).text
+	if node is LineEdit:
+		return (node as LineEdit).text
+	if node is TextEdit:
+		return (node as TextEdit).text
+	return ""
+
+
+## --- Author hook serialization ------------------------------------------------
+
+## Converts a _ravensight_state() result into JSON-safe values: vectors become
+## arrays, everything unrecognized becomes its str() form, and recursion stops
+## at MAX_STATE_DEPTH so a cyclic structure cannot hang the game.
+func _jsonify(value: Variant, depth: int) -> Variant:
+	if depth >= MAX_STATE_DEPTH:
+		return str(value)
+	match typeof(value):
+		TYPE_NIL, TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING, TYPE_STRING_NAME:
+			return value if typeof(value) != TYPE_STRING_NAME else str(value)
+		TYPE_VECTOR2, TYPE_VECTOR2I:
+			return [value.x, value.y]
+		TYPE_VECTOR3, TYPE_VECTOR3I:
+			return [value.x, value.y, value.z]
+		TYPE_DICTIONARY:
+			var out := {}
+			for key in (value as Dictionary):
+				out[str(key)] = _jsonify((value as Dictionary)[key], depth + 1)
+			return out
+		TYPE_ARRAY, TYPE_PACKED_STRING_ARRAY, TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY, TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY:
+			var list: Array = []
+			for item in value:
+				list.append(_jsonify(item, depth + 1))
+			return list
+		_:
+			return str(value)
+
+
+## --- Keycodes -----------------------------------------------------------------
+
+func _resolve_keycode(raw: Variant) -> int:
+	if typeof(raw) == TYPE_INT or typeof(raw) == TYPE_FLOAT:
+		return int(raw)
+	# A single character is resolved before any trimming. strip_edges() turns
+	# " " into "", so typing a sentence used to fail on its first space.
+	var literal := str(raw)
+	if literal.length() == 1:
+		if literal == " ":
+			return KEY_SPACE
+		if literal == "\t":
+			return KEY_TAB
+		if literal == "\n" or literal == "\r":
+			return KEY_ENTER
+		return literal.to_upper().unicode_at(0)
+	var key_name := literal.strip_edges()
+	if key_name.is_empty():
+		return KEY_NONE
+	var found := OS.find_keycode_from_string(key_name)
+	if found != KEY_NONE:
+		return found
+	if key_name.begins_with("KEY_"):
+		found = OS.find_keycode_from_string(key_name.substr(4))
+		if found != KEY_NONE:
+			return found
+	var aliases := {
+		"enter": KEY_ENTER,
+		"return": KEY_ENTER,
+		"esc": KEY_ESCAPE,
+		"escape": KEY_ESCAPE,
+		"space": KEY_SPACE,
+		"tab": KEY_TAB,
+		"backspace": KEY_BACKSPACE,
+		"arrowup": KEY_UP,
+		"arrowdown": KEY_DOWN,
+		"arrowleft": KEY_LEFT,
+		"arrowright": KEY_RIGHT,
+	}
+	var lowered := key_name.to_lower()
+	if aliases.has(lowered):
+		return int(aliases[lowered])
+	if key_name.length() == 1:
+		return key_name.to_upper().unicode_at(0)
+	return KEY_NONE
+
+
+## A single printable character also carries its unicode, so text actually
+## lands in a LineEdit rather than only firing a raw key handler.
+func _unicode_for(raw: Variant) -> int:
+	if typeof(raw) != TYPE_STRING and typeof(raw) != TYPE_STRING_NAME:
+		return 0
+	var literal := str(raw)
+	if literal.length() != 1:
+		return 0
+	return literal.unicode_at(0)
+
+
+## --- Frame bookkeeping --------------------------------------------------------
+
+func _tick_waits() -> void:
+	if _pending_waits.is_empty():
+		return
+	var still_waiting: Array = []
+	for wait in _pending_waits:
+		wait["left"] = int(wait["left"]) - 1
+		if int(wait["left"]) <= 0:
+			_send_result(wait["id"], {"frame": Engine.get_process_frames()})
+		else:
+			still_waiting.append(wait)
+	_pending_waits = still_waiting
+
+
+func _check_scene_change() -> void:
+	var scene := get_tree().current_scene
+	var path := scene.scene_file_path if scene != null else ""
+	if path == _last_scene_path:
+		return
+	_last_scene_path = path
+	if path.is_empty():
+		# Mid transition change_scene_to_file() leaves current_scene null for a
+		# frame. Reporting that as a scene change would tell the persona the
+		# screen went blank, so only the arrival is announced.
+		return
+	_notify("scene_changed", {"scene": path, "node": str(scene.get_path()) if scene != null else ""})
+
+
+func _is_headless() -> bool:
+	return DisplayServer.get_name() == "headless"
+
+
+## --- Wire format --------------------------------------------------------------
+
+func _send_result(id: Variant, result: Variant) -> void:
+	_send({"jsonrpc": "2.0", "id": id, "result": result})
+
+
+func _send_error(id: Variant, code: int, message: String, data: Variant = null) -> void:
+	var error := {"code": code, "message": message}
+	if data != null:
+		error["data"] = data
+	_send({"jsonrpc": "2.0", "id": id, "error": error})
+
+
+func _notify(type: String, params: Dictionary) -> void:
+	var body := params.duplicate()
+	body["type"] = type
+	body["frame"] = Engine.get_process_frames()
+	_send({"jsonrpc": "2.0", "method": "event", "params": body})
+
+
+func _send(message: Dictionary) -> void:
+	if _peer == null or _peer.get_status() != StreamPeerTCP.STATUS_CONNECTED:
+		return
+	_peer.put_data((JSON.stringify(message) + "\n").to_utf8_buffer())