# BEE WARS — Real-Time Grand Strategy: Design Doc & Roadmap

> Status: **APPROVED — Phase 1 complete** · Created 2026-06-07 · Owner: Avo
> Locked: 2 win paths (Domination + Cultural), faction mapping (§3), full kits, all dead content implemented, battles auto-resolve w/ optional watch, ~9s/tick pace.
> Target: transform Bee Wars from a turn-based 4X into a **pausable real-time grand strategy** (Stellaris/HOI feel), then build out two victory paths, asymmetric faction identities, full faction kits, and all currently-dead content on top of the real-time core.

---

## 1. Vision

Bee Wars becomes a **real-time grand strategy** game:
- Time flows **continuously**. The player can **pause**, and run at **slow / normal / fast** speeds.
- The deep 4X systems (economy, politics, factions, influence, diplomacy) are **kept** — just unpaused.
- The game already ships a real-time *battle* engine (16ms tick, unit AI, projectiles). We extend that real-time philosophy to the **strategic layer** (map, economy, AI), which is currently turn-based.
- **Bold re-architecture:** we rewrite the core loop to real-time now (foundation first), accepting temporary breakage while systems are ported.

## 2. Victory Paths (the "goals")

Only **two** win conditions, each fully implemented, tracked with a **live progress meter**, and reachable:

### 2.1 Military Domination
- Win by controlling a **dominant share of the map** (target ~65% of territories) **held continuously** for a sustained duration (e.g. 60s game-time) — the hold prevents win-flicker.
- Eliminating all rivals is also an instant Domination win.
- Live meter: "Territorial Control %" with the hold timer.

### 2.2 Cultural / Influence
- Win by **culturally dominating** the map: accumulate influence so that your influence is dominant across a target share of territories (including enemy-owned ones), **held** for a duration.
- Influence accrues continuously and can flip enemy territory (the influence system exists; we make it a true victory).
- Live meter: "Cultural Dominance %" with the hold timer.

### 2.3 Dropped as victories → repurposed as TOOLS
- **Economic** (10k honey) and **Political/Alliance** wins are **removed** as victory conditions.
- Economy now **funds** armies and influence campaigns. Alliances now provide **military aid** and **accelerate influence spread**. They are means, not ends.

### 2.4 Loss conditions (kept)
- Colony collapse (workers, queen HP, or territory hits 0).
- Revolution (unrest reaches 100).
- A rival achieving Domination or Cultural victory.

## 3. Faction Signature Mapping (LOCKED ✅ 2026-06-07)

Each of the 10 factions gets a clear identity and a signature win path it is built to reach. Roughly half conquest, half culture; Buckfast is the flexible generalist.

| Faction | Signature Style | Win Path | Engine / how it wins |
|---|---|---|---|
| **Africanized** | Relentless aggression | **Domination** | Free raiders, +atk, fast expansion — overwhelm early |
| **German Dark** | Defensive fortress | **Domination** | Turtle, escalating war bonus, grind enemies down |
| **Russian** | Attrition & resilience | **Domination** | Outlast; gets stronger as it loses land; indestructible builds |
| **Stingless** | Chemical denial / siege | **Domination** | Acid attrition, poison captured land, deny enemy economy |
| **Buckfast** | Balanced / adaptive | **Flexible (either)** | No weaknesses, event-immune, steady — pivots to either path |
| **Caucasian** | Cultural reach | **Cultural** | Influence ×2, long reach, the premier flipper of territory |
| **Italian** | Economic → cultural | **Cultural** | Wealth & diplomacy funnel into influence projection |
| **Carniolan** | Expansion + diplomacy | **Cultural** | Scout/expand/ally, spread influence through the network |
| **Cape** | Subversion / parasite | **Cultural** | Infiltrate & convert enemy territory from within |
| **Asian** | Alliance / protection | **Cultural** | Alliance hub diffuses culture; defensive, hard to dislodge |

> Domination camp: Africanized, German, Russian, Stingless (+Buckfast flex). Cultural camp: Caucasian, Italian, Carniolan, Cape, Asian (+Buckfast flex).

## 4. Faction Kits — "everything real" (free design license)

Implement every faction's **passive**, **unique unit abilities**, and **all 30 hero abilities** as real mechanics. Where a current description is weak/boring/broken, **redesign** it to be fun and competitive (license granted). Known gaps to fix:
- **Cape "Fake Alliance"** — currently does nothing. Redesign into a real subversion mechanic.
- **Buckfast** event immunity — extend beyond 2 event types; make it the consistency faction.
- **Asian "Suicide Sting at 20% HP"** — implement the HP threshold; tune Heat Ball.
- **German** Heritage Drone death-explosion (dead code) + Last Stand unit unlock condition.
- **Stingless** Propolis Maze movement cost + Wax Entomber seal + reconcile `acidBuff`/`acidCharges`.
- **Caucasian** "hidden honey" flavor → real mechanic or cut.
- **Heroes**: all 30 abilities (3 × 10) become real — in RTS terms, cooldown-based active abilities + passives.

## 5. Content — implement ALL the dead/partial systems

| System | Today | Plan |
|---|---|---|
| Tech tree | 5/9 real (t1c, t2a, t3b dead) | Implement all 9; rework as continuous research |
| Ideology buildings | ~10/25 real | Implement all effects |
| Territory buildings | 3/15 real | Implement all 15 |
| Wonders | 3 full / 2 partial / 2 dead (w4, w7) | Implement/fix all 8 |
| Hero abilities | 0/30 real | Implement all 30 |
| Achievements | bonuses mostly dead flags | Wire all bonuses |
| Espionage | intel only | Add sabotage actions |
| Influence | accrues + can flip | Becomes a victory path (§2.2) |

## 6. RTS Architecture (technical plan)

Core change: replace the discrete turn loop with a **continuous clock + fixed-step accumulator** (the standard real-time-GS pattern — a smooth clock with under-the-hood ticks, like Stellaris' daily tick).

1. **Game clock**: `gameTime` (seconds) advanced by a `requestAnimationFrame` loop; `gameSpeed ∈ {0 paused, 0.5, 1, 2, 3}`. `dt = (now-last)/1000 * gameSpeed`.
2. **Fixed-step accumulator**: accumulate `dt`; every fixed `STEP` (e.g. economy/politics tick) run the existing per-"turn" logic, scaled to the step. 1 legacy "turn" maps to a tunable number of seconds (pacing knob). Smooth systems (movement, influence, resource bars) update every frame by `dt`.
3. **Continuous economy**: per-turn income → per-second rates; resource bars rise smoothly.
4. **Continuous movement**: units follow paths over time; territory capture on arrival/contact; combat triggers on contact (reuse the battle engine or auto-resolve).
5. **Continuous AI**: AI evaluates/acts on its own cadence, pursuing its signature win path.
6. **Events / seasons / politics**: driven by `gameTime` timers instead of turn counters.
7. **Win checks**: evaluated continuously with hold-timers.
8. **UI**: replace "End Turn" with **pause / speed controls** + a **game clock**; add the two **victory meters**; keep all deep panels (pausable). Top bar shows clock + speed.

### Compatibility strategy
- Keep the legacy per-turn functions intact initially; the accumulator calls them as fixed steps so the game keeps *working* while we port system-by-system to smooth `dt`. This makes "bold" safe-enough: the game runs in real time on day one, then each system is upgraded from stepped → smooth.

## 7. Phased Roadmap

- **Phase 0 — Design lock** (this doc + faction-mapping sign-off). ← *we are here*
- **Phase 1 — Real-time core loop**: clock, pause/speed UI, accumulator driving existing turn logic; remove/replace End Turn; clock + speed in the top bar. *Game now plays in real time.*
- **Phase 2 — Continuous economy & movement**: smooth resource accrual; units move/capture in real time; contact-based combat.
- **Phase 3 — Victory paths**: implement Domination + Cultural with live meters & hold timers; remove Economic/Political wins; fix the survival/last-standing double-fire.
- **Phase 4 — Faction signature kits**: passives, unit abilities, all 30 hero abilities; wire each faction to its signature path; AI path-pursuit hooks.
- **Phase 5 — Content build-out**: all dead techs, ideology/territory buildings, wonders, achievements, espionage sabotage.
- **Phase 6 — Real-time AI**: AI that pursues its win path under the clock, reacts to the player.
- **Phase 7 — Balance, polish & onboarding**: tune rates/thresholds, pause-friendly UX, tutorial for the real-time flow.

## 8. Decisions & risks
- **Pacing knob (DECIDED)**: `SECONDS_PER_TURN = 9` at 1× (deliberate). 2×/3× available. Tune in Phase 7.
- **Battle integration (DECIDED)**: map contacts **auto-resolve** via combat math; a **"watch"** button opens the existing real-time battle scene optionally. No forced pause-and-fight.
- **Save/load**: must serialize `gameTime`/timers + `gameSpeed` (Phase 1 added these globals). Extend `_bwSerializeGame`.
- **RAF & visibility**: clock is `requestAnimationFrame`-driven, so it auto-pauses when the tab is hidden (desirable for single-player). Consider a `visibilitychange` UX hint later.
- Re-architecture will break things temporarily (accepted, per "bold").

## 9. Progress log
- **2026-06-07 — Phase 1 DONE**: real-time clock + accumulator in `gameLoop`; `rtsTick()` quietly drives the strategic layer; pause/0.5/1/2/3 speeds (`setGameSpeed`); live clock in HUD replacing "End Turn"; Space = pause; per-turn summary modal suppressed in `rtsMode`; game starts paused; defensive faction guard in `Game` constructor; pace set to 9s/tick. Verified by measurement (pause freezes, 3× = exact 3×, turns auto-advance).
- **2026-06-07 — Phase 2 MOVEMENT done & verified**: armies now travel in real time. New Army fields `path/dest/seg/px/py/intent`; `findPath` BFS; `issueMove` (defers everything to arrival) with `moveTo` alias; `advanceArmies()` per-frame stepper + `armyArriveHop()` (single home for capture/claim/merge/auto-combat/HQ-nullify/reveal); `secsForHop` (< SECONDS_PER_TURN); `armyCombat(…,arriving)` skips teleport on arrival; `captureTerr` fixes orphan-HQ. clickHex + AI loop rewired to `issueMove`; render draws from `px/py`; save skips transit fields. Also fixed a real **double-tax bug** (calcTaxIncome was added in both collect() and processGovernors). Verified via eval: findPath valid chain; single-hop capture defers ownership to arrival; multi-hop march; canMove gate blocks re-order mid-transit; contested arrival auto-resolves with no teleport snap; 8 AI ticks ran with 0 errors / 13 battles / no stuck armies / no NaN.
- **2026-06-07 — Movement adversarial review done & fixes applied**: a review workflow (32 findings → 11 verified) caught real bugs, all fixed & re-verified: save/load px/py NaN (init after ref-resolve); siege result now re-queues the march instead of stranding the army; crossing-army combat detection; **ghost-army rout** (surviving defenders zeroed off a captured hex); fog visibility checks in-transit seg endpoints; wonder no longer pre-assigns ownership before arrival; double-rename guarded. NOTE: the review's suggested fix for `secsForHop` terrain was WRONG (would make rough terrain faster) — caught it via eval and reverted; original numerator placement is correct. Re-verified: siege retries→captures, defender zeroed (no ghost), save/load all px valid, rough>flat hop time, 10 AI ticks 0 errors. Movement is HARDENED.
- **2026-06-07 — Phase 2 ECONOMY done & verified**: `econTick(c,dt)` accrues the dominant flows per game-second (nectar income + tax − upkeep − population consumption, plus honey/propolis/royal-jelly), driven from `gameLoop` for every alive colony. `collect()` stripped down to discrete per-tick steps only (conversion, spoilage, famine, desert). Deficit tracking is now a continuous `_defAcc` timer (crisis at 3 & 5 tick-equivalents). Resources are floats, floored at all display sites (HUD, Resources widget, Army Builder). Fixed the **double-tax** bug en route. Verified by eval: per-0.5s slice == expected, full-tick total == exact per-tick net (NO inflation/double-count), honey gain == honProd(); 40s integration run (econTick+rtsTick+movement) = 0 errors, no NaN, caps respected.
- **PHASE 2 COMPLETE.** The strategic layer is now genuinely real-time: continuous clock, smooth economy, armies that travel & fight in real time.
- **2026-06-07 — Phase 3 VICTORY PATHS done & verified**: `chkWin()` rewritten to exactly two win paths, each requiring a sustained HOLD. **Military Domination** = control ≥`DOM_THRESHOLD` (0.6) of passable territory for `DOM_HOLD_TICKS` (4) ticks. **Cultural** = `culturalReach(c)` (owned territories + enemy/neutral territories where the colony has dominant influence ≥`CULT_MIN_INF` 40) ≥`CULT_THRESHOLD` (0.6) of the map, held `CULT_HOLD_TICKS` (4). Economic (10k honey) & Political (allyTurns) wins REMOVED (honey/alliances remain as tools; the a_peace achievement still uses allyTurns). Survival/last-standing merged into ONE elimination check (fixes the double-fire). The "Power" colony-drawer widget is now a **Victory** widget with two live progress meters (⚔ Domination, 🎭 Cultural) showing %/goal + a 🔒 hold counter, with the power score beneath. Verified by eval: economic+political no longer win; domination fires at exactly 4 held ticks; cultural fires from influence dominance; survival single-fires; meters render; 12-tick integration run = 0 errors, no spurious victories.
- **PHASE 3 COMPLETE.** Tunable knobs (`DOM_THRESHOLD`, hold ticks, `CULT_MIN_INF`, etc.) live beside the RTS globals for Phase 7 balancing.
- **2026-06-07 — Phase 4 DESIGNED + started**: a design workflow produced concrete code-level implementation specs for all 10 faction kits (passive + ~4 unit abilities + 3 hero abilities + signature wiring each, ~90 abilities total) — saved in `_phase4_specs.txt`. First slice IMPLEMENTED & verified: the Cultural factions' core influence identity in `processInfluence` — Italian 1.5× (Merchant's Reach) ×2 while its hero lives (Golden Pheromone), Carniolan +3 (Alpine spread), Caucasian ×2. Verified: Italian infRate 8→12→24-with-hero.
- **2026-06-07 — Phase 4 CORE KITS implemented & verified** (user said "just do everything"). Rather than a literal 150-hook transcription of the over-detailed specs, implemented clean, consolidated, robust versions capturing each faction's identity + signature-path pull, mainly via a new per-tick **Phase 4 block in `runPassive`** + `processInfluence` rate boosts + key combat/hero hooks. CULTURAL: Italian (1.5× inf, hero 2×), Carniolan (+3 inf, Alpine influence-surge replacing the old land-grab, hero auto-reveal), Caucasian (×2 inf, Fragrant Overspill radiation, Tara Harvest near-death steal), Cape (infiltration→influence leak), Asian (good-relations→influence). DOMINATION: Russian (martyr scales with land + decays, Dmitri Iron Will survive-at-1HP + drought purge), German (Wrath milestones→permanent ATK, Last Stand atk×2/def×1.5, Brunhilde Unbreakable def×3/tick), Africanized/Stingless (largely pre-existing combat kept). FLEXIBLE: Buckfast (Hybrid Vigor regenerating charges = event shield + income×/influence× bonus, Brother Anselm Miracle revive). New colony fields init'd; `heroRescue()` helper added. Verified: 10-tick integration 0 errors; vigor mods, martyr formula, Iron Will (1 HP), Miracle (50%) all confirmed.
- **2026-06-07 — Phase 4 extended to all 10 hero kits.** Added signature hero auto-effects for the remaining factions: Stingless Zara (bonus acid), Asian Hana (diplo warmth + cultural-diplomacy influence), Cape The Nameless (deepens subversion influence), Africanized El Diablo (Blood Frenzy +15% atk). Now EVERY faction has a passive + signature hero effect + signature-path wiring. Verified: 12-tick integration, 0 errors, no console errors.
- **Remaining (lower-impact polish):** granular per-unit combat sub-bonuses, ultimate redesigns, and battle-scene `FACTION_BAT_FX` effects from the specs — captured in `_phase4_specs.txt` if desired later.
- **PHASE 4 COMPLETE.**
- **2026-06-07 — Phase 5 (dead content) DONE**: made ~23 previously-dead items real (mapped via workflow). Techs t1c (auto-reveal)/t2a (−20% build cost)/t3b (+2 move range). Wonders w1 (built-guard), w4 (honey/propolis Spring x1.5), w5 (2× research progress), w6 (permanent +25% atk/def), w7 (trust/turn). Territory buildings tb_farm/tb_armory/tb_fortress/tb_academy/tb_festival/tb_labor/tb_watchtower/tb_culture (consolidated block + `_bldDefBonus` read in Army.def). Ideology ib_science_q/ib_culture/ib_parliament/ib_breeding. Achievements a_eyes (2× scout)/a_peace (+25 trade)/a_winter (winter immunity). Verified 0-error. (Remaining intricate ones — ib_town/commune/iron/shadow/hive/black/manor/chem_parl, tb_vault/barracks/rally/tradepost, cost20/tier4, w0 event-proof — noted as lower-priority polish.)
- **2026-06-07 — Phase 6 (real-time AI) DONE**: `aiGoal(c)` tags each colony dom/cult by signature path. Domination AIs press toward enemy/neutral land (multi-hop march to nearest enemy when no adjacency); Cultural AIs hold owned influence-border hexes and skip offensive wars (combat gated to dom). Verified: an AI legitimately wins via its path; 0 crashes over 50+ ticks.
- **2026-06-07 — Phase 7 (balance pass) DONE (first pass)**: KEY FIX — **decoupled influence from territory ownership** (influence is now capped at 99 and drives `culturalReach`/Cultural victory but no longer flips ownership), eliminating the cultural-conquers-everything snowball. Softened Domination AI aggression (probabilistic attacks vs neutral-seeking) to prevent mutual annihilation. Added defensive null-guards to the moth/mutation events (empty-`alive()` edge case). Result: contested games, no runaway snowball (max ~20% territory in AI-vs-AI), both paths viable, 0 errors in natural play. **Balance is iterative — recommend real playtesting for final tuning of rates/thresholds (all knobs sit beside the RTS globals).**
- **ALL 7 PHASES COMPLETE.** Bee Wars is a playable, pausable real-time grand strategy with 2 win paths, 10 distinct faction kits, real content, path-pursuing AI, and a first balance pass.
- Then Phase 5 (dead content), 6 (real-time AI pursuing win paths), 7 (balance).