# Development Roadmap

Phased development plan for the Roguelite Platformer.

---

## Overview

| Phase | Focus | Dependencies |
|-------|-------|--------------|
| 1 | Core Loop | None |
| 2 | Juice & Polish | Phase 1 |
| 3 | Meta-Progression | Phase 1 |
| 4 | Content | Phases 1-3 |
| 5 | Polish & Release | Phases 1-4 |

---

## Phase 1: Core Loop

**Goal:** Playable prototype with basic mechanics

### Project Setup
- [ ] Initialize Vite + Phaser 3 + TypeScript project
- [ ] Configure ESLint and Prettier
- [ ] Set up project structure (`src/`, `assets/`, `docs/`)
- [ ] Create `game.config.ts` with Phaser configuration
- [ ] Create `physics.config.ts` with Arcade physics settings

### Base Scenes
- [ ] **BootScene** - Initialize game settings
- [ ] **PreloadScene** - Asset loading with progress bar
- [ ] **GameScene** - Main gameplay scene
- [ ] **GameOverScene** - Death screen with restart option

### Player
- [ ] Create `Player.ts` entity class
- [ ] Create `PlayerController.ts` for input handling
- [ ] Implement horizontal movement (left/right)
- [ ] Implement jump mechanics
- [ ] Implement **Coyote Time** (100ms grace period)
- [ ] Implement **Input Buffering** (100ms jump buffer)
- [ ] Implement **Variable Jump Height** (hold for higher jump)
- [ ] Implement **Edge Correction** (4px ledge assist)
- [ ] Add responsive controls (minimal acceleration/drag)

### Projectile System
- [ ] Create `Projectile.ts` entity class
- [ ] Implement projectile firing (direction based on player facing)
- [ ] Implement projectile pool (max 3 active)
- [ ] Implement cooldown system (~3 seconds per projectile)
- [ ] Add projectile UI indicator in HUD

### Enemy (Patroller)
- [ ] Create `Enemy.ts` base class
- [ ] Create `Patroller.ts` enemy type
- [ ] Implement patrol behavior (back-and-forth movement)
- [ ] Implement platform edge detection
- [ ] Implement enemy states: ACTIVE, STUNNED
- [ ] Implement stun mechanic (3 seconds duration)
- [ ] Add visual stun indicator (circular timer)
- [ ] Implement collision: active enemy kills player
- [ ] Implement collision: stunned enemy is passable

### Collectibles
- [ ] Create `Coin.ts` entity class
- [ ] Implement coin collection mechanics
- [ ] Add coin counter to HUD
- [ ] Implement level completion condition (all coins collected)

### Level Structure
- [ ] Implement basic tilemap loading
- [ ] Create simple test level (single room)
- [ ] Implement player spawn point
- [ ] Implement level exit (triggers on all coins collected)
- [ ] Implement level transition logic

### Core HUD
- [ ] Create `UIScene.ts` (parallel overlay)
- [ ] Display coin counter (collected/total)
- [ ] Display projectile indicators with cooldowns
- [ ] Display current level number

### Game Over
- [ ] Implement player death on enemy contact
- [ ] Implement player death on hazard contact (spikes)
- [ ] Show Game Over screen with score
- [ ] Implement restart functionality

### Phase 1 Completion Criteria
- [ ] Player can move, jump, and shoot
- [ ] Game feel mechanics working (coyote time, input buffer, variable jump)
- [ ] Patroller enemy patrols and can be stunned
- [ ] Coins can be collected
- [ ] Level transitions work
- [ ] Death/restart cycle works

---

## Phase 2: Juice & Polish

**Goal:** Game feels good to play

### Particles
- [ ] Create `ParticleManager.ts` system
- [ ] **Dust particles** - on landing
- [ ] **Dust particles** - while running (periodic)
- [ ] **Projectile cloud** - on firing
- [ ] **Stun stars** - when enemy stunned
- [ ] **Coin sparkle** - coin idle animation
- [ ] **Death explosion** - on player death

### Visual Feedback
- [ ] Implement **Squash & Stretch** for player jump/land
- [ ] Implement **Squash** for enemy stun
- [ ] Add coin pulse animation
- [ ] Add projectile trail effect

### Screen Effects
- [ ] Create `CameraManager.ts` system
- [ ] Implement **Screen Shake** - micro shake on stun
- [ ] Implement **Screen Shake** - stronger shake on death
- [ ] Add settings option to disable screen shake

### Hitstop
- [ ] Implement **Freeze Frame** (2-3 frames) on projectile hit
- [ ] Apply hitstop to physics pause, not game pause

### Audio
- [ ] Create `AudioManager.ts` system
- [ ] **SFX**: Jump
- [ ] **SFX**: Land
- [ ] **SFX**: Shoot projectile
- [ ] **SFX**: Enemy stunned
- [ ] **SFX**: Coin collected
- [ ] **SFX**: Player death
- [ ] **SFX**: Level complete
- [ ] **SFX**: Menu selection
- [ ] **Music**: Gameplay loop
- [ ] **Music**: Menu theme
- [ ] Implement volume controls

### Phase 2 Completion Criteria
- [ ] All particle effects implemented
- [ ] Squash/stretch animations working
- [ ] Screen shake working with toggle option
- [ ] Hitstop adds impact to hits
- [ ] All sound effects in place
- [ ] Background music playing

---

## Phase 3: Meta-Progression

**Goal:** Death -> Shop -> New Run cycle

### Save System
- [ ] Create `SaveManager.ts` with localStorage
- [ ] Implement save data structure
- [ ] Implement save on state change
- [ ] Implement load on game start
- [ ] Implement save data migration (version support)

### State Management
- [ ] Create `GameStateManager.ts`
- [ ] Implement `RunState` (resets each run)
- [ ] Implement `MetaState` (persists across runs)
- [ ] Implement GasCoin currency system
- [ ] Implement coin -> GasCoin conversion (1:1 + level bonus)

### Shop Scene
- [ ] Create `ShopScene.ts`
- [ ] Design shop UI layout
- [ ] Implement upgrade display (name, description, price)
- [ ] Implement purchase mechanics
- [ ] Implement upgrade activation/deactivation
- [ ] Show owned upgrades vs available upgrades
- [ ] Show GasCoin balance

### Upgrade System
- [ ] Create `UpgradeManager.ts`
- [ ] Define `upgrades.config.ts` with all upgrades
- [ ] Implement upgrade effect application
- [ ] Implement 5-10 basic upgrades:
  - [ ] Light Boots (+10% speed)
  - [ ] Spring Boots (+15% jump)
  - [ ] Heavy Armor (+1 HP, -15% speed)
  - [ ] Large Magazine (+1 projectile)
  - [ ] Fast Reload (-20% cooldown)
  - [ ] Range Boost (+30% projectile range)
  - [ ] Strong Stun (+1s stun duration)
  - [ ] Magnet (coin attraction)
  - [ ] Eagle Eye (minimap)
  - [ ] Danger Sense (enemy highlight)

### Game Over Enhancement
- [ ] Show run statistics:
  - [ ] Levels completed
  - [ ] Coins collected
  - [ ] Enemies stunned
  - [ ] Time played
- [ ] Show GasCoins earned
- [ ] Add "Go to Shop" button
- [ ] Add "Play Again" button

### Phase 3 Completion Criteria
- [ ] Progress saves correctly
- [ ] GasCoins accumulate across runs
- [ ] Shop allows purchasing upgrades
- [ ] Purchased upgrades affect gameplay
- [ ] Game Over shows stats and earnings

---

## Phase 4: Content

**Goal:** Gameplay variety

### Additional Enemies
- [ ] **Jumper** - Vertical jumping enemy (level 3+)
- [ ] **Flyer** - Fixed flight path enemy (level 5+)
- [ ] **Chaser** - Slow pursuit enemy (level 7+)
- [ ] **Sprinter** - Fast patrol enemy (level 10+)
- [ ] Implement enemy spawn rules by level

### Hazards
- [ ] Create `Hazard.ts` base class
- [ ] **Spikes** - Static instant death (level 2+)
- [ ] **Falling Platform** - Collapses after 0.5s (level 4+)
- [ ] **Saw** - Moving along path (level 6+)
- [ ] **Turret** - Shoots at intervals (level 8+)
- [ ] **Laser** - Toggles on/off (level 10+)
- [ ] Implement hazard spawn rules by level

### Power-ups
- [ ] Create `PowerUp.ts` entity class
- [ ] **Shield** - Blocks 1 hit
- [ ] **Magnet** - Attracts coins (15s)
- [ ] **Clock** - Slows enemies 50% (10s)
- [ ] **Coffee** - +50% player speed (10s)
- [ ] **Infinity** - Unlimited projectiles (8s)
- [ ] **Ghost** - Phase through enemies (5s)
- [ ] Implement 10% spawn chance per level
- [ ] Add power-up timer to HUD

### Procedural Generation
- [ ] Create `LevelGenerator.ts`
- [ ] Create `RoomPlacer.ts` for room grid
- [ ] Create `PathValidator.ts` for path validation
- [ ] Design room templates (JSON)
- [ ] Implement 4x4 room grid system
- [ ] Implement guaranteed path algorithm
- [ ] Implement difficulty scaling:
  - [ ] Levels 1-2: 6-8 rooms, 5-8 coins, 2-3 enemies
  - [ ] Levels 3-5: 8-10 rooms, 8-12 coins, 4-6 enemies
  - [ ] Levels 6-9: 10-12 rooms, 12-16 coins, 6-8 enemies
  - [ ] Levels 10+: 12-16 rooms, 16-20 coins, 8-12 enemies
- [ ] Create `SeededRandom.ts` for deterministic generation

### More Upgrades
- [ ] **Double Jump** - Unlock: reach level 5
- [ ] **Dash** - Unlock: collect 500 coins in one run
- [ ] **Second Chance** - Unlock: die 50 times
- [ ] **Explosive Projectile** - Area stun, -1 ammo
- [ ] **Ricochet** - Bounces off walls
- [ ] **Rapid Fire** - -40% cooldown, -30% stun duration
- [ ] **Greed** - +50% coins, +25% enemies
- [ ] **Hardcore** - x2 score, no coyote time
- [ ] **Berserker** - Frenzy mode at 0 HP
- [ ] **Pacifist** - x3 score, no projectiles
- [ ] **Speedrun** - Time challenge mode

### Achievement System
- [ ] Create achievement tracking
- [ ] Implement achievement triggers
- [ ] Add achievement notifications
- [ ] Create achievement display in menu
- [ ] Implement unlock requirements for upgrades

### Phase 4 Completion Criteria
- [ ] All 5 enemy types implemented and balanced
- [ ] All 5 hazard types implemented
- [ ] All 6 power-ups working
- [ ] Procedural generation creates varied levels
- [ ] Difficulty scales appropriately
- [ ] Additional upgrades purchasable
- [ ] Achievements tracking and unlocking

---

## Phase 5: Polish & Release

**Goal:** Release-ready product

### Combo System
- [ ] Create `ScoreManager.ts`
- [ ] Implement combo multiplier (x1 -> x2 -> x3 -> x5 -> x10)
- [ ] Implement 2-second combo timeout
- [ ] Add combo display to HUD
- [ ] Implement level bonuses:
  - [ ] Fast completion (<30s): +50% score
  - [ ] No damage: +25% score
  - [ ] No projectiles: +100% score

### Leaderboard
- [ ] Implement local leaderboard (top 10)
- [ ] Create leaderboard display screen
- [ ] Add score entry on new high score
- [ ] Show rank on Game Over screen

### Full UI/UX
- [ ] Create `MenuScene.ts` with full menu:
  - [ ] Play button
  - [ ] Shop button
  - [ ] Leaderboard button
  - [ ] Settings button
  - [ ] Achievements button
- [ ] Create `PauseScene.ts`:
  - [ ] Continue button
  - [ ] Settings button
  - [ ] Show current seed
  - [ ] Quit to menu (with confirmation)
- [ ] Polish all UI transitions
- [ ] Add button hover/click feedback

### Seed System
- [ ] Display level seed on pause screen
- [ ] Implement seed input mode
- [ ] Add "Practice Mode" (seeded, no leaderboard)

### Settings
- [ ] Music volume slider
- [ ] SFX volume slider
- [ ] Screen shake toggle
- [ ] Show FPS toggle
- [ ] Reset progress (with confirmation)

### Balance Pass
- [ ] Tune player movement speeds
- [ ] Tune jump heights
- [ ] Tune projectile cooldowns
- [ ] Tune stun durations
- [ ] Tune enemy speeds and behaviors
- [ ] Tune upgrade costs
- [ ] Tune difficulty scaling
- [ ] Playtest and iterate

### Bug Fixing & QA
- [ ] Fix known bugs
- [ ] Test all features end-to-end
- [ ] Test save/load edge cases
- [ ] Test on multiple browsers
- [ ] Performance optimization
- [ ] Memory leak checks

### Phase 5 Completion Criteria
- [ ] Combo system adds depth to gameplay
- [ ] Leaderboard encourages replayability
- [ ] Full menu navigation working
- [ ] Seed system allows practice
- [ ] Settings all functional
- [ ] Game balanced and fair
- [ ] No critical bugs

---

## Future (Post-MVP)

### Backend Integration
- [ ] Global leaderboard API
- [ ] User accounts (optional)
- [ ] Cloud save sync

### Daily Challenges
- [ ] Daily seed generation
- [ ] Separate daily leaderboard
- [ ] Daily rewards

### Bosses
- [ ] Design boss mechanics
- [ ] Implement boss encounters (every 5 levels?)
- [ ] Boss-specific rewards

### Mobile Support
- [ ] Touch controls
- [ ] UI scaling
- [ ] Mobile-specific optimizations

### Multiplayer
- [ ] Race mode (2 players)
- [ ] Shared leaderboard
- [ ] Ghost replays

### Platform Release
- [ ] Steam integration
- [ ] Achievements (Steam)
- [ ] Cloud saves (Steam)

---

## Task Dependencies

```
Phase 1 (Core Loop)
    │
    ├──────────────────┐
    │                  │
    ▼                  ▼
Phase 2            Phase 3
(Juice)         (Meta-Progression)
    │                  │
    └─────────┬────────┘
              │
              ▼
        Phase 4 (Content)
              │
              ▼
        Phase 5 (Polish)
              │
              ▼
          RELEASE
              │
              ▼
        Future Updates
```

---

## Risk Mitigation

| Risk | Mitigation |
|------|------------|
| Scope creep | Stick to MVP features per phase |
| Game feel issues | Prioritize Phase 2 polish early |
| Balance problems | Iterative testing each phase |
| Save data corruption | Version migrations, backup system |
| Performance issues | Object pooling, culling from start |

---

## Success Metrics

### Phase 1
- Can play multiple rounds
- Death/restart cycle smooth
- Player movement feels responsive

### Phase 2
- Game "feels good" to play
- Feedback is satisfying
- Audio enhances experience

### Phase 3
- Players want to unlock upgrades
- Meta loop is engaging
- Progress feels meaningful

### Phase 4
- Variety keeps runs interesting
- Difficulty curve is fair
- Content feels sufficient

### Phase 5
- No critical bugs
- Performance is stable
- Ready for public release