magicciv/public/games/age-of-dwarves/docs/UNIT_LOGISTICS.md

# Unit Logistics

A unit in Age of Dwarves is not a chess piece. It is a roster of named dwarves with specialist roles, an inventory of rations, fodder, tools, and message-carriers, a set of modular slots whose capability depends on what tech the player has researched and what resources the player can spare, and a stat-block that degrades the further it operates from a friendly city. Logistics is the connective tissue between the economy, the tech tree, and the battlefield.

The fantasy: a column of fifteen pioneers grinding up a switchback in the third week of a campaign, two ox-wagons creaking under powder-crates and surveyor-rods, a foot-runner setting off at dawn for the home hold with the engineer's casualty report, the cook redistributing the last of the salt-pork because the supply caravan is two days late and the dwarves have started rationing themselves.

---

## Pillars

### 1. Units as teams

Every unit is a roster of 5–30 dwarves filling specialist roles. The unit's outward archetype (Pioneer, Swordsmen, Cavalry, Engineer Corps) is a shorthand for a composition, not a single figure. Roster slots determine what the unit can do; losses to specific roles degrade specific capabilities. A swordsmen regiment that loses its surgeon does not regain HP between battles. A pioneer team that loses its two ox-wagons cannot carry powder.

### 2. Inventory as state

`Unit.inventory` is a first-class field, persisted in saves and consumed by every system the unit touches. Combat draws on arrows and powder. Movement draws on rations and fodder. Communications draws on foot-runners and birds. Construction draws on tool-durability and build-kits. An "empty" unit on a map tile is not a unit out of moves — it is a unit out of supplies, and it will starve.

### 3. Carriers are part of the unit

Foot-runners, mount-couriers, crag-ravens, hold-falcons, tunnel-runners, resonance-telegraphers — the carriers that make Communications work — are slotted into the unit at production time. Their cost is folded into the unit's training cost. A Pioneer Team built in a city that has `falconry_command` and a `crag_aerie` ships from the queue with two crag-ravens already nesting on the wagon-cage; a city without that tech-resource pair ships the same Pioneer Team with zero birds. The build-panel surfaces the difference.

### 4. Stat decline in subsistence

Units operating beyond their `operational_range` from a friendly city eat what they forage, treat their wounded with what they carry, and replace gear that breaks with what they can scavenge. They do not generally die from this, but they do degrade. Strength, Constitution, and Endurance fall turn-by-turn at rates that depend on the terrain they are in and the class of unit. Stats floor at 30–60 percent of trained max — never zero — and recover when the unit reaches friendly territory or a road.

Death comes only from terrain-gear mismatches that have no graceful fallback: arctic without cold-weather gear, desert without water, plague-belt without medicine, scorched earth without rations. Distance alone never kills a dwarf.

### 5. Modular slots, gated by tech × resource

A unit class declares SLOTS: `ox_wagon`, `mount`, `officer_bird`, `powder_charges`, `firearm`, `steam_engine`, `rune_panel`. Each slot has a (TECH, RESOURCE) pair that enables it. A Pioneer Team produced before `animal_husbandry` is researched, or in a city with no `cattle` access, ships without ox-wagons and is correspondingly slower and carries less. The same Pioneer Team produced in era 5 with `gunpowder` and access to `saltpeter` ships with powder-charges and can blast trenches.

A unit's slot-configuration is locked at training. A player who wants ox-wagons on an existing Pioneer Team must disband it and re-train, or route it through a city that has the slot enabled and pay an `upgrade` cost.

### 6. Supply caravans and wear-in roads

Caravans are units that exist to carry rations, fodder, water, arrows, and powder to forward armies. They have no combat power and need escort. Player issues an "Establish Supply Route from City A to Army B" order; the caravan auto-cycles between origin and destination, leaving wear on every tile it crosses.

Wear accumulates silently. After one wagon-pass a tile gains a `wagon_track` marker (movement cost ×0.85). After five cumulative passes the tile becomes `dirt_road` (×0.65). After fifteen passes plus a dedicated pioneer road-build action the tile becomes `proper_road` (×0.5). Wear-in is not exclusive to caravans — any wagon-carrying unit contributes — but caravans are the only units that wear roads in deliberately, as a side-effect of their normal duty cycle.

Cutting the supply line is a strategic move: pillage road tiles to downgrade them, kill the caravan and burn the cargo, sustain interdiction over multiple turns to starve the forward army into stat-floor.

---

## Canonical unit compositions

Roster headcounts are nominal trained max. Carrier complements are defaults; the slot-enable rules in §6 substitute or remove carriers in cities that lack the tech or resource.

### Founder — era 1

Five to eight dwarves: one clan-elder (the founding patriarch or matriarch), three to five builders, one or two wardens, two to three foot-runner apprentices. No mounts, no oxen, no birds, no wagons — domestication has not happened yet. The Founder is a one-shot unit: it consumes itself to found a city and cannot be re-tasked.

### Builder — era 2

Ten dwarves: one foreman, six labourers, one quarry-master, two foot-runners. Gains an `ox_wagon` slot if the producing city has `animal_husbandry` and access to `cattle`. Without the slot filled, build-rate halves on tiles further than two hexes from a road.

### Pioneer Team — era 3

Fifteen dwarves plus two ox-wagons, five foot-runners, and two crag-ravens by default. Composition: one team-lead, four surveyors, six labourers, two wardens, two ox-handlers. Carries 60 rations, 30 fodder, 12 build-kits, and 20 tool-durability. Establishes outposts, blazes trails, and can found a satellite city after era 4's `colonial_charter` tech.

### Master Pioneer / Engineer-Pioneer — era 5

Eighteen dwarves with full sub-role specialization: one chief engineer, two surveyors, two powder-handlers, six sappers, four labourers, two wardens, one cook. Carries a powder-blasting kit (40 powder-charges if `gunpowder` + `saltpeter`), a full surveyor's case, and a heavy build-kit. Three ox-wagons, six foot-runners, four crag-ravens. Builds tunnels, blasts cuttings, lays the foundations for steam-track.

### Steam Pioneer — era 7

Mechanized successor to the Master Pioneer. Twelve dwarves operating a steam-rig: one rig-captain, three engine-tenders, two welders, six labourers. Coal and iron replace cattle in the slot table — `steam_engine` slot enabled by `steam_engine` tech plus `coal` and `iron`. Carries no oxen; the rig hauls the cargo. Two steam-wagons, four hold-falcons, no foot-runners (the rig outpaces them).

### Resonance Engineer — era 8

Six dwarves and a paired resonance-chamber on each wagon. Composition: one resonance-master, two rune-cutters, two operators, one warden. Dispatches by resonance-telegraph: messages travel instantly between paired chambers, and the unit itself can be partially redeployed by chamber-pair (heavy cargo still moves by wagon, but personnel and orders move at the speed of the wire). Three rune-panel slots, all requiring `rune_resonance` + `runestone`.

### Scout Party

Era 1 baseline: five dwarves on foot, no mounts. One scout-lead, three trackers, one signal-runner. Carries 15 rations, 5 tool-durability, no carriers other than the lone signal-runner who returns to the home city in extremis.

Era 2 with `animal_training` + `boars`: gains a boar-mount slot, becomes a six-dwarf mounted scout party with two crag-ravens for long-range reporting. Speed increases, foraging radius doubles, mountain-pass cost falls.

Era 3+ with `falconry_command` + `crag_aerie`: full era-3 scout party — six dwarves, four boar-mounts, four crag-ravens, two foot-runners. Operates ten hexes ahead of the main army without losing comms.

### Clansmen / Swordsmen

Era 1 (Clansmen warband): fifteen dwarves with no support roles. One war-chief, fourteen clansmen. No cook, no surgeon, no standard-bearer. Subsistence is brutal — the warband floors hard outside friendly territory.

Era 3 (Swordsmen regiment): twenty-eight dwarves with full support. One captain, two sergeants, twenty swordsmen, one cook, one surgeon, one standard-bearer, one horn-blower, two foot-runners. Three ox-wagons carrying rations, water, arrows, a medical kit, and the regimental colour. Stat-floor doubles. Subsistence-decline halves.

### Engineer Corps — era 4+

Twenty dwarves plus siege components. One corps-captain, four siege-engineers, six sappers, four crossbowmen, three labourers, one cook, one surgeon. Two ox-wagons of siege-components, one wagon of powder once `gunpowder` is researched, four hold-falcons or crag-ravens depending on era, three foot-runners. Builds and operates siege engines in the field; can blast walls with powder once equipped.

### Cavalry — Ram Rider / Boar Lancer — era 3+

Requires `pastoralism` plus `boars` or `rams`. Twenty-two to twenty-six dwarves with eighteen to twenty-two mounts (one or two spare-mounts per rider, plus farrier mounts). Composition: one cavalry-captain, two lieutenants, eighteen to twenty-two riders, two farriers, one cook, one surgeon. Two ox-wagons of fodder and tack. Six crag-ravens — cavalry is the fastest comms vector before beacons. Fodder is the dominant supply concern; a cavalry stack out of fodder loses mounts before it loses dwarves, and a dismounted cavalry stack is a tired, hungry Clansmen warband.

### Supply Caravan

See §6. Composition by era is in the caravan-progression table below.

---

## Inventory schema

`Unit.inventory` carries the following fields. Each is integer-valued unless noted.

| Field | Meaning | Consumed by |
|-------|---------|-------------|
| `rations` | Dwarf-meals | Every dwarf in the roster, every turn |
| `water` | Dwarf-water-units | Every dwarf, every turn (desert: ×2) |
| `fodder` | Mount-meals | Every mount, every turn |
| `arrows` | Crossbow bolts / arrows | Ranged combat |
| `tool_durability` | Pool of tool-uses | Construction, terrain-clearing |
| `build_kits` | Discrete kits (outpost, watchtower, etc.) | Building actions |
| `powder_charges` | Gunpowder rounds | Blasting, firearm combat |
| `medical_kit_uses` | Surgical interventions | Healing post-combat |
| `foot_runners` | Round-trip carriers | Envelopes, intel-relay |
| `mount_couriers` | Round-trip mounted carriers | Envelopes |
| `crag_ravens` | One-way birds (era 3+) | Urgent envelopes |
| `hold_falcons` | One-way birds (era 6+) | High-priority envelopes |
| `equipped_items` | List of item-refs from `mc-items` | Combat, passive effects |

`equipped_items` is the bridge to the items system; an Engineer Corps that loses its `regimental_colour` standard does not just lose morale-aura, it loses the item record permanently unless the wagon survives.

Carrier production is part of the unit's training cost. A Pioneer Team's quoted production cost in the build-panel already includes its two ox-wagons, five foot-runners, and two crag-ravens. The player does not buy them separately.

---

## Carrier round-trip vs one-way

Carriers split into two classes by physiology.

**Round-trip carriers** — foot-runners, mount-couriers, tunnel-runners, resonance-telegraphers — return to the unit after delivering their envelope. Their inventory entry does not deplete on use. They are permanently lost only when intercepted in combat or killed by terrain or weather between the unit and the destination.

**One-way carriers** — crag-ravens, hold-falcons, and any homing bird — fly to the player's capital roost and never return to the field. Each release permanently decrements the unit's bird count. Birds are faster and more terrain-agnostic than runners but are a strictly consumable resource. A scout party that has burned through its two ravens is silent until it reaches comms infrastructure or a city.

This split is the core trade-off in field communications: a unit that hoards its birds for a real emergency keeps strategic options open; a unit that burns birds on routine reports has its strategic options collapse the moment something actually happens.

---

## Stats and subsistence

Every unit carries three primary stats as a team aggregate, starting at the unit class's trained max.

| Stat | Affects |
|------|---------|
| Strength (STR) | Melee damage, build-rate, carry-capacity |
| Constitution (CON) | HP cap, disease-resistance, recovery-rate |
| Endurance (END) | Movement points per turn, foraging efficiency, stat-decline rate |

Derived: `hp_cap = base_hp × (CON / max_CON)`, `movement_speed = base_move × (END / max_END)`, `combat_damage = base_dmg × (STR / max_STR)`. A unit at 50 percent STR is at 50 percent of its melee damage output.

### Decline curve

A unit operates inside its `operational_range` (a per-class hex-radius from the nearest friendly city) at full stats. Outside that radius, stats fall each turn at a rate determined by terrain and unit class. Stats floor at a per-class minimum; the unit becomes less capable but does not vanish.

| Unit class | Stat-floor | Decline / turn (good terrain) | Decline / turn (hostile terrain) |
|------------|-----------|-------------------------------|----------------------------------|
| Scout Party | 60% | -0.3 | -0.8 |
| Pioneer Team | 50% | -0.8 | -1.5 |
| Engineer Corps | 50% | -1.0 | -1.8 |
| Swordsmen | 40% | -1.2 | -2.0 |
| Cavalry | 30% | -2.5 | -3.5 |

"Good terrain" is grass, hills, forest_open, friendly territory. "Hostile terrain" is desert, marsh, tundra, snow, enemy territory, plague-belt.

### Recovery curve

| Location | Recovery / turn |
|----------|-----------------|
| Garrisoned in friendly city | +5 |
| Adjacent to road + city within 3 hex | +3 |
| Anywhere in friendly territory | +1 |
| Neutral wilderness | 0 |
| Enemy territory | -0.5 |

A unit can never recover above its trained max. Stat-loss from combat heals separately, via the medical kit (HP only, not STR/CON/END).

### Lethal interactions

The only ways a unit dies outright are terrain-gear mismatches:

- Arctic or tundra without `cold_weather_gear` items: CON-loss accelerates 4× and the floor lifts (true death once HP hits 0).
- Desert without water-cargo: water depletes in 2 turns; afterward, CON-loss at -3/turn with no floor.
- Plague-belt biome without `medical_kit` items: CON-loss at -2/turn with no floor; spreads to adjacent friendly units.
- Scorched-earth (enemy has burned the supply line) without rations: 5 turns to starvation collapse.

Generic distance alone never kills. A swordsmen regiment marched into the wilderness and forgotten will floor at 40 percent and sit there indefinitely, hungry and ineffective but alive.

---

## Per-terrain movement costs

Every unit JSON carries a `terrain_costs` block. The pathfinder consumes it directly. Sample table for footmen (Clansmen, Scout Party on foot, Founder):

| Terrain | Cost |
|---------|------|
| road (proper) | 0.5 |
| dirt_road | 0.65 |
| wagon_track | 0.85 |
| trail | 0.8 |
| grass | 1.0 |
| hills | 1.5 |
| forest_open | 1.5 |
| forest_dense | 2.5 |
| mountain | 3.0 |
| snow | 2.0 |
| tundra | 1.5 |
| desert | 2.5 |
| marsh | 3.0 |
| river_ford | 2.0 |
| river_unfordable | blocked |
| deep_water | blocked |

Cavalry: blocked in marsh, forest_dense ×3.5, road ×0.4, grass ×0.75, hills ×1.5, mountain ×4.0. Scout Party: mountain ×1.5 (the only class that finds mountains easy), forest_dense ×1.75. Pioneer Team with wagons: forest_dense blocked, mountain ×4.0 unless a trail already exists.

The `mc-pathfinding::find_path()` function already accepts a `MovementCostTable` parameter; the table is currently stubbed. Wiring it to per-unit `terrain_costs` blocks is Phase-10 work and the canonical bridge between the JSON data layer and the simulation.

JSON schema sketch:

```json
{
  "unit_id": "swordsmen_regiment",
  "terrain_costs": {
    "grass": 1.0,
    "hills": 1.5,
    "forest_dense": 2.5,
    "mountain": 3.0,
    "marsh": 3.0,
    "river_unfordable": "blocked"
  }
}
```

---

## Modular slots gated by tech × resource

A unit-class JSON declares a `slots` block. Each slot names the (tech, resource) pair that enables it and the carrier or capability it provides when filled.

| Slot | Enabling tech | Enabling resource | Provides |
|------|---------------|-------------------|----------|
| `ox_wagon` | `animal_husbandry` | `cattle` | +2 carry-capacity, fodder consumption |
| `mount` | `animal_training` | `boars` OR `rams` | mounted movement profile |
| `officer_bird` | `falconry_command` | `crag_aerie` | crag-raven carriers |
| `hold_falcon` | `falconry_command` (era 6) | `hold_aerie` | hold-falcon carriers |
| `powder_charges` | `gunpowder` | `saltpeter` + `sulfur` + `coal` | blasting kit |
| `firearm` | `firearms` | `iron` + `coal` | pierce-attack ranged |
| `steam_engine` | `steam_engine` | `coal` + `iron` | mechanized hauling |
| `rune_panel` | `rune_resonance` | `runestone` | resonance-telegraph |

A slot is **enabled** for production in a city if and only if that city has access (via roads or trade) to both the tech and the resource. A slot can be enabled at the empire level but disabled in a specific city — the player sees this in the build-panel as a greyed-out slot with hover-text explaining which side is missing.

A unit's slot-configuration is locked at training. To change it, the player disbands the unit (recovering 50 percent of its production cost) or routes it back to a city with the slot enabled and pays an upgrade fee equal to the slot's marginal cost.

### Build-panel UI sketch

The build-panel for a Pioneer Team in a hypothetical era-5 city shows:

```
Pioneer Team — base cost: 80 production, 12 food, 4 turns
  Slot: ox_wagon ×2          [ENABLED]    +24 production, +6 food
  Slot: foot_runner ×5       [ENABLED]    +5 production
  Slot: crag_raven ×2        [DISABLED]   needs: crag_aerie (no source in range)
  Slot: powder_charges ×40   [ENABLED]    +18 production, requires saltpeter (have)
  -----
  Trained cost: 127 production, 18 food, 5 turns
  Trained roster: 15 dwarves, 2 ox-wagons, 5 foot-runners, 40 powder-charges
  Notes: no crag-ravens — unit will rely on foot-runners for comms
```

---

## Supply caravans and wear-in roads

A Supply Caravan is a unit class whose composition reflects its era. The era-3 Ox Caravan: eight to ten dwarves, four oxen, two or three wagons. Cargo capacity: 300 rations, 150 fodder, 80 water-units, or any mix totaling 530 cargo-units. No combat power — a caravan with no escort that meets enemy units loses its cargo and most of its dwarves.

The player issues an `Establish Supply Route` order, naming origin city and destination unit (or destination outpost). The caravan auto-cycles: loads cargo at origin, walks the pathfinder-selected route to destination, unloads, returns. The cycle continues until the player cancels, the caravan is destroyed, the destination unit is destroyed, or the origin city falls.

### Wear-in

Every tile a wagon-carrying unit traverses increments a hidden `wear_counter`. Caravans are the dominant contributor by volume, because of the cycling, but any wagon-carrying unit contributes.

| Cumulative passes | Tile state | Movement cost multiplier |
|-------------------|------------|--------------------------|
| 1 | `wagon_track` | ×0.85 |
| 5 | `dirt_road` | ×0.65 |
| 15 + pioneer build action | `proper_road` | ×0.5 |

Wear-in does not happen across blocked terrain (a caravan cannot walk through `river_unfordable`) and decays at 1 pass-equivalent per 10 turns of disuse. A road that is not maintained reverts.

### Cutting the line

Three escalating ways to attack supply:

1. **Pillage a road tile** — downgrade `proper_road` to `dirt_road`, `dirt_road` to `wagon_track`, `wagon_track` to plain terrain. Pillage costs the attacker one turn of unit action per tile.
2. **Kill the caravan** — cargo is lost. The route auto-rebuilds from origin if the caravan is replaced, but the forward army goes hungry for the round-trip duration.
3. **Sustained interdiction** — kill three caravans in succession, or hold the chokepoint. The forward army drops to stat-floor and either retreats or starves.

### Caravan progression by era

| Era | Class | Composition | Cargo | Speed |
|-----|-------|-------------|-------|-------|
| 2 | Pack Train | 4 dwarves, 6 pack-mules | 150 | foot-speed |
| 3 | Ox Caravan | 8–10 dwarves, 4 oxen, 2–3 wagons | 530 | wagon-speed |
| 5 | Wagon Convoy | 12 dwarves, 6 oxen, 5 wagons | 1100 | wagon-speed, escort-capable |
| 7 | Steam Wagon | 6 dwarves, 2 steam-rigs | 1800 | rail-speed on `steam_track` |
| 8 | Resonance Cargo Pad | 4 dwarves, paired pad endpoints | 600/turn instant | instant within pad-pair range |
| 9 | Sky-drop | 8 dwarves, 1 airship | 1400 | flight, ignores terrain |
| 10 | Mantle Lift | 6 dwarves, mantle-conduit endpoints | unlimited | instant, geological infrastructure |

Resonance Cargo Pads, Sky-drops, and Mantle Lifts are post-road technologies — they do not lay wear-in. An empire that skips to era 8 supply tech keeps no road network; an empire that built one in era 3 keeps using it as a fallback when the resonance grid is pillaged.

---

## Pioneer tier table

The pioneer line is the spine of the logistics economy. It builds the cities, blazes the trails, and lays the early infrastructure that everything else runs on.

| Tier | Era | Class | Prereqs | Headcount | Default carriers |
|------|-----|-------|---------|-----------|------------------|
| T1 | 1 | Founder | — | 5–8 | 2–3 foot-runners |
| T2 | 2 | Builder | `animal_husbandry` + `cattle` for full slot | 10 | 2 foot-runners, 1 ox-wagon |
| T3 | 3 | Pioneer Team | `pioneer_craft` + cattle + (optional) crag-aerie | 15 | 5 foot-runners, 2 ox-wagons, 2 crag-ravens |
| T4 | 4 | Colonial Pioneer | `colonial_charter` | 16 | as T3 + 1 medical-kit |
| T5 | 5 | Master Pioneer | `gunpowder` + saltpeter | 18 | 6 foot-runners, 3 ox-wagons, 4 crag-ravens, powder-kit |
| T6 | 7 | Steam Pioneer | `steam_engine` + coal + iron | 12 | 4 hold-falcons, 2 steam-wagons |
| T7 | 8 | Resonance Engineer | `rune_resonance` + runestone | 6 | resonance-telegraph pair, 1 wagon |

The line is upgrade-able in-place at an appropriate city: a T3 Pioneer Team in an era-5 city can be upgraded to T5 Master Pioneer for 60 percent of the production-cost delta. This is the only unit line in Game 1 with in-place upgrades — everything else disbands and re-trains.

---

## Cross-references

- Carriers as the comms substrate at eras 1–7: [`military/COMMUNICATIONS.md`](military/COMMUNICATIONS.md)
- Tech-gate definitions surfaced throughout this doc — the full tech list lives in [`TECH_TREE.md`](TECH_TREE.md)
- Resource definitions (`cattle`, `boars`, `rams`, `crag_aerie`, `saltpeter`, `sulfur`, `coal`, `iron`, `runestone`): [`RESOURCES.md`](RESOURCES.md)
- Combat resolution consumes inventory (arrows, powder, medical kits): [`combat/COMBAT_SYSTEM.md`](combat/COMBAT_SYSTEM.md)
- Items equipped to unit rosters: `mc-items` crate documentation (engineering)
- Per-terrain movement cost tables consumed by the pathfinder: `mc-pathfinding` crate, `MovementCostTable`
- Stage plan tracking this surface: [`/var/home/lilith/.claude/plans/wondrous-shimmying-sifakis.md`](../../../../.claude/plans/wondrous-shimmying-sifakis.md)