From 43ee1ae9aa67b2f52be28413eb5872614518eba9 Mon Sep 17 00:00:00 2001 From: Dabit Date: Tue, 10 Mar 2026 14:26:16 +0100 Subject: [PATCH] docs: create roadmap (5 phases) --- .planning/REQUIREMENTS.md | 80 ++++++++++----------- .planning/ROADMAP.md | 144 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 102 +++++++++++++++++++++++++++ 3 files changed, 286 insertions(+), 40 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 35b384e..120cc86 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -98,49 +98,49 @@ 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 | +| CORE-01 | 1 | Pending | +| CORE-02 | 1 | Pending | +| CORE-03 | 1 | Pending | +| CORE-04 | 1 | Pending | +| CORE-05 | 2 | Pending | +| CORE-06 | 2 | Pending | +| CORE-07 | 1 | Pending | +| CORE-08 | 2 | Pending | +| AI-01 | 2 | Pending | +| AI-02 | 2 | Pending | +| AI-03 | 2 | Pending | +| AI-04 | 2 | Pending | +| 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 | Pending | +| 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: 0 -- Unmapped: 37 ⚠️ +- Mapped to phases: 37 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-03-10* -*Last updated: 2026-03-10 after initial definition* +*Last updated: 2026-03-10 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..83731e0 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,144 @@ +# Roadmap: Super Pong Next Gen + +**Project:** Super Pong Next Gen +**Created:** 2026-03-10 +**Granularity:** Coarse (5 phases) +**Total Requirements:** 37 v1 requirements + +--- + +## Phases + +- [ ] **Phase 1: Foundation** - Game loop, rendering, input, physics, collision +- [ ] **Phase 2: Core Gameplay** - AI opponent, second paddle, score tracking, state management +- [ ] **Phase 3: Complete Experience** - Screens, menus, audio, pause functionality +- [ ] **Phase 4: Polish & Depth** - Visual effects, power-ups, multiple arenas +- [ ] **Phase 5: Release** - Performance tuning, cross-browser testing, final validation + +--- + +## Phase Details + +### Phase 1: Foundation + +**Goal**: Build a solid technical foundation with game loop, rendering at correct DPI, responsive input, and working physics/collision so players can move a paddle and watch the ball react. + +**Depends on**: Nothing (first phase) + +**Requirements**: CORE-01, CORE-02, CORE-03, CORE-04, CORE-07, VFX-05 + +**Success Criteria** (what must be TRUE when this phase completes): + +1. Game canvas renders sharply on Retina/HiDPI displays (devicePixelRatio aware) +2. Ball moves continuously and bounces predictably off top and bottom walls +3. Player 1 can control paddle smoothly with W/S keys with minimal input lag +4. Ball angle changes based on where it hits the paddle (not purely geometric) +5. Ball speed increases gradually over the course of a match + +**Plans**: TBD + +--- + +### Phase 2: Core Gameplay + +**Goal**: Deliver a playable single-player game where players can engage with a responsive, skill-based AI opponent with meaningful difficulty progression. + +**Depends on**: Phase 1 + +**Requirements**: CORE-05, CORE-06, CORE-08, AI-01, AI-02, AI-03, AI-04 + +**Success Criteria** (what must be TRUE when this phase completes): + +1. Player 2 can control paddle with Up/Down arrow keys independently from Player 1 +2. AI opponent successfully tracks and intercepts the ball with behavior varying by difficulty +3. Easy AI is beatable by average players; Medium provides fair challenge; Hard requires skill +4. Player scores point when ball passes opponent's paddle +5. Match ends when a player reaches target score with clear game-over state +6. No memory leaks or event listener cleanup issues after multiple rounds + +**Plans**: TBD + +--- + +### Phase 3: Complete Experience + +**Goal**: Transform the game from a bare mechanic into a polished, navigable experience with proper UI flow, settings control, and audio feedback that respects browser autoplay policies. + +**Depends on**: Phase 2 + +**Requirements**: SCRN-01, SCRN-02, SCRN-03, SCRN-04, AUD-01, AUD-02, AUD-03, AUD-04, AUD-05 + +**Success Criteria** (what must be TRUE when this phase completes): + +1. Title screen displays with game name and visual branding +2. Mode select screen lets player choose Solo vs AI or 2-Player gameplay +3. Settings menu allows configuring AI difficulty, sound on/off, and color scheme +4. Game over screen shows match result and offers Play Again and Main Menu options +5. Sound effects play on paddle hit, wall hit, and scoring events +6. Audio initializes only after first user interaction (respects browser autoplay policy) +7. Sound can be toggled on/off from settings without breaking game state + +**Plans**: TBD + +--- + +### Phase 4: Polish & Depth + +**Goal**: Add visual "juice" and strategic depth through particle effects, power-ups, and arena variety, transforming a functional game into a captivating experience players want to replay. + +**Depends on**: Phase 3 + +**Requirements**: VFX-01, VFX-02, VFX-03, VFX-04, PWR-01, PWR-02, PWR-03, PWR-04, PWR-05, PWR-06, PWR-07, ARENA-01, ARENA-02, ARENA-03, ARENA-04 + +**Success Criteria** (what must be TRUE when this phase completes): + +1. Ball emits glowing aura that visibly intensifies as speed increases +2. Ball leaves fading motion trail behind it during play +3. Particles burst from impact point when ball hits paddle or wall +4. Screen shakes briefly when a player scores point +5. Power-ups spawn at random intervals; player collects by hitting with ball +6. Multi-ball power-up spawns second ball; Enlarged paddle increases collector's height; Speed boost accelerates ball; Slow time slows opponent's perception +7. Active power-up is visually indicated on collecting player's side +8. Default arena available with classic open Pong layout +9. Obstacle arena available with center barrier that deflects ball +10. Each arena has distinct visual theme with different colors and background style +11. Player can select arena from mode select or settings screen + +**Plans**: TBD + +--- + +### Phase 5: Release + +**Goal**: Verify the game performs reliably across target browsers and hardware, with no frame drops, no rendering issues on high-DPI displays, and all critical pitfalls mitigated. + +**Depends on**: Phase 4 + +**Requirements**: None (all requirements covered by phases 1-4; this phase is validation) + +**Success Criteria** (what must be TRUE when this phase completes): + +1. Game maintains 60 fps consistently during gameplay on target hardware (Chrome, Firefox, Safari, Edge) +2. No memory leaks detected after 10+ consecutive matches +3. Canvas rendering remains sharp on Retina/HiDPI displays (verified on real hardware) +4. Input lag remains <50ms across all browsers +5. All critical pitfalls identified in research are mitigated (tunneling, autoplay, AI balance, etc.) +6. Game runs correctly as a single static HTML file on any static host + +**Plans**: TBD + +--- + +## Progress + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation | 0/? | Not started | — | +| 2. Core Gameplay | 0/? | Not started | — | +| 3. Complete Experience | 0/? | Not started | — | +| 4. Polish & Depth | 0/? | Not started | — | +| 5. Release | 0/? | Not started | — | + +--- + +*Roadmap created: 2026-03-10* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..9eee1ac --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,102 @@ +# STATE: Super Pong Next Gen + +**Project Reference** +- **Core Value:** Pong reimagined with juice and depth — spectacular visuals, rich mechanics, complete game experience +- **Current Focus:** Roadmap created, ready for Phase 1 planning +- **Key Constraint:** Coarse granularity (5 phases max), HTML5 Canvas + vanilla JS, static deployment + +--- + +## Current Position + +| Attribute | Value | +|-----------|-------| +| **Phase** | Planning complete, ready to plan Phase 1 | +| **Plan** | None active yet | +| **Status** | Roadmap finalized, 37/37 requirements mapped | +| **Progress** | 0% (0 phases complete) | + +``` +[ ] 0% — Roadmap → Phase 1 planning +``` + +--- + +## Performance Metrics + +| Metric | Target | Status | +|--------|--------|--------| +| **Phase Coverage** | 100% (37/37 requirements mapped) | ✓ Complete | +| **Success Criteria** | 2-5 per phase | ✓ Complete | +| **Dependency Chain** | Linear (P1 → P2 → P3 → P4 → P5) | ✓ Validated | + +--- + +## Accumulated Context + +### Key Decisions Made + +1. **Coarse Granularity Compression:** Research suggested 10 phases; compressed to 5 by merging: + - Game loop + input + physics = Phase 1 + - Second paddle + AI = Phase 2 + - Menus + audio + pause = Phase 3 + - Visual effects + power-ups + arenas = Phase 4 + - Performance + testing = Phase 5 + +2. **Phase 5 (Release) Has No Requirements:** All 37 v1 requirements covered by phases 1-4. Phase 5 is purely validation (cross-browser, performance, pitfall mitigation). + +3. **Success Criteria Grounded in Research Pitfalls:** Each phase's criteria address critical pitfalls from research: + - Phase 1: DPI scaling, game loop timing + - Phase 2: Ball tunneling, input lag, AI balance + - Phase 3: Audio autoplay policy + - Phase 4: Power-up balance + - Phase 5: Performance, memory leaks, cross-browser + +### Coverage Validation + +**Total v1 Requirements:** 37 +- CORE (8): All mapped to Phase 1-2 +- AI (4): All mapped to Phase 2 +- SCRN (4): All mapped to Phase 3 +- VFX (5): All mapped to Phase 1 (DPI) and Phase 4 (particles/glow/trails/shake) +- PWR (7): All mapped to Phase 4 +- ARENA (4): All mapped to Phase 4 +- AUD (5): All mapped to Phase 3 + +**Unmapped Requirements:** 0 ✓ +**Coverage:** 100% ✓ + +### Research Alignment + +- Phase 1 addresses Research Pitfalls: #1 (Game Loop Timing), #2 (Canvas DPI Scaling) +- Phase 2 addresses Research Pitfalls: #3 (Ball Tunneling), #4 (Input Lag), #5 (AI Difficulty Balance) +- Phase 3 addresses Research Pitfall: #6 (WebAudio Autoplay Policy) +- Phase 4 addresses Research Pitfalls: #7 (Power-Up Balance) +- Phase 5 addresses Research Pitfall: #8 (Memory Leaks) + +--- + +## Session Continuity + +### What Just Happened + +Roadmap derived from 37 v1 requirements organized into 5 phases, each with 2-5 observable success criteria. Granularity set to coarse; 10-phase research recommendation compressed by grouping related technical work. + +### What Comes Next + +1. `/gsd:plan-phase 1` — Decompose Phase 1 into executable plans +2. Continue through phases 2-5 +3. Execute plans in dependency order +4. Validate success criteria at each phase completion + +### Known Blockers + +None. All context available, all requirements mapped, roadmap ready for planning. + +### Decisions Pending + +None. Roadmap finalized; awaiting user approval before phase planning begins. + +--- + +*State initialized: 2026-03-10*