docs(military): 📝 Improve military communications documentation with detailed ranges, delivery mechanics, and tactical coordination rules
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
autocommit
parent
6b0bf433f6
commit
b887268eae
1 changed files with 161 additions and 0 deletions
161
public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md
Normal file
161
public/games/age-of-dwarves/docs/military/COMMUNICATIONS.md
Normal file
|
|
@ -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 <hex>" 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)
|
||||
Loading…
Add table
Reference in a new issue