From b802b56d203ea0e4b32563b2d89ddaefaae5f336 Mon Sep 17 00:00:00 2001 From: autocommit Date: Tue, 19 May 2026 00:27:21 -0700 Subject: [PATCH] =?UTF-8?q?docs(military):=20=F0=9F=93=9D=20Update=20milit?= =?UTF-8?q?ary=20communications=20documentation=20to=20clarify=20in-game?= =?UTF-8?q?=20strategies,=20mechanics,=20and=20terminology=20for=20the=20"?= =?UTF-8?q?age-of-dwarves"=20game?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Lilith Autocommit --- .../docs/military/COMMUNICATIONS.md | 204 ++++++++++++++---- 1 file changed, 157 insertions(+), 47 deletions(-) diff --git a/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md b/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md index 0c950f4e..45f82e50 100644 --- a/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md +++ b/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md @@ -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)