diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 438f174..3d5e342 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -1,146 +1,39 @@ -# Detailed Requirements for Defender Browser Clone -**Status**: Draft v0.1 - Initial capture for agent planning and implementation. -**Related**: See README.md for overview. Issues will reference specific sections. ---- +## UAT Checklist (v0.2 - Current) -## 1. Functional Requirements +**Preparation**: Open `index.html` (or serve). Play 5-10 minutes per tester. Note bugs, feel, suggestions in Issue comments or new issues. -### 1.1 Game World & Environment -- **FR-1.1.1**: Implement a horizontally wrapping playfield of configurable width (e.g. 4096-8192 world units). Viewport (canvas) shows ~1/4 to 1/2 of world at once. - - Acceptance: Player flying left continuously eventually returns to start position; no seams visible in terrain or entities. -- **FR-1.1.2**: Scrolling viewport smoothly follows player ship X position, with look-ahead or centered bias. Y scroll locked or minimal (focus on horizontal action). -- **FR-1.1.3**: Terrain generation: Simple procedural jagged ground (e.g. series of connected line segments or sine-based with noise, or pre-defined heightmap that tiles/wraps). Ground is solid; player/enemies/bombs collide or land on it. - - Acceptance: Terrain scrolls seamlessly with world; visually distinct from background; at least 3-5 "peaks/valleys" visible. -- **FR-1.1.4**: Background: Static or slowly parallax starfield (small white dots or simple shapes) in upper 60-70% of screen. Optional subtle nebula gradient. +### Core Controls & Flight (FR-1.2) +- [ ] Ship momentum responsive? (thrust feels good, no sticky controls) +- [ ] Can navigate terrain without frustration? Skim ground safely? +- [ ] World wrap seamless? -### 1.2 Player Entity & Controls -- **FR-1.2.1**: Player ship represented as simple geometric shape (triangle or arrow-like) or basic sprite. Supports facing left/right (flip or separate draw). -- **FR-1.2.2**: Physics: Velocity vector (vx, vy). Thrust input adds acceleration in desired direction (up, down, left, right). Friction/drag optional or low for arcade feel. Max speed cap. - - Acceptance: Ship feels responsive but with momentum; doesn't stop instantly; can "fly" in curves. -- **FR-1.2.3**: Input handling: Polled keyboard state (key pressed map). Arrow keys or WASD map to thrust directions. Prevent opposite simultaneous? Or allow for strafing feel. -- **FR-1.2.4**: Boundary: Player cannot fly off top/bottom of screen (clamp or bounce). Can skim close to terrain without instant death (small hitbox or grace). -- **FR-1.2.5**: Death condition: Overlap with enemy, enemy projectile, or terrain (precise hitbox). Lose 1 life, brief respawn invuln (2-3 sec, flashing), reset position to safe start. +### Combat (FR-1.3, 1.4) +- [ ] Laser accurate, satisfying? Rate of fire good? +- [ ] Enemies (landers, bombers) challenging but fair? AI seeks humans? +- [ ] Collisions feel fair? -### 1.3 Weapons & Special Abilities -- **FR-1.3.1**: Primary fire (Space or Ctrl): Spawn fast-moving laser bolt(s) from ship nose, traveling in facing direction (or fixed right if no facing). Bolts have limited lifetime or travel distance. Rate limit (e.g. 5-10/sec). - - Acceptance: Visual bolt (line or rect), destroys most enemy types on contact, disappears on hit or edge. -- **FR-1.3.2**: Smart Bomb (Shift or B): Limited stock (start 3-5). On activate: Destroy all on-screen enemies (and perhaps their projectiles). Visual: Expanding ring or flash + particles. Cooldown or stock decrement. - - Acceptance: Clears visible threats instantly; does not affect off-screen or player. -- **FR-1.3.3**: Hyperspace (H or Enter): Teleport player to random X,Y in safe zone (not inside terrain/enemy cluster). Small chance (~10-20%) of failure/death on bad spawn. Visual warp effect (shrink/expand or particles). +### Rescue (FR-1.5) +- [ ] Abduction visible? Shoot lander → human falls? +- [ ] Catching falling humans rewarding? Bonus points work? -### 1.4 Enemies & AI -- **FR-1.4.1**: Entity system supports multiple types with shared base (position, velocity, health, type tag). Update loop processes all. -- **FR-1.4.2 Lander**: - - Slow-medium speed flyer. - - Behavior: Wander or patrol horizontally, periodically dive toward nearest human on ground. If reaches human and not shot, "picks up" (human removed or attached), flies upward off-screen (human lost -> score penalty or mutant spawn?). - - Destroyed by 1-2 laser hits. -- **FR-1.4.3 Mutant**: - - Fast, zig-zag or homing toward player. - - Spawns from pods or failed abductions. - - More aggressive, higher points. -- **FR-1.4.4 Bomber**: - - Flies at constant height or pattern, periodically drops bomb projectile that falls with gravity or straight down, explodes on ground or contact. -- **FR-1.4.5 Pod / Swarmer**: - - Pod: Slow, durable. On death spawns 3-5 small fast erratic Swarmers. - - Swarmer: Tiny, high speed random or seek player briefly, low health. -- **FR-1.4.6 Baiter** (later waves): Fast, direct pursuit of player, appears when wave timer or low enemy count. -- **FR-1.4.7**: All enemies wrap X like world. Simple avoidance of terrain or bounce. Collision with player = mutual damage or player death + enemy death. +### Specials & Progression (FR-1.3, 1.7) +- [ ] Smart Bomb (Shift) effective screen clear? +- [ ] Hyperspace (H) fun/risky? +- [ ] Waves advance smoothly? Increasing difficulty? -### 1.5 Humans & Rescue Mechanics -- **FR-1.5.1**: 8-12 static or slowly walking human sprites/shapes on terrain surface (random or even spacing initially). -- **FR-1.5.2**: If lander reaches human position and "lands", human is abducted (remove human, perhaps visual carry animation). If lander reaches top of screen with human -> human dies (lose points or life? usually just lost human, wave harder). -- **FR-1.5.3**: Shooting lander while carrying human: Human detaches and falls (parachute or freefall animation). Player must maneuver ship to collide/catch the falling human (small window). -- **FR-1.5.4**: Successful catch: Player can "deposit" by flying low over empty terrain spot or auto on catch? Bonus points (e.g. 500-1000). Human returns to ground pool. -- **FR-1.5.5**: All humans lost or wave complete -> bonus or next wave. +### Polish (FR-1.6, 1.8, 1.9) +- [ ] Radar useful for awareness? +- [ ] HUD clear? Particles/explosions immersive? +- [ ] Audio cues (laser/explosion/catch) enhance experience? +- [ ] Pause/Game Over intuitive? -### 1.6 Radar / Mini-Map -- **FR-1.6.1**: Horizontal bar or strip at very top of canvas (10-20px high). Represents full world width scaled to canvas width. -- **FR-1.6.2**: Draw small colored shapes/dots for: - - Player: bright green or white triangle/dot. - - Landers/Humans: distinct colors (e.g. lander yellow, human blue, mutant red, etc.). - - Enemies aggregate or individual if not too many. -- **FR-1.6.3**: Updates every frame or throttled. No interaction, pure info. +### General +- [ ] 60 FPS stable? +- [ ] Fun factor? Reminiscent of classic Defender? +- [ ] Bugs/crashes? Edge cases (low lives, many entities)? -### 1.7 Scoring, Lives, Waves -- **FR-1.7.1**: Score increments on enemy destroy (different values: lander=150, mutant=300, etc.), human rescue bonus, smart bomb use? Display large at top-left. -- **FR-1.7.2**: High score persisted in localStorage, shown on title/game over. Simple 5-10 entry list with initials input on new high. -- **FR-1.7.3**: Lives: Start 3-5. Extra life every 10k or 20k points. Visual: small ship icons in HUD. -- **FR-1.7.4**: Wave system: Start wave 1. When all (or most) enemies cleared or after time, advance. Each wave: increase spawn rate, max active enemies, introduce new types or mutations (faster, more baiters). Display "WAVE X" on start. +**Pass Criteria**: All core [ ] marked, major bugs fixed, positive feedback on feel. Then advance to Phase 2. -### 1.8 Game States & UI -- **FR-1.8.1**: State machine: `TITLE` (attract/demo loop optional), `PLAYING`, `PAUSED`, `GAME_OVER`, `HIGH_SCORE_ENTRY`. -- **FR-1.8.2**: HUD always in PLAYING: Score, HiScore, Lives (icons), Wave, SmartBombs count, perhaps FPS debug toggle. -- **FR-1.8.3**: Title screen: Game name big, "Press SPACE to start", simple instructions or attract mode showing AI play? -- **FR-1.8.4**: Pause: Overlay dim + "PAUSED - Press P to resume". Stop updates but keep render. -- **FR-1.8.5**: Game Over: Big text, final score, "Press R to restart" or auto to title. If high score, prompt initials (3 letters via keyboard). - -### 1.9 Audio & Visual Effects -- **FR-1.9.1**: Web Audio context. Simple synth: laser = short high saw or square wave + decay; explosion = noise burst lowpass; thrust = low hum or whoosh; mutant siren = oscillating tone; smartbomb = whoosh + chime. - - Toggle mute button or key (M). Volume master or per type. -- **FR-1.9.2**: Particles: Array of {x,y,vx,vy,life,color,size}. Emit on explosion (many outward), thrust (few behind ship), bullet hit, human catch. Update: life--, pos += vel, alpha fade, remove dead. -- **FR-1.9.3**: Screen effects: On player death or big bomb, brief white flash or red tint + short camera shake (offset canvas draw by random small amount decaying). - -## 2. Non-Functional Requirements - -- **NFR-2.1 Performance**: Stable 60 FPS (or 30 fallback) on mid-range hardware (2020+ laptop i5/equivalent, integrated or discrete GPU). Measure with simple FPS counter. Avoid per-frame allocations in hot paths; pool objects. -- **NFR-2.2 Browser Support**: ES6+ JS, Canvas 2D. Tested latest 2 versions Chrome, Firefox, Safari, Edge. No polyfills needed. Touch events for basic play on mobile (optional buttons overlay). -- **NFR-2.3 Code Structure**: Initially single `index.html` with sections for HTML/CSS/JS for rapid iteration. Refactor to `src/` modules (e.g. using