settled-reach/client/scripts/protocol/protocol.gd

class_name Protocol
## MessagePack codec for the Rust↔Godot wire protocol (D-020).
##
## Encodes/decodes ObserverSnapshot and PlayerInput to match
## rmp_serde's named-field encoding of server/src/bridge/types.rs.
##
## Wire format notes (rmp_serde with to_vec_named):
##   Structs  → msgpack maps with string keys
##   Unit enum variants (no data) → bare strings ("MoveNorth", "Npc")
##   Data enum variants → single-element maps ({"UsePerceptionMode": "thermal"})


# -- Decode: bytes from server → GDScript types --------------------------------

## Decode an ObserverSnapshot from MessagePack bytes.
## Returns { "tick": int, "entities": Array[Dictionary] } or null on error.
static func decode_snapshot(bytes: PackedByteArray) -> Variant:
	var result = Messagepack.decode(bytes)
	if result.status != null:
		push_error("Protocol: msgpack decode failed: %s" % result.status)
		return null

	var raw = result.value
	if not raw is Dictionary or not raw.has("tick") or not raw.has("entities"):
		push_error("Protocol: snapshot missing required fields")
		return null

	var entities: Array[Dictionary] = []
	var raw_entities: Array = raw["entities"]
	var dropped := 0
	for raw_entity in raw_entities:
		var entity = _decode_entity(raw_entity)
		if entity != null:
			entities.append(entity)
		else:
			dropped += 1

	if dropped > 0:
		push_error("Protocol: %d/%d entities failed to decode (D-010 information boundary violation)" % [dropped, raw_entities.size()])

	# GDScript int is signed 64-bit. Rust tick is u64 but will not exceed 2^63
	# in any realistic scenario (would require ~29 billion years at 10 ticks/game-minute per D-031).
	var tick: int = raw["tick"]
	return {
		"tick": tick,
		"entities": entities,
		"decode_errors": dropped,
	}


## Decode a single VisibleEntity from a raw msgpack map.
static func _decode_entity(raw: Dictionary) -> Variant:
	if not raw.has("entity_id") or not raw.has("x") or not raw.has("y") \
			or not raw.has("z") or not raw.has("kind"):
		push_warning("Protocol: entity missing required fields: %s" % str(raw.keys()))
		return null

	var entity_id: int = raw["entity_id"]
	return {
		"entity_id": entity_id,
		"x": float(raw["x"]),
		"y": float(raw["y"]),
		"z": int(raw["z"]),
		"kind": _decode_enum_variant(raw["kind"]),
	}


## Decode an enum variant from rmp_serde's encoding.
## Unit variants are bare strings, data variants are single-element maps.
## Returns { "variant": String, "data": Variant } in both cases.
static func _decode_enum_variant(raw) -> Dictionary:
	if raw is String:
		return { "variant": raw, "data": null }
	elif raw is Dictionary and raw.size() == 1:
		var variant_name: String = raw.keys()[0]
		return { "variant": variant_name, "data": raw[variant_name] }
	else:
		push_warning("Protocol: unexpected enum encoding: %s" % str(raw))
		return { "variant": "Unknown", "data": raw }


# -- Encode: GDScript types → bytes to server ----------------------------------

## Encode a PlayerInput to MessagePack bytes.
## action_name: one of "MoveNorth", "MoveSouth", "MoveEast", "MoveWest",
##              "Interact", "UsePerceptionMode", "Pause", "Unpause"
## action_data: null for unit variants, String for UsePerceptionMode
static func encode_player_input(tick: int, action_name: String, action_data: Variant = null) -> PackedByteArray:
	var action_value: Variant
	if action_data != null:
		# Data variant → single-element map
		action_value = { action_name: action_data }
	else:
		# Unit variant → bare string
		action_value = action_name

	var input := {
		"tick": tick,
		"action": action_value,
	}

	var result = Messagepack.encode(input)
	if result.status != null:
		push_error("Protocol: msgpack encode failed: %s" % result.status)
		return PackedByteArray()

	return result.value


## Encode an array of PlayerInputs to MessagePack bytes (Vec<PlayerInput> wire format).
## Server expects one framed message per tick containing all inputs as a msgpack array.
## Each entry: { "tick": int, "action_name": String, "action_data": Variant (optional) }
static func encode_player_inputs(inputs: Array) -> PackedByteArray:
	var wire_inputs: Array = []
	for input in inputs:
		var action_name: String = input["action_name"]
		var action_data: Variant = input.get("action_data")
		var action_value: Variant
		if action_data != null:
			action_value = { action_name: action_data }
		else:
			action_value = action_name
		wire_inputs.append({
			"tick": input["tick"],
			"action": action_value,
		})

	var result = Messagepack.encode(wire_inputs)
	if result.status != null:
		push_error("Protocol: msgpack encode failed: %s" % result.status)
		return PackedByteArray()

	return result.value


## Decode a PlayerInput from MessagePack bytes (used in tests / echo scenarios).
## Returns { "tick": int, "action": { "variant": String, "data": Variant } } or null.
static func decode_player_input(bytes: PackedByteArray) -> Variant:
	var result = Messagepack.decode(bytes)
	if result.status != null:
		push_error("Protocol: msgpack decode failed: %s" % result.status)
		return null

	var raw = result.value
	if not raw is Dictionary or not raw.has("tick") or not raw.has("action"):
		push_error("Protocol: player_input missing required fields")
		return null

	var tick: int = raw["tick"]
	return {
		"tick": tick,
		"action": _decode_enum_variant(raw["action"]),
	}