# AgentCraft — Brood Conflict
### Game Design Document v0.1

---

## 1. Overview

**AgentCraft** is a Terran‑focused real‑time strategy game built for Solana, designed to feel as close to StarCraft: Brood War as possible. Players build a Terran base, mine minerals, train Terran units, and compete in weekly faction wars — but all three playable factions are Terran sub‑factions, each with a distinct combat doctrine. The aesthetic is pure Brood War: real Terran sprites, no visual effects, no fluff.

- **Platform:** Web (mobile‑optimised canvas)
- **Blockchain:** Solana (token $ORE, base unlock 1 SOL)
- **Genre:** RTS / base‑builder / faction war
- **One‑line pitch:** "Brood War Terran, three ways."

---

## 2. Factions

Three playable **Terran sub‑factions**, chosen at game start. All three use the same Terran unit roster (SCV, Marine, etc.) and the same Terran building set. The difference is purely strategic — each gets a passive combat or economy bonus. The goal is to make every game feel like a Terran mirror match-up where doctrine, not race, decides the winner.

| Faction | Ethos | Passive Bonus |
|---|---|---|
| **The Forge** 🛡️ | Armoured, defensive | Armour +20%, Bunker defence +60% |
| **The Hive** 🐝 | Swarm, cost‑efficient | Units −20% cost |
| **The Syndicate** 🔮 | Stealth, economy | Mining yield +25%, Tech −20% cost |

---

## 3. Economy

### 3.1 Resources

| Resource | Symbol | Acquisition |
|---|---|---|
| **Minerals** | M | SCV mining trips from mineral patches |
| **$ORE** | ORE | On‑chain token; earned via Convergence, spent on unlocks |

Players start with **50 M**. Minerals are the primary in‑game currency for units, buildings, and upgrades.

### 3.2 Mining Loop

- SCVs walk from the Command Center to a mineral patch (~8‑second round trip).
- Each trip delivers **1 M × (1 + miningPerWorker bonus)** to the player's pool.
- **Tech upgrades** increase mining yield per SCV.
- Mining is **per‑trip** (not continuous) — ore ticks up only when the SCV reaches the CC.

### 3.3 Tech Tree

| Upgrade | Base Cost | Effect |
|---|---|---|
| **Engineering Bay** | 150 M | +2 M per SCV per trip (stacks) |
| **Comsat Scan** | 25 M | Reveals map / shields base for 10s |

Costs scale: `150 + (techLevel × 75)`. Syndicate pays 80% of tech costs.

---

## 4. Units & Buildings

### 4.1 Command Center

The heart of the base. Placed at map centre on game start. Produces SCVs.

### 4.2 SCV (Worker)

| Stat | Value |
|---|---|
| Cost | 50 M (ramps 1.15× per worker) |
| Role | Mineral mining |
| Animation | 2‑frame walk (frames 6, 12 on spritesheet) |
| Behaviour | Walk to mineral → wait → return to CC |

Worker cost: `floor(50 × 1.15^(workers − 1))`.

### 4.3 Marine (Fighter)

| Stat | Value |
|---|---|
| Cost | 50 M (Hive: 40 M) |
| Role | Combat / Convergence |
| Animation | 2‑frame stance (frames 0, 3) |
| Max visible | 12 on field; overflow counted in UI |

### 4.4 Bunker (Defence)

| Stat | Value |
|---|---|
| Cost | 100 M |
| Defence | +5 (Forge: +8) |
| Max placed | 6 |

---

## 5. Convergence

The core combat loop. Commit Marines for a sector assault, risking casualties for mineral reward.

### 5.1 Rules

- **Requirement:** 5+ Marines on field
- **Cooldown:** 30 seconds after each assault
- **Mechanic:** Player selects 1–N Marines to commit
- **Casualties:** 50% of committed Marines are KIA (rounded down)
- **Outcome:** Random placement (33% each):

| Placement | Multiplier |
|---|---|
| 1st (Victory) 🏆 | 1.4× mineral yield |
| 2nd (Draw) 🥈 | 1.0× |
| 3rd (Defeat) 🥉 | 0.6× |

**Yield formula:**
```
Base = committed × (0.8 + rand(0–0.7))
Yield = floor(Base × factionMultiplier × placementMultiplier)
```

Faction multipliers: Forge 1.15, Hive 1.05, Syndicate 1.1.

### 5.2 Weekly Faction War (Planned)

Each faction's total Convergence score across all players is tallied weekly. Winning faction receives $ORE rewards split by contribution.

---

## 6. Technology

### 6.1 Display

- Canvas (fixed aspect, responsive)
- Bottom panel UI on mobile (top‑left on desktop)
- Real‑time mineral count, unit counts, defence rating
- Event log for key actions

### 6.2 Sprites — Terran Only

All sprites are **Terran assets only**, extracted from StarCraft: Brood War via Spriters Resource. Every faction uses the exact same sprites — the Forge, the Hive, and the Syndicate all field Terran SCVs, Marines, Bunkers, and Command Centers. Gameplay differences come from stat bonuses, not cosmetic variation.

| Asset | File | Size |
|---|---|---|
| Command Center | `terran_b0_x224.png` | 150×86 |
| Bunker | `terran_b2_x152.png` | 46×75 |
| SCV (18 frames) | `SCV_sheet.png` | 368×164 |
| Marine (6 frames) | `MarineSprites.png` | 339×678 |
| Mineral Patch | `mineral_sprite.png` | 64×64 |
| Terrain Tile | `terrain_tile.png` | 32×32 |

**Not yet available** (no usable sprites acquired): Firebat, Medic, Vulture, Goliath, Siege Tank, Dropship, Science Vessel, Wraith wreckage, Valkyrie, Missile Turret, Supply Depot, Refinery, Engineering Bay, Academy, Factory, Starport, Science Facility, Armory, add‑on buildings. These are tracked as future additions to bring AgentCraft closer to a full Brood War unit roster.

### 6.3 Terrain

Dark green‑brown isometric grid, tiled from the 32×32 terrain tile. No visual effects — no glow, no pulsing, no overlays, no CSS animations. Pure Brood War Terran aesthetic — the game should feel like you're on the backwater colony maps of the Terran campaign.

---

## 7. Roadmap

| Phase | Features |
|---|---|
| **Alpha** (current) | Single‑player mining loop, Convergence battles, 3 Terran sub‑factions, Terran sprites only (SCV, Marine, CC, Bunker) |
| **Beta** | On‑chain $ORE, Solana wallet connect, leaderboard |
| **Sprite expansion** | Firebat, Medic, Vulture, Goliath, Siege Tank, Factory/Starport/Science buildings + add‑ons |
| **Launch** | Weekly faction wars, full Terran unit production queue |
| **Post‑launch** | League system, cosmetic unlocks, replay system |

---

## 8. Technical Notes

- **Served via:** Tailscale Funnel (direct, no reverse proxy)
- **Port:** 9091
- **Caching:** Disabled (`http-server -c-1`)
- **Canvas:** 1080×608 base resolution, DPR‑scaled up to 2×
- **Faction data:** Client‑side only (stubbed for now)
- **Blockchain:** All crypto stubbed; $ORE, 1 SOL base unlock

---

*Design notes and game data are wiki‑verified, not training‑data guesses.*