# 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.*