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"})

## Protocol version — must match server PROTOCOL_VERSION in bridge/types.rs.
## Reject snapshots where version != this value.
const PROTOCOL_VERSION: int = 8


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

## Decode an ObserverSnapshot from MessagePack bytes.
## Returns decoded snapshot Dictionary or null on error.
## v2 fields (version, game_time, player_facing, visible_tiles) default to null/empty
## when decoding v1 snapshots for backward compatibility.
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

	# Version check: reject snapshots from incompatible server
	var version: Variant = raw.get("version")
	if version != PROTOCOL_VERSION:
		push_error("Protocol: version mismatch (got %s, expected %s). Server and client are out of sync." % [version, PROTOCOL_VERSION])
		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"]

	# version already checked above; game_time for HUD display
	var game_time: Variant = raw.get("game_time")

	# player_facing: FacingDirection is a unit enum → bare string in rmp_serde
	var player_facing: Variant = null
	var raw_facing: Variant = raw.get("player_facing")
	if raw_facing is String:
		player_facing = raw_facing

	# visible_tiles: Array of {x, y, z, visibility, tile_kind}
	var visible_tiles: Array = []
	var raw_vtiles: Variant = raw.get("visible_tiles")
	if raw_vtiles is Array:
		for raw_tile in raw_vtiles:
			if raw_tile is Dictionary and raw_tile.has("x") and raw_tile.has("y") and raw_tile.has("z"):
				var tile_entry := {
					"x": int(raw_tile["x"]),
					"y": int(raw_tile["y"]),
					"z": int(raw_tile["z"]),
				}
				var vis: Variant = raw_tile.get("visibility")
				if vis is String:
					tile_entry["visibility"] = vis
				# tile_kind: Floor/Wall/Door/Object — map to client tile type strings
				var kind: Variant = raw_tile.get("tile_kind")
				if kind is String:
					tile_entry["type"] = kind.to_lower()
				else:
					tile_entry["type"] = "floor"
				visible_tiles.append(tile_entry)

	# v4: nearby_interactions (#404/#405)
	var nearby_interactions: Array = []
	var raw_interactions: Variant = raw.get("nearby_interactions")
	if raw_interactions is Array:
		for raw_ni in raw_interactions:
			var ni = _decode_nearby_interaction(raw_ni)
			if ni != null:
				nearby_interactions.append(ni)

	# v5: current_monologue (#414)
	var current_monologue: Variant = null
	var raw_monologue: Variant = raw.get("current_monologue")
	if raw_monologue is Dictionary and raw_monologue.has("text"):
		current_monologue = {
			"id": str(raw_monologue.get("id", "")),
			"text": str(raw_monologue["text"]),
			"duration_seconds": float(raw_monologue.get("duration_seconds", 5.0)),
		}

	# v6: player_stance (#449, D-053) — unit enum → bare string
	var player_stance: String = "Walk"
	var raw_stance: Variant = raw.get("player_stance")
	if raw_stance is String:
		player_stance = raw_stance

	# v6: player_inventory (#449, D-065) — array of {item_id, name, slot}
	var player_inventory: Array = []
	var raw_inventory: Variant = raw.get("player_inventory")
	if raw_inventory is Array:
		for raw_item in raw_inventory:
			if raw_item is Dictionary and raw_item.has("item_id") and raw_item.has("name"):
				player_inventory.append({
					"item_id": int(raw_item["item_id"]),
					"name": str(raw_item["name"]),
					"slot": int(raw_item.get("slot", 0)),
				})

	# v7: pending_recognitions (#431, D-059/D-060) — cognitive delay fog entities
	# Bounded: server sends at most ~50 pending recognitions per snapshot (practical limit
	# given perception range). Excessive arrays are truncated to prevent allocation abuse.
	const MAX_PENDING_RECOGNITIONS: int = 64
	var pending_recognitions: Array = []
	var raw_recognitions: Variant = raw.get("pending_recognitions")
	if raw_recognitions is Array:
		var count := 0
		for raw_pr in raw_recognitions:
			if count >= MAX_PENDING_RECOGNITIONS:
				push_warning("Protocol: pending_recognitions truncated at %d entries" % MAX_PENDING_RECOGNITIONS)
				break
			if raw_pr is Dictionary and raw_pr.has("entity_id") and raw_pr.has("x") and raw_pr.has("y"):
				pending_recognitions.append({
					"entity_id": int(raw_pr["entity_id"]),
					"x": float(raw_pr["x"]),
					"y": float(raw_pr["y"]),
					"z": int(raw_pr.get("z", 0)),
					"remaining_ticks": int(raw_pr.get("remaining_ticks", 0)),
					"total_delay_ticks": int(raw_pr.get("total_delay_ticks", 1)),
				})
				count += 1

	# v7: current_dialogue (#435, D-061/D-062) — NPC speech + player response options
	# Options carry response_id for server round-trip and priority for display ordering.
	# Locked options are invisible (D-062): server filters before sending.
	var current_dialogue: Variant = null
	var raw_dialogue: Variant = raw.get("current_dialogue")
	if raw_dialogue is Dictionary and raw_dialogue.has("speech"):
		var dialogue_options: Array = []
		var raw_options: Variant = raw_dialogue.get("options")
		if raw_options is Array:
			for raw_opt in raw_options:
				if raw_opt is Dictionary and raw_opt.has("text"):
					dialogue_options.append({
						"text": str(raw_opt["text"]),
						"response_id": str(raw_opt.get("response_id", "")),
						"priority": int(raw_opt.get("priority", 0)),
						"confrontation": bool(raw_opt.get("confrontation", false)),
					})
		current_dialogue = {
			"npc_name": str(raw_dialogue.get("npc_name", "")),
			"npc_entity_id": int(raw_dialogue.get("npc_entity_id", -1)),
			"speech": str(raw_dialogue["speech"]),
			"options": dialogue_options,
		}

	# v8: dialogue_response (#305, D-028) — NPC's spoken dialogue line from server
	# Separate from current_dialogue (client-side rich dialogue state).
	var dialogue_response: Variant = null
	var raw_dr: Variant = raw.get("dialogue_response")
	if raw_dr is Dictionary and raw_dr.has("text"):
		dialogue_response = {
			"line_id": str(raw_dr.get("line_id", "")),
			"text": str(raw_dr["text"]),
			"speaker_entity_id": int(raw_dr.get("speaker_entity_id", -1)),
		}

	return {
		"tick": tick,
		"entities": entities,
		"decode_errors": dropped,
		"version": version,
		"game_time": game_time,
		"player_facing": player_facing,
		"player_stance": player_stance,
		"player_inventory": player_inventory,
		"visible_tiles": visible_tiles,
		"nearby_interactions": nearby_interactions,
		"current_monologue": current_monologue,
		"current_dialogue": current_dialogue,
		"dialogue_response": dialogue_response,
		"pending_recognitions": pending_recognitions,
	}


## 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"]

	# v2: visibility sector (Forward/Peripheral). null for v1 entities.
	var visibility: Variant = null
	var raw_vis: Variant = raw.get("visibility")
	if raw_vis is String:
		visibility = raw_vis

	# v4: relationship (D-033) and observation state
	var relationship: String = "Unknown"
	var raw_rel: Variant = raw.get("relationship")
	if raw_rel is String:
		relationship = raw_rel

	var observation: Variant = "Visible"
	var raw_obs: Variant = raw.get("observation")
	if raw_obs is String:
		observation = raw_obs
	elif raw_obs is Dictionary:
		observation = _decode_enum_variant(raw_obs)

	return {
		"entity_id": entity_id,
		"x": float(raw["x"]),
		"y": float(raw["y"]),
		"z": int(raw["z"]),
		"kind": _decode_enum_variant(raw["kind"]),
		"visibility": visibility,
		"relationship": relationship,
		"observation": observation,
	}


## Decode a NearbyInteraction from a raw msgpack map.
## Returns {entity_id, entity_type, distance, verbs: [{kind, label, priority, available}]} or null.
static func _decode_nearby_interaction(raw) -> Variant:
	if not raw is Dictionary:
		return null
	if not raw.has("entity_id") or not raw.has("verbs"):
		push_warning("Protocol: nearby_interaction missing required fields: %s" % str(raw.keys()))
		return null
	var verbs: Array[Dictionary] = []
	var raw_verbs: Variant = raw.get("verbs")
	if raw_verbs is Array:
		for rv in raw_verbs:
			var verb = _decode_verb_option(rv)
			if verb != null:
				verbs.append(verb)
	if verbs.is_empty():
		return null
	var entity_type: String = ""
	var raw_et: Variant = raw.get("entity_type")
	if raw_et is String:
		entity_type = raw_et
	return {
		"entity_id": int(raw["entity_id"]),
		"entity_type": entity_type,
		"distance": int(raw.get("distance", 0)),
		"verbs": verbs,
	}


## Decode a VerbOption from a raw msgpack map.
## Returns {kind, label, priority, available} or null.
static func _decode_verb_option(raw) -> Variant:
	if not raw is Dictionary or not raw.has("label"):
		return null
	var kind: String = ""
	var raw_kind: Variant = raw.get("kind")
	if raw_kind is String:
		kind = raw_kind
	return {
		"kind": kind,
		"label": str(raw["label"]),
		"priority": int(raw.get("priority", 0)),
		"available": bool(raw.get("available", true)),
	}


## 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 = _encode_action(action_name, action_data)

	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")
		wire_inputs.append({
			"tick": input["tick"],
			"action": _encode_action(action_name, action_data),
		})

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

	return result.value


## Encode a PlayerAction for the wire.
## Struct variants (Interact) always need their fields even when null.
## Unit variants (MoveNorth, Pause, etc.) encode as bare strings.
static func _encode_action(action_name: String, action_data: Variant) -> Variant:
	if action_data != null:
		return { action_name: action_data }
	# Interact is a struct variant — server expects named fields, not a bare string
	if action_name == "Interact":
		return { "Interact": { "target_entity_id": null, "verb": null } }
	return action_name


## 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"]),
	}