Expand province logistics documentation (#8426)

docs/eagle0pedia/src/content/docs/provinces/index.md

@@ -5,56 +5,225 @@ description: Reference for Eagle provinces, resources, infrastructure, orders, a
 
 Provinces are the strategic map locations in Eagle. They hold resources, heroes, battalions, province orders, incoming armies, local events, and the Shardok map used when battles occur there.
 
-The player-facing province model is `ProvinceView`. Public information includes id, name, ruling faction, known events, known incoming armies, and an `as_of` date. When the player has full information, `FullProvinceInfo` adds the detailed local state.
+The player-facing province model is `ProvinceView`. Public information includes id, name, ruling faction, known events, known incoming armies, and an `as_of` date. When you have full information, `FullProvinceInfo` adds the detailed local state: gold, food, caps, support, food consumption, battalions, heroes, orders, incoming shipments, and local events.
 
-## Province Stats
+<!--
+Source map:
+- Province view fields: src/main/protobuf/net/eagle0/eagle/views/province_view.proto and src/main/scala/net/eagle0/eagle/library/util/view_filters/ProvinceViewFilter.scala.
+- Province utilities: src/main/scala/net/eagle0/eagle/library/util/province/ProvinceUtils.scala.
+- New year production and yearly degradation: src/main/scala/net/eagle0/eagle/library/actions/impl/action/NewYearAction.scala.
+- New round caps, price-index drift, empty-province devastation repair, and hero-cap loyalty pressure: src/main/scala/net/eagle0/eagle/library/actions/impl/action/NewRoundAction.scala.
+- Food consumption and starvation: src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformFoodConsumptionPhaseAction.scala.
+- Shipment arrival: src/main/scala/net/eagle0/eagle/library/actions/impl/action/ShipmentArrivedAction.scala and src/main/scala/net/eagle0/eagle/library/actions/impl/action/PerformProvinceMoveResolutionAction.scala.
+- Price index: src/main/scala/net/eagle0/eagle/library/util/PriceIndexUtils.scala.
+- Settings: src/main/resources/net/eagle0/eagle/settings.tsv.
+-->
 
-- **Economy** affects gold production and the province's economic strength.
-- **Agriculture** affects food production and the province's ability to sustain armies and heroes.
-- **Infrastructure** affects development quality and can cap certain troop improvements.
-- **Economy devastation**, **agriculture devastation**, and **infrastructure devastation** track war damage or disaster damage to those systems.
-- **Support** represents local backing for the ruling faction.
+## Strategic Role
 
-## Supplies
+A province is both a resource base and a staging point. It can:
 
-Provinces store gold and food. They also have gold and food caps. Commands such as feast, alms, trade, organize troops, send supplies, and march all interact with province supplies.
+- Produce gold and food at the new year.
+- Store gold and food between commands.
+- Feed stationed battalions each round.
+- Hold heroes, battalions, prisoners, unaffiliated heroes, and events.
+- Launch March, Send Supplies, Train, Improve, Arm Troops, Trade, and other province commands.
+- Become a Shardok battlefield when hostile armies meet there.
+
+The important strategic question is usually not just "how high are the stats?" It is "can this province keep support above 40, feed its troops, store enough supplies, and stage the actions I need before another faction interferes?"
+
+## Development Stats
+
+The three main development stats are **economy**, **agriculture**, and **infrastructure**.
+
+- **Economy** drives annual gold production. A supported province produces 35 gold per effective economy at the new year.
+- **Agriculture** drives annual food production. A supported province produces 50 food per effective agriculture at the new year.
+- **Infrastructure** increases gold and food storage caps, affects improvement quality, and caps how far battalions can be armed.
+
+Each stat has a matching devastation track. The effective value is the stat minus its devastation, never below 0. For example, 80 agriculture with 25 agriculture devastation behaves like 55 effective agriculture for production and other effective-stat checks.
+
+Improve can raise economy, agriculture, or infrastructure. It can also repair devastation across all three devastation tracks. Engineers get a bonus when improving.
+
+## Support
+
+Support is local backing for the ruling faction. It ranges from 0 to 100 and is one of the most important province numbers.
+
+A province needs at least **40 support** to provide annual gold and food production. If support is below 40, the province does not produce taxes at the new year. That also matters for prestige: supported provinces are worth prestige to the ruling faction.
+
+Support changes through several commands and events:
+
+- **Alms** spends food to raise support.
+- **Improve** raises support as a side effect.
+- **Riot** damage reduces support by 25 if the riot is not stopped.
+- **Suppress Beasts** can raise support on success.
+- Province events can raise or lower support.
+
+Support also affects risk. Low support makes the province less useful economically and affects riot timing.
+
+## Gold
+
+Gold pays for many strategic actions. Feast, Organize Troops, Arm Troops, Divine, Hero Gift, diplomacy, Trade buys, and some other commands spend gold.
+
+At the new year, supported provinces gain annual gold equal to:
+
+`effective economy * 35`
+
+Gold is stored in the province until spent, traded, shipped, marched away, captured through conquest, or lost because the province is over its storage cap.
+
+Feast costs gold, not food: 20 gold per ruling-faction hero in the province, multiplied by the province price index.
+
+## Food
+
+Food supports armies and can also be spent strategically.
+
+At the new year, supported provinces gain annual food equal to:
+
+`effective agriculture * 50`
+
+Food is consumed during the Food Consumption phase by battalions stationed in the province and by moving armies. The province view exposes monthly food consumption so you can judge how long the province can feed its current troops.
+
+Food is also used by:
+
+- **Alms**, which spends food to raise support.
+- **Trade**, which buys or sells food for gold.
+- **Send Supplies**, which can ship food to another province.
+- **March**, which can carry food with moving armies.
+- Riot gifts, if you choose to give food.
+
+## Food Consumption and Starvation
+
+Food consumption happens during the Food Consumption phase, after Province Move Resolution, player commands, hostile army setup, and battle requests, but before Battle Resolution.
+
+This timing matters:
+
+- A Send Supplies shipment that arrives during Province Move Resolution is available before the destination province consumes food later that same round.
+- A friendly marching army that arrives during Province Move Resolution can also bring food before that round's food consumption.
+- Moving armies consume food from their own carried supplies while they are still incoming.
+
+If a province cannot feed its battalions, it spends all remaining province food and the battalions are reduced. The maximum battalion reduction from a food shortage is 20% in a single food-consumption event.
+
+The same starvation rule applies to moving armies: if the army's carried food is not enough, the moving battalions are reduced and the army's food drops to 0.
+
+Low-food warnings look ahead to incoming food, upcoming taxes, support, and expected production. If the province has enough food arriving before the next consumption, the warning can account for that.
+
+## Storage Caps
+
+Provinces have separate gold and food caps. These caps are based on effective development and infrastructure:
+
+- Gold cap uses effective economy plus effective infrastructure.
+- Food cap uses effective agriculture plus effective infrastructure.
+- Both start from a base storage limit of 5000.
+- Each point of relevant development or infrastructure adds 50 storage.
+- A faction's focus province gets 1.5x storage.
+
+Being over cap is not an immediate hard cutoff. During New Round processing, the province loses 20% of the amount above each cap, rounded up. Excess supplies therefore decay over time unless you spend them, ship them, trade them, or move them.
 
 ## Price Index
 
-The price index reflects local price pressure. Spending-heavy commands can move it, and costs can scale by it.
+Price index is local price pressure. It changes costs and trade prices in the province.
+
+The normal range is 0.75 to 1.5. A price index above 1 makes local purchases more expensive; below 1 makes them cheaper.
+
+Gold spending can push the price index upward. Selling food counts as negative gold spending and can push it downward. Each gold spent changes the index by 0.0001, clamped to the normal range.
+
+The price index also drifts each new round toward a local steady state based on development and devastation. It moves 10% of the distance toward that steady state per round.
+
+Commands affected by price index include:
+
+- **Feast** gold cost.
+- **Organize Troops** troop costs.
+- **Arm Troops** armament costs.
+- **Trade** buy and sell prices.
+- **Divine** cost.
+- **Hero Gift** loyalty gained per gold.
+
+## Devastation
+
+Devastation is damage to province systems. Economy, agriculture, and infrastructure each have their own devastation value.
+
+Devastation reduces the corresponding effective stat. That means:
+
+- Economy devastation reduces gold production and gold storage.
+- Agriculture devastation reduces food production and food storage.
+- Infrastructure devastation reduces storage, armament ceiling, and infrastructure-dependent checks.
+
+Battles and province events can add devastation. Riots add economy and infrastructure devastation. Blizzards, droughts, floods, epidemics, and battle results can damage different province systems.
+
+Improve with the Devastation option repairs all three devastation tracks. Empty provinces also recover devastation slowly during new round processing.
+
+## Infrastructure and Troops
+
+Infrastructure matters militarily because it caps armament. Arm Troops cannot raise a battalion's ARM above the province's effective infrastructure.
+
+Economy and agriculture also affect which battalion types can be raised in the province. Battalion type availability checks the province's effective economy and effective agriculture against the battalion type's minimums.
+
+Training is handled by **Train**. Armament is handled by **Arm Troops**. Organizing troop counts, creating battalions, resizing battalions, and dismissing battalions are handled by **Organize Troops**.
+
+## Heroes and Hero Cap
+
+A province has a hero cap. The default map data sets hero cap from castle count: each castle gives 5 hero capacity.
+
+Going over the cap is allowed, but it creates loyalty pressure. During new round processing, if the province has too many established ruling-faction heroes, those heroes lose loyalty. Newly joined heroes are exempt for their first few rounds.
+
+This is why moving heroes around is not just about command access. Keeping too many heroes stacked in one province can create long-term loyalty damage.
 
 ## Ruling Faction and Ruling Hero
 
-A province can have a ruling faction and a ruling hero. Full province info also tracks the ordered list of ruling-faction heroes currently in the province.
+A province can have a ruling faction and a ruling hero. The ruling hero is the local leader for the province.
 
-## Battalions and Defenders
+If a faction leader rules the province, the player can command that leader directly. If a vassal rules it, the province acts through vassal behavior during the Vassal Commands phase unless another special phase interrupts it.
 
-Provinces contain battalions and may have a defending army. Organize, train, arm, march, defend, and attack-related commands all depend on province military state.
-
-## Incoming Armies
-
-Incoming armies represent forces that are moving toward the province but have not arrived or resolved yet. They can trigger defense choices, battles, or other strategic consequences.
+Province leadership also matters for riots. The province leader's Charisma affects riot size and gift success, even if another hero is selected to crack down.
 
 ## Province Orders
 
-Province orders are standing instructions for the province. The `Issue Orders` command changes them and can also change the faction's focus province.
+Province orders are standing instructions for vassal-led provinces. The **Issue Orders** command changes them and can also set or clear the faction focus province.
 
-## Tactical Map
+The main orders are:
 
-Each province has a `hex_map_name`. When a battle occurs there, Eagle uses that name to connect the strategic province to the Shardok tactical map.
+- **Entrust:** let the vassal judge the situation.
+- **Develop:** build up and improve the province.
+- **Mobilize:** prepare military strength and supplies.
+- **Expand:** look for growth, movement, and attack opportunities.
 
-## Castles
+The focus province also affects logistics. Vassals may ship excess gold and food toward the focus province if one is set, or toward the nearest faction leader if not.
 
-`castle_count` records the province's fortification count. Castles matter for defensive strength and battle setup.
+## Incoming Armies
 
-## Hero Cap
+Incoming armies represent forces that are moving toward the province but have not arrived or resolved yet.
 
-`hero_cap` limits how many ruling-faction heroes the province can comfortably hold.
+Friendly incoming armies arrive during Province Move Resolution if the destination is already ruled by their faction. Hostile arrivals do not simply enter the province; they can become hostile army groups and later trigger conquest, attack decisions, defense decisions, battle requests, and Shardok battles.
 
-## Unaffiliated Heroes
+Incoming armies can carry gold and food. If supplies arrive with a friendly movement, transit loss can reduce the amount received.
 
-Unaffiliated heroes in a province are potential recruits, quest-givers, outlaws, or heroes asking to join. Province info exposes their basics and recruitment information when known.
+## Incoming Shipments
 
-## Province Map Data
+Incoming shipments are supplies sent by **Send Supplies**.
 
-`province_map.tsv` defines province ids, names, neighbor ids, neighbor positions, tactical map names, neighbor names, and castle counts. This is the source for strategic map adjacency and province identity.
+The origin province loses the selected gold and food immediately. The destination receives an incoming shipment scheduled for the next round. During the next round's Province Move Resolution phase, the shipment arrives before food consumption. 10% is lost in transit, rounded down after loss.
+
+Because shipments arrive before food consumption, shipping food can prevent starvation in the destination province during the arrival round.
+
+## Province Events
+
+Province events are temporary or local conditions that affect the province.
+
+Important event types include:
+
+- **Riot:** requires a decision if it reaches Handle Riot. If not stopped, it causes support loss and devastation.
+- **Beasts:** can damage support over time and can be suppressed for rewards and prestige.
+- **Blizzard:** damages province systems and affects supplies.
+- **Drought:** damages agriculture.
+- **Flood:** damages infrastructure and agriculture.
+- **Epidemic:** damages economy, battalions, and hero vigor, and can spread or end over time.
+- **Festival:** improves support and prestige while active.
+
+Some events can be created or changed by commands. Mages can use **Control Weather** to start or end blizzards and droughts. Necromancers can use **Start Epidemic**.
+
+## Tactical Map and Castles
+
+Each province has a `hex_map_name`. When a battle occurs there, Eagle uses that name to choose the Shardok tactical map.
+
+`castle_count` records the province's fortification count. Castles matter for hero capacity, defensive setup, tactical objectives, and some battle behavior.
+
+The source map data in `province_map.tsv` defines province ids, names, neighbor ids, neighbor positions, tactical map names, neighbor names, and castle counts.