Bullosseum/DESIGN.md

# Bullosseum — Game Design Document

> Living document. `?` marks open questions.

---

## Elevator Pitch

You are the bull. Waves of cowboys, matadors, and gladiators pour into your arena — each with their own tricks to dodge or counter your charge. Survive, wreck things, pick upgrades. Every run is different. Goofy low-poly mayhem.

---

## Art Direction

- **Style:** Low-poly, chunky geometry, flat or minimal shading
- **Tone:** Goofy and physical — think *Gang Beasts* meets *Vampire Survivors* energy
- **Camera:** Third-person, spring-arm collision avoidance
- **Palette:** Warm sand/terracotta arena, vivid faction colours (red/gold for matadors, brown/blue for cowboys, iron/purple for gladiators)
- **Particles:** Stylised cartoon puffs — dust, impact sparks, ragdoll stars
- **Audio direction:** ?

---

## Confirmed Mechanics

- Third-person bull locomotion with momentum (walk, charge)
- Wide committed turning arc during charge — charges feel like commitments
- Visual turn lag (body leans)
- Spring-arm camera with zoom
- Sand dust particles at hooves (walk = small, charge = big)
- Jolt Physics backend

---

## Run Structure (Vampire Survivors-inspired)

```
Start run → Wave spawns → Kill enemies → Wave cleared → Pick upgrade → Next wave → ... → Die or achieve target
```

- **No hard time limit per wave** — pressure comes from enemy density escalating
- **Upgrade picks between waves** — choose 1 of 3 options (stat, ability, passive synergy)
- **Fail state is soft** — getting overwhelmed is a death spiral, not a timeout. You stop being able to charge effectively and get cornered
- **Run length:** ? (15–25 minutes for a full run feels right for web)
- **Meta progression:** ? Unlock new starting abilities or bull cosmetics across runs

### Wave Escalation — Faction Ramp

Factions are introduced one at a time so each mechanic gets space to teach itself before mixing begins.

| Waves | Faction makeup | Boss |
|---|---|---|
| 1–3 | Matadors only | — |
| 4 | Matadors only | El Presidente |
| 5–7 | Matadors + Cowboys introduced | — |
| 8 | Mixed (matadors + cowboys) | Sheriff |
| 9–11 | All three factions introduced | — |
| 12 | Mixed (all three) | Centurion |
| 13+ | Full chaos — all factions, escalating density | Repeat bosses + ? final boss |

- Each new faction's first wave is a "pure" wave so the player can learn the pattern before it mixes
- Bosses appear solo — the arena clears before a boss spawns, making it feel like a duel
- ? After wave 12, does a loop begin (harder repeat) or does a final boss end the run?

---

## Enemy Factions

### Matadors (the classics)
The trickiest faction — they're designed around baiting your charge.

| Enemy | Behaviour |
|---|---|
| Matador | Waves red cape to draw your charge, sidesteps at last moment. Must catch them off-guard or predict the dodge |
| Banderillero | Plants slow-flags in the ground — charges into one stuns the bull briefly |
| Picador | Mounted on horse, tanky, slow. Horse must be hit first before the rider is vulnerable |
| ? El Presidente (boss) | Summons matadors and teleports around the arena in bursts |

### Cowboys
The herd faction — individually easy, dangerous in groups.

| Enemy | Behaviour |
|---|---|
| Cowboy | Throws lasso to root you for 1–2s, then runs. Easy to hit, just annoying |
| Wrangler | Herds other enemies toward you — a force multiplier |
| Mounted Cowboy | Circles you on horseback, throwing dynamite. Must cut off the riding arc |
| ? Sheriff (boss) | Shotgun blast that staggers the bull; spawns deputies on death |

### Gladiators
The armour faction — charge angles matter.

| Enemy | Behaviour |
|---|---|
| Legionary | Front shield absorbs charges completely. Must hit from the side or behind |
| Net-thrower | Long-range root that holds you in place for 3s |
| Archer | Stationary on elevated platform (arena wall edge), fires slowing arrows |
| ? Centurion (boss) | Buffs nearby gladiators, has a charge-reflect shield that bounces you back |

---

## Ability System

Three slots total — always the same structure, filled differently every run.

```
[Charge ──────────] [Medium  □] [Ultimate  □]
   always on           1 slot      1 slot
```

### Slot 1 — Charge (always on)
| | Description |
|---|---|
| **Charge** | Hold to build, release to sprint. Committed arc, hard to steer. The foundation everything else is built around |

### Slot 2 — Medium Ability
Cooldown ~8–15s. Tactical, reactive, fills gaps that charge can't. One equipped at a time.

| Ability | Description | Good against |
|---|---|---|
| **Stomp** | Slam front hooves — short-range AoE stun | Matador clusters, anything close |
| **Gore** | Upward headbutt — launches a single target | Shielded gladiators (bypasses front shield) |
| **Tail Whip** | 360° sweep behind and to the sides | Cowboys lassooing from behind |
| **Bull Roar** | Knockback shockwave — no damage, pure space creation | Net-throwers, tight groups |
| **Ground Pound** | From a jump, landing creates a shockwave crater | Mounted enemies (dismounts them) |
| **Counter** | Narrow window — if you charge as an attack lands, explosive ricochet | Picadors, centurion reflect |

### Slot 3 — Ultimate Ability
Cooldown ~35–50s, or requires a full charge meter. High impact. One equipped at a time.

| Ability | Description | Good against |
|---|---|---|
| **Stampede** | ~5s of zero deceleration — can't stop or steer well, flattens everything in the path | Boss phases, dense waves |
| **Enrage** | ~8s berserk: charge speed +60%, hitbox wider, ignores all slows and roots | Lasso/net-heavy waves |
| **Red Mist** | Every enemy on screen gets a red target marker and is pulled slightly toward you — brief guaranteed hits | Matador dodge phase |
| **Thunder Horn** | Next charge is electrified — chains damage to up to 4 nearby enemies on contact | Gladiator formations |
| **Call of the Herd** | Summon 3 ghost bulls that charge in parallel alongside you for 6s | Any — pure chaos |

### Card Pick Screen (between every wave)
Game pauses. Three cards shown — pick one.

| Card type | Examples |
|---|---|
| **New medium** | Swap current medium for a different one |
| **New ultimate** | Swap current ultimate for a different one |
| **Stat boost** | +charge speed, +turn rate, −medium cooldown, −ultimate cooldown |
| **Passive modifier** | Changes how your *current* ability behaves (see below) |
| **Synergy** | Unlocks a cross-ability combo effect |

**Passive modifier examples:**
- Stomp → "Dust Blind" — stun cloud also blocks enemy vision for 2s
- Gore → "Pinball" — launched enemy bounces off walls and damages others on landing
- Stampede → "Aftershock" — leaves a trembling ground trail that slows enemies for 5s
- Enrage → "Bloodlust" — kills during enrage reduce remaining cooldown

**Synergy examples:**
- Charge + Stomp = "Seismic Run" — charging for 2s+ turns your next stomp into a ground wave
- Gore + Thunder Horn = "Lightning Rod" — electrified gore sends a chain to the whole group
- ? Others to discover during design

---

## Arena Design

Each faction maps to an arena environment. Mixed-faction waves could transition the arena or blend themes.

| Faction | Arena | Hazards |
|---|---|---|
| Matadors | Sand bullring, wooden barrier ring | Flags slow movement, open centre is the danger zone |
| Cowboys | Frontier rodeo grounds, hay bales, fences | Lasso posts (rope traps), horse stampede lanes |
| Gladiators | Roman colosseum, stone floor, iron gates | Archer towers on walls, spike traps, wet stone (slide) |

- ? Does the arena change mid-run or is one arena selected at run start?
- ? Destructible fence/barrier sections throughout?

---

## Core Loop Revisited

```
Move → Spot threat pattern → Position approach angle → Charge/Ability → Chain hits → Wave clear
         ↑                                                                                  ↓
    Dodge/react to debuffs (lasso, net, slow-flag)                            Pick upgrade (1 of 3)
```

The **positioning** step is where skill expression lives: which enemy to hit first, what angle to approach a shielded gladiator, whether to charge the matador or fake him out.

---

## Open Questions

1. **Meta progression** — cosmetic unlocks only, or do you unlock new starting medium/ultimate options across runs?
2. **Arena change** — single arena per run, or does the arena theme shift when a new faction is introduced mid-run?
3. **After wave 12** — infinite loop with scaling difficulty, or a final boss that ends the run cleanly?
4. **Ability replacement** — when you pick a new medium/ultimate card, does it always replace the slot, or can you upgrade an existing ability through repeated picks (level 1→2→3)?
5. **Web scope** — vertical slice (matadors only, 4 waves, one ability tree) or full 12-wave game?

---

## References

- *Vampire Survivors* — wave escalation, upgrade pick loop, run length
- *Gang Beasts* — ragdoll slapstick commitment
- *Katamari* / *Donut County* — simple core verb scaled through variety
- *Superhot* — charge-as-commitment, every move mattering
- *Cult of the Lamb* — faction variety with distinct visual languages