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