# ROACH KINGDOM WARS — Design Bible v1.0

> **Rule the world beneath the world.**
> A premium real-time strategy game set in the underground civilization of intelligent roaches. Built to stand on its own as a world-class RTS — the blockchain layer is an optional reward skin, never the point.

---

## 0. The One-Sentence Pitch

*Beneath the dead cities, five roach kingdoms wage war across thirteen living biomes — build your colony, command a hero, and conquer the underworld in a strategy game so good you forget it touches crypto at all.*

**The test every decision must pass:**
> "Would someone who has never heard of Web3 still want to spend hundreds of hours playing this?"
> If yes — ship it. If no — cut it.

---

## 1. Vision & Design Pillars

| # | Pillar | What it means in practice |
|---|--------|---------------------------|
| 1 | **Game first, chain optional** | Core loop is fun with zero wallet connected. Crypto = cosmetic ownership + optional collectibles only. Never pay-to-win. |
| 2 | **A living underworld** | Every biome has its own light, weather, music, creatures, secrets. The map *reacts* — events, weather, dungeons. |
| 3 | **Every unit is a character** | No generic sprites. Idle behaviours, emotes, personality. You should recognise a faction from across the map. |
| 4 | **Cinematic, not cartoon** | Pixar-grade creature design on realistic cave environments. Volumetric light, fog, glow, particles. Feels alive. |
| 5 | **Discovery is a reward** | Hundreds of easter eggs, hidden dungeons, treasure chests. Players hunt secrets for months. |
| 6 | **Fair forever** | All progression is cosmetic. Competitive balance is sacred. Skill wins, never spend. |

---

## 2. The World

An enormous subterranean civilization built entirely by intelligent roaches, sprawling beneath abandoned human cities. No humans — only the kingdoms of the dark.

### 2.1 The Thirteen Biomes
Each biome ships with unique **lighting, ambience, resources, architecture, creatures, music, and secrets.**

| Biome | Signature look | Hazard / mechanic | Resource bias |
|-------|----------------|-------------------|---------------|
| Ancient Sewer Kingdoms | green murk, dripping pipes, bioslime | flooding tides | high Biomass |
| Abandoned Subway Systems | flickering rails, distant trains | rogue train events | Scrap-rich |
| Forgotten Laboratories | sterile teal light, broken glass | toxic spill zones | Crystal + tech relics |
| Giant Mushroom Forests | bioluminescent canopy, spore haze | spore clouds (vision) | massive Biomass |
| Crystal Caverns | refracted rainbow light shafts | crystal eruptions | premium Crystal |
| Insect Cities | carved chitin towers, lantern glow | neutral insect NPCs | balanced |
| Abandoned Bunkers | steel corridors, red alarm light | sealed blast doors / loot | Scrap + armor |
| Underground Rivers | flowing water, reflections | current pushes units | Biomass |
| Mechanical Junkyards | rust, steam, sparks | conveyor hazards | Scrap king |
| Volcanic Caves | lava glow, ember rain | lava eruptions | Crystal + heat power |
| Fungal Jungles | dense glowing flora | parasitic fungus | Biomass overflow |
| Radioactive Tunnels | sickly green pulse | radiation damage-over-time | rare mutagens |
| Frozen Underground Caverns | ice-blue, fog breath | slow + brittle terrain | Crystal |

> **Design rule:** players should *never* see the same map twice in a row. Procedural biome dressing + hand-authored landmarks.

### 2.2 World Events (mid-match dynamic)
Earthquake · Flood · Gas leak · Crystal eruption · Meteor impact · Ant invasion · Spider migration · Treasure caravan · Underground collapse.
→ Each forces a strategic pivot (reroute, defend, exploit). Telegraphed 10–15s ahead with audio + screen cue.

### 2.3 Weather (per-biome)
Dust storms · Steam vents · Poison fog · Crystal rain · Lava eruptions · Glowing spores · Water flooding.
→ Affects **vision, movement speed, and lighting** dynamically.

---

## 3. Factions (the 5 kingdoms)

Each must be recognisable from a distance by **silhouette + color + motion language.**

### 3.1 Iron Shell Kingdom — `#5a9bff` (iron blue)
Heavy armour, steel plates, massive shields, blue energy cores, military discipline.
**Playstyle:** turtle & overwhelm. Best defense, slow but unbreakable. **Motion:** rigid, marching.

### 3.2 Acid Swarm — `#8bff5a` (acid green)
Bright green carapaces, poison sacs, long claws, organic armour, frenzied.
**Playstyle:** aggression & numbers. Cheap units, damage-over-time. **Motion:** twitchy, fast, skittering.

### 3.3 Royal Colony — `#f5c451` (royal gold)
Elegant gold armour, royal banners, throne halls, ornate decorated units.
**Playstyle:** economy & buffs. Aura commanders, late-game powerhouses. **Motion:** regal, deliberate.

### 3.4 Scrap Legion — `#ff8a3d` (rust ember)
Mechanical body parts, rust, chains, steam, scrap cannons, mechanical wings.
**Playstyle:** tech & artillery. Salvage mechanics, siege. **Motion:** clanking, steam-puffed.

### 3.5 Crystal Hive — `#b15aff` (crystal purple)
Crystal armour, purple glow, floating energy, magical abilities, beautiful lighting.
**Playstyle:** energy & control. Spells, teleports, shields. **Motion:** floaty, shimmering.

---

## 4. Hero Commanders

Players choose **one Commander** before the match. Each has a **passive · 2 active skills · ultimate · voice lines · unique skin line.**

| Commander | Faction lean | Passive | Ultimate (signature) |
|-----------|--------------|---------|----------------------|
| **Queen Scarlet** | Royal Colony | nearby units +15% attack | *Royal Decree* — global rally + heal |
| **General Ironclaw** | Iron Shell | buildings +25% HP | *Iron Wall* — summon shield bastion line |
| **Doctor Venom** | Acid Swarm | attacks apply poison | *Plague Bloom* — area DoT cloud |
| **King Titan** | Iron Shell | trains heavy units faster | *Titan Smash* — meteor melee shockwave |
| **Shadow Hunter** | Crystal Hive | units cloak in fog | *Night Ambush* — mass cloak + crit |
| **Engineer Scrapjaw** | Scrap Legion | auto-salvages wrecks | *Scrap Storm* — deploy artillery turrets |

> Commanders are the **hero fantasy hook** — heavily skinned, voiced, and the centerpiece of the cosmetic economy.

---

## 5. Core Gameplay Loop

```
SCOUT → HARVEST (Biomass + Crystal) → BUILD (tech up) → ARMY → ENGAGE → EXPAND → WIN
        ↘ react to World Events / Weather ↘ raid Hidden Dungeons / chests ↗
```

### 5.1 Economy
- **Biomass** — from fungus/mushroom nodes. Funds units & basic buildings.
- **Crystal** — from crystal nodes. Funds tech, towers, hero skills.
- **Population cap** — raised by building Nests/Hatcheries.

### 5.2 Building Evolution (visual tiers)
Every structure **visibly grows** as it upgrades — players feel pride watching their kingdom rise:
`L1 dirt mound → L2 wood supports → L3 stone walls → L4 metal reinforcement → L5 glowing fortress.`

### 5.3 Units
Each unit: unique animation, idle behaviour, sounds, emotes, attack style.
- **Drones** clean antennae, carry tools, inspect rocks, wave, celebrate finished builds.
- Combat roster per faction: melee, ranged, siege, flyer, special.

### 5.4 Exploration & Secrets
- **Treasure chests** (Wood → Iron → Crystal → Royal → Legendary) drop XP, resources, cosmetics, titles, frames; **rarely** an optional NFT collectible.
- **Hidden dungeons** behind secret rocks: mini-boss + puzzle + relic + lore. Entrances relocate each match.
- **Hundreds of easter eggs**: golden spoon skeleton, sword-in-stone, sleeping giant beetle, secret dev room, golden mushroom, UFO crash, mysterious portal/merchant.

---

## 6. Game Modes
1v1 · 2v2 · 3v3 · 4v4 · Clan Wars · Tournament · Ranked Seasons · Spectator · Replay system.
**Future:** Co-op Raids · AI Kingdoms · Seasonal story campaigns · Community maps (moderated) · Cross-platform (PC + mobile).

---

## 7. Progression & Cosmetics (ALL cosmetic — never power)
Commander skins · Kingdom themes · Castle appearances · Flags · Titles · Portraits · Victory animations · Emotes · Loading screens · Music packs · Pet companions · Avatar frames · Banners.

## 8. Live Events (weekly content engine)
Crystal Festival · Zombie Fungus Infection · Spider Queen Invasion · Golden Roach Weekend · Treasure Hunt · Double XP · Kingdom Championship · Halloween Underground · Winter Caverns.

---

## 9. Art Direction
- **Style:** Pixar-quality creature design × realistic cave environments. Not cartoon, not photoreal — *stylised-real*.
- **Lighting:** volumetric light shafts, dynamic shadows, glowing crystals, biolume rim-light, cinematic fog.
- **FX:** particles, reflections, moving grass, flowing water, animated fungi, embers, spores.
- **Rule:** *nothing static.* Flags, mushrooms, crystals, smoke, water, machinery — all animate.

## 10. Audio
- Per-biome ambience (water drips, wind, distant cave noise, machinery, echoes, creature calls).
- Dynamic battle music (intensity scales with combat).
- Commander voice lines, unit barks, UI biolume stingers.

---

## 11. Technical Architecture

| Layer | Choice (recommended) | Why |
|-------|----------------------|-----|
| Marketing site | Static HTML/CSS/JS, zero-build, deploy to Vercel | instant "go live", no toolchain, fast on mobile |
| **Demo / vertical slice** | **HTML5 Canvas + vanilla JS (this repo)** | runs offline, no deps, proves the loop |
| Production game (phase 2+) | **Phaser 3 (2.5D)** → optional PixiJS/WebGL shaders for cave FX | fastest path to a fun, shippable, mobile-capable RTS |
| Cinematic 3D (stretch) | Three.js / R3F for hero & trailer moments | "Pixar" hero shots without 3D-RTS cost |
| Netcode (PvP) | Authoritative server, deterministic lockstep for RTS | cheat-resistant, replay-friendly |
| Backend | Supabase (accounts, cosmetics, seasons, leaderboards) | already in stack |
| Optional chain | EVM/Solana — cosmetic NFTs + collectibles only | reward layer, sandboxed from gameplay |

**Performance commandments (carry into every build):**
- Fixed logical canvas, rAF + delta time.
- Bake static backgrounds to offscreen canvas; blit, don't redraw.
- Cache per-type gradients in a `Map`; never recompute per frame.
- No `shadowBlur` in hot loops. Throttle HUD text to ~10fps.
- Cap particle/effect arrays. Pause heavy work off-screen.

---

## 12. Monetization (fair-first)
1. **Cosmetics shop** — skins, themes, emotes, pets. The core business.
2. **Battle Pass / Season track** — cosmetic rewards, free + premium lanes.
3. **Optional NFT collectibles** — rare cosmetic ownership, tradeable; *uncommon* drop chance so gameplay stays balanced.
4. **No pay-to-win. Ever.** This is the brand's moat.

## 13. Optional Blockchain Layer (sandboxed)
- Owns: cosmetic skins, collectibles, community-event trophies.
- Touches: **nothing** that affects match balance.
- Wallet is optional; the entire game is playable and progressable without it.
- Pre-launch security gate (rate limits, spend caps, RLS, no client secrets) applies before any on-chain feature ships.

---

## 14. Roadmap (6 phases)

| Phase | Deliverable | Status |
|-------|-------------|--------|
| **P0 — Pitch** | This bible + cinematic marketing site + playable slice | **THIS REPO** |
| P1 — Vertical slice+ | Phaser RTS: 1 faction, 1 biome, full economy + combat + AI | next |
| P2 — Core game | 5 factions, 6 commanders, 4 biomes, ranked 1v1 | — |
| P3 — World | 13 biomes, world events, weather, dungeons, easter eggs | — |
| P4 — Live ops | Seasons, live events, cosmetics shop, clans, tournaments | — |
| P5 — Platform | Mobile, community maps, co-op raids, optional chain layer | — |

## 15. North-Star KPIs
- D1 / D7 / D30 retention (game must be *sticky* without spend)
- Avg session length & matches/day
- % players who discover ≥1 secret (target the "months of discovery" feel)
- Wishlist → install → ranked-match conversion
- Cosmetic attach rate (never P2W pressure)

---

*Living document. Every feature added must restate which pillar it serves and pass the one-sentence test in §0.*