# Digital Spaceport Arcade — Design Document

> A full 8-bit retro arcade suite. Four games, one synthwave landing page,
> published on `0.0.0.0:8099`. Pure JS (no Python). Built & validated by
> **Athena** (OpenClaw agent, budzo #5).

## 1. Vision

A browser-based arcade that feels like a 1980s spaceport: CRT scanlines,
neon synthwave palette, chiptune audio, high-score boards, and four
hand-crafted retro games rendered on HTML5 canvas.

**Theme:** *Digital Spaceport Arcade* — a neon spaceport where pilots
dock, refuel, and compete.

## 2. Tech Stack

| Layer      | Choice                                   | Why |
|------------|------------------------------------------|-----|
| Server     | Node.js + Express (static)               | JS-only requirement, trivial static serving |
| Rendering  | HTML5 Canvas 2D (no WebGL dependency)    | Works everywhere incl. headless SwiftShader |
| Audio      | Web Audio API (procedural chiptune)      | Zero asset files, authentic 8-bit sound |
| Fonts      | Google Fonts "Press Start 2P" + fallback | Authentic 8-bit type |
| Validation | Puppeteer (headless Chrome) + screenshots | Real browser, real rendering, real input |
| State      | localStorage (high scores, settings)     | No backend needed |

**No external game libraries.** Everything is hand-rolled for full control
and zero dependency risk.

## 3. Architecture

```
dsp-space-arcade/
├── DESIGN.md                  ← this file (living doc)
├── package.json
├── server.js                  ← Express static server, port 8099, bind 0.0.0.0
├── public/
│   ├── index.html             ← synthwave landing page
│   ├── css/
│   │   └── style.css          ← synthwave theme, CRT effects, cards
│   ├── js/
│   │   ├── core/
│   │   │   ├── engine.js      ← shared game loop, input, audio, highscores
│   │   │   ├── audio.js       ← Web Audio chiptune synth
│   │   │   ├── sprites.js     ← procedural sprite/pixel-art generator
│   │   │   └── ui.js          ← shared UI (load screen, HUD, pause, gameover)
│   │   └── games/
│   │       ├── asteroid.js    ← Game 1
│   │       ├── breakout.js    ← Game 2
│   │       ├── snake.js       ← Game 3
│   │       └── spaceinvaders.js ← Game 4
│   ├── games/
│   │   ├── asteroid.html
│   │   ├── breakout.html
│   │   ├── snake.html
│   │   └── spaceinvaders.html
│   ├── img/                   ← generated thumbnails (PNG)
│   └── audio/                 ← (reserved; audio is procedural)
└── tools/
    ├── gen-thumbnails.js      ← renders each game's attract screen to PNG
    └── validate.js            ← puppeteer: load, play, screenshot, assert
```

## 4. Shared Core (`core/`)

### engine.js
- Fixed-timestep game loop (60 FPS target, accumulator pattern).
- Input manager: keyboard (arrows/WASD/space) + gamepad-ready.
- High-score store: `localStorage` keyed per game, top 10, name entry.
- Screen shake, particle system, screen flash — shared juice.

### audio.js
- Web Audio API chiptune engine.
- Square/triangle/noise oscillators, 8-bit style.
- SFX: shoot, explode, powerup, gameover, levelup, menu.
- Background music: short looping chiptune per game (procedural, no files).
- Master mute toggle (M key + UI button).

### sprites.js
- Procedural pixel-art generator: draws sprites from string maps
  (e.g. `"..XX..",".XXXX."`) into offscreen canvases at 1x, scaled up
  with `imageSmoothingEnabled = false` for crisp 8-bit look.
- Palette system per game.

### ui.js
- **Load screen**: animated "INSERT COIN" / progress bar with fake
  asset-loading steps (authentic retro feel).
- **HUD**: score, lives, level, high score.
- **Pause** (P/Esc), **Game Over** screen with score + high-score entry.
- **Attract mode**: demo plays behind title screen.

## 5. The Four Games

### 5.1 ASTEROID FIELD (Asteroids clone)
- Rotating ship, thrust + turn, wrap-around screen.
- Asteroids split into smaller rocks (3→2→1).
- Hyperspace jump (random teleport, risky).
- Waves of increasing difficulty; UFO enemy appears.
- **Controls:** ←→/AD turn, ↑/W thrust, SPACE fire, X hyperspace.

### 5.2 NEON BREAKER (Breakout clone)
- Paddle, ball, brick grid with multiple hit points.
- Power-ups: wide paddle, multi-ball, sticky, laser.
- Levels with different brick layouts.
- **Controls:** ←→/AD move, SPACE launch/catch. Mouse + pointer lock.

### 5.3 SNAKE PROTOCOL (Snake, spaceport theme)
- Grid-based snake eating energy cells.
- Speed increases with score; walls = death (or wrap on easy).
- Special cells: bonus (5x), slow-mo, ghost (pass through self).
- **Controls:** arrows/WASD.

### 5.4 INVADER DOCK (Space Invaders clone)
- Grid of invaders descending in formation, firing back.
- Player cannon, shield bunkers that erode.
- Invaders speed up as they're destroyed; boss row.
- **Controls:** ←→/AD move, SPACE fire.

### Retro features in EVERY game
- [x] Load screen with progress
- [x] Title / attract screen
- [x] High score board (top 10, name entry, localStorage)
- [x] Lives system
- [x] Levels / increasing difficulty
- [x] Pause
- [x] Game over + restart
- [x] Chiptune SFX + background music
- [x] Particles / explosions / screen shake
- [x] CRT scanline + vignette overlay
- [x] Mute toggle

## 6. Landing Page (synthwave)

- Animated gradient sky (purple→pink→orange), retro sun with scanlines,
  perspective neon grid floor, parallax stars.
- Title: **DIGITAL SPACEPORT ARCADE** in glowing Press Start 2P.
- 4 game cards, each with:
  - Generated thumbnail (attract-mode screenshot, 8-bit style).
  - Title, tagline, "INSERT COIN" button.
  - Hover: card lifts, neon glow intensifies, thumbnail animates.
- Footer: credits, "Built by Athena — budzo #5", controls legend.
- Responsive; works on mobile (touch controls per game).

## 7. Validation Plan (Puppeteer)

For each game + landing page:
1. Load page, wait for load screen to finish.
2. Screenshot title screen.
3. Simulate gameplay (key presses) for N seconds.
4. Screenshot mid-game (verify rendering, HUD, no blank canvas).
5. Assert: canvas has non-uniform pixels (game is rendering),
   no JS console errors, score element present.
6. Trigger game over where feasible; screenshot.
7. Save all screenshots to `tools/shots/` for review.

## 8. Progress Log

| # | Task | Status | Notes |
|---|------|--------|-------|
| 1 | Scaffold dirs + server | ✅ | express, port 8099, 0.0.0.0 |
| 2 | Core: engine.js | ✅ | mouse + pointer lock support |
| 3 | Core: audio.js | ✅ | chiptune SFX + BGM |
| 4 | Core: sprites.js | ✅ | procedural pixel art |
| 5 | Core: ui.js | ✅ | load/HUD/pause/gameover |
| 6 | Game: Asteroid Field | ✅ | validated |
| 7 | Game: Neon Breaker | ✅ | validated, mouse + pointer lock |
| 8 | Game: Snake Protocol | ✅ | validated |
| 9 | Game: Invader Dock | ✅ | validated |
| 10 | Landing page + CSS | ✅ | synthwave theme |
| 11 | Thumbnails (generated) | ✅ | 4 PNG attract screens |
| 12 | Puppeteer validation | ✅ | all 4 games + landing pass |
| 13 | Publish on 8099 + verify | ✅ | running, healthz ok |

## 9. Sign-off

> *Built with love, neon, and 8-bit grit.*
> — **Athena** 🦉 (budzo #5, alive)