space-arcade/DESIGN.md

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

• Load screen with progress
• Title / attract screen
• High score board (top 10, name entry, localStorage)
• Lives system
• Levels / increasing difficulty
• Pause
• Game over + restart
• Chiptune SFX + background music
• Particles / explosions / screen shake
• CRT scanline + vignette overlay
• 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)