diff options
Diffstat (limited to 'docs/superpowers/specs')
| -rw-r--r-- | docs/superpowers/specs/2026-04-05-demos-design.md | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-04-05-demos-design.md b/docs/superpowers/specs/2026-04-05-demos-design.md new file mode 100644 index 0000000..f51f260 --- /dev/null +++ b/docs/superpowers/specs/2026-04-05-demos-design.md @@ -0,0 +1,223 @@ +# Downstroke Demo Games Design + +**Date:** 2026-04-05 +**Status:** Approved +**Scope:** `demo/` folder, 5 demo games, Makefile `make demos` target, CLAUDE.md update + +--- + +## Goal + +Provide 5 small self-contained demo games in `demo/` that collectively exercise every engine system. Each demo compiles to its own executable (`bin/demo-*`). They replace the macroknight integration test for Milestone 8 and serve as living documentation of the engine API. + +--- + +## File Layout + +``` +demo/ + assets/ ← copied from macroknight/assets (not symlinked) + monochrome-transparent.png ← tileset spritesheet + monochrome_transparent.tsx ← tileset metadata (TSX) + level-0.tmx ← level used by platformer, topdown, sandbox + DejaVuSans.ttf ← font for audio demo text + jump.wav ← sound effect (platformer jump, shmup shoot) + theme.ogg ← music (audio demo) + platformer.scm + shmup.scm + topdown.scm + audio.scm + sandbox.scm +``` + +**Omitted from copy:** `prefabs.scm`, `macroknight.tiled-project`, `macroknight.tiled-session` — macroknight-specific files not needed by any demo. + +--- + +## Build + +### Makefile additions + +```makefile +DEMO_NAMES := platformer shmup topdown audio sandbox +DEMO_BINS := $(patsubst %,bin/demo-%,$(DEMO_NAMES)) + +demos: engine $(DEMO_BINS) + +bin/demo-%: demo/%.scm $(OBJECT_FILES) | bin + csc demo/$*.scm $(OBJECT_FILES) -o bin/demo-$* -I bin +``` + +- `make` — builds engine modules only (unchanged) +- `make demos` — builds all 5 demo executables; depends on engine being built first +- Demos are compiled as programs (not units), linked against all engine `.o` files + +### CLAUDE.md update + +Add to the Build & Test section: + +> `make demos` must always succeed. A demo that fails to compile is a build failure. Run `make && make demos` to verify both engine and demos build cleanly. + +--- + +## Demo Code Pattern + +Every demo follows this ~30-line structure: + +```scheme +(import (prefix sdl2 "sdl2:") + (prefix sdl2-ttf "ttf:") + (prefix sdl2-image "img:") + downstroke/engine + downstroke/world + downstroke/tilemap + downstroke/renderer + downstroke/input + downstroke/physics + downstroke/assets) + +(define *game* + (make-game + title: "Demo: <Name>" width: 600 height: 400 + preload: (lambda (game) ...) ;; load tilemap, tileset texture, sounds + create: (lambda (game) ...) ;; build scene, place entities + update: (lambda (game dt) ...) ;; input dispatch, physics calls + render: (lambda (game) ...))) ;; HUD overlay (optional) + +(game-run! *game*) +``` + +Tile IDs in entity plists are placeholder values — to be adjusted visually after first run. + +--- + +## The 5 Demos + +### 1. `demo/platformer.scm` — Platformer + +**Systems exercised:** `input`, `physics` (gravity + tile collision), `renderer` (tilemap + entities), `world`/scene, camera follow, audio (sound effect) + +**Mechanics:** +- Player entity with gravity, left/right movement, jump +- Tile collision via `apply-physics` from `physics.scm` +- Camera follows player horizontally +- Jump sound via macroknight's `sound.scm` (or direct SDL_mixer call) +- Level: `demo/assets/level-0.tmx` +- Tile IDs: placeholder (user adjusts) + +**Key entity plist:** +```scheme +(list #:type 'player + #:x 100 #:y 50 + #:width 16 #:height 16 + #:vx 0 #:vy 0 + #:gravity? #t + #:on-ground? #f + #:tile-id 1) +``` + +**Update logic:** read input → set `#:vx` from left/right → jump sets `#:vy` → call physics step → update camera x to follow player x. + +--- + +### 2. `demo/shmup.scm` — Shoot-em-up + +**Systems exercised:** `entity` (spawning/removal), entity-entity collision via `physics.scm`, `input`, `renderer`, `world`/scene (no tilemap) + +**Mechanics:** +- Player ship at bottom, moves left/right +- Space bar fires bullet upward (new entity added to scene) +- Enemies spawn from top at random x positions every N frames, move downward +- Bullet-enemy collision: both entities removed from scene +- No tilemap — plain background (black/SDL clear) +- No gravity on any entity +- `jump.wav` plays on shoot + +**Key entity plists:** +```scheme +;; player +(list #:type 'player #:x 280 #:y 360 #:width 16 #:height 16 #:vx 0 #:vy 0 #:tile-id 2) +;; bullet +(list #:type 'bullet #:x px #:y 340 #:width 4 #:height 8 #:vx 0 #:vy -5 #:tile-id 3) +;; enemy +(list #:type 'enemy #:x rx #:y 0 #:width 16 #:height 16 #:vx 0 #:vy 2 #:tile-id 4) +``` + +**Update logic:** move entities by vx/vy each frame → AABB collision check between bullets and enemies → filter dead entities from scene → spawn new enemy every 60 frames → read input for player movement and shoot. + +--- + +### 3. `demo/topdown.scm` — Top-down explorer + +**Systems exercised:** `input` (8-directional), `renderer` (tilemap + entity), `world`/scene, camera follow (both axes), `physics` (no gravity) + +**Mechanics:** +- Player entity moves in 8 directions (WASD or arrows) +- No gravity (`#:gravity? #f`) +- Camera follows player on both x and y axes +- Level: `demo/assets/level-0.tmx` (same tilemap, different movement feel) +- No audio + +**Update logic:** read input → set `#:vx` and `#:vy` from direction keys → apply tile collision (no gravity component) → update camera to center on player. + +--- + +### 4. `demo/audio.scm` — Audio showcase + +**Systems exercised:** audio (sound effects + music), `renderer` (text via `draw-ui-text`), `input`, `assets` + +**Mechanics:** +- Static screen with text instructions rendered via `draw-ui-text` +- Press **J** → play `jump.wav` +- Press **M** → toggle `theme.ogg` music on/off +- Press **Escape** → quit +- No tilemap, no physics, no moving entities +- Uses `DejaVuSans.ttf` for text +- Audio calls via macroknight's `sound.scm` functions (`load-sounds!`, `play-sound!`, `load-music!`, `play-music!`, `stop-music!`) — or direct SDL_mixer FFI if sound.scm is not available + +**Display:** colored rectangle background + text labels for each key binding. + +--- + +### 5. `demo/sandbox.scm` — Physics sandbox + +**Systems exercised:** `physics` (gravity + tile collision + entity-entity collision), `renderer`, `world`/scene, no player input + +**Mechanics:** +- 10 entities spawned at random x positions near the top of the screen +- All have `#:gravity? #t` +- Physics step runs each frame (gravity accelerates, tile collision stops them) +- Entities rest on floor tiles or bounce (depending on physics.scm behavior) +- No player — pure observation of physics pipeline +- Level: `demo/assets/level-0.tmx` +- After all entities settle (or after 10 seconds), loop: despawn all, respawn at new random positions + +--- + +## Systems Coverage Matrix + +| System / Module | platformer | shmup | topdown | audio | sandbox | +|---|---|---|---|---|---| +| `engine` (make-game, game-run!) | ✓ | ✓ | ✓ | ✓ | ✓ | +| `input` | ✓ | ✓ | ✓ | ✓ | — | +| `physics` (gravity) | ✓ | — | — | — | ✓ | +| `physics` (tile collision) | ✓ | — | ✓ | — | ✓ | +| `physics` (entity collision) | — | ✓ | — | — | ✓ | +| `renderer` (tilemap) | ✓ | — | ✓ | — | ✓ | +| `renderer` (entities) | ✓ | ✓ | ✓ | — | ✓ | +| `renderer` (text) | — | — | — | ✓ | — | +| `world` / scene | ✓ | ✓ | ✓ | — | ✓ | +| `assets` registry | ✓ | ✓ | ✓ | ✓ | ✓ | +| audio (sound) | ✓ | ✓ | — | ✓ | — | +| audio (music) | — | — | — | ✓ | — | +| camera follow | ✓ (x) | — | ✓ (xy) | — | — | + +--- + +## Out of Scope + +- Animation state machine (`animation.scm`) — not yet extracted to downstroke +- AI (`ai.scm`) — not yet extracted +- Prefab system — not yet extracted +- Scene transitions — Milestone 9 +- Asset-type-specific load helpers (`game-load-tilemap!` etc.) — Milestone 6 |