applications/magicciv
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs(military): 📝 Update military communications documentation to clarify in-game strategies, mechanics, and terminology for the "age-of-dwarves" game

Browse source 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
autocommit 2026-05-19 00:27:21 -07:00
parent 6012378cf1
commit b802b56d20
1 changed files with 157 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

204
public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md
View file

@ -1,63 +1,145 @@
# Communications
Information about your rivals — that they exist, that they're mobilizing, that their northern hold burned last winter — physically travels through the world along the same hexes your armies do, carried by runners, beacon-chains, and resonance wires. **Knowing** is a fourth strategic resource alongside gold, production, and science. The communications tier you build (or pillage) governs how fresh your strategic picture is.
Information about your rivals — that they exist, that they're mobilizing, that their northern hold burned last winter — physically travels through the world along the same hexes your armies do, carried by foot-runners, ravens, beacon-chains, and resonance wires. **Knowing** is a fourth strategic resource alongside gold, production, and science. The communications infrastructure you build (or pillage) governs how fresh your strategic picture is.
The fantasy: a Foreman dwarf hammering a wall-map while a soot-streaked runner gasps out a six-turn-old report about troop movements that, somewhere out there, have already happened.
---
## Pillars
## 0. How information moves
### 1. First contact
Three dispatch sites generate messages. All three share the same carrier substrate, the same routing engine, and the same `Envelope` abstraction.
### Field-unit dispatches
A scout, pioneer, or any unit in the field carries a small complement of foot-runners (and, era permitting, birds or mounts) in its inventory. When the unit observes something worth reporting — first contact, a new city sighting, a stack of enemy units, the discovery of a strategic resource — it releases a carrier. The carrier walks, flies, or rides toward the player's capital along the cheapest available route.
### Capital dispatches
The capital maintains its own carrier stockpile, replenished by population, the `messenger_post` improvement, and the `resonance_chamber` building. Diplomatic envelopes — war declaration, treaty offer, treaty accept/decline, peace proposal, tribute demand, intel share, joint-attack plan, research-agreement payout — consume one carrier from the capital pool on dispatch. The carrier travels to the **other player's** capital.
### Scouting-post dispatches
A `scouting_post` improvement on a frontier hex carries a small stockpile of its own and auto-dispatches a carrier whenever its vision detects something significant: an enemy stack enters its sight radius, a previously-unseen city is spotted, a friendly unit reports in. Frontier coverage without the cost of permanent garrisons.
All three dispatch types produce the same payload shape:
```
Envelope { sender, recipient, payload, route, dispatched_turn, eta_turn }
```
Effects (war state, treaty signature, vision-share activation, intel-log entry) apply at envelope **arrival**, not dispatch.
---
## 1. Auto-routing through best available channel
When an envelope dispatches, the routing engine finds the cheapest path through every channel network the sender owns. Each tile belongs to multiple overlapping channel networks: walking (always), road (era 2), tunnel (era 3), beacon line-of-sight chain (era 6), steam-track (era 7), resonance-wire (era 8), radio (era 9), satellite uplink (era 9), mantle-choir (era 10).
A multi-channel Dijkstra picks the fastest route end-to-end, switching carrier mid-route as needed. The carrier hops between networks at adjacency: a foot-runner walks into a beacon-tower's hex and the beacon's signal carries on; a resonance-wire terminates at a relay and a tunnel-runner picks up the dispatch.
### Worked example
A frontier scout-post 80 hexes from the capital dispatches a sighting:
1. Scout-post → nearest radio relay (15 hex): foot-runner walks, 4 turns.
2. Radio relay (era 9) → next radio relay (25 hex): instant.
3. Radio relay → resonance chamber (20 hex): instant.
4. Resonance chamber → capital (20 hex): same-turn.
A well-developed network collapses 80 hex of foot travel into same-turn arrival. The carrier consumed is the **first leg**'s foot-runner; the radio and resonance segments are broadcast infrastructure and cost nothing.
### Severance
Pillaging a radio tower or resonance wire collapses that route at solve-time. The routing engine re-plans through the next-cheapest channel — typically a slower carrier-on-foot fallback. An envelope already mid-flight on a severed segment falls back to its carrier walking the remaining distance.
---
## 2. Carrier types — round-trip vs one-way
| Carrier | Direction | Inventory cost on dispatch |
|---|---|---|
| Foot-runner | Round-trip | None — runner returns unless killed |
| Mount courier | Round-trip | None — courier returns unless killed |
| Tunnel-runner | Round-trip | None — runner returns unless killed |
| Resonance-telegrapher | Round-trip | None — operator returns unless killed |
| Crag-raven (proposal, era 2) | One-way | Permanent: bird flies home, never returns to field |
| Hold-falcon | One-way | Permanent: bird flies home, never returns to field |
| Radio | Broadcast | None — no carrier travels |
| Resonance-wire | Broadcast | None — no carrier travels |
| Comms-satellite | Broadcast | None — no carrier travels |
| Mantle-choir | Broadcast | None — no carrier travels |
**Round-trip carriers** (people) walk to the destination, deliver, and walk back. Inventory does not deplete unless the carrier is intercepted and killed en route.
**One-way carriers** (birds) fly home to their roost and never re-enter the field. Inventory permanently decrements on release.
**Broadcast infrastructure** moves no physical carrier — the wire vibrates, the radio modulates, the choir resonates. No inventory cost per dispatch.
Permanent loss occurs only by death: runners cut down by enemy patrols crossing their path, birds taken by predators or weather. Loss rates scale with terrain and the route's exposure to hostile vision.
---
## 3. Carriers are part of unit training cost
A unit's production cost includes its carrier complement. A Pioneer Team shipping with 5 foot-runners + 2 crag-ravens has those carriers folded into its baseline cost — the player does not separately buy inventory.
When a carrier dies, that unit-instance permanently loses it. Restock paths:
- **Rebuild**: the unit is destroyed and re-produced from a city; fresh complement.
- **Upgrade**: era-tier upgrades refresh inventory as part of the upgrade cost.
- **Supply visit**: a friendly supply unit (era 4+) reaching the unit's hex tops up carrier inventory from its own stock.
Capitals and scouting-posts replenish through population, the `messenger_post` improvement, and the `resonance_chamber` building. Capital carrier stockpile is the bottleneck on heavy diplomatic correspondence — a player running many simultaneous treaties, war-decs, and vision-shares can run a deficit.
---
## 4. First contact
A player only appears in another player's diplomacy panel and score table after **contact** is established. Contact occurs when either:
- a unit or city of player A has had a tile of player B's unit/city in its `VISIBLE` set for ≥1 turn, **or**
- a unit or city of player A has had a tile of player B's unit/city in its `VISIBLE` set for at least 1 turn, or
- a courier envelope between A and B's capitals has been successfully delivered (any payload).
Contact is symmetric on first witness and permanent. A `PlayerDiscovered` event fires the turn it occurs; UX shows a "FIRST CONTACT — Clan Goldvein, scouts north of the Bronze Pass" toast.
### 2. Universal courier channel
---
Every inter-player payload — treaty offer / accept / decline, war declaration, peace proposal, tribute demand, intel share, joint-attack plan, research-agreement payout — travels as a courier `Envelope`. Effects apply at envelope arrival (`eta_turn`), not at dispatch. The envelope wraps:
## 5. Perceived state
```
Envelope { sender, recipient, payload, route, dispatched_turn }
```
Every player carries a **PerceivedState** — what their capital knows right now — distinct from the underlying ground truth. When a unit sees an enemy at hex X on turn T, that observation is dispatched as a field-unit envelope; it arrives at the player's capital after the routing engine resolves its path. The AI's tactical and strategic heuristics read PerceivedState; only its lookahead-rollouts simulate against ground truth.
The route is an A* path between the two capitals, computed at dispatch using era-tier-aware terrain costs (foot-runners avoid mountains, tunnel-runners prefer caves, resonance-telegraphers ignore distance). Envelopes age, can be intercepted (severance of a required infrastructure tile on the planned path), and consume `envelope_throughput` capacity on the sender.
A stale enemy marker on the strategic map shows a clock icon and the turn-of-last-update. A stack moving inside a tight beacon-and-radio mesh draws live; one outside resyncs only when a carrier gets home.
### 3. Perceived state
---
Every player carries a **PerceivedState** — what their capital "knows right now" — distinct from the underlying ground truth. When a unit sees an enemy at hex X on turn T, that observation is timestamped and queued for propagation; it arrives at the player's capital at turn:
## 6. Vision-share post-delivery
```
T + ceil(hex_distance(observer, capital) / comm_steps_per_turn(tier))
```
Once a SharedMap or DefensivePact envelope is delivered, ongoing ally vision-share remains active only while a current courier link exists. Heartbeat envelopes auto-spawn while a share-agreement is active, keeping the link warm. **Each heartbeat consumes one carrier from the sender's capital stockpile** — a player maintaining many active vision-shares carries a real ongoing carrier cost, paid out of the same pool as their war-decs and treaty offers.
Foot-runner default: 4 hex/turn. Beacon chains (LoS-connected `beacon_tower` improvements): `near_instant` (1 turn end-to-end). Resonance wires: `instant` (same-turn end-phase). The AI's tactical and strategic heuristics read PerceivedState; only its lookahead-rollouts simulate against ground truth.
Pillage a severable wire on the path → the share collapses to `SEEN_STALE` until the link is repaired; the treaty itself is not broken.
A stale enemy marker on the strategic map shows a clock icon and the turn-of-last-update. A stack moving inside beacon vision draws live; one outside resyncs only when a runner gets home.
Share latency in turns equals the routing-engine cost of the highest-tier infrastructure on the path: you see what your ally saw N turns ago. Resonance-wire allies share in real time; allies linked only by foot-runner relays share with multi-turn lag.
### 4. Vision-share post-delivery
---
Once a SharedMap or DefensivePact envelope is delivered, ongoing ally vision-share remains active only while a current courier link exists. Heartbeat envelopes auto-spawn while a share-agreement is active, keeping the link warm. Pillage a severable wire on the path → the share collapses to `SEEN_STALE` until the link is repaired; the treaty itself is not broken.
## 7. Information decay
Share latency in turns equals the `comm_tier_latency` of the highest-tier infrastructure on the path: you see what your ally saw N turns ago. Resonance-wire allies share in real time; beacon-only allies share with a one-turn lag.
Tiles that leave a player's `VISIBLE` set retain a `LastSeen` snapshot. With time, that snapshot fades:
### 5. Information decay
| Age (turns out of vision) | Fidelity |
|---------------------------|----------|
| 0 → decay_short | Biome + garrison count + improvements + city pop |
| decay_short → decay_long | Biome + "a city was here" + last_known_owner |
| > decay_long | Biome only ("you remember… mountains?") |
Tiles that leave a player's `VISIBLE` set retain a `LastSeen` snapshot. With time, that snapshot **fades**:
`decay_short` and `decay_long` scale with the network density of the observer's carrier infrastructure. Better comms equals longer accurate memory — not because individual observations last longer, but because the auto-routing engine brings fresh sightings home faster, refreshing `LastSeen` on nearby tiles before the old snapshot fades. A scout-post connected by radio relay refreshes its surroundings every turn; a scout-post relying on foot-runners refreshes whenever the runner makes the round-trip.
| Age (turns out of vision) | Fidelity |
|---------------------------|--------------------------------------------------------------------------|
| 0 → decay_short | Biome + garrison count + improvements + city pop |
| decay_short → decay_long | Biome + "a city was here" + last_known_owner |
| > decay_long | Biome only ("you remember… mountains?") |
The strategic map renders aged tiles with desaturation by fidelity tier; tooltips show the last-observed turn.
`decay_short` and `decay_long` scale with the observer player's comm_tier. Better comms = longer accurate memory, because patrol runners constantly refresh nearby observations. The strategic map renders aged tiles with desaturation by fidelity tier; tooltips show the last-observed turn.
---
### 6. Reveal events
## 8. Reveal events
The replay event stream carries:
@ -66,18 +148,27 @@ The replay event stream carries:
- `UnitSpotted { player, archetype, at_hex, in_territory_of }` (debounced per stack)
- `EnvelopeDispatched / Delivered / Intercepted { payload_kind, ... }`
- `LinkSevered / LinkRestored { players, at_hex }`
- `CarrierKilled { player, carrier_kind, at_hex }`
- `LastSeenDecayed { player, hex, new_fidelity }` (silent — AI consumption only)
These events are the AI's only asynchronous inputs. The perception filter materializes PerceivedState by replaying events delivered up to the current turn against its memory.
### 7. Capital-loss blackout
---
When a player loses their capital, all in-flight outbound envelopes are dropped, comm_tier on remaining links drops by 1, and decay timers accelerate by 50% until a new seat-of-power is named. **The player names a new capital on their next turn** — it is a forced choice surfaced at start-of-turn (pick any surviving city). Blackout lasts a single turn unless the player ends turn without choosing; an auto-promote fallback (highest-pop city, tie-break by lowest `city_id`) prevents AI stalls. A capital siege is not just symbolic; it deafens an entire civilization for the duration of the interregnum, but the interregnum is short by design.
## 9. Capital-loss blackout
### 8. Beacon-tap counter-intel
When a player loses their capital, all in-flight outbound envelopes are dropped, effective comm-tier on remaining links drops by 1, and decay timers accelerate by 50% until a new seat-of-power is named. **The player names a new capital on their next turn** — it is a forced choice surfaced at start-of-turn (pick any surviving city). Blackout lasts a single turn unless the player ends turn without choosing; an auto-promote fallback (highest-pop city, tie-break by lowest `city_id`) prevents AI stalls. A capital siege is not just symbolic; it deafens an entire civilization for the duration of the interregnum, but the interregnum is short by design.
Full mechanics: [`COMMUNICATIONS_PHASE3.md`](./COMMUNICATIONS_PHASE3.md) §1.
---
## 10. Beacon-tap counter-intel
An enemy unit standing on a non-severable `beacon_tower` can **read** envelopes passing through, without blocking them. The intercepting player learns the payload; the envelope continues to its recipient. `EnvelopeIntercepted { readable: true }` fires. Beacon chains thus become a target for raiders, not only an asset for defenders.
Full mechanics: [`COMMUNICATIONS_PHASE3.md`](./COMMUNICATIONS_PHASE3.md) §2.
---
## War declaration semantics
@ -95,17 +186,24 @@ The strategic moment this creates: a high-tier attacker with resonance-wire comm
## Comm tiers
Comm tier is set by the highest-tier comms infrastructure connecting two endpoints. The tier table:
Comm tier is the dominant channel available on a route. The routing engine picks the cheapest mix, but each backbone defines its own ceiling.
| Tier | Era | Backbone | Steps/turn | Vision-share latency | Severance |
|------|-----|----------------------------------|--------------|----------------------|-----------|
| 0 | 1 | No infrastructure (foot) | 4 | n/a | n/a |
| 2 | 2 | `messenger_post` (roads) | 5 | n/a | n/a |
| 3 | 3 | `tunnel` improvement | 6 | 3 turns | non-severable |
| 6 | 6 | `beacon_tower` (LoS chain) | 12 (near-instant) | 1 turn | destroyable (not pillage) |
| 7 | 7 | `steam_track` | 16 | 1 turn | pillage-severable |
| 8 | 8 | `resonance_wire` + `resonance_chamber` | ∞ (instant) | 0 turns | pillage-severable |
| 9 | 9 | `hold_network_citadel` mesh | ∞ + reroute | 0 turns | mesh-redundant |
| Tier | Era | Backbone | Steps/turn | Vision-share latency | Severance |
|------|-----|----------|------------|----------------------|-----------|
| 0 | 1 | No infrastructure (foot) | 4 | n/a | n/a |
| 1 | 2 | `crag_raven` (one-way bird, proposal) | 8 | n/a | inventory-limited |
| 2 | 2 | `messenger_post` (roads) | 5 | n/a | n/a |
| 3 | 3 | `tunnel` improvement | 6 | 3 turns | non-severable |
| 6 | 6 | `beacon_tower` (LoS chain) | 12 (near-instant) | 1 turn | destroyable (not pillage) |
| 7 | 7 | `steam_track` | 16 | 1 turn | pillage-severable |
| 8 | 8 | `resonance_wire` + `resonance_chamber` | ∞ (instant) | 0 turns | pillage-severable |
| 9 | 9 | `hold_network_citadel` mesh + radio | ∞ + reroute | 0 turns | mesh-redundant |
| 9 | 9 | `spaceport` + `comms_sat` (satellite uplink) | ∞ (orbital) | 0 turns | ASAT-vulnerable |
| 10 | 10 | `mantle_choir` (sub-tectonic resonance, dwarven apex) | ∞ | 0 turns | unjammable from surface |
The era-2 crag-raven entry is a proposed name pending sign-off, gated by the `animal_training` tech.
The era-10 `mantle_choir` is the dwarven race-specialized apex — other races receive their own T10 variants (sky-glass for elves, hive-mind broadcast for kzzkyt) in their respective game scope.
The `adamantine_echo` world wonder grants `courier_delay_reduction: 1` (all outbound envelopes one tier faster) and `envelope_intercept_resistance: 0.5` (half the interception chance on severable infra).
@ -113,6 +211,9 @@ The `adamantine_echo` world wonder grants `courier_delay_reduction: 1` (all outb
## Infrastructure interactions
### Roads and messenger posts (era 2)
Cleared trails increase foot-runner steps/turn. Messenger posts cache fresh runners closer to the frontier, reducing dispatch latency.
### Tunnels (era 3)
Plain inter-hold backbone. Couriers traversing tunnels are concealed from surface observation. Not severable — must be physically captured.
@ -125,8 +226,14 @@ Industrial-tier message lines. Severable by pillage. Carries envelopes at tier-7
### Resonance wires (era 8)
Pairs of rune-etched stone panels transmit encoded messages as vibration through the rock itself. Instant within the same turn. Pillage-severable. The `resonance_chamber` building enables courier production and grants `envelope_throughput: 2` — a city can dispatch two simultaneous envelopes to the same recipient.
### Hold network citadels (era 9)
Wonder-tier mesh nodes. If both endpoints own a citadel, an envelope automatically reroutes around any single point of failure. The first true redundant comms layer.
### Hold network citadels and radio (era 9)
Wonder-tier mesh nodes. If both endpoints own a citadel, an envelope automatically reroutes around any single point of failure. Radio towers add cheap broadcast hops to the routing graph, the first true redundant comms layer.
### Satellites (era 9)
A `spaceport` launches `comms_sat` orbiters. Satellite uplinks bypass terrain entirely and provide a top-tier broadcast channel. Vulnerable to ASAT weapons — a counter-strike can blind a satellite-dependent civilization in a single salvo.
### Mantle-choir (era 10, dwarven)
A `mantle_choir` chamber resonates through the sub-tectonic mantle itself, beneath any surface interdiction. Unjammable from surface, immune to ASAT, immune to pillage. The dwarven apex backbone.
---
@ -135,10 +242,11 @@ Wonder-tier mesh nodes. If both endpoints own a citadel, an envelope automatical
A successful comms layer feels like:
1. **Surprise dawn attack.** A neighbour with better comms strikes; your border garrisons fight back automatically, but your capital takes three turns to officially register the war and shift civics.
2. **Beacon ROI.** Players who fortify a beacon chain along their frontier mobilize ~3–4 turns faster than players who didn't. The replay can measure `time_to_first_response_unit_dispatched`.
2. **Beacon ROI.** Players who fortify a beacon chain along their frontier mobilize 3–4 turns faster than players who didn't. The replay can measure `time_to_first_response_unit_dispatched`.
3. **Stale-ghost misplay.** A player or AI marches a stack to a last-known enemy position and finds empty terrain. The intel was real — when it left the runner's hand. It just isn't real anymore.
4. **Pillage as a comms weapon.** Players raid a single `resonance_wire` tile specifically to sever a DefensivePact share. The `LinkSevered` event fires; ally vision collapses to `SEEN_STALE`.
5. **First-contact memorability.** Playtesters can name the turn they first met Clan Goldvein.
5. **Carrier deficit.** A player at war on three fronts, maintaining two vision-shares, runs short of capital carriers. The next treaty offer waits a turn for the stockpile to recover.
6. **First-contact memorability.** Playtesters can name the turn they first met Clan Goldvein.
---
@ -155,7 +263,9 @@ A successful comms layer feels like:
## Cross-references
- Hex movement and LoS rules: [`../HEX_GEOMETRY.md`](../HEX_GEOMETRY.md), [`../HEX_CONVENTIONS.md`](../HEX_CONVENTIONS.md)
- Era and tier progression: [`../../../docs/PLANET_LIFECYCLE.md`](../PLANET_LIFECYCLE.md) (era pacing) and `project_5tier_5era_system` in design memory
- Unit logistics and carrier inventory: [`../UNIT_LOGISTICS.md`](../UNIT_LOGISTICS.md)
- Tech tree gating of comms backbones: [`../TECH_TREE.md`](../TECH_TREE.md)
- Phase 3 sub-spec: [`COMMUNICATIONS_PHASE3.md`](./COMMUNICATIONS_PHASE3.md)
- Combat resolution and edge ZOC: [`../combat/COMBAT_SYSTEM.md`](../combat/COMBAT_SYSTEM.md)
- Politics and civic axes: [`../politics/AUTHORITY.md`](../politics/AUTHORITY.md), [`../politics/GOVERNMENT.md`](../politics/GOVERNMENT.md)
- Weather and observation lenses: [`../WEATHER_HISTORY.md`](../WEATHER_HISTORY.md)