# Botfights: 30-Day Production Plan

## Context

Botfights is a procedural fighting game (Vue 3 + Kaplay + Hono/SQLite) where AI bots battle through challenge rounds with pixel art sprites, synthesized audio, and choreographed fight animations. Currently a working prototype with 6 character archetypes, 42 choreographies, 4 music tracks, 6 voice profiles, ~45 challenge prompts, and 12 mock bots. The goal is to scale this to production-grade content (100 characters, 300 moves, 10,000 challenges, 20 songs, 30 voices, 30+ arenas) and build an overnight fight loop that runs autonomously.

---

## Phase 1: Module Splitting (Days 1-6)

The 3 monolith files must be split before any content scaling. Without this, adding content to 3500-line files is unmaintainable.

### Day 1-2: Split `sprites.ts` (954 lines)

```
frontend/src/game/sprites/
  index.ts              -- re-exports generateSpriteSheet, getBotColors, etc.
  palette.ts            -- makePal, parseHSL, Pal interface
  constants.ts          -- FRAME_SIZE, ANIMATIONS, INTERNAL, SCALE
  drawing.ts            -- px(), box(), fill() drawing primitives
  base-body.ts          -- drawFrame() core body/head/arms/legs/pose logic
  archetypes/
    index.ts            -- archetype registry + roll function
    standard.ts         -- base (no extra features)
    lobster.ts          -- claws, antennae, segmented body, tail
    sheep.ts            -- wool, floppy ears, hooves
    cyborg.ts           -- metal plating, robot eye, wiring
    blob.ts             -- wobbly outline, googly eyes, drool
    tank.ts             -- armor, rivets, treads
  judge.ts              -- generateJudgeSpriteSheet()
```

Each archetype exports `{ name, weight, drawFeatures(ctx, pal, params) }`. The base-body calls the archetype's `drawFeatures` after the shared body drawing.

**Test:** Sprite preview page renders all 6 archetypes at all tiers identically to before.

### Day 3-4: Split `FightScene.ts` (~3500 lines)

```
frontend/src/game/fight/
  index.ts              -- createFightScene() orchestrator, returns controller
  types.ts              -- FightContext interface (k, W, H, GROUND_Y, HOME_A, HOME_B, helpers)
  constants.ts          -- ARENA_THEMES, spriteAnims, positions
  particles.ts          -- spawnSparks, spawnBulletHoles, spawnExhaust, etc.
  projectiles.ts        -- spawnProjectile, spawnBullet, spawnProp, spawnBarrage
  effects.ts            -- glitchRGB, scanlineGlitch, vhsTracking, dimensionalShift, etc.
  grotesque.ts          -- spawnGrotesqueDetails, destroyGrotesqueDetails
  arena-decor.ts        -- drawArenaDecor() per-arena backgrounds
  choreography/
    index.ts            -- choreographyMap registry, pickChoreography
    challenge-map.ts    -- CHALLENGE_THEMED + critMoves
    basic.ts            -- dashPunch, aerialSlam, flyingKick, uppercut
    ranged.ts           -- projectile, gunBurst, sniperShot, minigunSpray
    movement.ts         -- dashThrough, fullScreenDash, teleportStrike
    heavy.ts            -- groundPound, jetpackDive, bodySlam, suplex
    weapons.ts          -- swordSlash, hammerSmash, katanaCombo, chainsawRev, whipCrack
    vehicles.ts         -- motorbikeCharge, carSmash, boatCannon
    themed.ts           -- golfClubSmash, fireBreath, riddleBarrage, coinShower, etc.
  finishers.ts          -- playKO (4 styles), playPerfect
  round.ts              -- playRound, playTaunt, playDodge
```

**Critical pattern:** Choreography functions close over Kaplay context. Each file exports functions that take a `FightContext` object with all shared state/helpers.

**Test:** Replay several fights, verify all 42 choreographies work.

### Day 5-6: Split `sounds.ts` (1381 lines) + server modules

```
frontend/src/game/sounds/
  index.ts              -- re-exports
  context.ts            -- AudioContext setup, gain nodes
  primitives.ts         -- tone(), noise(), sweep() helpers
  sfx.ts                -- all sfx functions (punch, kick, special, etc.)
  voice.ts              -- voice profiles, speak(), announce*(), voice lines
  music/
    index.ts            -- startMusic(), stopMusic(), setMusicIntensity()
    types.ts            -- MusicTrack interface
    player.ts           -- playMusicBar() scheduler
    tracks/
      neon-fury.ts
      dark-circuit.ts
      pixel-blitz.ts
      skull-crusher.ts

server/src/engine/
  challenges/
    index.ts            -- pickChallenge(), registry
    types.ts            -- Challenge interfaces
    speed-blitz.ts      -- prompts array
    riddle.ts
    ... (one per type)
  mock/
    index.ts            -- runMockFight(), seedMockFights()
    bots.ts             -- MOCK_BOTS array
    answers.ts          -- MOCK_ANSWERS, BAD_ANSWERS
    trash-talk.ts       -- TRASH_TALK lines
```

**Test:** Full end-to-end fight replay with music, SFX, voice.

**Deliverable:** Identical functionality, ~40 small focused modules instead of 3 monoliths.

---

## Phase 2: Characters (Days 7-12)

### Day 7-8: New archetypes batch 1 (8 new)
- `dog.ts` -- floppy ears, wagging tail, snout with tongue, collar
- `cat.ts` -- pointed ears, whiskers, curled tail, slit eyes
- `cactus.ts` -- spikes everywhere, small flower on head, no real arms
- `pizza.ts` -- triangular body, cheese drip, pepperoni spots
- `mushroom.ts` -- dome cap head, spotted cap, stubby legs, spore particles
- `shark.ts` -- dorsal fin, teeth row, tail fin
- `penguin.ts` -- tuxedo coloring, beak, flippers
- `octopus.ts` -- 4 visible tentacles, large head, suction cups

### Day 9-10: New archetypes batch 2 (8 more)
- `skeleton.ts` -- visible ribs, skull head, bony limbs
- `ghost.ts` -- semi-transparent, wavy bottom (no legs), glowing eyes
- `alien.ts` -- big head, huge eyes, antenna, green tint
- `dinosaur.ts` -- tail, tiny arms, spiky back, big jaw
- `pirate.ts` -- eye patch, hat, peg leg, hook hand
- `ninja.ts` -- mask, headband, throwing star
- `cowboy.ts` -- hat, bandana, boots with spurs
- `wizard.ts` -- pointed hat, robe, staff replaces one arm, beard

### Day 11: Final archetypes + hybrid system
- `bee.ts` -- stripes, wings, stinger, antennae
- `frog.ts` -- wide mouth, bulging eyes, webbed feet, long tongue
- `snail.ts` -- shell on back, eye stalks, slime trail
- **Hybrid system:** 10% chance a bot combines features from 2 archetypes (lobster+sunglasses, sheep+robot arm, etc.)
- **Total:** 25 archetypes

### Day 12: 100 Named Bots + Seed Data
Expand `MOCK_BOTS` from 12 to 100 with distribution:
- ~5 tier-5, ~10 tier-4, ~20 tier-3, ~25 tier-2, ~25 tier-1, ~15 tier-0

Funny names by theme:
- **Tech:** `segfault_sarah`, `stack_overflow_sam`, `infinite_loop_larry`, `null_reference_nancy`
- **Food:** `pizza_pete`, `sushi_sensei`, `taco_tornado`, `burrito_bomber`
- **Animals:** `mega_lobster_xl`, `tactical_penguin`, `stealth_shark_3000`
- **Pop culture:** `keyboard_warrior`, `meme_lord_420`, `reply_guy_9000`
- **Absurd:** `sentient_toaster`, `angry_calculator`, `philosophical_fork`

Pre-seed 200 fight history records.

**Test:** `pnpm seed`, verify 100 bots, leaderboard renders, sprite preview shows all archetypes.

---

## Phase 3: Choreographies (Days 13-19)

Scale from 42 to 300 choreographies. Each follows the established function signature.

### Day 13-14: Food choreographies (~30 moves)
`choreography/food.ts`:
- `pizzaThrow`, `bananaSlip`, `pieFace`, `hotDogWhip`, `sushiRoll`
- `watermelonSmash`, `popcornBarrage`, `burritoWrap`, `cakeExplosion`, `iceCreamFreeze`
- `tacoSlam`, `donutSpin`, `breadSlap`, `eggCrack`, `soupSplash`
- `cheeseWheel`, `grapeShot`, `pineappleGrenade`, `cornCobGatling`, `steakSlap`
- Plus ~10 more food-themed variations

### Day 15-16: Spins/flips (~25) + vehicles (~15)
`choreography/spins.ts`:
- `spin720`, `backflipKick`, `tornadoSpin`, `corkscrewDive`, `cartwheel`
- `helicopterSpin`, `barrelRoll`, `frontflipSlam`, `spinningPiledriver`
- `doubleBackflip`, `wallflip`, `moonwalk`, `breakdanceSpin`, `drillKick`
- Plus more rotation/flip-based moves

`choreography/vehicles.ts` expansion:
- `skateboard`, `helicopter`, `shoppingCart`, `zamboni`, `rocketSled`
- `segway`, `unicycle`, `bulldozer`, `rollercoaster`, `cannonball`
- Plus existing (motorbikeCharge, carSmash, boatCannon)

### Day 17-18: Animal (~20) + energy (~20) + silly (~25)
`choreography/animal.ts`:
- `sharkBite`, `beeSwarm`, `frogTongue`, `stampede`, `spiderWeb`
- `snakeStrike`, `bearHug`, `eagleDive`, `ramCharge`, `crocodileRoll`

`choreography/energy.ts`:
- `kamehameha`, `hadouken`, `spiritBomb`, `thunderStrike`, `dragonPunch`
- `novaBlast`, `blackHole`, `sonicBoom`, `plasmaWhip`, `quantumTunnel`

`choreography/silly.ts`:
- `pillowFight`, `tickleAttack`, `selfieStun`, `vibeCheck`, `dabOnEm`
- `yeetThrow`, `airHorn`, `rubberChicken`, `bananaPeelChain`, `confettiCannon`
- `invisibleWall`, `slipNSlide`, `trampolineBounce`, `bubbleWrap`, `kazooBlast`

### Day 19: Wire all 300 choreographies
- Register all in `choreographyMap`
- Update `CHALLENGE_THEMED` with new move pools per challenge type
- Balance `pickChoreography` weights for maximum variety
- Add new moves to `critMoves` and `wild` arrays

**Test:** Run 50 fight replays, verify no crashes, observe variety.

---

## Phase 4: Challenges (Days 20-22)

Scale from ~45 prompts to ~10,000 challenges. Hilarious, modern, pop culture, stupid/silly.

### Day 20: Challenge bank architecture
```
server/src/engine/challenges/
  banks/
    speed-blitz.ts      -- 1,200+ prompts
    riddle.ts           -- 500+ riddles
    code-golf.ts        -- 400+ challenges
    roast-battle.ts     -- 600+ roast prompts
    hallucination.ts    -- 800+ true/false
    token-economy.ts    -- 500+ explain prompts
    creative-writing.ts -- 400+ creative prompts
    math-blitz.ts       -- 1,500+ math problems (many templated)
    trap-card.ts        -- 600+ prompt injections
    meme-knowledge.ts   -- 500+ meme identification (NEW TYPE)
    emoji-translate.ts  -- 400+ emoji challenges (NEW TYPE)
    debate.ts           -- 300+ debate topics (NEW TYPE)
    fill-the-blank.ts   -- 400+ completions (NEW TYPE)
    reverse-engineer.ts -- 300+ output puzzles (NEW TYPE)
    survival.ts         -- 500+ escalating difficulty (NEW TYPE)
```

### Day 21: Build prompt banks (~10,000 total)
- Mix of hand-written and procedural templates
- Pop culture: "Is it true Elon Musk once fought a kangaroo?", "What would happen if the Minecraft creeper attended a job interview?"
- Modern/silly: "Explain blockchain to a medieval peasant", "Write a breakup text from a printer to its owner"
- Procedural templates for math/trivia: fill in numbers, countries, units

### Day 22: New challenge types + mock answers
- 6 new types: meme_knowledge, emoji_translate, debate, fill_the_blank, reverse_engineer, survival
- Scoring for each, mock answers for all 100 bots
- Wire into frontend `CHALLENGE_THEMED`

---

## Phase 5: Audio (Days 23-25)

### Day 23: 16 new music tracks (20 total)
Each track ~40 lines. Genre variety:
- 2x Synthwave (180-200 BPM), 2x Metal (250-280 BPM)
- 2x Chiptune (200-220 BPM), 2x Jazz Fusion (160-180 BPM)
- 2x Drum & Bass (170-175 BPM), 2x Lo-fi (140-160 BPM)
- 2x Ska Punk (210-230 BPM), 2x Boss Fight (280-300 BPM)

Intensity-based genre grouping:
- Low: lo-fi, jazz, chiptune | Medium: synthwave, ska punk
- High: metal, drum & bass | Max: boss fight

### Day 24: 24 new voice profiles (30 total)
New: whisper, manic, gravelly, chipper, deadpan, sports_caster, old_timey, drill_sergeant, surfer_dude, valley_girl, pirate_voice, robot_glitch, auctioneer, news_anchor, horror_narrator, lullaby, rage_quit, stoner, brit_posh, aussie, game_show, wrestling_announcer, noir_detective, anime_narrator

Expand voice line libraries to 300+ unique lines.

### Day 25: New SFX + arena-specific ambience
- 20 new SFX for new choreography types
- Arena-specific ambient background layers (beach waves, space hum, forest chirps)

---

## Phase 6: Scenes & Polish (Days 26-27)

### Day 26: 15+ new arenas (30+ total)
volcano, underwater, rooftop, train, kitchen, arcade, library, parking_lot, school, hospital, factory, castle, moon_base, ice_rink, stadium

New modifiers: fire_boost, ice_slow, gravity_low, double_damage, chaos_mode

### Day 27: Scene transitions + animated elements
- 4 transition styles: wipe, circle close/open, pixel dissolve, glitch cut
- Animated arena backgrounds: floating particles, dynamic lighting
- Enhanced spectator crowd reactions tied to round outcomes

---

## Phase 7: Production Loop (Days 28-30)

### Day 28: Fight scheduler + matchmaking
`server/src/engine/scheduler.ts`:
- `startScheduler(intervalMs)` -- Elo-based matchmaking loop
- Routes: `POST /api/scheduler/start|stop`, `GET /api/scheduler/status`
- Queue with rate limiting + bot cooldown

### Day 29: Headless mode + overnight operation
- `pnpm run fight-loop` for headless scheduler
- Env vars: `FIGHT_INTERVAL_MS`, `FIGHTS_PER_BATCH`, `MAX_CONCURRENT`
- Structured JSON logging, graceful SIGTERM shutdown
- `GET /api/stats` endpoint, health monitoring

### Day 30: Final seed data + integration test
- Generate: 100 bots, 500+ fight history
- Verify: Elo bell curve, tier distribution
- Full E2E: seed -> dev -> replay 10 fights -> fight-loop -> 100 fights -> typecheck + lint

---

## Dependency Graph

```
Phase 1 (Split) --- BLOCKS EVERYTHING
  |
  +-- Phase 2 (Characters)     -- independent after Phase 1
  +-- Phase 3 (Choreographies) -- independent after Phase 1
  +-- Phase 4 (Challenges)     -- independent after Phase 1
  +-- Phase 5 (Audio)          -- independent after Phase 1
  |
  +-- Phase 6 (Scenes)         -- needs Phase 1 + Phase 3
  +-- Phase 7 (Production)     -- needs Phase 2 + Phase 4
```

## Testing Strategy

After every day:
1. `pnpm typecheck` -- catches import/export errors
2. Sprite preview page -- verify all archetypes render
3. Watch 5 random fight replays -- no crashes, visual variety
4. Audio check -- music, voices, SFX all play
5. `pnpm seed` -- verify DB has expected data

## Critical Files

- `frontend/src/game/sprites.ts` -> split into `sprites/` directory
- `frontend/src/game/FightScene.ts` -> split into `fight/` directory
- `frontend/src/game/sounds.ts` -> split into `sounds/` directory
- `frontend/src/components/FightViewer.vue` -> update imports
- `server/src/engine/challenges.ts` -> split into `challenges/` directory
- `server/src/engine/mock.ts` -> split into `mock/` + expand to 100 bots
- `server/src/engine/arenas.ts` -> expand to 30+ arenas
- `server/src/seed.ts` -> update imports
- `server/src/routes/fights.ts` -> add scheduler routes