02-units-and-industry.md · 223 requirements

02 — Units and Industry

This document specifies what a unit is as data — the complete attribute schema and the closed capability-flag vocabulary that together let a custom unit set be a JSON file rather than a code change — and the Industry ladder, the per-city rating that decides both how much a city produces and which unit classes it may build. Industry is how this game delivers escalating complexity: rules that no unit exercises are invisible, so controlling when unit classes become available controls the entire complexity curve with no second system. It also specifies the production queue that turns Works into units, the rule that capture degrades Industry — the load-bearing anti-snowball mechanism this document owns — and the full shipped roster of twenty manoeuvre units plus three auxiliaries, with concrete stats, a one-sentence role each, and an explicit statement of every counter relationship. It says nothing about how combat resolves (11-combat.md), where Works and Manpower come from (12-economy.md), how orders are issued (13-command.md), or how terrain costs movement (01-game-rules.md).

Status: Draft v0.2 · Owner: unassigned · Depends on: docs/design/00-direction.md, docs/design/01-decision-turn-model.md, docs/design/units.md, docs/design/economy.md, 01-game-rules.md (terrain, movement, map, fog), 10-turn-model.md (Initiative, activation, Forming Up), 11-combat.md (resolution, modifiers, damage application), 12-economy.md (Works, Manpower, Integration, city classes and traits, supply), 13-command.md (Consignments, Requisitions, Doctrines, Dispatch), 03-architecture.md (determinism, integer arithmetic, canonical hashing)

Replacement notice, binding. This document replaces 02-unit-sets-content.md in its entirety. That file is a transcription of another game's unit tables and is void under docs/design/00-direction.md §2. No value, name, table, or rule carries across, and its US-NNN requirement numbers are not the ones used here. Every cross-document citation of a US-NNN identifier written before this file existed is stale and must be re-resolved against this document. See §16.

Naming note. 13-command.md uses strength where this document uses hits; the two are the same quantity, and CM's "current and maximum strength" are this document's hitsRemaining and hits. 12-economy.md's Works is the build currency this document prices units in; Manpower is the second cost axis. There is no third resource and no per-turn upkeep of any kind (§2.3).


1. Scope, ownership, and the arithmetic contract

US-010 This document MUST be the single normative source for: the unit definition schema; the closed capability-flag vocabulary; unit instance state; the Industry rating and its ladder; the buildable-set test; the production queue and its funding rules; Industry degradation on capture and on strike; and the shipped roster's stat lines.

US-020 This document MUST NOT define: combat resolution, damage application, or combat modifiers (11-combat.md); Works generation, Manpower levy, Integration, Unrest, city classes, city traits, supply states, or garrison requirements (12-economy.md); terrain movement costs, passability, stacking limits, or the coastal test (01-game-rules.md); Initiative computation, activation order, Forming Up, or Stance (10-turn-model.md); order stacks, Postures, Sanctions, Consignments, Requisitions, or the Dispatch (13-command.md); victory conditions (14-victory.md).

US-030 Every quantity defined in this document MUST be an integer. No unit attribute, cost, multiplier, or derived value in this document MAY require Q16.16 fixed-point or floating-point arithmetic. Where a fractional ratio is needed it MUST be expressed per-mille as an integer numerator over an implicit denominator of 1000, and applied as floor(value × permille / 1000).

Rationale: the unit and production layer is the most heavily modded surface in the game and the one most likely to be edited by hand. Restricting it to integers means a custom set cannot introduce a desync through rounding, means every cost and multiplier is exactly what it reads as on the card, and means this whole subsystem needs no fixed-point review. The economy subsystem reached the same conclusion independently for the same reasons.

US-040 Where a chain of per-mille multipliers is applied to one value, each MUST be applied in the order stated by the requirement that introduces it, with a floor after each step. An implementation MUST NOT reassociate, batch, or defer the divisions.

Rationale: floor(floor(a × p / 1000) × q / 1000) and floor(a × p × q / 1000000) differ, and both are defensible. Fixing the order is what makes the result reproducible across implementations, which the canonical hash requires.

US-050 All iteration over unit definitions in the simulation core MUST occur in ascending lexicographic order of unit id. All iteration over a city's production queue MUST occur in queue index order. No engine behaviour MAY depend on the order in which unit definitions were loaded, on hash-map iteration order, or on object identity.

US-060 No code in the simulation core MAY branch on a unit's id, name, or display text. Every behavioural difference between units MUST be expressed through the attributes of §2 and the flag vocabulary of §3. This MUST be enforced by a CI lint over the core package.

Rationale: this is the rule that makes custom unit sets a real feature rather than a promise. A single if (unit.id === 'submarine') in the core is the end of it: from that moment a modder's new unit can never behave like a submarine, and the promise silently becomes a lie. It is mechanically checkable, so it is checked.


2. The unit definition schema

A unit definition is a record in a unit set. It is pure data: integers, enumerated strings, and booleans. The complete schema follows. Every field is listed; there are no optional behaviours hidden behind absent fields except where a field is explicitly nullable.

2.1 Identity and taxonomy

US-070 Every unit definition MUST carry the following identity fields.

Field Type Constraint Meaning
id string matches ^[a-z][a-z0-9_]{1,31}$, unique within its set Stable key. Referenced by saves, replays, and the canonical hash.
setId string matches ^[a-z][a-z0-9_]{1,31}$ The unit set that owns this definition.
name string 1–32 characters Display name.
role string 1–160 characters The unit's one-sentence role (§9).
class enum one of US-090 Taxonomy key for Requisitions, Doctrines, trait discounts and AI evaluation.

US-080 A unit definition's id MUST NOT change across game versions once shipped. Renaming a unit MUST be done by changing name only. Rationale: id appears in every saved game and every replay; changing one silently invalidates every stored game that referenced it.

US-090 class MUST be one of exactly the following eighteen values. This enumeration is closed; adding a value is a schema version change.

recon · infantry · garrison · artillery · armour · engineer · air_defence · fighter · bomber · missile · transport_sea · transport_air · escort · submarine · capital_ship · carrier · administration · logistics

US-100 class MUST be the key by which 13-command.md's Requisition rows (CM-1240), Doctrine defaults (CM-790) and 12-economy.md's class-scoped city-trait discounts select units. No subsystem MAY select units by id for these purposes.

Rationale: a Requisition that names armour keeps working when a mod adds a third tank; a Requisition that names heavy_armour does not. Taxonomy is the seam that lets the command and economy layers be written once against a roster they do not know.

US-110 Every value of the class enumeration MUST be carried by at least one unit in the shipped roster. A CI check MUST fail if any value is unused.

Rationale: an enumeration value no shipped unit exercises is an untested code path that a modder will be the first to discover. If we cannot justify a class with a unit, we do not ship the class.

2.2 Domain, movement and vision

US-120 Every unit definition MUST carry the following movement and detection fields.

Field Type Range Meaning
domain enum land · sea · air Which tiles the unit may occupy. 01-game-rules.md owns passability.
terrainClass enum foot · wheeled · tracked · naval · air Index into the terrain movement-cost table owned by 01-game-rules.md.
draft int 0–3 Sea only. Minimum water depth class the unit may enter. 0 for non-sea units.
move int 0–32 Movement points per turn.
vision int 0–12 Sight radius in tiles against surface units and terrain.
visionAir int 0–16 Sight radius against units with domain = air.
endurance int 0–8 Air only. Turns the unit may spend away from a base before it is lost. 0 for non-air units.
zoc bool Whether the unit exerts a zone of control on adjacent tiles.
mayOccupyCity bool Whether the unit may end movement inside a friendly city.

US-130 terrainClass MUST be consistent with domain: a land unit MUST use foot, wheeled or tracked; a sea unit MUST use naval; an air unit MUST use air. A CI check MUST enforce this.

US-140 visionAir MUST be greater than or equal to vision for every unit. Rationale: an aircraft is visible against the sky from further away than a tank is visible against a hillside. A unit that saw aircraft less well than it saw ground would need a story nobody has, and permitting it invites a modder to build an accidental blind spot.

US-150 draft MUST be non-zero if and only if domain = sea. A sea unit MUST NOT enter a water tile whose depth class is lower than its draft. Depth classes and their map representation are owned by 01-game-rules.md.

US-160 move MAY be zero. A unit with move = 0 MUST still activate, and MAY act (attack, bombard, build, repair) from the tile it occupies.

US-170 The three movement classes foot, wheeled and tracked MUST each be carried by at least one shipped land unit, and their terrain cost profiles MUST differ from one another in at least three terrain types. Rationale: three land movement classes that behave nearly alike are two classes of confusion for no strategic return. The distinction has to be visible in play or it should not exist.

2.3 Cost

US-180 Every unit definition MUST carry the following cost fields.

Field Type Range Meaning
worksCost int 1–9999 Works consumed to complete one unit.
manpowerCost int 0–999 Manpower consumed at completion.
costEscalationPerOwnedPerMille int 0–2000 Per-mille increase in both costs per unit of this class the ordering player already owns or has in production.

US-190 A unit's price at the moment an order is enqueued MUST be computed as:

n            = count of units of this class the player owns or has in production
escalation   = 1000 + n × costEscalationPerOwnedPerMille
worksPrice   = floor(worksCost    × escalation / 1000)
manpowerPrice= floor(manpowerCost × escalation / 1000)

Any city-trait discount owned by 12-economy.md MUST then be applied to worksPrice and manpowerPrice, each as a per-mille multiplier with a floor, in ascending lexicographic order of trait name where a city carries more than one applicable trait.

US-200 The price computed by US-190 MUST be stored on the production order at the moment it is enqueued and MUST NOT be recomputed while that order remains in the queue.

Rationale: an escalating price that rises while you are paying it is a moving goalpost, and the player cannot plan against it. Fixing the price at enqueue time means the queue you see is the queue you get, and it makes the escalation a decision about when to commit rather than a punishment for committing slowly.

US-210 There MUST NOT be any per-turn upkeep, maintenance, drain, or efficiency penalty charged against a unit for existing, and no production rate in this game MAY be a function of a player's total unit count.

Rationale: this is the direction brief's named weakness (§6, "opaque anti-snowball economics") and it is refused outright. A unit is paid for once, at commissioning, in two visible currencies. The brakes on growth are Industry degradation on capture (§6), the escalating price of administration (12-economy.md), integration time, and supply geography — every one of them a thing the player can see, price, and plan around. A hidden tax on having an army punishes the exact behaviour the game is about.

US-220 costEscalationPerOwnedPerMille MUST be zero for every unit of a combat, transport or engineering class. It MAY be non-zero only for classes whose scarcity is itself a designed brake.

2.4 Combat attributes

US-230 Every unit definition MUST carry the following combat fields. All are whole points; §11 governs their conversion for combat resolution.

Field Type Range Meaning
hits int 1–40 Damage the unit absorbs before destruction.
atkLand int 0–40 Attack strength against a defender in the land domain.
atkSea int 0–40 Attack strength against a defender in the sea domain.
atkAir int 0–40 Attack strength against a defender in the air domain.
def int 0–40 Defence strength against every attacker, in every domain.
flak int 0–40 Return-fire strength against attackers in the air domain only.
strikeRun int 0–12 Maximum combat rounds before the unit disengages. 0 means no limit.
initiativeBase int 0–100 The unit's class base term in the Initiative score owned by 10-turn-model.md.

US-240 An atk* value of 0 MUST mean the unit cannot initiate combat against a defender in that domain at all. It MUST NOT be treated as a very weak attack.

Rationale: three attack numbers instead of a per-unit target matrix is the load-bearing simplification of the whole roster. It puts every counter relationship in three integers a player reads off a card, it is trivially data-driven, and "this thing cannot touch that thing" becomes a zero in a column rather than a rule in a manual. That only works if zero is absolute.

US-250 def MUST be a single value applied against attackers from every domain. There MUST NOT be a per-domain defence vector.

Rationale: a full attack-by-defence matrix is four times the tuning burden for texture the three attack values already provide, and it is unreadable on a unit card. Asymmetry between "hard to hit from the air" and "hard to hit on the ground" is expressed by flak and by highAltitude, which are two numbers a player can hold rather than nine.

US-260 flak MUST apply only against attackers whose domain is air, MUST resolve before the attacker's own strike, and MUST NOT apply when the unit is itself the attacker. 11-combat.md owns the resolution procedure.

Rationale: making anti-air a property of units rather than a unit class is what lets a destroyer be naturally dangerous to aircraft with no code that knows what a destroyer is — and it means the entire anti-air rules surface is dormant, and invisible, in a game where nobody has built an aircraft. That is the escalation thesis working with no extra machinery.

US-270 strikeRun MUST limit the number of resolution rounds only when the defender's domain is land or sea. An engagement in which both participants have domain = air MUST resolve without a round limit.

Rationale: aircraft break off from ground targets because a strike is a pass, not a siege; aircraft cannot break off from each other, because the other aeroplane is also fast. Mechanically this is what makes air superiority decisive rather than attritional: fighters that meet bombers finish the job, so contesting the sky is a real commitment and losing it is a real loss. Without this rule a fighter needs four sorties to down one bomber and air combat degenerates into mutual pecking.

US-280 initiativeBase MUST be the only unit-definition input to Initiative. 10-turn-model.md owns every other term and owns the formula. Creation sequence MUST remain the tiebreak that makes the activation order total.

US-290 initiativeBase values MUST be assigned to express when in a battle a unit commits, not how fast it moves: reconnaissance and prepared fires open, lift and screening forces position, exploitation forces follow, assault infantry and engineers go in last.

Rationale: this is not decoration — it is what makes combined arms possible inside a single turn. Artillery must activate before the infantry it is supporting, or the bombardment lands after the assault and the game's most interesting mechanic cannot be executed at all. Ordering by speed would put the guns last and quietly break it. Ordering by commitment sequence puts the guns at 72–74 and the infantry at 32, which is exactly the ordering an operation needs.

2.5 Transport

US-300 Every unit definition MUST carry the following transport fields.

Field Type Range Meaning
slots int 0–8 Slots this unit consumes as cargo. 0 means it cannot be carried.
capacity int 0–16 Slots this unit provides to cargo. 0 means it carries nothing.
carryDomains set of enum subset of {land, sea, air} Which cargo domains it accepts. Empty if capacity = 0.
carryMaxSlots int 0–8 Largest single cargo item it accepts, by slots. 0 if capacity = 0.

US-310 A unit MAY be loaded onto a carrier if and only if all of: the carrier's capacity minus its currently used slots is at least the cargo's slots; the cargo's domain is in the carrier's carryDomains; the cargo's slots is at most the carrier's carryMaxSlots; and the cargo's slots is non-zero.

US-320 Cargo MUST NOT count toward any tile stacking limit owned by 01-game-rules.md; only the carrier occupies the tile.

US-330 Cargo MUST NOT contribute flak, vision, zoc, or any defensive value to its carrier, and MUST NOT be attacked independently of it.

Rationale: cargo that fights from inside the hold turns every transport into a warship and removes the entire reason escorts exist. The one exception is assaultLanding (US-560), which is a purchased capability on one hull rather than a general rule.

US-340 A carrier MUST NOT be loaded as cargo onto another carrier. Nested transport MUST be rejected at order time.

2.6 Build requirements

US-350 Every unit definition MUST carry a buildRequirements record with the following fields.

Field Type Range Meaning
minIndustry int 1–4 Minimum city Industry (§5).
requiresCoastal bool The producing city must be coastal for this unit's terrainClass.
requiresTraits set of string 0–3 entries City traits (12-economy.md) the producing city must carry.
minCityClass enum any · town · city · metropolis Minimum city class.
minIntegration int 0–100 Minimum city Integration (12-economy.md).

US-360 A unit definition U MUST be buildable in city C by player P if and only if all of:

  1. U.buildRequirements.minIndustry ≤ min(C.industry, P.industryCap)
  2. requiresCoastal is false, or C is coastal for U.terrainClass per 01-game-rules.md
  3. every trait in requiresTraits is present on C
  4. C's class is at least minCityClass
  5. C's Integration is at least minIntegration
  6. U.setId is the unit set in force for this game

US-370 Every clause of US-360 MUST be evaluated identically for AI seats and for human seats, and the failing clause MUST be reportable to the client so a greyed-out build option can state why it is greyed out in one sentence.

Rationale: a disabled button with no explanation is the single most common way a strategy game teaches a player that it is arbitrary. Six clauses is a small enough set that the reason is always one short sentence.

2.7 Capability parameters

US-380 Every unit definition MUST carry the following parameterised capability fields. A value of 0 means the capability is absent.

Field Type Range Meaning
bombardRange int 0–6 Indirect-fire range in tiles (§3.3).
bombardShots int 0–6 Indirect-fire rounds resolved per bombardment.
interceptZone int 0–4 Radius within which hostile air ending movement is engaged automatically.
cityStrike int 0–2 Severity of works strikes this unit may make (§6.4).
repairAdjacent int 0–4 Hits per turn restored to an adjacent friendly unit.
repairEmbarked int 0–4 Hits per turn restored to units carried as cargo.
buildables set of enum subset of {road, airfield, fort, bridge} Terrain constructions this unit may make. 01-game-rules.md owns their effects.
commandRating int or null 1–24 or null Optional command span override for 13-command.md (CM-2170). Null in the shipped roster.

US-390 bombardRange and bombardShots MUST both be non-zero or both be zero. A unit with non-zero bombardShots MUST have a non-zero atkLand.

US-400 commandRating MUST be permitted to be null, and MUST be null for every unit in the shipped roster. Where it is null, the default command span of 13-command.md applies unchanged.

Rationale: the field exists because 13-command.md asked for it and a custom set may want a headquarters unit. Shipping it null everywhere is honest: we are not shipping a headquarters unit, and pretending otherwise would put an untested code path in the core.

2.8 Unit instance state

A unit definition is shared and immutable. A unit instance on the map carries the mutable state below. This is authoritative game state and contributes to the canonical hash.

US-410 Every unit instance MUST carry: defId (the definition id), owner, sequence (the monotonically increasing global creation number, owned by 10-turn-model.md as the Initiative tiebreak), tile, hitsRemaining, enduranceRemaining, cargo (ordered list of carried instance references), carriedBy (instance reference or null), movePointsRemaining, and veterancy.

US-420 hitsRemaining MUST persist across turns. Damage MUST NOT reset at turn boundaries and MUST be removed only by the repair rules of §14.

Rationale: persistent damage is what makes a unit a formation with a history rather than a token that is either alive or not. It creates the repair economy, gives withdrawal a purpose, makes a costly victory genuinely costly, and gives the Engineer and the Carrier something to do. It is also the reason the direction brief's complaint about flat attrition combat has an answer: outcomes are graded, not binary.

US-430 hitsRemaining MUST be in [0, definition.hits]. A unit reaching hitsRemaining = 0 MUST be removed from the map. 11-combat.md owns when and how hits are lost.

US-440 veterancy MUST be an integer in [0, 3] stored on the instance. This document defines the field and its range only; 10-turn-model.md owns how veterancy is earned and what it modifies, and 11-combat.md owns any combat effect. No requirement in this document MAY read veterancy.

Rationale: the design left veterancy deliberately undesigned because seniority in the activation order already gives old units an advantage and two "experience matters" systems fight each other. That is a turn-model decision, not a unit-data decision. What the unit layer owes is the field, its range, and the guarantee that it is hashed — so that whichever way the turn model settles it, no save format changes.

US-450 enduranceRemaining MUST be in [0, definition.endurance] and MUST be maintained per §14.3.

US-460 A unit's instance state MUST be fully serialisable as integers and references, with no derived caches that are not recomputable from it. The canonical hash MUST cover every field named in US-410.


3. The capability flag vocabulary

Flags are booleans. Together with the parameterised fields of §2.7 they are the complete and closed vocabulary of unit behaviour. There is no scripting hook in a unit set.

US-470 The set of capability flags MUST be exactly the eighteen values enumerated in §3.1–§3.5. A unit set MUST NOT introduce a flag, and the core MUST reject a set that names an unknown flag rather than ignoring it.

US-480 Every flag in the vocabulary MUST be carried by at least one unit in the shipped roster. A CI check MUST fail if any flag is unused.

Rationale: a reserved flag that nothing uses is an untested branch with a promise attached. The design proposal carried one (clearMines, explicitly used by no unit) and it is cut here for exactly this reason. If a capability is worth a code path it is worth a shipped unit that exercises it; if no shipped unit wants it, the capability is speculative and belongs in the WASM plugin escape hatch, not in the closed vocabulary.

US-490 Three flags — reactiveOnly, garrisonOnly and expendable — MUST be classified as restrictive. A restrictive flag narrows what a unit may do and MUST be treated as a disadvantage by the non-domination test of §10, never as a capability.

Rationale: without this classification the domination test reads a restriction as a feature and concludes that a unit which may not attack, may not move, or dies after one use is superior to one that may do all three. The Militia and the Missile are both cheap enough that the test would otherwise flag them as dominating units they are plainly worse than.

3.1 Ground and capture

Flag Meaning
capture The unit may take an enemy or neutral city by entering its tile.
entrench The unit gains the stationary defence bonus owned by 11-combat.md after a turn in which it did not move.
garrisonOnly Restrictive. The unit may never leave the tile of the city that produced it.
reactiveOnly Restrictive. The unit may never initiate an attack on its own activation. It fights only when attacked and through interceptZone.

US-500 Only a unit with capture MAY change a city's ownership. Cargo MUST NOT capture while carried; it MUST be unloaded onto the city tile first, except under assaultLanding (US-560).

US-510 entrench MUST be carried only by units whose terrainClass is foot or wheeled. Rationale: digging in is what dismounted troops and towed crews do. A tank that entrenches is a tank that has stopped being a tank, and giving tracked units the bonus erases the whole reason infantry is the answer to a dug-in line.

US-520 A unit with garrisonOnly MUST NOT be given a March, Screen, Survey or Attach Posture, and MUST NOT be loaded as cargo. It MUST remain eligible to defend, to entrench, and to count toward 12-economy.md's garrison requirement.

US-530 A unit with reactiveOnly MUST still activate in the Cascade, MUST be able to move, and MUST resolve interceptZone engagements and defensive flak normally.

3.2 Transport and delivery

Flag Meaning
cargoLost Destruction of this unit destroys all cargo aboard it.
assaultLanding Cargo may attack directly from aboard this unit, at the attacker penalty owned by 11-combat.md.
airdrop Cargo may be unloaded onto an unoccupied land tile that contains no enemy unit and no enemy or neutral city.
airbase Embarked air units' enduranceRemaining is reset to full each turn they end aboard.

US-540 Every unit with capacity > 0 MUST carry cargoLost. Rationale: cargo that survives its sinking transport removes every consequence from losing the escort battle, and the whole point of a convoy is that the convoy can be lost. There is no design in which a transport is worth risking if the cargo swims home.

US-550 A unit with airdrop MUST NOT permit a drop that captures a city. Capture MUST remain a movement outcome only.

Rationale: an air-dropped capture is a one-turn, zero-warning loss of a rear city with no approach a defender could have watched. Requiring the dropped unit to survive a turn on the ground before it can walk in gives the defender exactly one turn to react, which is the difference between a raid and a gotcha.

US-560 A unit with assaultLanding MUST permit its cargo to attack an adjacent land tile from aboard, without unloading, during the cargo's own activation. The carrier MUST have completed its own activation for that turn, which US-290's initiative assignment guarantees by giving lift units a higher initiativeBase than the assault troops they carry.

US-570 A unit with airbase MUST reset the enduranceRemaining of every air unit that ends its activation aboard, and MUST apply repairEmbarked to them per §14.

US-580 An air unit MAY launch from a carrier that has not yet activated this turn, using the carrier's current tile. Rationale: without this, a carrier's air wing is hostage to the carrier's initiative and the whole hull becomes unusable in the turn it repositions — a 510-Works capability purchase that only works every other turn is not a capability, it is a bug with a price tag.

3.3 Fire support

Flag Meaning
siege Bombard effect is doubled against defenders inside cities and forts.
ambush The first round of an engagement this unit initiates is one-sided; the defender cannot score.

US-590 A unit with non-zero bombardShots MAY, in place of all other action on its activation, resolve bombardShots single combat rounds against one target within bombardRange, using atkLand against the target's def. The bombarding unit MUST NOT take damage from the exchange.

US-600 Bombardment MUST target a tile whose occupant's domain is land. A bombarding unit MUST NOT bombard sea or air targets regardless of its atkSea or atkAir values.

Rationale: indirect fire against a manoeuvring ship or an aeroplane is a different weapon system with different physics, and modelling it here would make every gun a universal answer. Naval gunfire support is the same mechanism pointed at the shore, which is why the warships carry bombardRange rather than a separate flag.

US-610 Bombardment MUST NOT reduce a target below hitsRemaining = 1, MUST ignore the entrenchment modifier when computing the target's defence, and MUST apply the Suppressed condition on any round that scores. 11-combat.md owns the Suppressed condition and the entrenchment modifier.

Rationale: three properties, each doing one job. Artillery cannot take ground, so it never replaces infantry and never wins a game on its own. It ignores entrenchment because un-digging a dug-in defender is precisely what artillery is for. It suppresses because that is the lever that turns a hopeless frontal assault into a viable operation — see the worked example in §12.3, where 52 Works of guns move an assault from a 7.7% proposition to a 49.2% one. That single number is the answer to the direction brief's complaint that flat attrition combat has no tactical texture.

US-620 A unit that bombards MUST NOT move, attack, build or repair in the same activation.

US-630 ambush MUST apply only when the unit initiates the engagement, and MUST NOT apply if the defender detected the unit at the start of the current turn.

3.4 Detection and concealment

Flag Meaning
submerged Invisible to all enemies except sonar units within their vision and units on an adjacent tile.
sonar Detects submerged units within vision.
highAltitude May be engaged only by units with intercept, or by units with flak ≥ 6.
intercept May engage air units passing through the unit's visionAir during their movement.

US-640 A submerged unit MUST be excluded from the knowledge view of every enemy player except where detected per §3.4. Detection MUST be recomputed at the start of each activation, not cached across the Cascade.

US-650 A submerged unit that initiates an attack MUST lose concealment for the remainder of the turn.

US-660 highAltitude MUST exclude every unit with flak < 6 and without intercept from engaging the unit at all — not merely reduce their odds.

Rationale: this is the sharpest tech gap the design permits, and it is deliberate. An Industry-2 army facing a Heavy Bomber has exactly one answer, and that is the pressure that makes refusing to climb the ladder cost something. It is a hard edge and it will feel bad the first time; the mitigations are that the encyclopedia shows it from turn one (§7), that the counter (Fighter) is available two tiers earlier and cheaper, and that a Destroyer screen already provides flak 6.

3.5 Special

Flag Meaning
expendable The unit is destroyed after resolving one attack, whatever the outcome.
administrator The unit drives Integration in the city whose tile it occupies. 12-economy.md owns the rate.
emplace The unit converts, over one full turn, into an immobile installation on its tile.
supplySource Once emplaced, the unit projects supply Reach. 12-economy.md owns propagation and range.

US-670 An expendable unit MUST be removed at the end of the combat it initiates, before any repair or end-of-turn processing, regardless of its hitsRemaining.

US-680 A unit with emplace MUST become immobile permanently once emplaced, MUST NOT be loaded as cargo thereafter, and MUST remain destroyable by normal combat.

US-690 administrator and supplySource MUST be inert in this document. Their entire behavioural definition belongs to 12-economy.md; this document owns only the flag, the stat line of the unit that carries it, and its place in the production queue.


4. Unit set validation

US-700 A unit set MUST be a JSON document containing a set identifier, a schema version, and an array of unit definitions. It MUST NOT contain executable code, expressions, or references to external files.

US-710 The core MUST validate a unit set at load and MUST reject the whole set — never partially load it — if any check in US-720 through US-790 fails.

US-720 Schema. Every field of §2 MUST be present, of the declared type, and within the declared range. Unknown fields MUST be rejected, not ignored.

Rationale: silently ignoring an unknown field is how a modder spends an afternoon wondering why stealth: true does nothing. Rejecting it with the field name and the line number is one error message and saves the afternoon.

US-730 Referential integrity. Every id MUST be unique within the set; every trait named in requiresTraits MUST exist in the trait vocabulary owned by 12-economy.md; every value in buildables MUST be in the construction vocabulary owned by 01-game-rules.md.

US-740 Consistency. Every cross-field constraint stated in §2 and §3 MUST hold: US-130, US-140, US-150, US-310, US-390, US-510, US-540.

US-750 Reachability. For every unit in the set there MUST exist at least one combination of city class, trait set, Industry level and Integration reachable in a standard game that satisfies its buildRequirements. A unit that can never be built MUST be a load error.

Rationale: an unbuildable unit is not a balance problem, it is a typo, and it will be discovered in turn 80 of someone's game rather than at load.

US-760 Flag and class coverage. The shipped set MUST exercise every flag (US-480) and every class (US-110). A custom set MUST NOT be required to.

US-770 Non-domination. The shipped set MUST contain no strictly dominated unit as defined in §10. A custom set failing this check MUST load with a warning naming the dominated unit and its dominator, not an error.

Rationale: we hold ourselves to a standard we do not impose on modders. Someone deliberately building a joke set, a historical set with obsolete equipment, or a teaching set with a strictly-worse trainer unit has a legitimate reason, and refusing to load it would be paternalistic. Warning is the right strength.

US-780 Build-time band. Every unit in the shipped set whose class is not administration, garrison or logistics MUST complete in 3 to 11 turns inclusive at the reference producer of US-1290. A custom set MUST NOT be required to.

US-790 Power ceiling. Every unit in the shipped set MUST satisfy the tier power ceiling of US-1310. A custom set MUST NOT be required to.

US-800 The validator MUST be a pure function of the set document, MUST produce identical diagnostics on every platform, and MUST report every failure in one pass rather than stopping at the first.


5. The Industry ladder

5.1 What Industry is

US-810 Every city MUST carry an integer Industry rating in [1, 4]. Industry MUST determine exactly two things and nothing else: the multiplier applied to the city's Works output (US-840), and which unit definitions the city may build (US-360).

US-820 The four Industry levels MUST be named and MUST have the following properties.

Industry Name Works multiplier Upgrade cost to reach (Works) Manpower What it unlocks
1 Depot ×1000‰ — (every city starts here) 5 manoeuvre units + 3 auxiliaries
2 Workshop ×1750‰ 90 0 +3 units: armour, fleet escorts, the sky
3 Foundry ×2750‰ 180 0 +6 units: concealment, strategic air, engineering, amphibious assault, air defence
4 Arsenal ×4000‰ 360 0 +6 units: fleet-scale power and strategic reach

US-830 Industry MUST be a per-city property. There MUST NOT be an empire-wide technology level, research points, research, or a technology tree of any kind.

Rationale: per-city Industry gives the map an industrial geography, and that geography is worth more than it costs. Frontier towns become cheap infantry mills; the one Arsenal on the safe coast is where carriers come from. There is now a reason to raid two hundred tiles behind the line and a reason to garrison a city nowhere near the front. It is legible in vocabulary players already have — "that city has a shipyard, this one doesn't" needs no tutorial — and it stops a single lucky capture from unlocking the whole game. The cost is a doubled management surface, and §7 and 13-command.md's Templates are the answer to that.

US-840 A city's effective Works per turn MUST be computed as floor(W × m / 1000), where W is the Integration-scaled effective Works owned by 12-economy.md and m is the Industry multiplier of US-820.

US-850 The Industry multiplier MUST apply to Works only. It MUST NOT affect Manpower levy, Population, Reach, Integration, Unrest, or garrison requirement.

Rationale: this asymmetry is doing more work than it looks like. A city's people do not multiply because you built a foundry, so climbing the ladder shifts a player from a manpower-bound economy toward a works-bound one — and the units that cost Works rather than people are precisely the mechanised, naval and air units the higher tiers unlock. The ladder therefore pays for itself in exactly the currency it generates. It also means the fast conqueror, whose captured cities yield Works immediately and Manpower never quite in time, is pushed toward Industry upgrades and mechanised forces, which is the same conclusion 12-economy.md reaches from the other direction. Two subsystems agreeing without coordination is the strongest evidence available that the shape is right.

US-860 Industry upgrades MUST cost zero Manpower.

Rationale: it is the escape valve. A player starved of people can always still invest, so a manpower crisis is a change of strategy rather than a dead end. A manpower cost here would close the only door left to a blitzer and turn the anti-snowball design into a death spiral.

5.2 Worked output and payback

US-870 The reference producer for all output statements in this document MUST be an untraited City-class city at Integration 100. Its effective Works per turn by Industry MUST be:

City class Base Works Ind 1 Ind 2 Ind 3 Ind 4
Town 6 6 10 16 24
City (reference) 12 12 21 33 48
Metropolis 20 20 35 55 80

US-880 The flat upgrade costs of US-820 MUST NOT be scaled by city class.

Rationale: flat costs mean a Metropolis pays back its Workshop in 6 turns, a City in 10, and a Town in 23. That is the industrial geography made of arithmetic rather than assertion: big cities become the industrial core because upgrading them is obviously correct, small ones stay cheap infantry mills because upgrading them obviously is not, and the player derives the map's economic shape themselves instead of being told it. Scaling the cost by class would flatten every city into the same decision and delete the geography.

US-890 Payback periods for the first upgrade, stated as a normative tuning fact:

City class Works/turn gained Upgrade cost Payback (turns)
Town +4 90 23
City +9 90 10
Metropolis +15 90 6

5.3 The player Industry cap

US-900 Every player MUST carry an integer Industry cap in [1, 4], set at game setup (§13) and constant thereafter unless a scenario changes it.

US-910 The Industry cap MUST gate two things: the maximum Industry to which that player may upgrade a city, and the buildable set per US-360 clause 1.

US-920 The Industry cap MUST NOT alter the Industry value of a city the player holds. A player with cap 2 who captures an Industry-4 city MUST retain that city at Industry 4, MUST receive its full Works multiplier, and MUST NOT be able to build units above minIndustry 2 in it.

Rationale: the cap exists for mixed-skill play, where it is a handicap on roster complexity — how much machinery a player is asked to run. It is not a handicap on production. Demolishing a captured factory to enforce a complexity setting would be an ugly, unexplainable event on the map, and would make the handicap punish conquest rather than limit depth. Giving the capped player the Works but not the toys is exactly the intended shape: a veteran capped at 2 is playing a genuinely harder game and is not being taxed for winning fights.

5.4 Progressive disclosure

US-930 The unit encyclopedia MUST be complete from turn one. Every unit's stat line, flags, role sentence, and counter relationships MUST be inspectable by every player at every point in the game, regardless of Industry, of what they have built, and of what they have seen.

Rationale: there is fog over the map, not over the rules. A player who is out-teched should be beaten by tempo and by having made worse decisions, never by not knowing what the thing that killed them was. Hiding stats converts a strategy game into a memory test that only rewards previous play, which is the opposite of the escalation this ladder is for.

US-940 Before spending any Works, a player MUST be able to inspect the full unlock set of any Industry level in any city they own, together with that upgrade's cost and its Works gain for that specific city.

US-950 On the turn a city's Industry upgrade completes, the client MUST present one unlock card per newly available unit, each containing: the unit's name, its role sentence, its full stat line, the two units it counters, and the two units that counter it (§9).

US-960 The first time a player observes an enemy unit of a class they have never produced, the client MUST present that unit's card unprompted — a contact briefing.

Rationale: the real hole in an in-game complexity ladder is that you can meet a unit class before you can build one. The briefing closes it. It costs one card, it fires at most twenty times per game, and it arrives at the single moment the player most wants to read it — which is also the moment the information sticks.

US-970 A city's Industry MUST be visible to any player with current vision on that city, and its last observed value MUST be retained in that player's knowledge view with its observation age.

Rationale: scouting industry becomes a genuine objective. An enemy Arsenal is worth a two-hundred-tile raid, and a player cannot plan that raid against a number they cannot see.


6. Capture, degradation, and works strikes

This section owns the single most important balancing rule in the unit and production layer.

6.1 Degradation on capture

US-980 When a city changes ownership, its Industry MUST be reduced by 1, to a minimum of 1 — unless the receiving player's recorded Industry memory for that city (US-1000) is greater than or equal to the city's Industry immediately before the transfer, in which case Industry MUST be unchanged.

US-990 Degradation MUST apply on every ownership change, including capture from a neutral holder and including a city changing hands twice in the same turn. Only one degradation MUST be applied per ownership change.

US-1000 Every city MUST record, per player, an Industry memory: the highest Industry that player ever held that city at. It MUST be updated at the end of every round in which the player holds the city, and MUST never decrease.

Rationale for the whole rule: without degradation, conquest of a developed empire is a jackpot and the game snowballs on capture rather than on production. Taking an Arsenal gets you a Foundry and a bill for 360 Works, which turns conquering an industrial core from a windfall into an investment — you still have to rebuild it — and makes defending yours proportionally more valuable than defending a frontier town.

Rationale for the memory exemption: the drop models the workforce and the management leaving, not the buildings burning. That is why it does not apply to a city's own government walking back in, and it is why an Engineer conducting the capture would not help either. It also means this rule and 12-economy.md's Loyalty memory share one mental model — your own ground comes back whole; someone else's does not — so a player learns one idea and gets two systems. And it stops the failure the naive rule produces: a border city changing hands eight times ratcheting to Industry 1 and becoming worthless to everybody, which is a spiral where both players lose and neither chose it.

US-1010 On any ownership change the city's Yard (§7.2) MUST be set to zero and its production queue MUST be emptied, unconditionally and including for the original owner retaking it.

Rationale: the Yard is materials on the shop floor and the queue is somebody else's plan. Neither survives a change of government. Making the Yard survive for the original owner would be a third special case for a small gain and would let a defender bank production inside a city they expect to lose and retake.

US-1020 Units already produced MUST be unaffected by degradation. A Cruiser built in an Arsenal MUST NOT be weakened, removed, or made unrepairable because the city that built it dropped to Foundry.

US-1030 After a transfer the city MUST adopt the receiving player's standing production for its class and traits, per 13-command.md's Consignment rules, and MUST NOT require player input to become productive.

6.2 Queue behaviour when Industry drops

US-1040 When a city's Industry falls below the minIndustry of an order already in its queue, that order MUST become Stalled. It MUST retain its position and its stored price, MUST NOT be cancelled, and MUST NOT consume Works.

US-1050 A Stalled order MUST be skipped for funding purposes; the queue MUST fund the first order that is not Stalled (§7.3). The Yard MUST NOT be lost.

Rationale: this is the design proposal's open question 8 and the answer is paused. Losing a half-built Cruiser to the strike that dropped the Industry, and then losing the accumulated Works as well, is a compounding punishment for one event — and compounding punishments are how a player learns that a mechanic is unfair rather than that it is dangerous.

US-1060 A city containing a Stalled order MUST raise a ProductionStalled condition for the Dispatch of 13-command.md, every turn, until the order is buildable or removed.

6.3 Rebuilding after degradation

US-1070 An Industry level lost to a works strike (§6.4) MUST be restorable at half the upgrade cost of US-820, rounded down, for 30 turns from the strike. After 30 turns the full cost applies.

Rationale: a bombed factory is damaged, not erased. Without this, 396 Works of Heavy Bomber permanently destroys 360 Works of upgrade every time it succeeds, and strategic bombing becomes a one-way ratchet that reduces every contested map to Industry 1. With it, bombing is a tempo and denial weapon — it costs the target time and Works and forces a decision — which is exactly the "attack their curve rather than their units" role the design wants, without the erasure.

US-1080 An Industry level lost to capture MUST NOT be eligible for the half-cost restoration of US-1070. The full upgrade cost applies.

Rationale: the two cases are different events and should price differently. Bombing damages plant you still hold; capture means the people who ran it are gone. Making conquest the expensive one is the anti-snowball rule doing its job.

6.4 Works strikes

US-1090 A unit with cityStrike ≥ 1 MAY, in place of attacking a unit, declare a works strike against an enemy city it could otherwise attack.

US-1100 A works strike MUST resolve strikeRun rounds against the city, using the striking unit's atkLand as the attack value and a works defence computed as:

worksDefence = 2000
             + 500 × (count of units in the city with flak ≥ 1)
             + 1000 if the city tile carries a fort

Each round that scores MUST accumulate one works hit. 11-combat.md owns the per-round procedure and the flak exchange that precedes the strike.

US-1110 Works hits accumulated in a single strike MUST have the following effects, applied once at the end of the strike.

Works hits Effect
0 None.
1 Yard reduced to floor(Yard / 2).
2 Yard reduced to 0.
3 or more Yard reduced to 0, and if the striking unit's cityStrike ≥ 2, Industry reduced by 1 (minimum 1).

US-1120 A city MUST NOT lose more than one Industry level to works strikes in any five-turn window, regardless of how many strikes it receives.

Rationale: without a floor on the rate, a coordinated flight of four Heavy Bombers erases an Arsenal to a Depot in one turn, which is a three-tier loss the defender could neither see coming nor answer. One level per five turns makes strategic bombing a campaign that the defender can respond to — with fighters, with an Air Defence Battery, with a fort, or by moving production — rather than a decapitation.

US-1130 A works strike MUST NOT reduce Industry below 1, MUST NOT change city ownership, MUST NOT damage units in the city, and MUST NOT affect Integration, Unrest, or Population.

US-1140 A works strike against a city the striking player cannot currently see MUST be a legal order and MUST resolve normally against the true city state.

Rationale: strategic bombing at range is precisely the case where you are shooting at your last-known intelligence. Requiring current vision would make the Heavy Bomber's whole reason for existing — reach beyond the front — unusable, and it would require a scouting apparatus for every strike that neither the roster nor the command layer offers.


7. The production queue

7.1 Orders

US-1150 Every city MUST carry a production queue: an ordered list of at most 8 orders, plus an optional repeating tail owned by 13-command.md's Templates and Requisitions.

US-1160 A production order MUST be one of exactly three kinds.

Kind Payload Owner of its effect
unit a unit definition id this document
industry none — upgrades the city by one Industry level this document
works a civic improvement key 12-economy.md

US-1170 Every order MUST store, at enqueue time: its kind, its payload, its worksPrice, its manpowerPrice, and the turn it was enqueued.

US-1180 A city MUST NOT hold more than one industry order in its queue at a time.

US-1190 An industry order MUST be ineligible, and therefore Stalled, whenever the city's Industry is already equal to min(4, owner's Industry cap).

US-1200 Removing an order from the queue MUST be free and MUST NOT alter the Yard.

Rationale: because progress accumulates in a single per-city Yard rather than against an individual order (§7.2), there is nothing to refund and no cancellation penalty to design. A player may reorder and re-plan freely, which is the correct amount of friction for a decision they will make hundreds of times.

US-1210 An order that has begun funding MUST NOT be cancelled, retargeted, or reordered by any automated system, only by explicit player action. This satisfies the obligation 13-command.md places on the production layer (CM-1270).

7.2 The Yard

US-1220 Every city MUST carry a single integer Yard, its accumulated unspent Works. The Yard MUST NOT be partitioned per order.

US-1230 At the top of each round, after 12-economy.md has computed the city's effective Works and this document has applied the Industry multiplier (US-840), that amount MUST be added to the Yard.

US-1240 The Yard MUST be capped at the worksPrice of the city's head eligible order. Where the queue contains no eligible order, the Yard MUST be capped at one turn of the city's effective Works. Works accrued above the cap MUST be discarded, and the city MUST raise a ProductionOverflow condition for the Dispatch on any turn discarding occurs.

Rationale: the cap is what stops a player banking forty turns of a quiet city's output and materialising a Cruiser the turn after they capture a port. Tying it to the head order's price means it never obstructs an honest long build — queue the Cruiser and you may bank the Cruiser — while making banking-for-later impossible, because there is nothing to bank toward. Raising a condition rather than silently discarding is the difference between a rule and a hidden tax; a city throwing away Works is a thing the player should be told once and then fix.

7.3 Funding and completion

US-1250 At the top of each round, after Yard accrual, each city MUST attempt to complete its head eligible order. An order is eligible when it is not Stalled and its payload satisfies US-360 for the city's current state.

US-1260 Where the head order is Stalled, the city MUST fund the first non-Stalled order in queue index order. The Stalled order MUST keep its queue position.

US-1270 An order MUST complete when Yard ≥ order.worksPrice and the owning player's Manpower pool is at least order.manpowerPrice. On completion, order.worksPrice MUST be deducted from the Yard, order.manpowerPrice MUST be deducted from Manpower, and the order MUST be removed from the queue.

US-1280 Where Yard ≥ order.worksPrice but Manpower is insufficient, the order MUST enter the Awaiting Levy state defined by 12-economy.md. The Works MUST be considered spent; the Yard MUST be reduced by worksPrice and the order MUST hold its place at the head of the queue until Manpower is paid.

US-1290 At most one order per city MUST complete per turn, regardless of how large the Yard is.

Rationale: this is a real rule with real consequences and it earns them. Without it a Metropolis Arsenal producing 80 Works a turn emits two Scouts every turn and becomes a swarm cannon, which erases the mass-versus-concentration tension the entire power curve of §12 is built to protect. With it, a large city produces large things — its efficient product is one that costs three to eleven turns of its own output — and small cities keep a genuine niche as the efficient producers of cheap units. There is no way to centralise, which is what keeps the map's industrial geography meaningful rather than collapsing to one super-city.

US-1300 The completion of an industry order MUST raise the city's Industry by exactly 1 and MUST take effect at the top of the following round, so that the Works multiplier for the completing round is the old one.

US-1310 A completed unit order MUST place the new unit on the city's tile, assign it the next global creation sequence, set hitsRemaining to full and enduranceRemaining to full, and hand it to 13-command.md for its initial order stack (CM-1170, CM-1180). It MUST require zero player input.

US-1320 Where a completed unit cannot legally be placed — a naval unit in a city that is not coastal for its terrainClass, or a tile at its stacking limit — the unit MUST be held hosted in the city, occupying no tile, until a legal placement exists. A hosted unit MUST NOT act and MUST be destroyed if the city falls.

US-1330 The reference producer of US-870 and the one-completion-per-turn rule of US-1290 together MUST yield a build time in [3, 11] turns for every manoeuvre unit at its unlock tier (US-780). §12.1 states the resulting table.


8. The roster

Twenty manoeuvre units and three auxiliaries. Every unit has a one-sentence role naming a thing no other unit does.

US-1340 The shipped unit set MUST be exactly the definitions of §8.1 through §8.5. Its setId MUST be standard.

US-1350 All costs in this section MUST be denominated in the Works scale defined by US-870, in which an untraited City-class city at Integration 100 and Industry 1 produces 12 Works per turn.

Rationale: costs are meaningless without a producer to measure them against. Stating the reference explicitly means that if 12-economy.md's base Works rates differ from the ones assumed here, every cost in this section scales by one integer factor and the build-time band of US-780 is the invariant that survives — rather than the roster and the economy quietly disagreeing about what a Works is.

8.1 Tier 1 — Depot (Industry 1). The complete simple game.

Unit W M Move Vis VisAir Hits atkL atkS atkA Def Flak Slots Cap Init Class Terrain
Scout 36 15 5 4 4 3 2 0 0 2 0 1 0 90 recon foot
Infantry 60 36 2 2 3 6 4 1 0 5 1 1 0 32 infantry foot
Field Gun 78 18 2 2 3 4 7 3 0 2 1 1 0 74 artillery wheeled
Transport 90 8 6 2 4 8 0 0 0 3 1 0 6 54 transport_sea naval
Corvette 102 18 8 3 5 7 3 6 0 5 3 0 0 62 escort naval

Flags and parameters: Scout capture; Infantry capture, entrench; Field Gun entrench, bombardRange 2, bombardShots 2; Transport cargoLost, draft 1, carryDomains {land}, carryMaxSlots 3; Corvette draft 1, bombardRange 1, bombardShots 1.

US-1360 Scoutreveals the map and punishes an undefended flank. It can capture, which is the entire reason your rear cities need garrisons. Three hits and defence 2 mean a single Infantry stops it dead, so it is a punishment for carelessness rather than a strategy.

US-1370 Infantrytakes cities and holds them; nothing on land is more cost-efficient at defending one. def 5 > atkLand 4 is deliberate and is the spine of the land game: infantry is better at holding than at taking, so the attacker must always bring more than the defender.

US-1380 Field Gungrinds down a dug-in defender so that infantry can finish it, and cannot take ground itself. It is placed at the bottom of the ladder on purpose, so that the most interesting mechanic in the game is available in the first fifteen turns rather than the first fifty.

US-1390 Transportthe only tier-1 way to move an army across water, and helpless while doing it. Eight hits so it does not evaporate; defence 3 so it must never travel alone; cargoLost so that losing the escort battle costs the army, not just the boat.

US-1400 Corvetteescorts convoys and contests coastal water; the cheapest thing that can sink a transport. draft 1 lets it go up rivers and into shallows where nothing bigger can follow, which is what keeps it relevant after the Destroyer arrives.

US-1410 The Field Gun MUST remain at Industry 1.

Rationale: this was an open question in the design proposal and it is decided here. Combined arms is the most interesting decision the combat model offers, and a player who does not meet it until Industry 3 has played fifty turns of a worse game. The cost is one extra concept on turn ten; the alternative — promoting the Scout out of tier 1 to compensate — trades the unit that teaches fog and exploration for the unit that teaches nothing until you own two of them. Five units on turn one is the right load, and this is the right five.

8.2 Tier 1 auxiliaries

These are units, so their stat lines and schema conformance are owned here. Their behaviour belongs to 12-economy.md, which owns garrison points, Integration rates, cost escalation basis, and supply propagation.

Unit W M Move Vis VisAir Hits atkL atkS atkA Def Flak Slots Init Class Terrain
Militia 40 16 1 1 2 5 2 0 0 4 1 0 12 garrison foot
Administrative Cadre 450 60 1 1 2 3 0 0 0 1 0 1 10 administration foot
Forward Depot 120 12 1 2 3 6 0 0 0 2 0 2 14 logistics foot

Flags and parameters: Militia entrench, garrisonOnly, reactiveOnly, slots 0; Administrative Cadre administrator, costEscalationPerOwnedPerMille 500, buildRequirements: minCityClass city, minIntegration 50; Forward Depot emplace, supplySource.

US-1420 Militiapays for occupation in a cheap, dedicated currency so that occupation never strands good infantry. It cannot leave its city, cannot attack, and cannot capture; it exists so a player is not clicking through fifty idle rifle companies every turn.

US-1430 Administrative Cadrethe visible convoy of bureaucrats that caps how fast an empire can digest what it conquers. Its escalating price is 12-economy.md's principal anti-snowball brake; this document owns only that the price escalates at 500‰ per Cadre already owned or in production, and that the price is fixed at enqueue (US-200).

US-1440 Forward Depotpushes supply beyond your integrated territory, and is exactly as strong as its link home. slots 2 so it can be shipped to an island; emplace so pushing it forward costs a turn.

US-1450 The three auxiliary units MUST be exempt from the build-time band of US-780. Rationale: the Cadre's price is a deliberate brake owned by another subsystem and would take 38 turns at the reference producer; forcing it into the band would mean overruling the anti-snowball design from the unit layer, which is not this document's decision to make.

8.3 Tier 2 — Workshop (Industry 2). Land war gets fast; the sky opens.

Unit W M Move Vis VisAir Hits atkL atkS atkA Def Flak Slots Init Class Terrain
Fighter 138 8 14 6 8 5 3 3 9 4 0 1 84 fighter air
Armour 156 20 4 3 4 8 9 2 0 6 1 2 50 armour tracked
Destroyer 192 36 10 4 6 10 4 9 5 7 6 0 60 escort naval

Flags and parameters: Fighter intercept, endurance 2, strikeRun 2; Armour capture; Destroyer sonar, draft 2, bombardRange 2, bombardShots 1.

US-1460 Fighterowns the sky over your own ground; short-legged, and near-useless against anything dug in. atkLand 3 is deliberately feeble: fighters win air superiority and see a very long way, they do not win ground battles. endurance 2 caps its operating radius at roughly fourteen tiles and makes airbase geography a real concern.

US-1470 Armourbreaks a line and exploits the gap, and is badly punished by rough ground. Two Infantry (120 Works, 12 hits, entrenchable) beat one Armour on the defence; one Armour beats two Infantry in the open. That trade is the map's question, not the roster's.

US-1480 Destroyerthe fleet's general-purpose escort, and the only mid-tier hull that can shoot at both submarines and aircraft. sonar and flak 6 are both dormant at the moment it unlocks, which is precisely the point: it is a good ship today and the indispensable ship the turn your opponent reaches Industry 3.

8.4 Tier 3 — Foundry (Industry 3). Concealment, strategic air, engineering, assault.

Unit W M Move Vis VisAir Hits atkL atkS atkA Def Flak Slots Cap Init Class Terrain
Air Defence Battery 126 24 2 4 8 5 1 0 11 4 12 1 0 18 air_defence wheeled
Engineer 132 40 2 2 3 5 1 0 0 3 1 1 0 26 engineer foot
Landing Ship 210 20 7 2 4 12 3 0 0 5 3 0 4 56 transport_sea naval
Heavy Artillery 216 48 1 2 3 6 14 6 0 3 1 3 0 72 artillery wheeled
Submarine 258 40 8 3 3 8 0 14 0 5 0 0 0 58 submarine naval
Bomber 264 16 12 4 6 6 12 10 1 3 0 2 0 78 bomber air

Flags and parameters: Air Defence Battery entrench, reactiveOnly, interceptZone 1; Engineer capture, entrench, repairAdjacent 1, buildables {road, airfield, fort, bridge}; Landing Ship assaultLanding, cargoLost, draft 1, carryDomains {land}, carryMaxSlots 3; Heavy Artillery entrench, siege, bombardRange 3, bombardShots 3; Submarine submerged, ambush, draft 2; Bomber endurance 2, strikeRun 3, cityStrike 1.

US-1490 Air Defence Batterymakes a stretch of sky expensive and is useless against anything on the ground. reactiveOnly means it never attacks on its own activation; atkLand 1 guarantees it can never be repurposed as a gun.

US-1500 Engineerturns terrain into infrastructure, and is the only way to make a large map traversable and a captured city defensible. On maps at the top of the supported size range it is not a specialist, it is the strategic-movement system. repairAdjacent 1 is the field answer to persistent damage.

US-1510 Landing Shipputs an assault ashore against a defended beach instead of needing an empty one. It is what stops island maps from degenerating into "whoever owns the water wins by default."

US-1520 Heavy Artilleryreduces fortified cities, and is nearly immobile and defenceless without a screen. siege doubles bombard effect against defenders in cities and forts; move 1, wheeled and slots 3 make moving a siege train an operation in itself.

US-1530 Submarinekills shipping and heavy hulls from concealment, and is helpless once found. atkSea 14 is the highest sea attack until Industry 4 and is meant to be frightening. It cannot attack land or air and cannot capture; its answer to being hunted is not to fight, it is to be somewhere else.

US-1540 Bomberprojects force anywhere inside a wide radius, and is the only tier-3 unit that can knock a city's works offline. cityStrike 1 lets it destroy accumulated build progress but never Industry, which makes it a tempo weapon against production rather than a weapon against the ladder.

8.5 Tier 4 — Arsenal (Industry 4). Fleet-scale power and strategic reach.

Unit W M Move Vis VisAir Hits atkL atkS atkA Def Flak Slots Cap Init Class Terrain
Missile 120 2 24 1 2 1 20 20 0 9 0 1 0 86 missile air
Air Transport 252 12 16 4 6 6 0 0 0 2 0 2 2 68 transport_air air
Heavy Armour 372 40 4 3 4 14 16 3 0 11 2 3 0 46 armour tracked
Heavy Bomber 396 24 14 5 7 9 16 12 0 5 0 3 0 80 bomber air
Cruiser 480 80 9 5 7 18 12 16 8 12 10 0 0 44 capital_ship naval
Carrier 510 60 9 5 7 16 0 2 0 8 8 0 4 40 carrier naval

Flags and parameters: Missile expendable, endurance 1, strikeRun 5; Air Transport airdrop, cargoLost, endurance 2, carryDomains {land}, carryMaxSlots 1; Heavy Armour capture; Heavy Bomber highAltitude, endurance 3, strikeRun 4, cityStrike 2; Cruiser sonar, draft 3, bombardRange 3, bombardShots 2, requiresTraits {shipworks}; Carrier airbase, cargoLost, draft 3, repairEmbarked 2, carryDomains {air}, carryMaxSlots 2, requiresTraits {shipworks}.

US-1550 Missiledeletes one undefended high-value target twenty-four tiles away, at no risk to anyone you would miss. At 120 Works and 2 Manpower it is the purest conversion of industry into effect in the game, which makes it the weapon of the Works-rich, Manpower-poor conqueror. Against a defended fleet it is a coin flip that buys little; against an artillery park, an air defence battery, a transport, an engineer or a Cadre it is decisive.

Rationale: the design proposal justified the Missile as an upkeep-free way to spend a production lead. There is no upkeep in this game (US-210), so that rationale does not survive, and the unit needed a real one. The one it has is better and it falls out of the two-resource economy: a player whose Manpower is starved by twenty undigested cities has Works and nobody to crew anything, and this is the only unit that turns Works into effect with essentially no people. It also names a role nothing else fills — reach 24 with no manned asset exposed — and it is stoppable, by Fighters and by Air Defence Batteries, which is what keeps it honest.

US-1560 Air Transportdrops infantry behind the line; the only unit that can put troops on a rear city with no ground approach. carryMaxSlots 1 means it moves Infantry, Engineers, Field Guns and Scouts, never Armour.

US-1570 Heavy Armourthe hammer that cracks a dug-in line at one point, expensive enough that losing one is a campaign event. slots 3 means one Transport carries two of them and nothing else.

US-1580 Heavy Bomberwrecks an enemy's industry from beyond the front, and cannot be touched by an army that did not climb. highAltitude is the sharpest expression of the tech gap this design permits (US-660). slots 3 exceeds a Carrier's carryMaxSlots 2, so it cannot operate from a flight deck.

US-1590 Cruiserthe strongest thing afloat gun for gun; slow, expensive, and a magnet for submarines and bombers. draft 3 bars it from shallows and rivers entirely, so it can be denied whole regions of a coastal map by geography alone.

US-1600 Carriermoves your air force's home and projects air power beyond your borders. Almost no attack of its own; four air slots, resets endurance, repairs 2 hits per turn to embarked aircraft. It is a capability purchase and it is priced as one.

US-1610 The Cruiser and the Carrier MUST require the shipworks city trait owned by 12-economy.md.

Rationale: capital hulls that can be laid down anywhere make every coastal city interchangeable and delete the naval half of the map's industrial geography. Requiring a specific trait turns a Shipworks port into a campaign objective worth a fleet action, and gives a player with no Shipworks a genuine strategic problem with a genuine answer — take one.


9. Roles and counter relationships

US-1620 Every unit MUST carry a role sentence naming a thing no other unit in the set does. Two units whose role sentences would be interchangeable MUST be treated as a design defect, not a balance problem.

US-1630 Every unit MUST have at least two units that counter it, and every unit whose class is not transport_sea, transport_air, engineer, carrier, administration or logistics MUST have at least two units it counters. Both lists MUST be stated in this document and shown on the unit card (US-950).

Rationale for the exemption: a Transport, an Engineer, a Carrier, a Cadre and a Depot counter nothing and are not supposed to. Forcing a counter list onto them would mean inventing an offensive role for units whose whole design is that they have none — and the exemption is one-sided, because everything in the game still has things that kill it.

Rationale: a counter relationship that exists only in the numbers is a counter relationship the player discovers by losing. Stating it makes the roster teachable in twenty cards instead of twenty games, and it is the mechanism that makes the escalation ladder work — each unlock arrives with its own place in a web the player already partly understands.

US-1640 The counter web of the shipped roster MUST be exactly the following.

Unit Counters Countered by
Scout undefended cities, exposed rear areas, unescorted Cadre and Engineers Infantry, Militia, Armour, any garrison at all
Infantry Scout, Air Transport landings, Armour in rough terrain and cities Field Gun, Heavy Artillery, Armour in the open, Bomber
Field Gun entrenched Infantry, Militia in cities, any dug-in defender Armour closing to contact, Bomber, Missile, Scout raids
Transport nothing — it is pure logistics Corvette, Submarine, Destroyer, Bomber
Corvette Transport, other Corvettes, shallow-water raiders Destroyer, Submarine, Cruiser, Bomber
Armour Infantry in the open, Field Gun, Engineer, Scout entrenched Infantry in cities or rough ground, Heavy Artillery, Bomber, terrain
Fighter Bomber, Heavy Bomber, Air Transport, Missile Air Defence Battery, Destroyer and Cruiser flak, its own endurance 2
Destroyer Corvette, Transport, detected Submarine, Bomber Cruiser, undetected Submarine, massed Bombers
Engineer terrain and distance — it counters the map, not a unit everything; def 3 and atkLand 1 mean it must never be alone
Air Defence Battery Fighter, Bomber, Missile, Air Transport within its zone Heavy Artillery, Armour, any ground attack at all
Landing Ship defended beaches, island garrisons Submarine, Destroyer, shore-based Field Gun, Bomber
Heavy Artillery fortified cities, entrenched stacks, Air Defence Batteries Armour breakthrough, Bomber, Missile, Scout raid, its own move 1
Submarine Transport, Landing Ship, Cruiser, Carrier Destroyer and Cruiser sonar, adjacency to anything at all
Bomber Armour, Heavy Artillery, unescorted shipping, city Yards Fighter, Air Defence Battery, Destroyer and Cruiser flak
Missile Heavy Artillery, Air Defence Battery, Engineer, Cadre, Transport Fighter intercept, Air Defence Battery interceptZone, its own expendability
Air Transport undefended rear cities, isolated garrisons Fighter, Air Defence Battery, any garrison at all
Heavy Armour dug-in lines at a single point, Armour, Infantry mass infantry frontage, Heavy Artillery, Bomber, rough terrain, slots 3 logistics
Heavy Bomber city Industry, Industry-2 armies, Heavy Artillery, capital ships Fighter, Air Defence Battery, Destroyer and Cruiser flak
Cruiser everything afloat gun for gun, shore targets, Corvette, Destroyer Submarine, massed Bombers, Missile, draft 3 geography
Carrier distance — it counters the map Submarine, Bomber, Cruiser, anything that finds it

US-1650 No unit in the shipped roster MAY have "everything" or "nothing" in its Counters column except where that is the literal design intent and is stated as such, as for the Transport, the Engineer and the Carrier.


10. Non-domination

US-1660 Unit A strictly dominates unit B when all of the following hold:

  1. A.domain = B.domain
  2. A.buildRequirements.minIndustry ≤ B.buildRequirements.minIndustry
  3. A.worksCost ≤ B.worksCost and A.manpowerCost ≤ B.manpowerCost
  4. A.slots ≤ B.slots
  5. every one of move, vision, visionAir, hits, atkLand, atkSea, atkAir, def, flak, capacity, bombardRange, bombardShots, interceptZone, cityStrike, repairAdjacent, repairEmbarked is greater than or equal on A than on B
  6. A.endurance ≥ B.endurance and A.draft ≤ B.draft
  7. A's non-restrictive flag set is a superset of B's, and A carries no restrictive flag that B does not
  8. A is strictly greater or strictly cheaper on at least one of the above

US-1670 The shipped roster MUST contain no strictly dominated unit.

US-1680 Every unit in the shipped roster MUST have a unique claim: a capability or price point that no cheaper unit of the same domain and no lower-tier unit provides.

Unit Unique claim
Scout Cheapest capture; the only unit with vision 4 at Industry 1
Infantry The best defence per Works in the game, and it entrenches
Field Gun The only Industry-1 indirect fire; the only unit that un-digs a defender before turn 20
Transport Six land slots — the largest sea lift, at any tier
Corvette Cheapest hull that can sink a Transport; the only warship with draft 1
Militia Cheapest body that satisfies a garrison requirement
Administrative Cadre The only administrator
Forward Depot The only mobile supplySource
Fighter The only intercept; the only counter to highAltitude
Armour The best land attack per Works below Industry 4
Destroyer Cheapest sonar; cheapest flak ≥ 6, the threshold that touches highAltitude
Air Defence Battery The only interceptZone; the highest flak in the game
Engineer The only buildables; the only mobile repair
Landing Ship The only assaultLanding
Heavy Artillery The only siege; range 3 and 3 shots, the deepest bombardment
Submarine The only submerged and the only ambush
Bomber The only Industry-3 cityStrike; the longest reach at its tier
Missile The highest attack in the game and the only expendable; 2 Manpower
Air Transport The only airdrop
Heavy Armour The highest def on land; the only 14-hit land unit
Heavy Bomber The only highAltitude and the only cityStrike 2
Cruiser The highest def and hits in the game
Carrier The only airbase and the only repairEmbarked

US-1690 A CI check MUST evaluate US-1660 across the shipped roster on every build and MUST fail on any dominated pair.


11. Conversion for combat

US-1700 Unit attack, defence and flak values MUST be stored in this document's tables as whole points and MUST be converted for combat resolution by multiplying by 1000, yielding per-mille strengths.

Rationale: carrying strengths in per-mille is what lets 11-combat.md's modifier chain compose without loss. Storing them in per-mille in the data would put three zeroes on every number on every unit card for no gain to the reader.

US-1710 11-combat.md owns the resolution procedure entirely. The roster of §8 is tuned against a model in which a per-round hit share is derived from the attacker's and defender's modified strengths, clamped away from certainty at both ends, and applied to persistent hit counts; in which a defender in a city, in rough terrain, or entrenched receives multiplicative defence bonuses; in which bombardment suppresses; and in which an attack launched from aboard a transport is penalised.

US-1720 If 11-combat.md's resolution procedure or modifier set changes materially, the roster of §8 MUST be re-tuned. The relationships of §9 are the design; the constants of §8 are an implementation of them against a specific procedure.

Rationale: stating this plainly is cheaper than discovering it. A change to how the share is computed does not invalidate "artillery softens, infantry takes ground" — it invalidates the number 7 on the Field Gun's attack line, and that is a re-tune, not a redesign.

US-1730 The client MUST be able to display an exact win probability for any proposed engagement before the player commits.

Rationale: a race between two integer hit counts at a fixed per-round probability has a closed form, so the honest odds are computable, not estimable. A modern strategy game that can tell the truth about a decision and instead makes the player guess is withholding information for no reason. It is also what makes the combined-arms lesson of §12.3 teachable: the player sees 7.7%, brings the guns, sees 49.2%, and has learned the game's central idea without a tutorial.


12. Balance laws and derivation

Every number in §8 is a design decision. These are the two rules that generated most of them, so that any single value can be re-argued on its own terms.

12.1 Law 1 — build times stay constant across the ladder

US-1740 The Industry output multipliers of US-820 MUST be chosen so that every manoeuvre unit takes between 3 and 11 turns to complete at the reference producer at that unit's unlock tier.

Tier Reference output Build times, cheapest to dearest
1 12 Scout 3 · Infantry 5 · Field Gun 7 · Transport 8 · Corvette 9
2 21 Fighter 7 · Armour 8 · Destroyer 10
3 33 Air Defence Battery 4 · Engineer 4 · Landing Ship 7 · Heavy Artillery 7 · Submarine 8 · Bomber 8
4 48 Missile 3 · Air Transport 6 · Heavy Armour 8 · Heavy Bomber 9 · Cruiser 10 · Carrier 11

US-1750 Industry upgrades MUST themselves fall inside the band at the reference producer: Workshop 8 turns, Foundry 9, Arsenal 11.

Rationale for the whole law: the rhythm of the game must not change as the pieces get bigger. A tier-4 empire is not waiting longer for its toys; it is getting better toys at the same cadence. That is what makes the ladder feel like growth rather than like a tax, and it is where the multipliers 1000/1750/2750/4000 come from — they are not a taste judgement, they are the solution to this constraint.

12.2 Law 2 — power grows as the square root of cost, with a small tier premium

US-1760 Define a unit's power index as P = 1000 × sqrt(primaryAttack × hits) / sqrt(worksCost), computed in per-mille, where primaryAttack is the greatest of atkLand, atkSea, atkAir.

US-1770 No unit in the shipped roster MAY exceed its tier's power ceiling.

Tier Ceiling Units at or near it
1 650 Corvette 642 · Infantry 632
2 690 Destroyer 685 · Armour 679
3 730 Air Defence Battery 661 · Submarine 659
4 780 Heavy Armour 776 · Cruiser 775

US-1780 A unit whose power index sits materially below its tier ceiling MUST have a stated capability it is buying instead.

Unit P What it buys instead
Scout 408 Five movement and four vision
Field Gun 599 Indirect fire that takes no return damage
Militia 500 Garrison points at the lowest price in the game
Fighter 571 intercept and air superiority
Landing Ship 414 assaultLanding and four land slots
Heavy Artillery 624 siege, range 3, and no return damage
Bomber 522 Reach, and cityStrike
Engineer 195 buildables and mobile repair
Missile 408 Reach 24, no manned asset exposed, and 2 Manpower
Air Transport 0 airdrop
Heavy Bomber 603 highAltitude and cityStrike 2
Carrier 250 airbase and repairEmbarked
Transport 0 Six land slots

US-1790 The ceiling MUST rise by approximately 20% across the whole ladder and no more.

Rationale: higher tiers must be better per point or nobody climbs, but the premium has to stay small enough that mass and concentration remain a live question at every tier. At these values five Infantry — 300 Works, 30 hits, five tiles of frontage — still beat one Heavy Armour at 372 Works and 14 hits across a broad front, and lose to it at a single point. A larger premium collapses that into "tech wins" and the whole ladder becomes a race rather than a decision.

US-1800 Tier 3 MUST be understood as the capability tier and tier 4 as the power tier: no tier-3 unit reaches its ceiling, and this is intentional.

Rationale: the Foundry is not bought for a better tank. It is bought for concealment, strategic air, engineering, amphibious assault and air defence — five capabilities that do not exist below it and that no amount of tier-2 Works can substitute for. Pretending tier 3 also had to hit a power target would have meant inflating six units past their roles. The upgrade still pays for itself in output alone: +12 Works per turn at the reference producer against a 180 Works cost is a 15-turn payback before a single new unit is built.

US-1810 The Manpower cost of every unit MUST be set so that infantry masses sit below the empire's own Works-to-Manpower supply ratio and mechanised, naval and air forces sit above it.

Unit W : M Bound by
Infantry 1.67 : 1 Manpower
Militia 2.50 : 1 roughly balanced
Heavy Artillery 4.50 : 1 Works
Destroyer 5.33 : 1 Works
Cruiser 6.00 : 1 Works
Armour 7.80 : 1 Works
Carrier 8.50 : 1 Works
Heavy Armour 9.30 : 1 Works
Bomber 16.50 : 1 Works
Fighter 17.25 : 1 Works
Missile 60.00 : 1 Works

Rationale: an empire's own supply ratio runs about 1.7:1 for a populous Metropolis to 3:1 for a Town-heavy holding, clustering near 2.2:1. Infantry priced below that band is manpower-bound; everything mechanised is works-bound. Which army a player can field is therefore dictated by the shape of the empire they hold, not merely its size — and that is the entire return on having a second resource. It also produces the striking result the economy design predicts from the other side: the fast conqueror, rich in captured factories and starved of people who will answer his call, is forced to mechanise.

12.3 Worked example — combined arms

US-1820 The following computation MUST hold under 11-combat.md's shipped resolution and is normative as a test vector.

An Infantry attacks an entrenched Infantry in a city on plains. Defender def 5 → 5000, city ×1500‰ → 7500, entrenched ×1250‰ → D = 9375, 6 hits. Attacker atkLand 4A = 4000, 6 hits.

share = 4000 × 1000 / (4000 + 9375) = 299. Racing 6 hits against 6 at p = 0.299, the attacker wins 7.7% of the time.

Now bring two Field Guns — 156 Works — and fire them first, which US-290's initiative assignment makes possible in the same turn. Bombard ignores entrenchment, so it resolves against 5000 × 1500‰ = 7500. share = 7000 × 1000 / (7000 + 7500) = 482. Four shots yield 1.93 expected hits, and any hit applies Suppressed.

The defender is now on about 4 hits, un-entrenched, with its city bonus halved: D = 5000 × 1250‰ = 6250. share = 4000 × 1000 / (4000 + 6250) = 390. Racing 6 attacker hits against 4 defender hits at p = 0.390, the attacker wins 49.2%.

Rationale: 7.7% to 49.2% for 156 Works of artillery. The interesting decision is not "do I roll the dice" but "have I brought the right combination, and did I spend a turn setting up." And a well-prepared assault still fails half the time, so the attacker must bring depth — which is exactly the texture the direction brief says flat attrition lacks.

12.4 Worked example — one bomber is not an answer

US-1830 A Bomber attacks a Destroyer. Flak resolves first: flak 6 → 6000 against the bomber's def 3 → 3000, share = 666, so a 66.6% chance the bomber takes a hit before it does anything. Then the run: A = 10000 against D = 7000, share = 588, limited to strikeRun 3. Expected outcome: 1.76 hits on the destroyer, 1.24 on the bomber, then the bomber breaks off.

Rationale: one bomber cannot sink a destroyer. Four bombers over two turns can, and will lose one doing it. Massed air works; sniping with air does not. And a fleet that brings a Destroyer screen has multiplied its own survivability without buying a single dedicated anti-air unit — because flak is an attribute, not a unit class.

12.5 Worked example — is the ladder worth climbing?

US-1840 One City-class city at Industry 1, 12 Works per turn, no captures.

Path A, tempo. Scout (turns 1–3) · Infantry (4–8) · Infantry (9–13) · Infantry (14–18) · Transport (19–26). At turn 26: one Scout, three Infantry, one Transport — 306 Works on the board, three cities holdable, and a boat.

Path B, industry. Scout (1–3) · Workshop, 90 Works (4–11) · output becomes 21 from turn 12 · Armour (12–19) · Destroyer in progress (20–26, 147 of 192 paid). At turn 26: one Scout, one Armour, most of a Destroyer — 339 Works of value, and three unit classes Path A cannot build.

The upgrade's break-even lands at turn 22. But Path A holds three cities at turn 18 and Path B holds one.

Rationale: the right tech pace is a function of the map and of the victory condition. On a crowded continent, tempo wins outright — the land is taken before the Workshop finishes. On an archipelago, or under a victory condition that runs past turn 60, the ladder wins. That is a genuinely good property: it means 14-victory.md's configurable conditions and this subsystem reinforce each other, and a short scored game and a long conquest game will not merely end differently, they will be played differently from turn four.


13. Setup: the shape of the curve

US-1850 Setup MUST NOT ask a player to choose a roster. It MUST ask for the shape of the Industry curve through the parameters of US-1860.

Rationale: the setup screen is where a new player is least equipped to judge how much complexity they want, and they will pick wrong in both directions. Moving the decision into the game hands it to the same person fifteen turns later, with information, with something at stake, and with the option to change their mind. It also means one roster, one balance surface, one AI evaluation function and one regression suite instead of four — which is the engineering budget that buys twenty properly tuned units instead of eighty badly tuned ones.

US-1860 Setup MUST expose exactly four parameters: start Industry (1–4), Industry cap (1–4, settable per player), upgrade cost multiplier (per-mille), and cap parity (whether all players share one cap).

US-1870 The following presets MUST ship, and MUST be presented with the sentence given.

Preset Start Cap Upgrade ׉ Costs For
Outpost 1 2 1000 90 A first game. Eight unit types, ever — a complete game of land, sea crossing and escort.
Standard 1 4 1000 90 / 180 / 360 The full arc. The default.
Escalation 1 4 600 54 / 108 / 216 Shorter games; the deep roster arrives by mid-game.
Total War 3 4 1000 360 Starts at the Foundry, for players who want the deep game immediately.
Fixed n n n Freezes the roster at one tier.

US-1880 The Fixed preset MUST be implemented purely as start = cap, with no additional code path.

Rationale: the classic fixed-tier experience falls out of this design as a degenerate case, for free. Anyone who wants "pick a set and play it" sets start equal to cap and has exactly that. We get their mode as a special case of ours; the reverse is not true, and that asymmetry is the whole argument for the ladder in one row of a table.

US-1890 The Industry cap MUST be settable per player, and MUST be the game's supported handicap mechanism for mixed-skill play.

US-1900 The start Industry parameter MUST apply to every city on the map at game start, not only to players' initial cities, unless the map data specifies a per-city Industry value, which MUST take precedence.

Rationale: if Total War raised only the starting cities, a player's first conquest would drop them back into the shallow game and the preset would fail at exactly the moment it mattered. Applying it to the map means the preset genuinely delivers the deep game, which is the only reliable way tier-4 play gets tested at all — and tier 4 is the most likely place for a balance disaster to hide, because most games will end before anyone reaches it naturally.

US-1910 Tier-4 balance MUST be validated by AI self-play at start Industry 3 and 4, and MUST NOT be validated by sampling ordinary Standard games.


14. Damage, repair and endurance

14.1 Damage

US-1920 Damage MUST persist across turns (US-420) and MUST be removed only by the repair sources of §14.2.

US-1930 A unit's current hitsRemaining MUST NOT reduce its attack, defence, movement or vision. A unit at 1 hit fights at full strength.

Rationale: a damage-scaled strength curve makes losing snowball inside a single engagement, punishes a player twice for the same bad turn, and makes the closed-form win predictor of US-1730 much harder to compute honestly. Hits as a pure race is legible, exactly predictable, and it means a damaged unit is a unit that is worth withdrawing — which is what gives repair and the Engineer a purpose.

14.2 Repair

US-1940 There MUST be exactly three repair sources: a friendly city (rate owned by 12-economy.md), a unit with repairAdjacent, and a carrier with repairEmbarked.

US-1950 repairAdjacent MUST restore its value in hits per turn to one adjacent friendly unit, chosen by the repairing unit's owner or, absent an order, by lowest hitsRemaining then lowest sequence.

US-1960 repairEmbarked MUST restore its value in hits per turn to every unit carried as cargo.

Rationale for the asymmetry: an engineer is one team with one set of tools and can be in one place; a carrier is a floating workshop whose entire purpose is servicing the air wing it carries. Making the carrier's repair per-unit rather than one-of is a large part of what a 510-Works capability purchase is buying.

US-1970 A unit MUST NOT repair on a turn in which it attacked or bombarded, and MUST NOT repair while its supply state is Extended or Isolated per 12-economy.md.

US-1980 Repair MUST resolve at the top of the round, before any activation, and MUST NOT exceed definition.hits.

US-1990 The Engineer's repairAdjacent 1 MUST return an Infantry to full in 6 turns and a Heavy Armour in 14; the Carrier's repairEmbarked 2 MUST return a Fighter to full in 3.

Rationale: these rates were asserted in the design proposal without derivation, and here is the derivation. Field repair should be slow enough that withdrawing to a city remains the better answer for a badly damaged formation, and fast enough that a fought-out line can be held rather than rotated. Six turns for an infantry battalion is roughly the time to build a replacement, which is the right indifference point. The carrier's rate is set so an air wing regenerates within one operational cycle — two turns aloft, one to rearm — because an air arm that cannot sortie again for six turns makes the hull worthless.

14.3 Endurance

US-2000 Aircraft range MUST be modelled as endurance in turns, not as fuel measured in movement points.

Rationale: this was an open question in the design proposal and it is decided here. Turns are integer-clean, need no per-unit stock, and make airbase geography a positional question a player can see on the map — "can I get home from there" — rather than an arithmetic one they must compute. Movement-point fuel models range more honestly on very large maps and is rejected because it converts every sortie into a subtraction problem and adds a per-unit ledger entry to a subsystem that has none. The honest cost is that on the largest supported maps the endurance radius is coarser than reality would be; that is a price worth paying and it is recorded in §17.

US-2010 At the end of every Cascade, an air unit that did not end its activation on a friendly city, a friendly airfield, or a unit with airbase MUST have enduranceRemaining decremented by 1.

US-2020 An air unit whose enduranceRemaining reaches 0 while not at a base MUST be removed from the map at the end of that Cascade.

US-2030 An air unit that ends its activation at a base MUST have enduranceRemaining reset to definition.endurance.

US-2040 The client MUST display enduranceRemaining on every air unit at all times, and MUST warn before committing an order that would leave a unit unable to reach any base.

Rationale: losing an aircraft to an arithmetic error the interface could have caught is not difficulty, it is a missing feature. The decision — go deep or come home — stays with the player; the subtraction does not.


15. Custom unit sets

US-2050 A custom unit set MUST be expressible as a single JSON document conforming to §2, using only the flag vocabulary of §3, with no scripting of any kind.

US-2060 The WASM plugin ABI MUST remain the only escape hatch for behaviour the flag vocabulary cannot express. A unit set MUST NOT be able to reach it.

Rationale: the boundary matters. A data set is safe to load from anywhere, is deterministic by construction, and cannot desync a multiplayer game. A plugin is none of those things and belongs behind a separate, explicit trust decision. Blurring the two would mean every shared unit set becomes a code-execution question.

US-2070 The shipped roster MUST use only the vocabulary of §2 and §3.

Rationale: this is the only honest way to prove the vocabulary is sufficient. If the game's own twenty units needed one special case, every modder's unit would need it too and would not have it.

US-2080 A game MUST use exactly one unit set. Mixing sets within a game MUST be rejected at setup.

US-2090 The unit set identifier and a content hash of its definitions MUST be included in the canonical game hash, so that two clients running different versions of a set desync immediately and loudly rather than silently diverging.

US-2100 A saved game or replay referencing a unit set that is absent or whose content hash differs MUST refuse to load, naming the set and both hashes.

US-2110 The encyclopedia (US-930) MUST be generated from the loaded unit set, not authored, so that a custom set is documented in-game to the same standard as the shipped one.


16. Contracts on other documents

Obligations this specification places on subsystems it does not own, recorded so that a change on either side is detectable.

US-2120 All prior US-NNN citations are stale. 02-unit-sets-content.md is void, and every requirement identifier it defined has been discarded. Sixty-eight distinct US-NNN identifiers are cited from 00-overview.md, 01-game-rules.md, 03-architecture.md, 04-ui-ux.md and 07-modding-content.md; none of them resolves to a requirement in this document, and the numbers have been reused for unrelated content. Every such citation MUST be re-resolved against this document before those files are considered current. The identifiers cited include US-020, US-050, US-055, US-057, US-060, US-070, US-073, US-075, US-077, US-140, US-150, US-180, US-190, US-200, US-220, US-227, US-390, US-400, US-420, US-440, US-450, US-455, US-460, US-465, US-475, US-490 and US-520.

US-2130 12-economy.md MUST provide: Works generation per city before the Industry multiplier of US-840; the Manpower pool, levy, and the Awaiting Levy state referenced by US-1280; city classes and their base Works, matching the reference producer of US-870 or stating the integer factor by which §8's costs must scale; the city trait vocabulary referenced by requiresTraits, including shipworks; Integration, referenced by minIntegration; supply states, referenced by US-1970; garrison requirements, satisfied by the Militia of US-1420; the Administrative Cadre's Integration rate and cost-escalation basis; the Forward Depot's Reach; and the repair rate for units in a friendly city. It MUST apply class-scoped trait discounts after this document's escalation, per US-190. It MUST NOT define unit stat lines for the Militia, Administrative Cadre or Forward Depot; those are owned by §8.2.

US-2140 11-combat.md MUST provide: the per-round resolution procedure the roster of §8 is tuned against; the entrenchment, city, terrain, Suppressed and amphibious-attack modifiers; the flak exchange preceding an air attack; the Suppressed condition applied by bombardment; the treatment of ambush, submerged, sonar, highAltitude, siege and assaultLanding in resolution; and the exact win predictor required by US-1730. It MUST honour US-270's rule that strikeRun does not bound air-to-air engagements.

US-2150 10-turn-model.md MUST provide: the Initiative formula consuming initiativeBase as the class base term, with creation sequence as the tiebreak; the global creation sequence counter referenced by US-410 and US-1310; Forming Up, which applies to every unit produced under §7; the meaning of veterancy in [0, 3] as declared by US-440; and the guarantee that a unit with move = 0 still occupies an activation slot. It MUST preserve the ordering property US-290 depends on: that a unit with a higher initiativeBase activates earlier, so that fire support and lift precede assault.

US-2160 01-game-rules.md MUST provide: the terrain movement-cost table indexed by terrainClass, with foot, wheeled and tracked differing in at least three terrain types per US-170; water depth classes indexed by draft; the coastal test referenced by requiresCoastal; tile stacking limits, against which US-320 exempts cargo; the effects of road, airfield, fort and bridge constructions named in buildables; the fort presence referenced by US-1100; and the fog and knowledge-view rules referenced by US-640 and US-970.

US-2170 13-command.md MUST surface the ProductionStalled condition of US-1060 and the ProductionOverflow condition of US-1240 through the Dispatch. Its Requisition rows (CM-1240) and Doctrine defaults (CM-790) MUST key on the class enumeration of US-090. Its obligation that in-progress production is never cancelled (CM-1270) is satisfied by US-1210. Its request for movement allowance, movement class, vision radius, current and maximum strength, city occupancy and an optional command rating (CM-2170) is satisfied by move, terrainClass, vision, hitsRemaining/hits, mayOccupyCity and commandRating. Its Replenish Reflex has no fuel or ammunition thresholds to read, because this design has neither; the nearest analogue is enduranceRemaining for air units under §14.3, and CM-2180's request MUST be re-resolved against that.

US-2180 14-victory.md MUST decide whether Industry level, unit classes built, or possession of specific unit types are legal victory-condition terms. "First to build a Carrier" and "hold three Arsenals" are natural objectives that sit exactly on the seam between that document and this one.

US-2190 04-ui-ux.md MUST own the presentation of the unlock card (US-950), the contact briefing (US-960), the encyclopedia (US-930), the greyed-build explanation (US-370), the endurance warning (US-2040), and the win-probability display (US-1730), implementing the content requirements stated here.

US-2200 03-architecture.md MUST include the unit-set content hash in the canonical game hash per US-2090, and MUST enforce the no-branching-on-id lint of US-060.


17. What could go wrong

Metrics with target bands. Deterministic simulation makes AI self-play cheap; a nightly self-play tournament should emit all of these.

US-2210 The following telemetry MUST be emitted by self-play runs and MUST be treated as release gates.

Failure Metric Alarm
Ladder too expensive; tiers 3–4 are dead content Distribution of maximum Industry reached at game end >70% of Standard games end at max Industry ≤ 2
Ladder too cheap; tempo play non-viable Median turn of first Workshop upgrade Earlier than turn 10
Tech snowball Win rate of a scripted "rush industry" opening against "rush units" at equal AI skill Outside 45–55%
Dead units Share of Works spent on each unit within the window it is available Any unit below 3%
Dominant units Same metric Any unit above 30%
Scout griefing Share of city captures made by units with hits ≤ 3 Above 15%
Submarine window Naval Works loss ratio in the band where subs exist but sonar is rare Attacker-favourable beyond 3:1
Combined arms not landing Share of successful city assaults preceded by bombardment in the same turn Below 50%
Bombard mandatory rather than valuable Share of city captures where the defender was at 1 hit before the assault Above 60%
Build-time band broken Turns-to-build for every unit at its unlock tier Outside 3–11
Capture degradation too punitive Share of captured cities whose Industry is rebuilt within 40 turns Below 25%
Works discarded by the Yard cap Share of city-turns raising ProductionOverflow Above 5%
Seniority penalty on tech Win rate of high-tier armies controlling for total Works Meaningfully below parity

US-2220 Two failures that no metric will catch MUST be watched in human playtest: whether the arrival of a new unit class is noticed and understood, and whether the per-city "unit or works?" question becomes tedious rather than interesting once an empire passes about a dozen cities.

US-2230 The known hard edges of this design MUST be recorded rather than hidden, and MUST be revisited after the first full playtest: a veteran can out-tech a newcomer inside one game, mitigated only by a per-player cap someone has to remember to set; an Industry-2 army facing Heavy Bombers has exactly one answer; tier 4 will be under-tested because most games end before it; and capture-degrades-Industry is correct design and an unpopular moment.


Open questions

  1. Should the Yard be per-city or per-order? A single per-city Yard makes cancellation free (US-1200) and the rules short, but it also means a player can accumulate against a Cruiser and, on the turn before completion, reorder the queue and spend the whole Yard on something else. That is arguably fine — the Works were always fungible — but it removes any commitment from a long build, and a per-order Yard would restore it at the cost of a refund rule, a partial-progress display, and an argument about what cancelling returns.

  2. Is one completion per city per turn too blunt at the top end? US-1290 does important work, but a Metropolis Arsenal with 12-economy.md's Works Expansion could produce 90+ Works a turn and be structurally unable to spend more than 51 of it on a Cruiser. The alternative — allowing multiple completions but forbidding two of the same unit — is uglier and may be more correct.

  3. Should the Industry multiplier be multiplicative on Works, or flat? Multiplicative concentrates industry in Metropolises and produces the industrial geography this document argues for (US-880). It also means a Town will rationally never reach Arsenal, so a player whose map gave them nine Towns and no City has a structurally worse game through no decision of their own. A flat +4 / +9 / +15 per level would equalise that and delete the geography. This is the decision most likely to be reversed.

  4. Is Industry memory (US-1000) too generous to the defender? Combined with 12-economy.md's Loyalty memory, a defender who retakes their own city gets full Integration, zero Unrest, and undamaged Industry — three restorations from one event. Each is individually justified and together they may make homeland recapture so strong that a contested border city is never worth taking at all.

  5. Is wheeled artillery a good idea or a trap? Making Field Gun, Heavy Artillery and Air Defence Battery road-dependent gives Engineers a purpose and makes artillery genuinely vulnerable in rough country. On a forested or mountainous map it may simply delete artillery from the game, which would take combined arms with it.

  6. Does bombardment need a consumable? Unlimited artillery fire may be too cheap. Ammunition tracking is exactly the fiddliness the direction brief warns against, and 12-economy.md rejected a third resource on the same grounds — but "the guns fire every turn forever" is the most likely place for the combat model to be exploited.

  7. Is tier 3 as the capability tier a real purchase or a trap? US-1800 states plainly that no tier-3 unit reaches its power ceiling. The Foundry pays for itself in Works alone in 15 turns, so the arithmetic holds — but a player who buys it and then finds their new units all lose fights per Works spent may reasonably conclude they were mis-sold, and the answer is a presentation problem this document cannot solve.

  8. Where does the boundary between class and unit identity sit for AI evaluation? 13-command.md's Requisitions key on class, which works. An AI evaluating whether to build a Submarine or a Bomber is making a decision class cannot express, and it must not make it by branching on id (US-060). The likely answer is a small set of scored capability tags derived from flags, and nobody has designed it.

  9. Should endurance scale with map size? US-2000 decides turns over movement-point fuel and accepts that the radius is coarse on the largest maps. A per-map endurance multiplier would fix it with one integer and would also be one more setup parameter nobody understands.

  10. Does the Missile survive contact with the victory system? A 120-Works, 2-Manpower, no-risk deletion of any undefended high-value target is exactly the tool that trivialises an objective-holding victory condition, and 14-victory.md has not yet been written against it.