ravensight-playtest 0.5.2 → 0.6.0

package/addons/ravensight_driver/driver.gd

@@ -19,9 +19,18 @@
 #
 # Requests are drained in _process, at most 8 per frame, so the scene tree is
 # read at a consistent point between frames.
+#
+# LOCKSTEP (RAVENSIGHT_DRIVER_LOCKSTEP=1, set by the CLI beside --fixed-fps) is
+# the deterministic mode. The game's clock is stopped from this node's _ready,
+# before the main scene loads, and only moves through the `step` request: apply
+# these inputs, run exactly this many ticks, stop, answer with a digest of the
+# state. `_sim_tick` counts those ticks and nothing else, so the time a persona
+# spends thinking is not in it. Parked frames still run, with a delta of zero:
+# game code that counts frames rather than using delta can still tell how long
+# it was parked, which is one of the limits docs/REPLAY.md names.
 extends Node
 
-const DRIVER_VERSION := "1.0.0"
+const DRIVER_VERSION := "1.2.0"
 const DEFAULT_PORT := 47800
 const FEATURE_TAG := "ravensight_driver"
 const ADDON_DIR := "ravensight_driver"
@@ -48,6 +57,13 @@ const ERR_HEADLESS := -32010
 const ERR_NODE_NOT_FOUND := -32011
 const ERR_ACTION_NOT_DEFINED := -32012
 const ERR_HOOK := -32020
+const ERR_NOT_LOCKSTEP := -32030
+
+const MAX_STEP_TICKS := 3600
+const MAX_STEP_EVENTS := 64
+const MAX_DIGEST_SUBTREES := 64
+const MAX_DRAW_WAIT_FRAMES := 30
+const MAX_DIGEST_STATE_BYTES := 4096
 
 var _server: TCPServer
 var _peer: StreamPeerTCP
@@ -59,6 +75,19 @@ var _pending_waits: Array = []
 var _last_scene_path := ""
 var _extra_methods := {}
 
+var _lockstep := false
+var _sim_tick := 0
+var _seed_value := 0
+var _step_left := 0
+var _step_id: Variant = null
+var _step_digest := true
+var _step_answer_next := false
+var _resume_scale := 1.0
+var _held_keys := {}
+var _held_actions := {}
+var _reasserted := 0
+var _step_clicks: Array = []
+
 ## --- Lifecycle ----------------------------------------------------------------
 
 func _ready() -> void:
@@ -68,6 +97,12 @@ func _ready() -> void:
 		queue_free()
 		return
 
+	# Before anything else, and before the main scene exists: a seed set after
+	# the first scene's _ready, or a clock stopped after its first frame, would
+	# already have let the wall clock into the run.
+	if OS.get_environment("RAVENSIGHT_DRIVER_LOCKSTEP") == "1":
+		_enter_lockstep(OS.get_environment("RAVENSIGHT_DRIVER_SEED"))
+
 	_token = OS.get_environment("RAVENSIGHT_DRIVER_TOKEN")
 	_authed = _token.is_empty()
 
@@ -145,6 +180,8 @@ func _on_sdk_event(event_name: String, data: Dictionary) -> void:
 ## --- Socket pump --------------------------------------------------------------
 
 func _process(_delta: float) -> void:
+	if _lockstep:
+		_advance_lockstep()
 	_accept_connections()
 	_read_client()
 	_drain_inbox()
@@ -228,6 +265,7 @@ func _close_client() -> void:
 	_buffer = PackedByteArray()
 	_inbox.clear()
 	_pending_waits.clear()
+	_step_id = null
 	_authed = _token.is_empty()
 
 
@@ -277,6 +315,9 @@ func _handle_line(line: String) -> void:
 		"key": _rpc_key(id, params)
 		"click": _rpc_click(id, params)
 		"wait_frames": _rpc_wait_frames(id, params)
+		"seed": _rpc_seed(id, params)
+		"step": _rpc_step(id, params)
+		"digest": _send_result(id, _lockstep_answer(true))
 		"screenshot": _rpc_screenshot(id, params)
 		"set_time_scale": _rpc_set_time_scale(id, params)
 		"list_actions": _send_result(id, {"actions": _action_names()})
@@ -348,6 +389,11 @@ func _rpc_ping(id: Variant) -> void:
 		"frame": Engine.get_process_frames(),
 		"time_scale": Engine.time_scale,
 		"main_scene": scene.scene_file_path if scene != null else "",
+		"lockstep": _lockstep,
+		"user_dir": OS.get_user_data_dir(),
+		"tick": _sim_tick,
+		"seed": _seed_value,
+		"ticks_per_second": Engine.physics_ticks_per_second,
 	})
 
 
@@ -443,6 +489,11 @@ func _rpc_key(id: Variant, params: Dictionary) -> void:
 	if keycode == KEY_NONE:
 		_send_error(id, ERR_INVALID_PARAMS, "unknown keycode: %s" % str(params.get("keycode")))
 		return
+	var event := _send_key_event(keycode, params)
+	_send_result(id, {"ok": true, "keycode": keycode, "pressed": event.pressed})
+
+
+func _send_key_event(keycode: int, params: Dictionary) -> InputEventKey:
 	var event := InputEventKey.new()
 	event.keycode = keycode
 	event.physical_keycode = keycode
@@ -453,7 +504,7 @@ func _rpc_key(id: Variant, params: Dictionary) -> void:
 	if unicode != 0:
 		event.unicode = unicode
 	Input.parse_input_event(event)
-	_send_result(id, {"ok": true, "keycode": keycode, "pressed": event.pressed})
+	return event
 
 
 func _rpc_click(id: Variant, params: Dictionary) -> void:
@@ -470,13 +521,40 @@ func _rpc_click(id: Variant, params: Dictionary) -> void:
 	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):
+		var at: Variant = _click_position(target)
+		if at == null:
 			_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()
+		pos = at
 	else:
 		pos = Vector2(float(params.get("x", 0.0)), float(params.get("y", 0.0)))
+	_send_click_events(pos, params)
+	_send_result(id, {"ok": true, "position": [pos.x, pos.y]})
+
+
+## Where a Control's centre is in the window. Mouse events are in window pixels and
+## a stretched project draws its canvas at another size, so the canvas position alone
+## landed somewhere else on any game with a stretch mode.
+func _window_position(control: Control) -> Vector2:
+	return get_window().get_final_transform() * control.get_global_rect().get_center()
+
 
+## Where a click on this node lands in the window, or null when it cannot be clicked.
+## A Node3D is clicked where the active camera draws its origin; one behind the camera,
+## or in a scene with no camera, is not on screen to click.
+func _click_position(target: Node) -> Variant:
+	if target is Control:
+		return _window_position(target as Control)
+	if target is Node3D:
+		var camera := (target as Node3D).get_viewport().get_camera_3d()
+		var at := (target as Node3D).global_position
+		if camera == null or camera.is_position_behind(at):
+			return null
+		return get_window().get_final_transform() * camera.unproject_position(at)
+	return null
+
+
+func _send_click_events(pos: Vector2, params: Dictionary) -> void:
 	var button := MOUSE_BUTTON_LEFT
 	match str(params.get("button", "left")):
 		"right": button = MOUSE_BUTTON_RIGHT
@@ -495,7 +573,6 @@ func _rpc_click(id: Variant, params: Dictionary) -> void:
 		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:
@@ -518,7 +595,7 @@ func _rpc_screenshot(id: Variant, params: Dictionary) -> void:
 	if _is_headless():
 		_send_error(id, ERR_HEADLESS, "screenshot unavailable in headless mode")
 		return
-	await RenderingServer.frame_post_draw
+	await _await_post_draw()
 	var image := get_viewport().get_texture().get_image()
 	if image == null:
 		_send_error(id, ERR_HEADLESS, "viewport produced no image")
@@ -538,14 +615,34 @@ func _rpc_screenshot(id: Variant, params: Dictionary) -> void:
 	})
 
 
+## The next drawn frame, or the last one. A window the desktop has covered or
+## moved to another space stops drawing, frame_post_draw never fires, and an
+## unbounded wait here hung the RPC until the client gave up on the run.
+func _await_post_draw() -> void:
+	var drawn := [false]
+	var mark := func() -> void: drawn[0] = true
+	RenderingServer.frame_post_draw.connect(mark, CONNECT_ONE_SHOT)
+	for _i in MAX_DRAW_WAIT_FRAMES:
+		await get_tree().process_frame
+		if drawn[0]:
+			return
+	if RenderingServer.frame_post_draw.is_connected(mark):
+		RenderingServer.frame_post_draw.disconnect(mark)
+
+
 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 previous := _resume_scale if _lockstep else Engine.time_scale
 	var scale := clampf(float(params.get("scale", 1.0)), 0.0, 16.0)
-	Engine.time_scale = scale
+	# In lockstep the clock belongs to `step`, so this names the rate the next
+	# step runs at rather than starting the game.
+	if _lockstep:
+		_resume_scale = scale
+	else:
+		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})
@@ -564,6 +661,307 @@ func _rpc_quit(id: Variant, params: Dictionary) -> void:
 	get_tree().quit(code)
 
 
+## --- Lockstep -----------------------------------------------------------------
+
+## Stops the clock and takes the seed. Runs in _ready, before the main scene, and
+## first in every frame's _process (the lowest priority there is), which is what
+## makes "this many ticks" exact: Engine.time_scale is read once at the top of an
+## iteration, so a change made here takes effect from the next one, and no node
+## ran a frame between this request and the stop.
+func _enter_lockstep(seed_text: String) -> void:
+	_lockstep = true
+	process_priority = -2147483648
+	_seed_value = int(seed_text) if seed_text.is_valid_int() else 0
+	seed(_seed_value)
+	var ticks_text := OS.get_environment("RAVENSIGHT_DRIVER_TICKS")
+	if ticks_text.is_valid_int() and int(ticks_text) > 0:
+		Engine.physics_ticks_per_second = int(ticks_text)
+	Engine.physics_jitter_fix = 0.0
+	Engine.max_physics_steps_per_frame = 1
+	_resume_scale = Engine.time_scale if Engine.time_scale > 0.0 else 1.0
+	Engine.time_scale = 0.0
+	_set_physics_running(false)
+	# Godot drops every held key when its window loses focus, so a desktop that
+	# moved focus during a hold cut the hold short at a tick the wall clock chose.
+	# A window that never takes focus has nothing to lose. Input here is synthetic
+	# anyway, and the run no longer takes the developer's keyboard.
+	get_window().unfocusable = true
+
+
+## A physics step with a delta of zero still moves things: a stack of rigid bodies
+## came out differently depending on how many parked frames it sat through, which
+## is a number the wall clock chooses. So the servers stop while the game is
+## parked. A game paused on its own keeps them stopped, as SceneTree does.
+func _set_physics_running(running: bool) -> void:
+	var active := running and not get_tree().paused
+	PhysicsServer2D.set_active(active)
+	PhysicsServer3D.set_active(active)
+
+
+func _advance_lockstep() -> void:
+	if _step_answer_next:
+		# The final tick ran to its end in the frame before this one, so the
+		# digest reads what that tick left and not what it was halfway through.
+		_step_answer_next = false
+		var id: Variant = _step_id
+		_step_id = null
+		_send_result(id, _lockstep_answer(_step_digest))
+		return
+	if _step_left > 0:
+		_reassert_held()
+		_sim_tick += 1
+		_step_left -= 1
+		if _step_left == 0:
+			# A rate the game set during the step is the game's own (a hit stop,
+			# a slow motion), so the next step resumes at it.
+			_resume_scale = Engine.time_scale
+			Engine.time_scale = 0.0
+			_set_physics_running(false)
+			_step_answer_next = true
+		return
+	if Engine.time_scale != 0.0:
+		_resume_scale = Engine.time_scale
+		Engine.time_scale = 0.0
+	# Nothing can move while parked, and an unthrottled loop would hold a core
+	# for as long as a persona thinks.
+	OS.delay_msec(2)
+
+
+## `seed{value}` reseeds the global generator. The seed the run starts on is the
+## one from RAVENSIGHT_DRIVER_SEED, taken before the first scene; this is for a
+## client that needs a known generator state again mid run.
+func _rpc_seed(id: Variant, params: Dictionary) -> void:
+	var problem := _check_params(params, {"value": "number"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	if not params.has("value"):
+		_send_error(id, ERR_INVALID_PARAMS, "value is required")
+		return
+	_seed_value = int(params.get("value"))
+	seed(_seed_value)
+	_send_result(id, {"seed": _seed_value, "lockstep": _lockstep, "tick": _sim_tick, "ticks_per_second": Engine.physics_ticks_per_second})
+
+
+## `step{events, ticks, digest}`: apply the inputs, run exactly `ticks` ticks,
+## stop, answer. One request, so nothing can land between the input and the first
+## tick that sees it, on a persona's run or on a replay of it.
+func _rpc_step(id: Variant, params: Dictionary) -> void:
+	if not _lockstep:
+		_send_error(id, ERR_NOT_LOCKSTEP, "step needs lockstep mode")
+		return
+	var problem := _check_params(params, {"ticks": "number", "events": "array", "digest": "boolean"})
+	if not problem.is_empty():
+		_send_error(id, ERR_INVALID_PARAMS, problem)
+		return
+	if _step_id != null:
+		_send_error(id, ERR_BUSY, "a step is already running")
+		return
+	var ticks: int = int(params.get("ticks", 1))
+	if ticks < 1 or ticks > MAX_STEP_TICKS:
+		_send_error(id, ERR_INVALID_PARAMS, "ticks must be 1 to %d" % MAX_STEP_TICKS)
+		return
+	var events: Array = params.get("events", [])
+	if events.size() > MAX_STEP_EVENTS:
+		_send_error(id, ERR_INVALID_PARAMS, "at most %d events in one step" % MAX_STEP_EVENTS)
+		return
+	# Every event is checked before the first is applied, so a refused step
+	# changes nothing.
+	var resolved: Array = []
+	for event in events:
+		var checked := _check_step_event(event)
+		if checked.has("code"):
+			_send_error(id, int(checked["code"]), str(checked["message"]), checked.get("data"))
+			return
+		resolved.append(checked)
+	_step_clicks = []
+	for checked in resolved:
+		_apply_step_event(checked)
+	_step_digest = bool(params.get("digest", true))
+	_step_id = id
+	_step_left = ticks
+	# A game that draws randf() in _process whatever its delta (a screen shake)
+	# spends the generator on every parked frame, and how many there were is the
+	# wall clock's choice. Reseeding from the tick puts the generator back on the
+	# one sequence this tick always gets, however long the game sat parked.
+	seed(_seed_value * 1000003 + _sim_tick)
+	Engine.time_scale = _resume_scale
+	_set_physics_running(true)
+
+
+## The desktop can take focus from a game mid hold, and Godot then drops every held
+## key. The trace says the key is down, so it goes back down on the next tick. The
+## count comes back in the digest: a run where this happened may be off by that much.
+func _reassert_held() -> void:
+	for keycode in _held_keys:
+		if not Input.is_physical_key_pressed(keycode):
+			_reasserted += 1
+			_send_key_event(int(keycode), _held_keys[keycode])
+	for action in _held_actions:
+		if not Input.is_action_pressed(action):
+			_reasserted += 1
+			Input.action_press(action)
+
+
+func _check_step_event(raw: Variant) -> Dictionary:
+	if typeof(raw) != TYPE_DICTIONARY:
+		return {"code": ERR_INVALID_PARAMS, "message": "an event must be an object"}
+	var event: Dictionary = raw
+	match str(event.get("type", "")):
+		"key":
+			var keycode := _resolve_keycode(event.get("keycode"))
+			if keycode == KEY_NONE:
+				return {"code": ERR_INVALID_PARAMS, "message": "unknown keycode: %s" % str(event.get("keycode"))}
+			return {"type": "key", "keycode": keycode, "params": event}
+		"action":
+			var action := str(event.get("action", ""))
+			if not InputMap.has_action(action):
+				return {"code": ERR_ACTION_NOT_DEFINED, "message": "input action not defined: %s" % action, "data": {"available_actions": _action_names()}}
+			return {"type": "action", "action": action, "pressed": bool(event.get("pressed", true))}
+		"click":
+			var pos := Vector2(float(event.get("x", 0.0)), float(event.get("y", 0.0)))
+			if event.has("node_path"):
+				var target := get_node_or_null(NodePath(str(event.get("node_path"))))
+				var at: Variant = _click_position(target)
+				if at == null:
+					return {"code": ERR_NODE_NOT_FOUND, "message": "clickable node not found: %s" % str(event.get("node_path"))}
+				pos = at
+			return {"type": "click", "position": pos, "params": event}
+	return {"code": ERR_INVALID_PARAMS, "message": "unknown event type: %s" % str(event.get("type", ""))}
+
+
+func _apply_step_event(event: Dictionary) -> void:
+	match str(event["type"]):
+		"key":
+			var key_params: Dictionary = event["params"]
+			_send_key_event(int(event["keycode"]), key_params)
+			if bool(key_params.get("pressed", true)):
+				_held_keys[int(event["keycode"])] = key_params
+			else:
+				_held_keys.erase(int(event["keycode"]))
+		"click":
+			var at: Vector2 = event["position"]
+			_step_clicks.append([at.x, at.y])
+			_send_click_events(at, event["params"])
+		"action":
+			var action := str(event["action"])
+			var pressed := bool(event["pressed"])
+			if pressed:
+				Input.action_press(action)
+				_held_actions[action] = true
+			else:
+				Input.action_release(action)
+				_held_actions.erase(action)
+			var input := InputEventAction.new()
+			input.action = action
+			input.pressed = pressed
+			Input.parse_input_event(input)
+
+
+func _lockstep_answer(with_digest: bool) -> Dictionary:
+	var out := {"tick": _sim_tick, "frame": Engine.get_process_frames(), "reasserted": _reasserted, "clicks": _step_clicks}
+	if with_digest:
+		out["digest"] = _state_digest()
+	return out
+
+
+## What the trace compares: the current scene's nodes and the game's own
+## _ravensight_state() hooks. Autoloads are left out on purpose. They hold what a
+## run is allowed to differ on (session ids, an SDK's network queue, audio), and
+## whatever they do to the game shows up in the scene. Floats are cut to three
+## places; a name Godot generated (@Sprite2D@123) comes from a process-wide
+## counter, so it is replaced with the node's position among its siblings.
+func _state_digest() -> Dictionary:
+	var scene := get_tree().current_scene
+	var out := {"scene": scene.scene_file_path if scene != null else "", "nodes": 0, "truncated": false, "subtrees": {}}
+	var budget := {"left": MAX_NODES, "truncated": false, "count": 0}
+	var parts := PackedStringArray()
+	if scene != null:
+		parts.append(_digest_fields(scene, 0))
+		budget["count"] = 1
+		var index := 0
+		for child in scene.get_children():
+			if _is_driver_node(child):
+				index += 1
+				continue
+			var own := PackedStringArray()
+			_digest_node(child, index, own, budget)
+			var joined := "".join(own)
+			parts.append(joined)
+			if index < MAX_DIGEST_SUBTREES:
+				out["subtrees"][_digest_name(child, index)] = joined.sha256_text().substr(0, 12)
+			index += 1
+	var states := {}
+	var hooks: Array = get_tree().get_nodes_in_group(STATE_GROUP)
+	for node in hooks:
+		if not node.has_method("_ravensight_state"):
+			continue
+		var raw: Variant = node.call("_ravensight_state")
+		if typeof(raw) == TYPE_DICTIONARY:
+			states[str(node.get_path())] = _jsonify(raw, 0)
+	var state_text := JSON.stringify(states, "", true)
+	parts.append(state_text)
+	out["nodes"] = budget["count"]
+	out["truncated"] = budget["truncated"]
+	out["state_hash"] = "".join(parts).sha256_text().substr(0, 32)
+	if state_text.to_utf8_buffer().size() <= MAX_DIGEST_STATE_BYTES:
+		out["game_state"] = states
+	return out
+
+
+func _digest_node(node: Node, index: int, parts: PackedStringArray, budget: Dictionary) -> void:
+	if int(budget["left"]) <= 0:
+		budget["truncated"] = true
+		return
+	budget["left"] = int(budget["left"]) - 1
+	budget["count"] = int(budget["count"]) + 1
+	parts.append(_digest_fields(node, index))
+	var child_index := 0
+	for child in node.get_children():
+		_digest_node(child, child_index, parts, budget)
+		child_index += 1
+
+
+func _digest_name(node: Node, index: int) -> String:
+	var node_name := str(node.name)
+	return "#%d" % index if node_name.begins_with("@") else node_name
+
+
+func _digest_fields(node: Node, index: int) -> String:
+	var fields := "%s|%s" % [node.get_class(), _digest_name(node, index)]
+	if node is CanvasItem:
+		fields += "|v%d" % int((node as CanvasItem).is_visible_in_tree())
+	if node is Node2D:
+		var n2 := node as Node2D
+		fields += "|%.3f,%.3f,%.3f" % [n2.global_position.x, n2.global_position.y, n2.global_rotation]
+	elif node is Node3D:
+		var n3 := node as Node3D
+		var p3 := n3.global_position
+		var a3 := n3.global_rotation
+		fields += "|v%d|%.3f,%.3f,%.3f|%.3f,%.3f,%.3f" % [int(n3.is_visible_in_tree()), p3.x, p3.y, p3.z, a3.x, a3.y, a3.z]
+	elif node is Control:
+		var rect := (node as Control).get_global_rect()
+		fields += "|%.3f,%.3f,%.3f,%.3f" % [rect.position.x, rect.position.y, rect.size.x, rect.size.y]
+	if node is CharacterBody2D:
+		var v2 := (node as CharacterBody2D).velocity
+		fields += "|%.3f,%.3f" % [v2.x, v2.y]
+	elif node is CharacterBody3D:
+		var v3 := (node as CharacterBody3D).velocity
+		fields += "|%.3f,%.3f,%.3f" % [v3.x, v3.y, v3.z]
+	elif node is RigidBody2D:
+		var r2 := (node as RigidBody2D).linear_velocity
+		fields += "|%.3f,%.3f" % [r2.x, r2.y]
+	elif node is RigidBody3D:
+		var r3 := (node as RigidBody3D).linear_velocity
+		fields += "|%.3f,%.3f,%.3f" % [r3.x, r3.y, r3.z]
+	var text := _text_of(node)
+	if not text.is_empty():
+		fields += "|t:" + text.substr(0, MAX_TEXT_CHARS)
+	if node is BaseButton:
+		fields += "|d%d" % int((node as BaseButton).disabled)
+	return fields + ";"
+
+
 func _is_number_quad(value: Variant) -> bool:
 	if typeof(value) != TYPE_ARRAY:
 		return false