applications/magicciv
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
magicciv/public/games/age-of-dwarves/docs/UNIT_LOGISTICS.md
autocommit de7a5418e6 docs(docs): 📝 Update technical documentation with game tech tree and unit logistics entries 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-05-26 02:21:13 -07:00

23 KiB
Raw Permalink Blame History

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:

{
  "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