Debug menu F1 (use ctrl to lock cam). Design.md doc

DESIGN.md

@@ -0,0 +1,205 @@
+# 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