# Defender Browser Clone

**A faithful browser-based HTML5 Canvas + vanilla JavaScript clone of the 1981 Williams arcade classic _Defender_.**

Initialized from the `Ty_Tech/template-app` template for Hermes AI Agent team workflows.

---

## Purpose

Recreate the fast, chaotic, addictive gameplay of original Defender in a modern, accessible web format. Use structured AI agent collaboration (via agents/ roles and AGENTS.md) to design, implement, test, review, and iterate on all systems. Capture requirements, decisions, and code history here in Gitea.

Playful yet production-quality goal: smooth 60 FPS arcade experience, self-contained (single HTML or minimal files), easy to run anywhere.

---

## High-Level Requirements

### Gameplay
- **World**: Large horizontally-wrapping cylindrical planet surface. Scrolling viewport follows player. Jagged terrain/ground layer at bottom. Simple starfield or nebular background.
- **Player Ship**: Momentum physics (velocity + thrust). 4 or 8 direction thrust (or facing-based). Vertical freedom with soft bounds or terrain avoidance. Visual direction facing (left/right flip support).
- **Controls** (keyboard first): Arrows/WASD thrust, Space=Fire laser, Shift=Smart Bomb (limited), H=Hyperspace (risky teleport), optional Reverse/Brake.
- **Weapons**: Forward laser bolts (rapid fire), Smart Bombs (screen-clear), Hyperspace.
- **Enemies**: Landers (abductors), Mutants (aggressive), Bombers (drop bombs), Pods (split into Swarmers), Baiters (hunters). Distinct AI behaviors, spawn patterns per wave.
- **Humans**: 8-10 on surface. Landers abduct them. Player rescues by destroying carrier then catching falling human and returning to ground for bonus.
- **Radar**: Top strip showing scaled world with color-coded blips for all entities.
- **Progression**: Waves with escalating difficulty (more enemies, faster, smarter). Score multipliers, extra lives on thresholds.
- **Death & Respawn**: Collide with enemy/terrain/bullet or bad hyperspace = lose life. Brief invulnerability on spawn.

### Technical & UX
- Pure vanilla JS + Canvas 2D (no frameworks for v1). Target fixed or responsive arcade aspect (e.g. 1024x768 or 800x600 internal).
- Game loop via requestAnimationFrame. Delta-time or fixed timestep.
- Efficient: object pooling for bullets/particles/enemies, simple AABB or circle collisions, spatial culling.
- States: Title/Attract, Playing, Paused (P), Game Over, High Score (localStorage).
- Effects: Particles (explosions, thrust, debris), screen flash/shake, simple palette (arcade neon on black).
- Audio: Web Audio API procedural tones/beeps/explosions (or oscillator synth). Mute toggle.
- Persistence: Local high scores list (name + score).
- Polish: Smooth scrolling, crisp pixel feel or vector-ish, clear HUD (score, lives as ship icons, wave, bombs left).

### Non-Functional
- Performance: 60 FPS stable on average laptop, graceful degradation.
- Compatibility: Chrome/Firefox/Edge/Safari recent versions. Keyboard primary; touch secondary.
- Maintainability: Modular code (even if single file initially), clear comments, agent-friendly structure. Use issues + PRs for all work.
- Scope: MVP first (basic flight + fire + 2 enemy types + score + radar stub), then expand via issues.

See `docs/REQUIREMENTS.md` for expanded functional breakdown, acceptance criteria, and phased milestones.

---

## Repo Structure (Adapted from Template)

```
.
├── index.html          # Game entry (single-file prototype preferred initially)
├── src/                # Future: game.js, Entity.js, systems/ (physics, render, input, audio)
├── docs/               # REQUIREMENTS.md, ARCHITECTURE.md, notes
├── agents/             # Role definitions (HA_Planner.md etc.)
├── .gitea/             # Issue & PR templates
├── AGENTS.md           # How agents work in this repo
├── README.md
└── (tasks/ or issues for tracking)
```

---

## Agent-Driven Workflow

- Use `/agents/HA_*` roles for specialized work (Planner for requirements, Architect for systems design, Coder for impl, Tester, Reviewer).
- Start features by creating Gitea issue (use feature.md template) or task doc.
- Code via PRs only. Reference issues in commits/messages.
- Human provides direction, approves merges, runs final playtests.

---

## Quick Start

```bash
git clone https://.../Ty_Tech/defender-browser-clone.git
cd defender-browser-clone
# Simplest: open index.html in browser
# Or: python -m http.server 8080 && open http://localhost:8080
```

**Initial controls (will evolve):** Arrow keys to fly, Space to shoot. Watch for updates in-game or README.

---

*Project led by human + Hermes AI Agents. Part of Ty_Tech ecosystem.*