# Vector Asteroids — Arcade Demo Blueprint

This repository milestone defines the complete design, technical architecture, and acceptance plan for **Vector Asteroids**, a polished single-file retro arcade demo inspired by classic vector Asteroids. The implementation target is deliberately strict: one self-contained `index.html`, no build step, no external assets, no framework, and no network access.

The milestone does **not** ship the playable game yet; it ships the implementation contract a competent engineer can use to build the demo without ambiguity.

## Hard implementation constraints

The final arcade demo must:

- Be delivered as a **single `index.html` file**.
- Contain all CSS and JavaScript inline.
- Use no external files of any kind:
  - no images
  - no audio files
  - no fonts
  - no JSON/data files
  - no WASM
  - no CDN links
  - no `fetch`
  - no `<script src>`
  - no ES module imports
- Run by opening `index.html` directly through:
  - `file://`
  - a plain static host
- Use only:
  - vanilla JavaScript
  - HTML5 Canvas 2D
  - Web Audio API synthesis
  - `localStorage` for high score/settings persistence, guarded with safe fallbacks

## Milestone deliverables

The blueprint package contains:

- [`docs/implementation-blueprint.md`](docs/implementation-blueprint.md)  
  Complete architecture and game systems specification, including loop structure, state machine, entity model, player mechanics, asteroid splitting, saucer AI, collision strategy, scoring, lives, waves, audio synthesis, rendering style, input, persistence, and responsiveness.

- [`docs/acceptance-checklist.md`](docs/acceptance-checklist.md)  
  Detailed validation plan for the finished `index.html`, including self-containment checks, file/network compatibility, gameplay requirements, audio behavior, persistence, responsiveness, and manual test scripts.

- [`docs/traceability-matrix.md`](docs/traceability-matrix.md)  
  Requirement-to-design-to-acceptance mapping to verify the original project request is fully represented in the implementation plan.

## Target player experience

The finished demo should feel like a compact, arcade-quality cabinet game:

- black void background with layered parallax stars
- glowing neon vector outlines
- responsive inertial ship physics
- flickering thrust flame and particle trail
- screen wrapping for ship, asteroids, bullets, and hazards
- jagged asteroids in three sizes that split convincingly
- increasingly difficult waves
- hostile flying saucers that shoot back
- explosions, sparks, screen shake, and bloom-like glow
- synthesized laser, thrust, explosion, saucer, extra-life, and beat sounds
- score, lives, level, high score, pause, title/attract, and game-over flows

## Implementation architecture summary

The final game should be implemented as a single immediately-invoked script inside `index.html`.

Recommended internal organization:

1. immutable configuration tables
2. math/vector/random helpers
3. safe storage helpers
4. input manager
5. audio synthesizer
6. canvas resize manager
7. game state and entity factories
8. update systems
9. collision systems
10. rendering systems
11. main `requestAnimationFrame` loop

No npm manifest, lockfile, bundler, or generated asset pipeline is needed.

## Primary controls

Keyboard is the primary control scheme:

| Action | Keys |
|---|---|
| Rotate left | Left Arrow, `A` |
| Rotate right | Right Arrow, `D` |
| Thrust | Up Arrow, `W` |
| Fire | Space, `J`, `K` |
| Hyperspace | Down Arrow, `S`, Shift, `H` |
| Start / restart | Enter, Space |
| Pause | `P`, Escape |
| Mute | `M` |

Touch controls are specified as an optional enhancement in the blueprint, but the keyboard path is mandatory.

## Persistence

The final game should persist:

- high score
- mute preference
- optional touch/control preference if implemented

The storage design uses namespaced versioned keys:

- `vectorAsteroids.highScore.v1`
- `vectorAsteroids.settings.v1`

All storage access must be wrapped in `try/catch` so the game still works in browsers or privacy modes where `localStorage` is blocked.

## Acceptance summary

A finished implementation is acceptable only if:

- `index.html` runs directly from disk with no server.
- The Network panel shows no requests after load.
- The source contains no external references or asset loads.
- Gameplay includes all required game states and arcade systems.
- Audio is synthesized at runtime and starts only after a user gesture.
- High score persists across reloads where `localStorage` is available.
- The canvas resizes cleanly and remains playable on different viewport sizes.
- The game loop remains smooth and frame-rate independent.

See the full checklist in [`docs/acceptance-checklist.md`](docs/acceptance-checklist.md).

## Dependencies

This design milestone declares no package dependencies.

The final implementation should use only stable browser APIs:

- CanvasRenderingContext2D
- requestAnimationFrame
- KeyboardEvent / PointerEvent
- Web Audio API
- localStorage
- Page Visibility API

Because there is no build step and no package manager, maintainers should not create a lockfile for this project.