178 lines
7.2 KiB
Markdown
178 lines
7.2 KiB
Markdown
# 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)
|