From b887268eae0a6d23c758d7caee9079ec56799710 Mon Sep 17 00:00:00 2001 From: autocommit Date: Mon, 18 May 2026 18:41:41 -0700 Subject: [PATCH] =?UTF-8?q?docs(military):=20=F0=9F=93=9D=20Improve=20mili?= =?UTF-8?q?tary=20communications=20documentation=20with=20detailed=20range?= =?UTF-8?q?s,=20delivery=20mechanics,=20and=20tactical=20coordination=20ru?= =?UTF-8?q?les?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Lilith Autocommit --- .../docs/military/COMMUNICATIONS.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md diff --git a/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md b/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md new file mode 100644 index 00000000..6be3b46c --- /dev/null +++ b/public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md @@ -0,0 +1,161 @@ +# 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. + +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 + +### 1. 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 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: + +``` +Envelope { sender, recipient, payload, route, dispatched_turn } +``` + +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. + +### 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: + +``` +T + ceil(hex_distance(observer, capital) / comm_steps_per_turn(tier)) +``` + +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. + +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. + +### 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. + +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. + +### 5. Information decay + +Tiles that leave a player's `VISIBLE` set retain a `LastSeen` snapshot. With time, that snapshot **fades**: + +| 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?") | + +`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 + +The replay event stream carries: + +- `PlayerDiscovered { discoverer, discovered, at_hex }` +- `CitySpotted { player, city_id, at_hex }` +- `UnitSpotted { player, archetype, at_hex, in_territory_of }` (debounced per stack) +- `EnvelopeDispatched / Delivered / Intercepted { payload_kind, ... }` +- `LinkSevered / LinkRestored { players, 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. A capital siege is not just symbolic; it deafens an entire civilization for the duration of the interregnum. + +### 8. 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. + +--- + +## War declaration semantics + +Communications speeds *strategic* response, never *self-defense*. The rules: + +- The **sender** enters `War` immediately on envelope dispatch. Sender units can attack on the same turn. +- **Defenders always retaliate when struck.** Combat resolution does not gate on the defender's formal `RelationState`; this is how combat already works and is preserved. Retaliation carries no diplomatic cost. +- The **recipient's** `RelationState` flips to `War` on envelope **delivery** or **interception**, not at dispatch. Until then, the recipient cannot issue strategic war moves — wartime civics, mobilization edicts, alliance-pact triggers, the AI's "war mode" branch — because their capital does not yet know who is attacking, or that the skirmishes on the border are part of a coordinated campaign rather than a raid. +- **UX guarantee:** an "UNDER ATTACK at " toast and map-flag fires the instant any of your units takes damage, regardless of formal status. Players are never confused about whether they are being attacked — only about whether their capital yet knows *who is doing it*. + +The strategic moment this creates: a high-tier attacker with resonance-wire comms can launch a credible surprise attack against a low-tier neighbour whose capital is still receiving the warning about the front-line skirmish three turns later — while the front-line units defend themselves automatically the whole time. + +--- + +## Comm tiers + +Comm tier is set by the highest-tier comms infrastructure connecting two endpoints. The tier table: + +| 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 | + +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). + +--- + +## Infrastructure interactions + +### Tunnels (era 3) +Plain inter-hold backbone. Couriers traversing tunnels are concealed from surface observation. Not severable — must be physically captured. + +### Beacons (era 6) +Mountaintop fire-towers relay coded smoke and flame signals through a line-of-sight chain. Each beacon's vision_bonus extends ground vision around it (+2 hex). The chain forms an implicit graph; sightings inside the chain's combined vision propagate near-instantly to any connected capital. A single beacon is killable (not pillage-severable), and losing it can break the chain into disconnected sub-graphs. + +### Steam tracks (era 7) +Industrial-tier message lines. Severable by pillage. Carries envelopes at tier-7 speed. + +### 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. + +--- + +## Player-visible signals + +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`. +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. + +--- + +## Out of scope + +- **Spies, embassies, active mis-information** — Game 2+. Active disinformation interacts with the perception filter non-trivially and demands an asymmetric-info UI that is not in Game 1 scope. +- **Magical comms, mind-link, scrying** — Game 3. +- **Archon-tier instant communications** — Game 3. +- **Worldwide news ticker** (wonder completions etc.) — UX feature, not sim. Wonder completion is global by design; unit positions are the simulated channel. The distinction is sharp on purpose. +- **Diplomatic language barriers** — single-race Game 1. + +--- + +## 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 +- 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)