feat: surface player routes for village needs

world/ui/ui.gd

@@ -291,13 +291,34 @@ func _build_opportunity_helper_display() -> String:
 		return ""
 	var helper: OpportunityHelperResult = simulation_manager.get_active_opportunity_helper()
 	if helper == null:
-		return "\nPossible helper: none informed, trusted, and able to supply"
+		var player_text := _build_opportunity_player_response_display()
+		return "\nPossible helper: none informed, trusted, and able to supply" + player_text
 	return (
 		"\nPossible helper: %s — %s\n%s"
 		% [_get_npc_name(helper.helper_npc_id), _get_action_name(helper.action_id), helper.reason]
 	)
 
 
+func _build_opportunity_player_response_display() -> String:
+	if not simulation_manager.has_method("get_active_opportunity_player_response"):
+		return ""
+	var response: OpportunityPlayerResponseResult = (
+		simulation_manager.get_active_opportunity_player_response()
+	)
+	if response == null:
+		return ""
+	var source_suffix := "" if response.available_source_count == 1 else "s"
+	return (
+		"\nPlayer route: %s → %s · %d finite source%s"
+		% [
+			_get_action_name(response.action_id),
+			String(response.target_id).replace("_", " ").capitalize(),
+			response.available_source_count,
+			source_suffix,
+		]
+	)
+
+
 func _build_npc_opportunity_display(npc: SimNPC) -> String:
 	if not simulation_manager.has_method("get_latest_opportunity_for_npc"):
 		return ""

world/ui/village_whisper_hud.gd

@@ -3,6 +3,7 @@ extends Control
 
 const DISPLAY_SECONDS := 4.2
 const ENTER_OFFSET := 8.0
+const FEEDBACK_PLAYER_RESPONSE := &"player_response"
 
 @export var simulation_manager: Node
 
@@ -15,6 +16,8 @@ var resting_position: Vector2
 var feedback_version := 0
 var active_trigger_event_id := OpportunityStateRecord.NO_EVENT_ID
 var informed_listener_id := -1
+var feedback_kind := &""
+var player_response_available := false
 
 
 func _ready() -> void:
@@ -28,12 +31,29 @@ func _ready() -> void:
 	simulation_manager.opportunity_invalidated.connect(_on_opportunity_invalidated)
 	simulation_manager.event_knowledge_transferred.connect(_on_event_knowledge_transferred)
 	simulation_manager.npc_decision_recorded.connect(_on_npc_decision_recorded)
+	simulation_manager.event_knowledge_changed.connect(_on_helper_facts_changed)
+	simulation_manager.event_knowledge_forgotten.connect(_on_helper_fact_forgotten)
+	simulation_manager.relationship_changed.connect(_on_helper_relationship_changed)
+	simulation_manager.npc_inventory_changed.connect(_on_helper_inventory_changed)
+	simulation_manager.village_changed.connect(_on_village_changed)
 	simulation_manager.state_restored.connect(_on_state_restored)
+	player_response_available = simulation_manager.get_active_opportunity_player_response() != null
 
 
 func _on_opportunity_opened(opportunity: OpportunityStateRecord) -> void:
 	active_trigger_event_id = opportunity.get_trigger_event_id()
 	informed_listener_id = -1
+	var player_response: OpportunityPlayerResponseResult = (
+		simulation_manager.get_active_opportunity_player_response()
+	)
+	player_response_available = player_response != null
+	if player_response != null:
+		_show_feedback(
+			"You can help",
+			_build_player_response_message(player_response),
+			FEEDBACK_PLAYER_RESPONSE
+		)
+		return
 	_show_feedback("Village need", _build_need_message(opportunity))
 
 
@@ -78,6 +98,44 @@ func _on_npc_decision_recorded(npc: SimNPC, decision: ActionSelectionResult) ->
 	)
 
 
+func _on_helper_facts_changed(_knower_id: int, _event: EconomicEventRecord) -> void:
+	_refresh_player_response()
+
+
+func _on_helper_fact_forgotten(_knower_id: int, _event: EconomicEventRecord) -> void:
+	_refresh_player_response()
+
+
+func _on_helper_relationship_changed(
+	_relationship: RelationshipStateRecord, _cause_event: EconomicEventRecord
+) -> void:
+	_refresh_player_response()
+
+
+func _on_helper_inventory_changed(_npc: SimNPC, _item_id: StringName, _amount: float) -> void:
+	_refresh_player_response()
+
+
+func _on_village_changed(_village: SimVillage) -> void:
+	_refresh_player_response()
+
+
+func _refresh_player_response() -> void:
+	var response: OpportunityPlayerResponseResult = (
+		simulation_manager.get_active_opportunity_player_response()
+	)
+	var is_available := response != null
+	if is_available == player_response_available:
+		return
+	player_response_available = is_available
+	if response != null:
+		_show_feedback(
+			"You can help", _build_player_response_message(response), FEEDBACK_PLAYER_RESPONSE
+		)
+	elif feedback_kind == FEEDBACK_PLAYER_RESPONSE:
+		_reset_feedback()
+
+
 func _on_opportunity_resolved(
 	opportunity: OpportunityStateRecord, resolution_event: EconomicEventRecord
 ) -> void:
@@ -92,6 +150,7 @@ func _on_opportunity_resolved(
 	)
 	_show_feedback("Need met", "%s %s." % [actor_name, outcome])
 	informed_listener_id = -1
+	player_response_available = false
 
 
 func _on_opportunity_invalidated(opportunity: OpportunityStateRecord) -> void:
@@ -99,6 +158,7 @@ func _on_opportunity_invalidated(opportunity: OpportunityStateRecord) -> void:
 		return
 	_show_feedback("Need closed", "The village could no longer act on this report.")
 	informed_listener_id = -1
+	player_response_available = false
 
 
 func _on_state_restored() -> void:
@@ -110,6 +170,7 @@ func _on_state_restored() -> void:
 		else OpportunityStateRecord.NO_EVENT_ID
 	)
 	informed_listener_id = -1
+	player_response_available = simulation_manager.get_active_opportunity_player_response() != null
 
 
 func _build_need_message(opportunity: OpportunityStateRecord) -> String:
@@ -123,6 +184,22 @@ func _build_need_message(opportunity: OpportunityStateRecord) -> String:
 	return "%s needs wood to finish %s." % [interested_name, action_name]
 
 
+func _build_player_response_message(response: OpportunityPlayerResponseResult) -> String:
+	var destination := _get_destination_name(response.target_id)
+	if response.resource_id == SimulationIds.RESOURCE_FOOD:
+		return "Forage food; it goes straight to the %s." % destination
+	return "Harvest a tree; wood goes straight to the %s." % destination
+
+
+func _get_destination_name(target_id: StringName) -> String:
+	match target_id:
+		SimulationIds.STORAGE_VILLAGE_PANTRY:
+			return "village pantry"
+		SimulationIds.STORAGE_VILLAGE_WOODPILE:
+			return "village woodpile"
+	return String(target_id).replace("_", " ")
+
+
 func _get_need_name(opportunity: OpportunityStateRecord) -> String:
 	return (
 		"empty-pantry worry"
@@ -143,13 +220,14 @@ func _get_npc_name(npc_id: int) -> String:
 	return "Someone"
 
 
-func _show_feedback(heading: String, body: String) -> void:
+func _show_feedback(heading: String, body: String, kind: StringName = &"") -> void:
 	feedback_version += 1
 	var version := feedback_version
 	if feedback_tween != null:
 		feedback_tween.kill()
 	kicker.text = heading.to_upper()
 	message.text = body
+	feedback_kind = kind
 	visible = true
 	position = resting_position + Vector2(0.0, ENTER_OFFSET)
 	modulate.a = 0.0
@@ -174,6 +252,7 @@ func _fade_after_delay(version: int) -> void:
 	await feedback_tween.finished
 	if version == feedback_version:
 		visible = false
+		feedback_kind = &""
 
 
 func _reset_feedback() -> void:
@@ -181,6 +260,7 @@ func _reset_feedback() -> void:
 	if feedback_tween != null:
 		feedback_tween.kill()
 	visible = false
+	feedback_kind = &""
 	position = resting_position
 	modulate.a = 0.0
 	if accent != null: