From 9b384234d8f4237eafe8289f4265d3a25e2688cc Mon Sep 17 00:00:00 2001 From: Dan Crosby Date: Sat, 6 Jun 2026 18:51:15 -0700 Subject: [PATCH] Clean up AI quest completion docs (#6937) --- docs/ai-quest-completion.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/ai-quest-completion.md b/docs/ai-quest-completion.md index 362dc14541..5a7f94d964 100644 --- a/docs/ai-quest-completion.md +++ b/docs/ai-quest-completion.md @@ -4,11 +4,18 @@ This document describes which quests the AI attempts to complete proactively to ## Overview -The AI attempts to complete quests via `FulfillQuestsCommandSelector`, which is invoked by `MidGameAIClient.chosenFulfillEasyQuestsCommand`. The AI only considers quests from unaffiliated heroes in provinces ruled by a faction leader. +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 -The AI processes quest handlers in priority order. The first handler that produces a valid command wins. +This section lists quests with direct `QuestCommandChooser` handlers in `FulfillQuestsCommandSelector`. ### Diplomacy Quests @@ -36,7 +43,8 @@ The AI processes quest handlers in priority order. The first handler that produc | `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 | -| `SpendOnFeastsQuest` | `SpendOnFeastsQuestCommandChooser` | Spend gold on feasts | +| `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 @@ -72,12 +80,6 @@ The AI processes quest handlers in priority order. The first handler that produc | `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 travel 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 toggles Travel when it directly enables an arm-completes finisher. | -### Riot Quests - -| Quest | Handler | Notes | -|-------|---------|-------| -| `SuppressRiotByForceQuest` | `CommandChoiceHelpers.handleRiotSelectedCommand` | When this quest exists and the faction has battalions, the AI prefers CrackDown over Give when handling riots. Not a quest command chooser — modifies existing riot handling priority. | - ### Reconnaissance Quests | Quest | Handler | Notes | @@ -105,6 +107,14 @@ The AI processes quest handlers in priority order. The first handler that produc | `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. @@ -153,7 +163,7 @@ The AI prioritizes quests in the order they appear in `FulfillQuestsCommandSelec 13. ReturnPrisoner 14. ReleaseAllPrisoners 15. ApprehendOutlaw -16. SpendOnFeasts +16. SpendOnFeastsInProvince / SpendOnFeastsAcrossRealm 17. RestProvince 18. DevelopProvinces 19. MobilizeProvinces