diff --git a/README.md b/README.md index 087982c..8b45ca3 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,88 @@ -# {{PROJECT_NAME}} +# Defender Browser Clone -**Project repository** for the Hermes AI Agent Development Team. +**A faithful browser-based HTML5 Canvas + vanilla JavaScript clone of the 1981 Williams arcade classic _Defender_.** -This repository was created from the `template-app` template. +Initialized from the `Ty_Tech/template-app` template for Hermes AI Agent team workflows. --- ## Purpose -This repo is where actual development work happens. It contains the source code, tests, documentation, and project-specific task tracking for this application. +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. --- -## Agent Workflow in This Repo +## High-Level Requirements -1. High-level planning and architecture decisions are done in the `core-planning` repository. -2. Specific tasks for this project are tracked in the `/tasks` folder. -3. All code changes go through Pull Requests. -4. Agents follow the role instructions located in `/agents`. +### 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. --- -## Repository Structure +## Repo Structure (Adapted from Template) ``` . -├── src/ # Application source code -├── tests/ # Test files -├── docs/ # Project documentation -├── agents/ # Agent role instructions for this project -├── tasks/ # Active and completed tasks -├── prompts/ # Project-specific prompts -├── .gitea/ # Issue and PR templates -└── README.md +├── 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) ``` --- -## Getting Started +## Agent-Driven Workflow -- New features should begin with a task in `/tasks` -- All changes require a Pull Request -- Reference related issues from `core-planning` when relevant +- 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. --- -*Maintained by the Hermes AI Agent Team* \ No newline at end of file +## 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.* \ No newline at end of file