feat: surface player routes for village needs

simulation/opportunities/VillageOpportunitySystem.gd

@@ -193,6 +193,62 @@ func find_capable_helper(
 	)
 
 
+func find_player_response(
+	opportunity: OpportunityStateRecord,
+	target_storage: StorageStateRecord,
+	resource_states: Dictionary,
+	has_capable_helper: bool
+) -> OpportunityPlayerResponseResult:
+	if (
+		opportunity == null
+		or not opportunity.is_open()
+		or target_storage == null
+		or target_storage.get_storage_id() != opportunity.get_target_id()
+		or has_capable_helper
+	):
+		return null
+	var remaining := maxf(
+		opportunity.get_target_amount() - target_storage.get_amount(opportunity.get_resource_id()),
+		0.0
+	)
+	if remaining <= 0.0 or target_storage.get_available_capacity() < remaining:
+		return null
+	var action_ids := _get_supply_action_ids(opportunity.get_resource_id())
+	if action_ids.is_empty():
+		return null
+	var gather_definition := SimulationDefinitions.get_action(action_ids["gather"])
+	if gather_definition == null:
+		return null
+	var available_source_count := _count_player_resource_sources(
+		remaining, opportunity.get_resource_id(), gather_definition, resource_states
+	)
+	if available_source_count == 0:
+		return null
+	return (
+		OpportunityPlayerResponseResult
+		. new(
+			{
+				"opportunity_id": opportunity.get_opportunity_id(),
+				"trigger_event_id": opportunity.get_trigger_event_id(),
+				"action_id": gather_definition.action_id,
+				"resource_id": opportunity.get_resource_id(),
+				"target_id": target_storage.get_storage_id(),
+				"available_source_count": available_source_count,
+				"reason":
+				(
+					"No capable helper; %d player-usable finite %s source%s can supply %s"
+					% [
+						available_source_count,
+						String(opportunity.get_resource_id()).capitalize(),
+						"" if available_source_count == 1 else "s",
+						String(target_storage.get_storage_id()),
+					]
+				),
+			}
+		)
+	)
+
+
 func _build_helper_candidate(
 	npc: SimNPC,
 	opportunity: OpportunityStateRecord,
@@ -299,6 +355,29 @@ static func _count_available_resource_sources(
 	return count
 
 
+static func _count_player_resource_sources(
+	remaining: float,
+	resource_id: StringName,
+	gather_definition: ActionDefinition,
+	resource_states: Dictionary
+) -> int:
+	var count := 0
+	for value in resource_states.values():
+		var state := value as ResourceStateRecord
+		if (
+			state == null
+			or state.get_action_id() != gather_definition.resource_action_id
+			or state.get_resource_id() != resource_id
+			or not state.can_player_use_resource()
+			or not state.can_extract()
+			or state.get_yield_per_action() <= 0.0
+			or state.get_amount_remaining() < remaining
+		):
+			continue
+		count += 1
+	return count
+
+
 static func _sort_helper_candidates(first: Dictionary, second: Dictionary) -> bool:
 	if first["uses_inventory"] != second["uses_inventory"]:
 		return bool(first["uses_inventory"])