From 02302b9f54a4d1653259d9eb3da546009de9cf7a Mon Sep 17 00:00:00 2001 From: michael <1+michael@noreply.git.casaderoll.de> Date: Thu, 24 Sep 2026 10:02:12 +0200 Subject: [PATCH] Add DESIGN.md --- DESIGN.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 DESIGN.md diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..d636da5 --- /dev/null +++ b/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)