Add DESIGN.md

DESIGN.md

@@ -0,0 +1,177 @@
+# 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)