feat(client): add interaction prompt system (#405)

Server-driven interaction prompt that displays "E - Talk" when near
an interactable NPC. Decodes v4 nearby_interactions from snapshot,
stores in GameState, renders via InteractionPrompt UI with fade
animation. Extensible interface (get_interaction_target/get_selected_verb)
for future radial verb menu (v0.2).

- Protocol: decode nearby_interactions array with nested VerbOption structs,
  entity relationship/observation fields, tick_rate in GameTime
- GameState: store/clear nearby_interactions per snapshot
- SimBridge: test mode generates v4 format with structured verbs
- InteractionPrompt: PanelContainer with fade in/out, polls GameState
- Tests: 19 new test cases covering protocol, state, sim bridge, UI, encoding
- Fixture assertions updated for v4 protocol version

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

client/scripts/autoloads/game_state.gd

@@ -19,6 +19,9 @@ var visibility_sectors: Dictionary = {}  # Vector2i -> "Forward"/"Peripheral"
 # refined when the server assigns explicit player entity IDs).
 var player_entity_id: int = 1
 
+# v4 fields (#404/#405)
+var nearby_interactions: Array = []  # [{entity_id, entity_type, distance, verbs: [{kind, label, priority, available}]}]
+
 func apply_snapshot(snapshot: Dictionary) -> void:
 	current_snapshot = snapshot
 
@@ -54,6 +57,12 @@ func apply_snapshot(snapshot: Dictionary) -> void:
 	if snapshot.has("player_facing") and snapshot.player_facing is String:
 		player_facing = snapshot.player_facing
 
+	# v4: nearby_interactions (#404/#405)
+	if snapshot.has("nearby_interactions") and snapshot.nearby_interactions is Array:
+		nearby_interactions = snapshot.nearby_interactions
+	else:
+		nearby_interactions = []
+
 	# v2: visible_tiles with visibility sectors
 	# Derives visible_positions when not explicitly provided (real server mode)
 	if snapshot.has("visible_tiles") and snapshot.visible_tiles is Array and snapshot.visible_tiles.size() > 0:

client/scripts/autoloads/sim_bridge.gd

@@ -294,20 +294,34 @@ func _test_snapshot() -> Dictionary:
 			"visibility": sector,
 		})
 
+	# v4: nearby_interactions when NPC is nearby and visible (#404/#405)
+	var nearby: Array = []
+	if npc_dist <= 2 and _test_has_los(Vector2i(px, py), npc_pos):
+		nearby.append({
+			"entity_id": 2,
+			"entity_type": "Npc",
+			"distance": npc_dist,
+			"verbs": [
+				{"kind": "Talk", "label": "Talk", "priority": 0, "available": true},
+				{"kind": "ExamineNpc", "label": "Examine", "priority": 1, "available": true},
+			],
+		})
+
 	return {
 		"tick": _test_tick,
-		"version": 2,
+		"version": 4,
 		"game_time": {
 			"day": 0,
 			"time_of_day": _test_tick * 10,
 			"day_phase": "Morning",
-			"paused": false,
+			"tick_rate": "Full",
 		},
 		"player_facing": _test_facing,
 		"entities": entities,
 		"tiles": _test_tiles(),
 		"visible_tiles": _test_visible_tiles(),
 		"visible_positions": _test_visible_positions(),
+		"nearby_interactions": nearby,
 	}
 
 # Generate a small test room: 8x6 room with walls, a door, and floor

client/scripts/constants.gd.uid

@@ -0,0 +1 @@
+uid://wmbu7ivynu5d

client/scripts/main.gd

@@ -4,6 +4,7 @@ extends Node2D
 @onready var camera = $Camera2D
 @onready var hud = $UILayer/HUD
 @onready var monologue_display = $UILayer/MonologueDisplay
+@onready var interaction_prompt = $UILayer/InteractionPrompt
 
 func _ready() -> void:
 	print("The Settled Reach — client initialized")
@@ -28,4 +29,12 @@ func _process(_delta: float) -> void:
 	# Send queued input to simulation
 	var inputs = InputMapper.flush_queue()
 	for input in inputs:
+		# TODO: Once server accepts Interact(InteractData), attach target + verb:
+		#   if input.action == InputMapper.Action.INTERACT:
+		#       var target_id: int = interaction_prompt.get_interaction_target()
+		#       if target_id >= 0:
+		#           input["action_data"] = {
+		#               "target_entity_id": target_id,
+		#               "verb": interaction_prompt.get_selected_verb(),
+		#           }
 		SimBridge.send_input(input)

client/scripts/protocol/protocol.gd

@@ -70,6 +70,15 @@ static func decode_snapshot(bytes: PackedByteArray) -> Variant:
 					tile_entry["visibility"] = vis
 				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)
+
 	return {
 		"tick": tick,
 		"entities": entities,
@@ -78,6 +87,7 @@ static func decode_snapshot(bytes: PackedByteArray) -> Variant:
 		"game_time": game_time,
 		"player_facing": player_facing,
 		"visible_tiles": visible_tiles,
+		"nearby_interactions": nearby_interactions,
 	}
 
 
@@ -96,6 +106,19 @@ static func _decode_entity(raw: Dictionary) -> Variant:
 	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"]),
@@ -103,6 +126,54 @@ static func _decode_entity(raw: Dictionary) -> Variant:
 		"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)),
 	}
 
 

client/scripts/rendering/tile_renderer.gd.uid

@@ -0,0 +1 @@
+uid://d2evnkstnqtpb