eagle0/docs/ai-quest-completion.md

AI Quest Completion Behavior

This document describes which quests the AI attempts to complete proactively to recruit unaffiliated heroes.

Overview

The AI attempts to complete most quests via FulfillQuestsCommandSelector, which is invoked by MidGameAIClient.chosenFulfillEasyQuestsCommand.

Important scope limits:

• The selector only considers quests from unaffiliated heroes in provinces owned by the acting faction.
• It further filters to provinces ruled by that faction's leader.
• It only emits a command when the corresponding command is currently available.
• Handler order is fixed. The first handler that produces a valid command wins.

Quests the AI Actively Completes

This section lists quests with direct QuestCommandChooser handlers in FulfillQuestsCommandSelector.

Diplomacy Quests

Quest	Handler	Conditions
TruceWithFactionQuest	TruceWithFactionQuestCommandChooser	Target faction must meet trust conditions for truce
TruceCountQuest	TruceCountQuestCommandChooser	Picks a random faction that meets trust conditions and isn't already in a truce/alliance
AllianceQuest	AllianceQuestCommandChooser	Target faction must meet trust conditions for alliance and not already be in an alliance
BetrayAllyQuest	BetrayAllyQuestCommandChooser	Break alliance with target faction. Only if factions don't share a border. Sends weakest non-leader hero.

Province Development Quests

Quest	Handler	Notes
ImproveAgricultureQuest	ImproveQuestCommandChooser	Issues an Improve command with Agriculture type
ImproveEconomyQuest	ImproveQuestCommandChooser	Issues an Improve command with Economy type
ImproveInfrastructureQuest	ImproveQuestCommandChooser	Issues an Improve command with Infrastructure type
TotalDevelopmentQuest	TotalDevelopmentQuestCommandChooser	Improve the lowest stat in the target province

Resource Giving Quests

Quest	Handler	Notes
AlmsToProvinceQuest	AlmsToProvinceQuestCommandChooser	Gives food to the specified province
AlmsAcrossRealmQuest	AlmsAcrossRealmQuestCommandChooser	Gives food from the province with the largest surplus
GiveToHeroesInProvinceQuest	GiveToHeroesInProvinceQuestCommandChooser	Gives gold to the hero with the lowest loyalty in the specified province
GiveToHeroesAcrossRealmQuest	GiveToHeroesAcrossRealmQuestCommandChooser	Gives gold from the province with the most gold available
SpendOnFeastsInProvinceQuest	SpendOnFeastsQuestCommandChooser	Spend gold on feasts in the quest holder's province
SpendOnFeastsAcrossRealmQuest	SpendOnFeastsQuestCommandChooser	Spend gold on the most expensive currently available feast
SendSuppliesQuest	SendSuppliesQuestCommandChooser	Send food to the target province

Prisoner Quests

Quest	Handler	Notes
ReleasePrisonerQuest	ReleasePrisonerQuestCommandChooser	Release a specific prisoner
ExilePrisonerQuest	ExilePrisonerQuestCommandChooser	Exile a specific prisoner
ExecutePrisonerQuest	ExecutePrisonerQuestCommandChooser	Execute a specific prisoner
ReturnPrisonerQuest	ReturnPrisonerQuestCommandChooser	Return a prisoner to their faction
ReleaseAllPrisonersQuest	ReleaseAllPrisonersQuestCommandChooser	Release all prisoners

Province Order Quests

Quest	Handler	Notes
DevelopProvincesQuest	DevelopProvincesQuestCommandChooser	Switches provinces to Develop order. Prefers provinces without hostile neighbors.
MobilizeProvincesQuest	MobilizeProvincesQuestCommandChooser	Switches provinces to Mobilize order. Prefers provinces with hostile neighbors. Skipped if a DevelopProvincesQuest also exists (conflict avoidance).

Weather/Epidemic Quests

Quest	Handler	Notes
StartEpidemicQuest	StartEpidemicQuestCommandChooser	Start an epidemic in a province. Skipped if the target province belongs to the acting faction.
StartBlizzardQuest	ControlWeatherQuestCommandChooser	Start a blizzard via ControlWeather command. Skipped if the target province belongs to the acting faction.
StartDroughtQuest	ControlWeatherQuestCommandChooser	Start a drought via ControlWeather command. Skipped if the target province belongs to the acting faction.

Military Quests

Quest	Handler	Notes
GrandArmyQuest	GrandArmyQuestCommandChooser	Uses OrganizeTroops to top off existing battalions and hire Light Infantry. Only executes if resources are sufficient to fully meet the troop target.
BattalionDiversityQuest	BattalionDiversityQuestCommandChooser	Hires one battalion of a missing type to reach 3+ distinct types. Only attempts if the province already has 2+ existing types, has sufficient development (meetsRequirements), and gold/food surplus.
UpgradeBattalionQuest	UpgradeBattalionQuestCommandChooser	Walks a priority tree per turn: arm-completes (with optional Visit Town and/or food sale setup) → train-completes → march in a pre-qualified neighbor battalion → organize/top-off of the target type → march in an unqualified neighbor battalion → develop Economy/Agriculture → train progress → develop Infrastructure → arm progress. Only chooses Visit Town when it directly enables an arm-completes finisher.

Reconnaissance Quests

Quest	Handler	Notes
ReconSpecificProvincesQuest	ReconSpecificProvincesQuestCommandChooser	Recon specific target provinces. Prefers not-yet-reconned targets.
ReconProvincesQuest	ReconProvincesQuestCommandChooser	Issues a Recon command to reconnoiter a province

Beast Quests

Quest	Handler	Notes
FightBeastsAloneQuest	FightBeastsAloneQuestCommandChooser	Send an expendable non-leader hero to fight beasts without a battalion. Hero must have power at most MaxExpendableHeroPowerRatio (default 0.75) times the quest-giving hero's power. Picks the weakest eligible hero.

Special Event Quests

Quest	Handler	Notes
ApprehendOutlawQuest	ApprehendOutlawQuestCommandChooser	Apprehend a specific outlaw hero when present in the province

Other Quests

Quest	Handler	Conditions
RestProvinceQuest	RestProvinceQuestCommandChooser	Use the Rest command in a specific province
SwearBrotherhoodWithHeroQuest	SwearBrotherhoodQuestCommandChooser	Swear brotherhood with a specific hero
DismissSpecificVassalQuest	DismissSpecificVassalCommandChooser	Only if province has more than 2 heroes AND the unaffiliated hero's power >= target hero's power * RequiredPowerMultiplierForDismiss

Quests the AI Handles Indirectly

These are not in FulfillQuestsCommandSelector, but other AI command-selection code can still bias toward completing them.

Quest	Handler	Notes
SuppressRiotByForceQuest	CommandChoiceHelpers.handleRiotSelectedCommand	When this quest exists and the faction has battalions, the AI prefers CrackDown over Give when handling riots.

Quests the AI Does Not Yet Attempt to Complete

The following quests have no handler and must be completed naturally through gameplay. They are listed in rough priority order for future implementation.

Planned for Implementation

None currently planned.

Not Planned

These quests are too situational, passive, or risky to actively pursue. They may be completed naturally through gameplay.

• BorderSecurityQuest - Have troops in a border province. Involves taking provinces; better left to organic expansion.
• DefeatFactionQuest - Defeat a specific faction. Too risky to pursue proactively.
• SpecificExpansionQuest - Conquer a specific province. Too risky.
• ExpandToProvincesQuest - Expand to control a certain number of provinces. Too risky.
• WinBattleOutnumberedQuest - Win a battle while outnumbered. Can't reliably engineer.
• WinBattlesQuest - Win a number of battles. Passive.
• RescueImprisonedLeaderQuest - Rescue an imprisoned leader. Complex multi-step.
• WealthQuest - Accumulate gold and food. Happens passively.
• RepairDevastationQuest - Repair devastation. Happens passively.

Implementation Details

The quest completion logic is located in:

• FulfillQuestsCommandSelector.scala - Main entry point, iterates through choosers
• quest_command_selectors/ - Individual quest handlers

Each chooser extends either:

• QuestCommandChooser - For quests requiring randomness
• DeterministicQuestCommandChooser - For quests with deterministic command selection

The AI prioritizes quests in the order they appear in FulfillQuestsCommandSelector.choosers:

1. TruceWithFaction
2. Improve (Agriculture/Economy/Infrastructure)
3. TotalDevelopment
4. AlmsToProvince
5. GiveToHeroesInProvince
6. AlmsAcrossRealm
7. GiveToHeroesAcrossRealm
8. TruceCount
9. DismissSpecificVassal
10. ReleasePrisoner
11. ExilePrisoner
12. ExecutePrisoner
13. ReturnPrisoner
14. ReleaseAllPrisoners
15. ApprehendOutlaw
16. SpendOnFeastsInProvince / SpendOnFeastsAcrossRealm
17. RestProvince
18. DevelopProvinces
19. MobilizeProvinces
20. SendSupplies
21. StartEpidemic
22. ControlWeather (StartBlizzard/StartDrought)
23. GrandArmy
24. FightBeastsAlone
25. BattalionDiversity
26. UpgradeBattalion
27. ReconSpecificProvinces
28. ReconProvinces
29. SwearBrotherhood
30. Alliance
31. BetrayAlly