gijs_pong/.planning/REQUIREMENTS.md

# Requirements: Super Pong Next Gen

**Defined:** 2026-03-10
**Core Value:** Pong reimagined with juice and depth — spectacular visuals, rich mechanics, complete game experience

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Core Gameplay

- [x] **CORE-01**: Ball moves continuously and bounces off top and bottom walls
- [x] **CORE-02**: Each player controls a paddle that deflects the ball
- [x] **CORE-03**: Ball angle changes based on where it hits the paddle (not purely geometric)
- [x] **CORE-04**: Ball speed increases gradually over the course of a match
- [ ] **CORE-05**: Player scores a point when ball passes opponent's paddle
- [ ] **CORE-06**: Match ends when a player reaches the target score (first to N points)
- [x] **CORE-07**: Player 1 controls paddle with keyboard (W/S keys)
- [x] **CORE-08**: Player 2 controls paddle with keyboard (Up/Down arrow keys)

### AI Opponent

- [x] **AI-01**: AI opponent tracks and intercepts the ball
- [x] **AI-02**: Easy difficulty: AI reacts slowly with error margin — beatable by any player
- [x] **AI-03**: Medium difficulty: AI reacts at moderate speed — provides fair challenge
- [x] **AI-04**: Hard difficulty: AI reacts fast but not perfectly — requires skill to beat

### Screens

- [ ] **SCRN-01**: Title screen displays game name with visual branding
- [ ] **SCRN-02**: Mode select screen lets player choose Solo vs AI or 2-Player
- [ ] **SCRN-03**: Settings menu allows configuring AI difficulty, sound on/off, and color scheme
- [ ] **SCRN-04**: Game over screen shows match result (winner) and offers Play Again and Main Menu options

### Visual Effects

- [ ] **VFX-01**: Ball emits a glowing aura that intensifies as speed increases
- [ ] **VFX-02**: Ball leaves a fading motion trail behind it
- [ ] **VFX-03**: Particles burst from ball impact point when ball hits paddle or wall
- [ ] **VFX-04**: Screen shakes briefly when a player scores a point
- [x] **VFX-05**: Canvas renders sharply on Retina/HiDPI displays (devicePixelRatio aware)

### Power-Ups

- [ ] **PWR-01**: Power-up spawns in the arena at random intervals during a match
- [ ] **PWR-02**: Player collects a power-up by hitting it with the ball
- [ ] **PWR-03**: Multi-ball power-up spawns a second ball in play
- [ ] **PWR-04**: Enlarged paddle power-up temporarily increases collector's paddle height
- [ ] **PWR-05**: Speed boost power-up temporarily increases ball speed
- [ ] **PWR-06**: Slow time power-up temporarily slows the opponent's ball perception (slows everything except collector's paddle)
- [ ] **PWR-07**: Active power-up is visually indicated on the collecting player's side

### Arenas

- [ ] **ARENA-01**: Default arena: classic open Pong layout
- [ ] **ARENA-02**: Obstacle arena: center barrier or pair of obstacles that deflect the ball
- [ ] **ARENA-03**: Each arena has a distinct visual theme (colors, background style)
- [ ] **ARENA-04**: Player selects arena from mode select or settings screen

### Audio

- [ ] **AUD-01**: Sound effect plays when ball hits a paddle
- [ ] **AUD-02**: Sound effect plays when ball hits top or bottom wall
- [ ] **AUD-03**: Sound effect plays when a player scores a point
- [ ] **AUD-04**: Audio context initializes only after first user interaction (respects browser autoplay policy)
- [ ] **AUD-05**: Sound can be toggled on/off from settings

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Experience

- **EXP-01**: Pause screen with resume option mid-match
- **EXP-02**: Background music loop during gameplay

### Content

- **CONT-01**: Third arena variant with moving obstacles
- **CONT-02**: Difficulty progression beyond hard (adaptive AI)
- **CONT-03**: Combo counter for consecutive paddle hits

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Online multiplayer | No backend, high complexity — out of scope for v1 |
| Mobile touch controls | Keyboard-first; separate design problem |
| Persistent leaderboards / accounts | Requires database / server |
| More than 4 power-up types | Research warns balance becomes unmanageable beyond 4 |
| Tutorial flow | Pong teaches itself; tutorial adds complexity for no gain |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| CORE-01 | 1 | Complete |
| CORE-02 | 1 | Complete |
| CORE-03 | 1 | Complete |
| CORE-04 | 1 | Complete |
| CORE-05 | 2 | Pending |
| CORE-06 | 2 | Pending |
| CORE-07 | 1 | Complete |
| CORE-08 | 2 | Complete |
| AI-01 | 2 | Complete |
| AI-02 | 2 | Complete |
| AI-03 | 2 | Complete |
| AI-04 | 2 | Complete |
| SCRN-01 | 3 | Pending |
| SCRN-02 | 3 | Pending |
| SCRN-03 | 3 | Pending |
| SCRN-04 | 3 | Pending |
| VFX-01 | 4 | Pending |
| VFX-02 | 4 | Pending |
| VFX-03 | 4 | Pending |
| VFX-04 | 4 | Pending |
| VFX-05 | 1 | Complete |
| PWR-01 | 4 | Pending |
| PWR-02 | 4 | Pending |
| PWR-03 | 4 | Pending |
| PWR-04 | 4 | Pending |
| PWR-05 | 4 | Pending |
| PWR-06 | 4 | Pending |
| PWR-07 | 4 | Pending |
| ARENA-01 | 4 | Pending |
| ARENA-02 | 4 | Pending |
| ARENA-03 | 4 | Pending |
| ARENA-04 | 4 | Pending |
| AUD-01 | 3 | Pending |
| AUD-02 | 3 | Pending |
| AUD-03 | 3 | Pending |
| AUD-04 | 3 | Pending |
| AUD-05 | 3 | Pending |

**Coverage:**
- v1 requirements: 37 total
- Mapped to phases: 37
- Unmapped: 0 ✓

---
*Requirements defined: 2026-03-10*
*Last updated: 2026-03-10 after roadmap creation*