defender-browser-clone/docs/REQUIREMENTS.md

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 <script type="module"> or simple globals) when >500 LOC or multiple devs/agents. Comment key systems. Use const/let, arrow funcs, classes for entities.
• NFR-2.4 Maintainability & Agent Use: All major features start as Gitea issue. PRs required for changes > trivial. Agents use HA_Coder etc to propose code; human reviews. Tests: Manual playtest checklist or simple automated (if add Jest later for pure logic).
• NFR-2.5 Accessibility & UX: High contrast mode toggle? Keyboard fully functional. No seizure-risk flashing (limit particle/strobe rate). Instructions visible or in-game help overlay (?). Responsive canvas size (maintain aspect, scale to window with letterbox or full).
• NFR-2.6 Assets: No external files initially. All graphics procedural (draw functions). Later: optional sprite sheet as data URL or separate small PNG if justified. Sound 100% generated.

3. Phased Implementation Milestones

Phase 0: Setup & Skeleton (Current)

• Repo created from template, README + this REQUIREMENTS captured via MCP.
• Basic HTML skeleton with canvas, game loop stub, input handler, simple ship draw + thrust test.
• Create initial issues for Phase 1 tasks.

Phase 1: MVP Playable (Core Loop)

• World scrolling + wrapping terrain (FR-1.1).
• Player ship movement + basic physics + bounds (FR-1.2).
• Laser fire + simple bullet management (FR-1.3.1).
• 1 enemy type (Lander) with basic AI + collision (FR-1.4.2 partial).
• Basic score, lives, death/respawn (FR-1.7 partial).
• Simple radar stub (FR-1.6).
• Game states minimal (play/pause/gameover).
• Particles for thrust/explosion start.
• Goal: Fly, shoot, see enemies die/collide, score points, die and respawn. ~1-2 hours focused agent work + review.

Phase 2: Core Mechanics Expansion

• Remaining enemy types + behaviors + wave spawner (FR-1.4, 1.7.4).
• Human abduction + rescue full (FR-1.5).
• Smart bomb + hyperspace (FR-1.3.2-3).
• Improved radar, HUD polish, scoring tables.
• Audio foundation (FR-1.9.1).
• Local high scores.

Phase 3: Polish & Release Ready

• Full particles, screen effects, attract mode/demo.
• Mobile touch controls + responsive.
• Balance tuning (difficulty curve, spawn rates, point values).
• Code cleanup, docs update (ARCHITECTURE.md), more tests if applicable.
• Optional: Simple level editor or config for waves.
• Deployable static (GitHub Pages ready).

Future / Stretch:

• Multiplayer? (local co-op split? or online later)
• Power-ups, different ships/weapons.
• Better visuals (pixel art sprites, lighting).
• Soundtrack or more complex synth.
• Leaderboard backend (Firebase or self-host simple).
• VR or other? No, stay 2D arcade.

4. Open Questions / Decisions to Capture in Issues

• Exact control scheme and physics constants (tweak values via playtest).
• Whether ship has explicit "facing" direction or always shoots "forward" relative to velocity.
• Terrain collision: soft landing or instant death on contact? (original allows skimming).
• Exact enemy counts per wave and intro order.
• Radar detail level vs perf (many entities).
• Use classes vs plain objects for entities (perf vs clarity for agents).

---

This document is living. Update via PR as design evolves. Reference specific FR/NFR IDs in issues and code comments.