Customize README.md for Defender browser clone project: add purpose, high-level requirements summary, structure, workflow, and quickstart
This commit is contained in:
@@ -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
|
## 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.
|
### Gameplay
|
||||||
2. Specific tasks for this project are tracked in the `/tasks` folder.
|
- **World**: Large horizontally-wrapping cylindrical planet surface. Scrolling viewport follows player. Jagged terrain/ground layer at bottom. Simple starfield or nebular background.
|
||||||
3. All code changes go through Pull Requests.
|
- **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).
|
||||||
4. Agents follow the role instructions located in `/agents`.
|
- **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
|
├── index.html # Game entry (single-file prototype preferred initially)
|
||||||
├── tests/ # Test files
|
├── src/ # Future: game.js, Entity.js, systems/ (physics, render, input, audio)
|
||||||
├── docs/ # Project documentation
|
├── docs/ # REQUIREMENTS.md, ARCHITECTURE.md, notes
|
||||||
├── agents/ # Agent role instructions for this project
|
├── agents/ # Role definitions (HA_Planner.md etc.)
|
||||||
├── tasks/ # Active and completed tasks
|
├── .gitea/ # Issue & PR templates
|
||||||
├── prompts/ # Project-specific prompts
|
├── AGENTS.md # How agents work in this repo
|
||||||
├── .gitea/ # Issue and PR templates
|
├── README.md
|
||||||
└── README.md
|
└── (tasks/ or issues for tracking)
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Getting Started
|
## Agent-Driven Workflow
|
||||||
|
|
||||||
- New features should begin with a task in `/tasks`
|
- Use `/agents/HA_*` roles for specialized work (Planner for requirements, Architect for systems design, Coder for impl, Tester, Reviewer).
|
||||||
- All changes require a Pull Request
|
- Start features by creating Gitea issue (use feature.md template) or task doc.
|
||||||
- Reference related issues from `core-planning` when relevant
|
- Code via PRs only. Reference issues in commits/messages.
|
||||||
|
- Human provides direction, approves merges, runs final playtests.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*Maintained by the Hermes AI Agent Team*
|
## 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.*
|
||||||
Reference in New Issue
Block a user