# Demo Games Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build 5 self-contained demo games in `demo/` that collectively exercise every engine system and compile via `make demos`.

**Architecture:** Each demo is a standalone Chicken Scheme program that imports downstroke engine modules and links against all engine `.o` files. Shared assets (tileset, levels, fonts, sounds) live in `demo/assets/` copied from macroknight. `mixer.scm` and `sound.scm` are adapted from macroknight and added to the engine build.

**Tech Stack:** Chicken Scheme, SDL2 (sdl2 egg), SDL2_mixer (via mixer FFI), SDL2_ttf (sdl2-ttf egg), SDL2_image (sdl2-image egg), SRFI-64 (tests not applicable to demo programs — `make demos` compilation success is the test).

---

## Key API Reference

Before implementing, keep these exact signatures in mind:

```scheme
;; Entity ops (downstroke/entity)
(entity-ref entity #:key [default])   ;; read field, default=#f
(entity-set entity #:key value)        ;; returns NEW entity (immutable)
(entity-type entity)                   ;; = (entity-ref entity #:type #f)

;; World (downstroke/world)
(make-scene entities: '() tilemap: #f camera: (make-camera x: 0 y: 0) tileset-texture: #f)
(make-camera x: 0 y: 0)
(scene-entities scene)
(scene-entities-set! scene list)       ;; mutates in place
(scene-camera scene)                   ;; camera-x, camera-y, camera-x-set!, camera-y-set!
(scene-tilemap scene)
(scene-tileset-texture scene)
(scene-add-entity scene entity)        ;; mutates, returns scene
(scene-filter-entities scene pred)     ;; mutates, returns scene
(scene-update-entities scene proc ...) ;; maps each proc over all entities

;; Tilemap (downstroke/tilemap)
(load-tilemap "path.tmx")              ;; loads TMX + TSX + PNG; returns tilemap
(tilemap-tileset tilemap)              ;; → tileset struct
(tileset-image tileset)                ;; → SDL texture (the tileset-texture for make-scene)

;; Physics (downstroke/physics)
;; Full platformer pipeline (execute in this order):
(apply-jump entity jump-pressed?)      ;; sets #:ay if on-ground
(apply-acceleration entity)            ;; consumes #:ay → #:vy, gated on #:gravity?
(apply-gravity entity)                 ;; adds *gravity*(=1) to #:vy, gated on #:gravity?
(apply-velocity-x entity)             ;; #:x += #:vx
(resolve-tile-collisions-x entity tm) ;; snaps #:x, zeros #:vx on hit
(apply-velocity-y entity)             ;; #:y += #:vy
(resolve-tile-collisions-y entity tm) ;; snaps #:y, zeros #:vy on hit
(detect-ground entity tm)             ;; sets #:on-ground?, gated on #:gravity?
;; Entity-entity collision:
(scene-resolve-collisions scene)       ;; mutates scene; needs #:solid? #t on both entities
;; AABB check:
(aabb-overlap? x1 y1 w1 h1 x2 y2 w2 h2)  ;; → bool

;; Input (downstroke/input)
(game-input game)                      ;; current input-state
(input-held? state 'action)           ;; true while button held
(input-pressed? state 'action)        ;; true only on first frame pressed
;; Default action names: up down left right a b start select quit
;; Keyboard: W/up=up, S/down=down, A/left=left, D/right=right,
;;           J/Z=a, K/X=b, return=start, escape=quit

;; Engine (downstroke/engine)
(game-run! game)
(game-scene game), (game-scene-set! game scene)
(game-renderer game)                   ;; SDL renderer — valid from preload: onward
(game-input game)                      ;; current input-state
(game-asset game key)                  ;; = (asset-ref (game-assets game) key)
(game-asset-set! game key value)
(game-camera game)                     ;; = (scene-camera (game-scene game))

;; Renderer (downstroke/renderer)
(render-scene! renderer scene)         ;; draws tilemap + entities (when tilemap present)
(draw-ui-text renderer font str color x y)

;; Sound (downstroke/sound) — after copying from macroknight
(init-audio!)
(load-sounds! '((key . "path.wav") ...))
(play-sound 'key)                      ;; NOTE: no bang
(load-music! "path.ogg")
(play-music! volume)                   ;; volume = 0.0–1.0
(stop-music!)                          ;; added when copying sound.scm
```

---

## File Structure

**New files to create:**
```
demo/assets/           ← copied from macroknight/assets/
  monochrome-transparent.png
  monochrome_transparent.tsx
  level-0.tmx
  DejaVuSans.ttf
  jump.wav
  theme.ogg
demo/platformer.scm
demo/shmup.scm
demo/topdown.scm
demo/audio.scm
demo/sandbox.scm
mixer.scm              ← adapted from macroknight (module renamed to downstroke/mixer)
sound.scm              ← adapted from macroknight (module renamed to downstroke/sound, +stop-music!)
```

**Files to modify:**
```
Makefile               ← add mixer/sound to MODULE_NAMES, update demos: target
CLAUDE.md              ← add make demos requirement
```

---

## Task 1: Infrastructure — assets, audio modules, Makefile, CLAUDE.md

**Files:**
- Create: `demo/assets/` (7 files copied from macroknight)
- Create: `mixer.scm` (adapted from `/home/gene/src/macroknight/mixer.scm`)
- Create: `sound.scm` (adapted from `/home/gene/src/macroknight/sound.scm`)
- Modify: `Makefile`
- Modify: `CLAUDE.md`

- [ ] **Step 1: Create demo/assets/ and copy asset files**

```bash
mkdir -p demo/assets
cp /home/gene/src/macroknight/assets/monochrome-transparent.png demo/assets/
cp /home/gene/src/macroknight/assets/monochrome_transparent.tsx demo/assets/
cp /home/gene/src/macroknight/assets/level-0.tmx demo/assets/
cp /home/gene/src/macroknight/assets/DejaVuSans.ttf demo/assets/
cp /home/gene/src/macroknight/assets/jump.wav demo/assets/
cp /home/gene/src/macroknight/assets/theme.ogg demo/assets/
```

Verify: `ls demo/assets/` shows 6 files (png, tsx, tmx, ttf, wav, ogg).

- [ ] **Step 2: Copy and adapt mixer.scm**

Copy `/home/gene/src/macroknight/mixer.scm` to `mixer.scm` in the downstroke root. Change the module declaration from:
```scheme
(module mixer *
```
to:
```scheme
(module downstroke/mixer *
```

No other changes needed.

- [ ] **Step 3: Copy and adapt sound.scm**

Copy `/home/gene/src/macroknight/sound.scm` to `sound.scm` in the downstroke root. Make three changes:

1. Change module declaration from `(module sound *` to `(module downstroke/sound *`
2. Change `(import ... mixer)` to `(import ... downstroke/mixer)`
3. Add `stop-music!` near the other music functions:

```scheme
(define (stop-music!) (mix-halt-music))
```

The full adapted `sound.scm` should look like:

```scheme
(module downstroke/sound *
  (import scheme
          (chicken base)
          (only srfi-1 for-each)
          downstroke/mixer)

  (define *sound-registry* '())
  (define *music* #f)

  (define (init-audio!)
    (mix-open-audio! 44100 mix-default-format 2 512))

  (define (load-sounds! sound-alist)
    (set! *sound-registry*
      (map (lambda (pair)
             (cons (car pair) (mix-load-chunk (cdr pair))))
           sound-alist)))

  (define (play-sound sym)
    (let ((entry (assq sym *sound-registry*)))
      (when (and entry (cdr entry))
        (mix-play-channel -1 (cdr entry) 0))))

  (define (load-music! path)
    (set! *music* (mix-load-mus path)))

  (define (play-music! volume)
    (when *music*
      (mix-play-music *music* -1)
      (mix-volume-music (inexact->exact (round (* volume 128))))))

  (define (stop-music!) (mix-halt-music))

  (define (set-music-volume! volume)
    (mix-volume-music (inexact->exact (round (* volume 128)))))

  (define (cleanup-audio!)
    (when *music*
      (mix-halt-music)
      (mix-free-music! *music*)
      (set! *music* #f))
    (for-each (lambda (pair) (mix-free-chunk! (cdr pair)))
              *sound-registry*)
    (set! *sound-registry* '())
    (mix-close-audio!)))
```

- [ ] **Step 4: Update Makefile**

Replace the current `MODULE_NAMES` line and add mixer/sound deps and demos target. The updated Makefile:

```makefile
.DEFAULT_GOAL := engine

# Modules listed in dependency order
MODULE_NAMES := entity tilemap world input physics renderer assets engine mixer sound
OBJECT_FILES := $(patsubst %,bin/%.o,$(MODULE_NAMES))

DEMO_NAMES := platformer shmup topdown audio sandbox
DEMO_BINS  := $(patsubst %,bin/demo-%,$(DEMO_NAMES))

# Build all engine modules
engine: $(OBJECT_FILES)

bin:
	@mkdir -p $@

downstroke:
	@mkdir -p $@

# Explicit inter-module dependencies
bin/entity.o:
bin/tilemap.o:
bin/world.o: bin/entity.o bin/tilemap.o
bin/input.o: bin/entity.o
bin/physics.o: bin/entity.o bin/world.o bin/tilemap.o
bin/renderer.o: bin/entity.o bin/tilemap.o bin/world.o
bin/assets.o:
bin/engine.o: bin/renderer.o bin/world.o bin/input.o bin/assets.o
bin/mixer.o:
bin/sound.o: bin/mixer.o

# Pattern rule: compile each module as a library unit
bin/%.o: %.scm | bin downstroke
	csc -c -J -unit downstroke/$* $*.scm -o bin/$*.o -I bin -L bin/downstroke
	@mkdir -p bin/downstroke && if [ -f downstroke/$*.import.scm ]; then mv downstroke/$*.import.scm bin/downstroke/; fi

.PHONY: clean test engine demos

clean:
	rm -rf bin
	rm -f *.import.scm
	rm -f *.log

test:
	@echo "Running unit tests..."
	@csi -s tests/entity-test.scm
	@csi -s tests/world-test.scm
	@csi -s tests/tilemap-test.scm
	@csi -s tests/physics-test.scm
	@csi -s tests/input-test.scm
	@csi -s tests/renderer-test.scm
	@csi -s tests/assets-test.scm
	@csi -s tests/engine-test.scm

demos: engine $(DEMO_BINS)

bin/demo-%: demo/%.scm $(OBJECT_FILES) | bin
	csc demo/$*.scm $(OBJECT_FILES) -o bin/demo-$* -I bin
```

- [ ] **Step 5: Update CLAUDE.md**

In the "Build & Test" section of `/home/gene/src/downstroke/CLAUDE.md`, update the code block:

```bash
make              # compile engine + all demos in demo/
make test         # run all SRFI-64 test suites
make demos        # build demo games only (verify they compile)
```

Also add after the build section (or at end of Build & Test):

> `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.

- [ ] **Step 6: Verify engine builds with mixer and sound**

```bash
cd /home/gene/src/downstroke
make clean && make
```

Expected: All 10 modules compile without errors. `bin/` contains `.o` files for all MODULE_NAMES including `mixer.o` and `sound.o`.

- [ ] **Step 7: Commit**

```bash
git add demo/assets/ mixer.scm sound.scm Makefile CLAUDE.md
git commit -m "feat: add demo infrastructure (assets, mixer/sound, Makefile demos target)"
```

---

## Task 2: demo/platformer.scm

Exercises: input, physics (gravity + tile collision + jump), renderer (tilemap + entities), world/scene, camera follow (x), audio (sound effect).

**Files:**
- Create: `demo/platformer.scm`

- [ ] **Step 1: Create demo/platformer.scm**

```scheme
(import scheme
        (chicken base)
        (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
        downstroke/entity
        downstroke/sound)

(define *game*
  (make-game
    title: "Demo: Platformer" width: 600 height: 400

    preload: (lambda (game)
      (init-audio!)
      (load-sounds! '((jump . "demo/assets/jump.wav")))
      (game-asset-set! game 'tilemap
        (load-tilemap "demo/assets/level-0.tmx")))

    create: (lambda (game)
      (let* ((tm  (game-asset game 'tilemap))
             (tex (tileset-image (tilemap-tileset tm)))
             (player (list #:type 'player
                           #:x 100 #:y 50
                           #:width 16 #:height 16
                           #:vx 0 #:vy 0
                           #:gravity? #t
                           #:on-ground? #f
                           #:tile-id 1)))
        (game-scene-set! game
          (make-scene
            entities:        (list player)
            tilemap:         tm
            camera:          (make-camera x: 0 y: 0)
            tileset-texture: tex))))

    update: (lambda (game dt)
      (let* ((input  (game-input game))
             (scene  (game-scene game))
             (tm     (scene-tilemap scene))
             (player (car (scene-entities scene)))
             ;; horizontal input
             (player (entity-set player #:vx
                       (cond
                         ((input-held? input 'left)  -3)
                         ((input-held? input 'right)  3)
                         (else 0))))
             ;; play jump sound when jump fires
             (_ (when (and (input-pressed? input 'a)
                           (entity-ref player #:on-ground? #f))
                  (play-sound 'jump)))
             ;; physics pipeline
             (player (apply-jump        player (input-pressed? input 'a)))
             (player (apply-acceleration player))
             (player (apply-gravity      player))
             (player (apply-velocity-x   player))
             (player (resolve-tile-collisions-x player tm))
             (player (apply-velocity-y   player))
             (player (resolve-tile-collisions-y player tm))
             (player (detect-ground      player tm)))
        ;; camera follows player x, clamped so we don't go negative
        (let ((cam-x (max 0 (- (entity-ref player #:x 0) 300))))
          (camera-x-set! (scene-camera scene) cam-x))
        ;; put player back
        (scene-entities-set! scene (list player))))))

(game-run! *game*)
```

- [ ] **Step 2: Verify it compiles**

```bash
cd /home/gene/src/downstroke
make demos
```

Expected: `bin/demo-platformer` is created with no errors.

- [ ] **Step 3: Smoke test — run and verify it opens a window**

```bash
./bin/demo-platformer
```

Expected: A window titled "Demo: Platformer" opens. Player entity (tile sprite) appears. Left/right moves it, J/Z triggers a jump with sound. Escape quits.

Note: Tile ID 1 may show the wrong sprite — that's expected. The spec says tile IDs are placeholder values to be adjusted visually.

- [ ] **Step 4: Commit**

```bash
git add demo/platformer.scm
git commit -m "feat: add platformer demo"
```

---

## Task 3: demo/shmup.scm

Exercises: entity spawning/removal, manual AABB collision, input, renderer (SDL colored rects in render: hook), world/scene (no tilemap), audio (sound effect on shoot).

The engine's `render-scene!` draws nothing for this scene (no tilemap). All visual output comes from the `render:` hook using `sdl2:render-fill-rect!`.

**Files:**
- Create: `demo/shmup.scm`

- [ ] **Step 1: Create demo/shmup.scm**

```scheme
(import scheme
        (chicken base)
        (prefix sdl2 "sdl2:")
        (prefix sdl2-ttf "ttf:")
        (prefix sdl2-image "img:")
        downstroke/engine
        downstroke/world
        downstroke/physics
        downstroke/input
        downstroke/entity
        downstroke/assets
        downstroke/sound)

;; Frame counter for enemy spawning
(define *frame-count* 0)

(define (make-bullet px py)
  (list #:type 'bullet #:x px #:y py #:width 4 #:height 8 #:vx 0 #:vy -6))

(define (make-enemy rx)
  (list #:type 'enemy #:x rx #:y 0 #:width 16 #:height 16 #:vx 0 #:vy 2))

(define (make-player)
  (list #:type 'player #:x 280 #:y 360 #:width 16 #:height 16 #:vx 0 #:vy 0))

;; Check collision between two entities using physics.scm's aabb-overlap?
(define (entities-overlap? a b)
  (aabb-overlap?
    (entity-ref a #:x 0) (entity-ref a #:y 0)
    (entity-ref a #:width 1) (entity-ref a #:height 1)
    (entity-ref b #:x 0) (entity-ref b #:y 0)
    (entity-ref b #:width 1) (entity-ref b #:height 1)))

;; Returns list of entities to remove (bullets and enemies that collide)
(define (find-collisions entities)
  (let ((bullets (filter (lambda (e) (eq? (entity-ref e #:type) 'bullet)) entities))
        (enemies  (filter (lambda (e) (eq? (entity-ref e #:type) 'enemy))  entities))
        (dead '()))
    (for-each
      (lambda (b)
        (for-each
          (lambda (en)
            (when (entities-overlap? b en)
              (set! dead (cons b (cons en dead)))))
          enemies))
      bullets)
    dead))

(define *game*
  (make-game
    title: "Demo: Shoot-em-up" width: 600 height: 400

    preload: (lambda (game)
      (init-audio!)
      (load-sounds! '((shoot . "demo/assets/jump.wav"))))

    create: (lambda (game)
      ;; No tilemap — render-scene! will draw nothing for this scene.
      ;; All drawing happens in the render: hook below.
      (game-scene-set! game
        (make-scene
          entities: (list (make-player))
          tilemap:  #f
          camera:   (make-camera x: 0 y: 0)
          tileset-texture: #f)))

    update: (lambda (game dt)
      (let* ((input   (game-input game))
             (scene   (game-scene game))
             (entities (scene-entities scene))
             (player  (car (filter (lambda (e) (eq? (entity-ref e #:type) 'player)) entities))))
        (set! *frame-count* (+ *frame-count* 1))

        ;; Move player left/right
        (let ((player (entity-set player #:vx
                        (cond
                          ((input-held? input 'left)  -4)
                          ((input-held? input 'right)  4)
                          (else 0)))))
          (let ((player (apply-velocity-x player)))
            ;; Clamp player to screen
            (let ((player (entity-set player #:x
                            (max 0 (min 584 (entity-ref player #:x 0))))))
              ;; Fire bullet on 'a'
              (when (input-pressed? input 'a)
                (play-sound 'shoot)
                (scene-add-entity scene
                  (make-bullet (+ (entity-ref player #:x 0) 6) 340)))

              ;; Spawn enemy every 60 frames
              (when (zero? (modulo *frame-count* 60))
                (scene-add-entity scene
                  (make-enemy (+ 20 (* (random 28) 20)))))

              ;; Update scene with current player
              (scene-entities-set! scene
                (cons player
                  (filter (lambda (e) (not (eq? (entity-ref e #:type) 'player)))
                          (scene-entities scene)))))))

        ;; Move bullets and enemies
        (scene-update-entities scene
          (lambda (e)
            (if (eq? (entity-ref e #:type) 'player)
                e
                (entity-set (entity-set e
                              #:x (+ (entity-ref e #:x 0) (entity-ref e #:vx 0)))
                            #:y (+ (entity-ref e #:y 0) (entity-ref e #:vy 0))))))

        ;; Remove bullet-enemy collisions
        (let ((dead (find-collisions (scene-entities scene))))
          (scene-filter-entities scene
            (lambda (e) (not (memq e dead)))))

        ;; Remove out-of-bounds bullets and enemies
        (scene-filter-entities scene
          (lambda (e)
            (let ((y (entity-ref e #:y 0)))
              (or (eq? (entity-ref e #:type) 'player)
                  (and (> y -20) (< y 420))))))))

    render: (lambda (game)
      (let* ((renderer (game-renderer game))
             (scene    (game-scene game))
             (entities (scene-entities scene)))
        (for-each
          (lambda (e)
            (let ((type (entity-ref e #:type 'unknown))
                  (x    (inexact->exact (floor (entity-ref e #:x 0))))
                  (y    (inexact->exact (floor (entity-ref e #:y 0))))
                  (w    (entity-ref e #:width 16))
                  (h    (entity-ref e #:height 16)))
              (sdl2:render-draw-color-set! renderer
                (case type
                  ((player) (sdl2:make-color 255 255 255 255))
                  ((bullet) (sdl2:make-color 255 255 0   255))
                  ((enemy)  (sdl2:make-color 255 50  50  255))
                  (else     (sdl2:make-color 100 100 100 255))))
              (sdl2:render-fill-rect! renderer
                (sdl2:make-rect x y w h))))
          entities)))))

(game-run! *game*)
```

- [ ] **Step 2: Verify it compiles**

```bash
make demos
```

Expected: `bin/demo-shmup` created with no errors.

- [ ] **Step 3: Smoke test**

```bash
./bin/demo-shmup
```

Expected: Black window. White player rectangle at bottom. J/Z fires yellow bullet upward (with sound). Red enemy rectangles fall from the top. Bullets disappear on contact with enemies. Escape quits.

- [ ] **Step 4: Commit**

```bash
git add demo/shmup.scm
git commit -m "feat: add shmup demo"
```

---

## Task 4: demo/topdown.scm

Exercises: input (8-directional), renderer (tilemap + entities), world/scene, camera follow (both axes), physics tile collision (no gravity).

**Files:**
- Create: `demo/topdown.scm`

- [ ] **Step 1: Create demo/topdown.scm**

```scheme
(import scheme
        (chicken base)
        (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
        downstroke/entity)

(define (clamp val lo hi) (max lo (min hi val)))

(define *game*
  (make-game
    title: "Demo: Top-down Explorer" width: 600 height: 400

    preload: (lambda (game)
      (game-asset-set! game 'tilemap
        (load-tilemap "demo/assets/level-0.tmx")))

    create: (lambda (game)
      (let* ((tm  (game-asset game 'tilemap))
             (tex (tileset-image (tilemap-tileset tm)))
             (player (list #:type 'player
                           #:x 100 #:y 100
                           #:width 16 #:height 16
                           #:vx 0 #:vy 0
                           #:gravity? #f
                           #:tile-id 1)))
        (game-scene-set! game
          (make-scene
            entities:        (list player)
            tilemap:         tm
            camera:          (make-camera x: 0 y: 0)
            tileset-texture: tex))))

    update: (lambda (game dt)
      (let* ((input  (game-input game))
             (scene  (game-scene game))
             (tm     (scene-tilemap scene))
             (player (car (scene-entities scene)))
             ;; 8-directional velocity
             (dx (+ (if (input-held? input 'left)  -3 0)
                    (if (input-held? input 'right)  3 0)))
             (dy (+ (if (input-held? input 'up)    -3 0)
                    (if (input-held? input 'down)    3 0)))
             (player (entity-set (entity-set player #:vx dx) #:vy dy))
             ;; tile collision on both axes
             (player (apply-velocity-x player))
             (player (resolve-tile-collisions-x player tm))
             (player (apply-velocity-y player))
             (player (resolve-tile-collisions-y player tm))
             ;; update camera to center on player
             (px (entity-ref player #:x 0))
             (py (entity-ref player #:y 0)))
        (camera-x-set! (scene-camera scene) (max 0 (- px 300)))
        (camera-y-set! (scene-camera scene) (max 0 (- py 200)))
        (scene-entities-set! scene (list player))))))

(game-run! *game*)
```

- [ ] **Step 2: Verify it compiles**

```bash
make demos
```

Expected: `bin/demo-topdown` created with no errors.

- [ ] **Step 3: Smoke test**

```bash
./bin/demo-topdown
```

Expected: Window with tilemap visible. Player sprite moves in 8 directions with WASD or arrow keys. Camera follows player on both axes. Escape quits.

- [ ] **Step 4: Commit**

```bash
git add demo/topdown.scm
git commit -m "feat: add topdown demo"
```

---

## Task 5: demo/audio.scm

Exercises: audio (sound effects + music), renderer (text via draw-ui-text), input, assets. No scene, no physics.

**Files:**
- Create: `demo/audio.scm`

- [ ] **Step 1: Create demo/audio.scm**

```scheme
(import scheme
        (chicken base)
        (prefix sdl2 "sdl2:")
        (prefix sdl2-ttf "ttf:")
        (prefix sdl2-image "img:")
        downstroke/engine
        downstroke/renderer
        downstroke/input
        downstroke/assets
        downstroke/sound)

;; Music toggle state
(define *music-on?* #f)

(define *game*
  (make-game
    title: "Demo: Audio" width: 600 height: 400

    preload: (lambda (game)
      (init-audio!)
      (load-sounds! '((jump . "demo/assets/jump.wav")))
      (load-music! "demo/assets/theme.ogg")
      (game-asset-set! game 'font
        (ttf:open-font "demo/assets/DejaVuSans.ttf" 20)))

    ;; No create: hook — no scene needed
    ;; engine.scm guards render-scene! with (when (game-scene game) ...)
    ;; so omitting game-scene-set! is safe.

    update: (lambda (game dt)
      (let ((input (game-input game)))
        ;; J = play jump sound
        (when (input-pressed? input 'a)
          (play-sound 'jump))
        ;; K/X = toggle music (mapped to 'b' in default input config)
        (when (input-pressed? input 'b)
          (if *music-on?*
              (begin (stop-music!) (set! *music-on?* #f))
              (begin (play-music! 0.5) (set! *music-on?* #t))))))

    render: (lambda (game)
      (let* ((renderer (game-renderer game))
             (font     (game-asset game 'font))
             (white    (sdl2:make-color 255 255 255 255))
             (gray     (sdl2:make-color 180 180 180 255)))
        ;; Background
        (sdl2:render-draw-color-set! renderer (sdl2:make-color 30 30 60 255))
        (sdl2:render-fill-rect! renderer (sdl2:make-rect 0 0 600 400))
        ;; Title
        (draw-ui-text renderer font "Audio Demo" white 220 80)
        ;; Instructions
        (draw-ui-text renderer font "J / Z   — play sound effect" gray 160 160)
        (draw-ui-text renderer font "K / X   — toggle music on/off" gray 160 200)
        (draw-ui-text renderer font "Escape  — quit" gray 160 240)
        ;; Music status
        (draw-ui-text renderer font
          (if *music-on?* "Music: ON" "Music: OFF")
          (if *music-on?*
              (sdl2:make-color 100 255 100 255)
              (sdl2:make-color 255 100 100 255))
          240 310)))))

(game-run! *game*)
```

**Note on key bindings:** The default input config maps `j`/`z` → `'a` action and `k`/`x` → `'b` action. So pressing J plays the sound and K toggles music. The display labels say "J / Z" and "K / X" accordingly. There is no direct key-to-symbol mapping in `*default-input-config*` for arbitrary keys; use the existing action names.

- [ ] **Step 2: Verify it compiles**

```bash
make demos
```

Expected: `bin/demo-audio` created with no errors.

- [ ] **Step 3: Smoke test**

```bash
./bin/demo-audio
```

Expected: Dark blue window with white text showing key bindings. J plays a sound. K toggles music (status shows ON/OFF in green/red). Escape quits.

- [ ] **Step 4: Commit**

```bash
git add demo/audio.scm
git commit -m "feat: add audio demo"
```

---

## Task 6: demo/sandbox.scm

Exercises: physics (gravity + tile collision + entity-entity collision), renderer, world/scene. No player input.

**Files:**
- Create: `demo/sandbox.scm`

- [ ] **Step 1: Create demo/sandbox.scm**

```scheme
(import scheme
        (chicken base)
        (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
        downstroke/entity)

;; Respawn timer (accumulates dt in milliseconds)
(define *elapsed* 0)
(define *respawn-interval* 10000)  ;; 10 seconds

(define (spawn-entities)
  (let loop ((i 0) (acc '()))
    (if (= i 10)
        acc
        (loop (+ i 1)
              (cons (list #:type 'box
                          #:x (+ 30 (* i 55))
                          #:y (+ 10 (* (random 4) 20))
                          #:width 16 #:height 16
                          #:vx 0 #:vy 0
                          #:gravity? #t
                          #:on-ground? #f
                          #:solid? #t
                          #:tile-id 1)
                    acc)))))

(define *game*
  (make-game
    title: "Demo: Physics Sandbox" width: 600 height: 400

    preload: (lambda (game)
      (game-asset-set! game 'tilemap
        (load-tilemap "demo/assets/level-0.tmx")))

    create: (lambda (game)
      (let* ((tm  (game-asset game 'tilemap))
             (tex (tileset-image (tilemap-tileset tm))))
        (game-scene-set! game
          (make-scene
            entities:        (spawn-entities)
            tilemap:         tm
            camera:          (make-camera x: 0 y: 0)
            tileset-texture: tex))))

    update: (lambda (game dt)
      (let* ((scene (game-scene game))
             (tm    (scene-tilemap scene)))
        ;; Advance respawn timer
        (set! *elapsed* (+ *elapsed* dt))
        (when (>= *elapsed* *respawn-interval*)
          (set! *elapsed* 0)
          (scene-entities-set! scene (spawn-entities)))

        ;; Physics pipeline for all entities
        (scene-update-entities scene
          apply-gravity
          apply-velocity-x
          (lambda (e) (resolve-tile-collisions-x e tm))
          apply-velocity-y
          (lambda (e) (resolve-tile-collisions-y e tm))
          (lambda (e) (detect-ground e tm)))

        ;; Entity-entity collision (push-apart, requires #:solid? #t)
        (scene-resolve-collisions scene)))))

(game-run! *game*)
```

- [ ] **Step 2: Verify it compiles**

```bash
make demos
```

Expected: `bin/demo-sandbox` created with no errors. All 5 `bin/demo-*` executables exist.

- [ ] **Step 3: Smoke test**

```bash
./bin/demo-sandbox
```

Expected: Window shows 10 tile sprites falling with gravity. They land on tilemap floor tiles, pile up, and push each other apart. After 10 seconds they respawn at random positions near the top. Escape quits.

- [ ] **Step 4: Final verification — make demos succeeds cleanly**

```bash
cd /home/gene/src/downstroke && make clean && make && make demos
```

Expected: Full clean build succeeds. All 5 demo binaries exist in `bin/`.

- [ ] **Step 5: Commit**

```bash
git add demo/sandbox.scm
git commit -m "feat: add sandbox demo"
```