chicken-game/docs/ROADMAP.md

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