docs: define v1 requirements

.planning/REQUIREMENTS.md

@@ -0,0 +1,146 @@
+# 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
+
+- [ ] **CORE-01**: Ball moves continuously and bounces off top and bottom walls
+- [ ] **CORE-02**: Each player controls a paddle that deflects the ball
+- [ ] **CORE-03**: Ball angle changes based on where it hits the paddle (not purely geometric)
+- [ ] **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)
+- [ ] **CORE-07**: Player 1 controls paddle with keyboard (W/S keys)
+- [ ] **CORE-08**: Player 2 controls paddle with keyboard (Up/Down arrow keys)
+
+### AI Opponent
+
+- [ ] **AI-01**: AI opponent tracks and intercepts the ball
+- [ ] **AI-02**: Easy difficulty: AI reacts slowly with error margin — beatable by any player
+- [ ] **AI-03**: Medium difficulty: AI reacts at moderate speed — provides fair challenge
+- [ ] **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
+- [ ] **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 | — | Pending |
+| CORE-02 | — | Pending |
+| CORE-03 | — | Pending |
+| CORE-04 | — | Pending |
+| CORE-05 | — | Pending |
+| CORE-06 | — | Pending |
+| CORE-07 | — | Pending |
+| CORE-08 | — | Pending |
+| AI-01 | — | Pending |
+| AI-02 | — | Pending |
+| AI-03 | — | Pending |
+| AI-04 | — | Pending |
+| SCRN-01 | — | Pending |
+| SCRN-02 | — | Pending |
+| SCRN-03 | — | Pending |
+| SCRN-04 | — | Pending |
+| VFX-01 | — | Pending |
+| VFX-02 | — | Pending |
+| VFX-03 | — | Pending |
+| VFX-04 | — | Pending |
+| VFX-05 | — | Pending |
+| PWR-01 | — | Pending |
+| PWR-02 | — | Pending |
+| PWR-03 | — | Pending |
+| PWR-04 | — | Pending |
+| PWR-05 | — | Pending |
+| PWR-06 | — | Pending |
+| PWR-07 | — | Pending |
+| ARENA-01 | — | Pending |
+| ARENA-02 | — | Pending |
+| ARENA-03 | — | Pending |
+| ARENA-04 | — | Pending |
+| AUD-01 | — | Pending |
+| AUD-02 | — | Pending |
+| AUD-03 | — | Pending |
+| AUD-04 | — | Pending |
+| AUD-05 | — | Pending |
+
+**Coverage:**
+- v1 requirements: 37 total
+- Mapped to phases: 0
+- Unmapped: 37 ⚠️
+
+---
+*Requirements defined: 2026-03-10*
+*Last updated: 2026-03-10 after initial definition*