From 7f506259ad8d257dbc63f822526767e86b51f4b9 Mon Sep 17 00:00:00 2001 From: Ty Date: Sat, 20 Jun 2026 01:20:29 +0000 Subject: [PATCH] Create detailed REQUIREMENTS.md in docs/ with functional/non-functional specs, acceptance criteria, and phased milestones for the Defender clone --- docs/REQUIREMENTS.md | 146 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/REQUIREMENTS.md diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md new file mode 100644 index 0000000..438f174 --- /dev/null +++ b/docs/REQUIREMENTS.md @@ -0,0 +1,146 @@ +# 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. + +--- + +## 1. Functional Requirements + +### 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. + +### 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. + +### 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). + +### 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. + +### 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. + +### 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. + +### 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. + +### 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