romdev-mcp 0.1.1

package/src/platforms/gg/MENTAL_MODEL.md

@@ -0,0 +1,155 @@
+# Game Gear — mental model
+
+One page. Read once before you write your first GG game.
+
+## CPU + memory map
+
+```
+Z80A @ 3.58 MHz, 8 KB cartridge RAM (system RAM bigger via mapper).
+$0000-$3FFF  ROM bank 0 (fixed)
+$4000-$7FFF  ROM bank 1 (mapper-switchable via port $FE)
+$8000-$BFFF  ROM bank 2 (mapper-switchable via port $FF)
+$C000-$DFFF  Work RAM
+$E000-$FFFB  Work RAM mirror
+$FFFC-$FFFF  Mapper control registers
+```
+
+Most 32 KB scaffolds fit in banks 0+1 and never touch the mapper.
+
+## VDP (display)
+
+GG VDP = SMS VDP in Mode 4, smaller visible viewport.
+
+- **Framebuffer:** 256×192 (same as SMS)
+- **Visible:** 160×144 centered (48 px border each side, 24 px top/bottom)
+- **Modes:** only Mode 4 (256×192 tile + sprite) is useful — the other
+  TMS9918 modes are inherited but not used.
+- **Palette:** 32 entries × 12-bit BGR (4-4-4) — twice the depth of
+  SMS. Each CRAM entry is 2 little-endian bytes. BG entries 0-15,
+  sprite entries 16-31.
+- **Tile size:** 8×8, 4bpp planar. 448 tile slots × 32 bytes each.
+- **Sprites:** 64 SAT entries, 8×8 or 8×16 mode. **Hardware limit: at
+  most 8 sprites per scanline.** Extra sprites on the same row are
+  silently dropped by the VDP — symptom is "the first 8 letters of
+  my 14-letter title render, the rest are invisible." For text
+  overlays > 8 chars on the same row, split across multiple Y rows
+  OR draw the text via the BG name table (no per-line limit).
+
+**Always render gameplay content inside (48, 24)..(207, 167)** so it's
+visible on real hardware. The bundled scaffolds work without this
+because gpgx shows the full framebuffer.
+
+### Sprite coords are hardware-space, NOT visible-space
+
+The libretro core's screenshot returns only the 160×144 visible region,
+but the bytes you write to OAM are still in 256×192 hardware
+coordinates. An 8×8 sprite at OAM `(X=48, Y=24)` appears at the
+**top-left of the visible region** (which is the same hardware-coord
+`(48, 24)`). The visible region is OAM `x ∈ [48, 207]`, `y ∈ [24, 167]`.
+
+To center a sprite on screen: target OAM `(48 + 76, 24 + 68)` for
+roughly visible center, not `(80, 72)`.
+
+The `inspectSprites` tool's X/Y fields report hardware coords too —
+match them up with hardware-coord arithmetic, not visible-coord.
+
+### SAT $D0 terminator — still a hazard if you write $D0 yourself
+
+The SMS/GG renderer treats Y=$D0 in **any** OAM Y byte as a HARD
+terminator — it stops scanning further sprite slots the moment it
+hits one. Earlier rounds of the bundled `gg_sprite_init()` wrote
+$D0 to every Y byte to "hide" sprites at boot — that caused the
+classic "I populated slots 0..5 and slot 6 was still $D0 so the
+renderer halted at slot 5" footgun.
+
+**The runtime now initialises unused slots to $E0** (off-screen,
+below the 192-line area, but NOT the terminator). Slots you don't
+touch stay invisible AND don't kill the renderer. You only have
+to worry about $D0 if you write it explicitly — e.g. to stop
+sprite scanning early as an optimisation.
+
+If sprites past a certain slot are missing in `inspectSprites`,
+check the live OAM Y bytes for $D0 in a slot before them. That's
+still the diagnosis; the runtime just doesn't create the problem
+on its own anymore.
+
+### R6 sprite-tile-base default: $0000, NOT $2000
+
+`gg_vdp_init()` sets R6 = 0xFB. R6 bit 2 is the SA13 select for
+sprite tile data — and bit 2 is **CLEAR** in 0xFB. That means
+sprite tiles read from `$0000-$1FFF`, **sharing the bank with BG
+tiles**. Many references (including the older comments we just
+fixed in `vdp_init.c` and `load_tiles.c`) say "R6=0xFB → sprite
+tiles at $2000" — that's wrong.
+
+If you want sprite tiles in their own bank at $2000, set
+`vdp_write_reg(6, 0xFF)` AND upload tiles to VRAM $2000. Otherwise
+upload sprite tiles to $0000 alongside BG tiles (just make sure
+they don't collide).
+
+The `inspectSprites` tool's `spriteTileDataBase` field reports the
+address the VDP is actually reading from — trust that over any
+comment.
+
+## I/O port map
+
+```
+$06   PSG stereo control (write — L/R routing per channel)
+$3E   memory control (mostly leave alone)
+$3F   I/O control (mostly leave alone)
+$7E   read = V-counter; write = ignored
+$7F   read = H-counter; write = PSG (4-channel SN76489)
+$BE   VDP data
+$BF   VDP control (address + register write)
+$DC   joypad A — D-pad + B1 + B2 (active low)
+$DD   joypad B — extra (mostly unused on GG)
+$00   GG-specific: bit 7 = START button (active low)
+$01-$05  GG-specific: link cable, sound balance, etc.
+```
+
+## Audio
+
+SN76489 PSG — same chip as SMS + Genesis. 4 channels: 3 squares + 1 noise.
+
+Write-only via port `$7F`. See `gg_sfx.h`/`gg_sfx.c` for the canonical
+wrapper (sfx_init / sfx_tone / sfx_noise / sfx_update / sfx_off — same
+function shape as nes_runtime / gb_runtime / gba_sfx / genesis_sfx /
+sms_sfx).
+
+Optional: GG-only stereo register at port `$06` (bits 0-3 = which
+channels route to the right speaker, bits 4-7 = same for left).
+Defaults to mono — write `0xFF` for "all channels to both speakers"
+explicitly.
+
+## Frame heartbeat
+
+```c
+#include "gg_hw.h"
+#include "gg_sfx.h"
+
+void main(void) {
+    gg_vdp_init();
+    sfx_init();
+    gg_vdp_display_on();
+
+    while (1) {
+        gg_vblank_wait();
+        sfx_update();
+        /* update game state, stage SAT, etc. */
+    }
+}
+```
+
+## Differences from SMS — quick reference
+
+- Visible 160×144 vs 256×192 — center content
+- 12-bit CRAM vs 6-bit — palettes are 64 bytes vs 32
+- One controller only (no port 2)
+- START button at port $00 bit 7 (not on PORT_JOY_A)
+- Optional PSG stereo register at port $06
+- ROM header magic is identical to SMS ("TMR SEGA" at $7FF0)
+
+Everything else (Z80, VDP control protocol, tile format, sprite SAT
+layout, joypad polling, BG name table at $3800) is identical to SMS.
+You can use sms_hw.h notes + helpers as a reference; the GG runtime
+files in lib/c/ are direct ports.

package/src/platforms/gg/TROUBLESHOOTING.md

@@ -0,0 +1,91 @@
+# Game Gear — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(`getPlatformDoc({platform:"gg", name:"mental_model"})`).
+
+## "ROM runs but content is off the screen"
+
+GG's visible viewport is **160×144 centered in a 256×192 framebuffer**.
+Anything you draw outside `(48, 24)..(207, 167)` is in the border —
+visible in headless emulator screenshots (gpgx shows the whole frame)
+but invisible on real hardware.
+
+The bundled scaffolds are direct ports of the SMS scaffolds and target
+the full 256×192 area. Works fine for development under gpgx; for
+shipping to a real GG, reposition sprite + tilemap content to the
+visible center.
+
+## "START button doesn't work"
+
+GG splits the START button onto a GG-specific port (`$00` bit 7,
+active low), separate from the D-pad/A/B which are on `$DC` like
+SMS. `gg_joypad_read()` already merges them — START shows up in bit 7
+of the returned byte (`JOY_START` mask).
+
+If you copied an SMS scaffold that uses PAUSE-as-START semantics
+(SMS pause button is at port $DD bit 4 IIRC), it won't work on GG;
+swap to JOY_START.
+
+## "Sound only comes out of one speaker"
+
+GG has a stereo control register at port `$06` that the SMS doesn't
+have. After power-on it defaults to a sensible state on real hardware
+but on some emulators / on real cartridge dev kits the L/R bits
+might be cleared. Force mono explicitly:
+
+```c
+__sfr __at 0x06 PORT_GG_PSG_STEREO;  /* already in gg_hw.h */
+PORT_GG_PSG_STEREO = 0xFF;  /* all 4 channels to both speakers */
+```
+
+(0xFF = bits 0-3 enable channels 0-3 on the right speaker, bits 4-7
+enable on the left.)
+
+## "Palette looks wrong — colors too saturated/wrong shade"
+
+GG palette is **4-4-4 BGR** (12 bits per entry) — twice as deep as
+SMS's 2-2-2. If you ported SMS palette bytes directly, you're feeding
+6-bit values into a 12-bit register and getting the wrong shade.
+
+Convert SMS palette bytes → GG palette bytes by reading the 2-2-2
+fields out of each SMS byte and shifting them to 4-4-4 nibbles:
+
+```c
+uint16_t sms_to_gg(uint8_t sms_byte) {
+    uint8_t r = (sms_byte) & 0x03;        /* 2 bits */
+    uint8_t g = (sms_byte >> 2) & 0x03;
+    uint8_t b = (sms_byte >> 4) & 0x03;
+    /* Scale 0..3 -> 0..F by *5 (close enough for 4-bit). */
+    return (uint16_t)((r * 5) | ((g * 5) << 4) | ((b * 5) << 8));
+}
+```
+
+Then store as `low = (gg & 0xFF)`, `high = (gg >> 8) & 0xFF` for the
+two-byte little-endian CRAM entry.
+
+## "Linking error: undefined reference to sms_joypad_read_p2"
+
+GG only has one controller. The SMS scaffolds use `sms_joypad_read_p2`
+for the two-controller patterns (Pong, 2P shmup). When porting, drop
+the P2 read + force `p2 = 0` so the AI fallback always engages.
+
+The bundled GG `sports.c` already does this — copy that pattern when
+porting other SMS multiplayer code.
+
+## "Build errors mention 'TMR SEGA' or ROM header"
+
+Same magic as SMS — gpgx accepts headerless ROMs fine for development.
+For real-hardware ROM-burning include a header at $7FF0:
+
+```
+db "TMR SEGA"
+dw 0                  ; reserved
+dw 0                  ; checksum (gpgx ignores)
+db 0x00, 0x00, 0x00   ; product code BCD
+db 0x00               ; product code high + version
+db 0x40               ; region (0x40 = GG)
+db 0x4C               ; ROM size (0x4C = 32 KB)
+```
+
+The bundled scaffolds build without a header — sufficient for the
+emulator-driven workflow. Add one before shipping to a cartridge.

package/src/platforms/gg/UPSTREAM_SOURCES.md

@@ -0,0 +1,36 @@
+# Game Gear — source you can read
+
+GG shares its toolchain (SDCC z80) + emulator (genesis_plus_gx) +
+most of the runtime with SMS (`sms_crt0.s` ≡ `gg_crt0.s` byte-for-
+byte; PSG protocol identical). The GG tree at `src/platforms/gg/`
+holds the GG-specific scaffolds and runtime helpers; SMS docs apply
+for everything else.
+
+GG-specific:
+- Visible viewport 160×144 inside 256×192 framebuffer — content
+  must be centered
+- CRAM is 12-bit BGR (vs SMS's 6-bit) — 64 bytes vs 32
+- START button at port $00 bit 7 (not on PORT_JOY_A)
+- Optional stereo via PSG stereo register at port $06
+- One controller only — no port 2 fallback patterns
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/gg/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/gg/lib/c/*` — VDP, joypad,
+   sprite_table, sfx, music. All small + readable.
+3. **SDCC z80 port** — WASM compiler shipped, source not bundled.
+4. **Upstream**:
+
+   | What | Upstream |
+   |---|---|
+   | SDCC | http://sdcc.sourceforge.net/ |
+   | genesis_plus_gx libretro | https://github.com/libretro/Genesis-Plus-GX |
+
+## GG-specific docs
+
+- **SMS Power!** covers GG too: https://www.smspower.org/Development/Documents
+  (most pages have GG addendum or work identically)
+- **GG-specific extensions** (CRAM depth, START): SMS Power's GG section
+
+For everything else, see `../sms/UPSTREAM_SOURCES.md`.

package/src/platforms/gg/lib/c/gg_crt0.s

@@ -0,0 +1,112 @@
+;; Game Gear crt0 for SDCC. Byte-identical to sms_crt0.s — GG uses the
+;; same Z80 boot model as SMS: same vector table at $0000, same IRQ
+;; mode 1 vector at $0038, same NMI at $0066 (the GG's pause-equivalent
+;; is the START button on port $00, NOT NMI — but NMI is still vectored
+;; for safety).
+;;
+;; Why this exists separately from sms_crt0.s: every project under
+;; createProject({platform:"gg"}) should be self-contained. Cross-
+;; platform-by-construction: a `.gg` ROM rebuilds without romdev
+;; running. Don't read from sms/lib at build time.
+;;
+;; Replaces SDCC's stock z80 crt0 (which assumes a host runtime that
+;; handles I/O via rst $08 — not what a GG cartridge needs). This one
+;; boots cleanly into a real cartridge: vector table at $0000, sets
+;; SP to $DFF0, calls main().
+;;
+;; Use via:
+;;   buildSource({
+;;     platform: "gg",
+;;     sources: {
+;;       "main.c": ...,
+;;       "gg_crt0.s": ...this file...,
+;;     },
+;;     crt0: ".module empty\n",  // <-- empty stock crt0
+;;   })
+;;
+;; OR pass the contents of this file as `crt0` to runSdld.
+
+        .module gg_crt0
+        .globl  _main
+        .globl  l__INITIALIZER
+        .globl  s__INITIALIZER
+        .globl  s__INITIALIZED
+
+;; ─── Reset vector at $0000 ────────────────────────────────────────
+        .area _HEADER (ABS)
+        .org    0x0000
+        di                          ; interrupts off until we're ready
+        im      1                   ; mode 1 — IRQs jump to $0038
+        ld      sp, #0xDFF0         ; GG/SMS stack (top of WRAM minus 16)
+        jp      gsinit              ; skip the interrupt vector table
+
+;; ─── RST handlers (default = return) ──────────────────────────────
+        .org    0x0008
+        ret
+        .ds     0x08 - 1
+        .org    0x0010
+        ret
+        .ds     0x08 - 1
+        .org    0x0018
+        ret
+        .ds     0x08 - 1
+        .org    0x0020
+        ret
+        .ds     0x08 - 1
+        .org    0x0028
+        ret
+        .ds     0x08 - 1
+        .org    0x0030
+        ret
+        .ds     0x08 - 1
+
+;; ─── IRQ vector at $0038 (IM 1) ───────────────────────────────────
+;; GG hits this on vblank IF VDP R1 bit 5 is set. Default = clear the
+;; VDP status flag and return. User code that wants a real ISR can
+;; install one by writing to (vdp_isr_ptr) and a `ld hl,(vdp_isr_ptr) /
+;; jp (hl)` shim — but for now a bare ei/reti keeps things simple.
+        .org    0x0038
+        push    af
+        in      a, (#0xBF)          ; read VDP status — clears IRQ flag
+        pop     af
+        ei
+        reti
+
+;; ─── NMI vector at $0066 ──────────────────────────────────────────
+;; GG has no Pause button — START is read from port $00 bit 7 instead.
+;; NMI is vectored for safety (some homebrew loaders trigger it).
+        .org    0x0066
+        retn
+
+;; ─── crt0 body ────────────────────────────────────────────────────
+;; Standard SDCC pattern: jump to a code area, run initializers, then
+;; call main. The initializer area is filled by sdcc when it sees
+;; global initializations.
+
+        .area   _HOME
+        .area   _CODE
+        .area   _GSINIT
+        .area   _GSFINAL
+
+        .area   _DATA
+        .area   _INITIALIZED
+        .area   _BSEG
+        .area   _BSS
+        .area   _HEAP
+
+        .area   _CODE
+
+gsinit:
+        ld      bc, #l__INITIALIZER
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_done
+        ld      de, #s__INITIALIZED
+        ld      hl, #s__INITIALIZER
+        ldir
+
+gsinit_done:
+        call    _main
+hang:
+        halt
+        jr      hang

package/src/platforms/gg/lib/c/gg_hw.h

@@ -0,0 +1,62 @@
+/* Game Gear hardware register declarations for SDCC.
+ *
+ * GG = "SMS in a handheld" — same Z80, same VDP (Mode 4), same SN76489 PSG,
+ * same I/O port layout for SMS-compatible reads. Key differences:
+ *
+ *   1. Visible viewport is 160×144 (vs SMS 256×192). The framebuffer is
+ *      still 256×192 internally; only the centered 160×144 region shows.
+ *      Borders fill the rest. Always render game content centered.
+ *
+ *   2. Input is at port $DC (same as SMS) PLUS port $00 (GG-specific
+ *      START button). When porting an SMS game, START on GG requires a
+ *      separate read.
+ *
+ *   3. PSG has a stereo control register at port $06 (write-only). Each
+ *      of the 4 PSG channels can be routed to L, R, or both. Defaults
+ *      to mono (both speakers, all channels). We don't touch it; if you
+ *      want stereo, write to PORT_GG_PSG_STEREO directly.
+ *
+ *   4. ROM header is at the same $7FF0-$7FFF region but the "TMR SEGA"
+ *      magic is identical; gpgx accepts headerless ROMs fine.
+ *
+ * SDCC __sfr declares Z80 I/O ports: reading the variable compiles to
+ * `in a, (port)`, writing to `out (port), a`. So port I/O is plain C
+ * assignment.
+ */
+#ifndef GG_HW_H
+#define GG_HW_H
+
+#include <stdint.h>
+
+/* ─── VDP (SMS-compatible) ──────────────────────────────────────── */
+__sfr __at 0xBE PORT_VDP_DATA;
+__sfr __at 0xBF PORT_VDP_CTRL;
+
+/* ─── PSG / counters (SMS-compatible) ───────────────────────────── */
+__sfr __at 0x7E PORT_V_COUNTER;
+__sfr __at 0x7F PORT_H_COUNTER;     /* write = PSG */
+
+/* ─── SMS-style controller ports (D-pad + 1/2) ──────────────────── */
+__sfr __at 0xDC PORT_JOY_A;
+__sfr __at 0xDD PORT_JOY_B;
+
+/* ─── GG-specific extras ───────────────────────────────────────── */
+__sfr __at 0x00 PORT_GG_INPUT;       /* bit 7 = START (active low) */
+__sfr __at 0x06 PORT_GG_PSG_STEREO;  /* PSG L/R routing, write-only */
+
+/* ─── Joypad bits (active low — invert after read) ─────────────── */
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+#define JOY_LEFT  0x04
+#define JOY_RIGHT 0x08
+#define JOY_B1    0x10
+#define JOY_B2    0x20
+#define JOY_START 0x80  /* on GG_INPUT bit 7, NOT on JOY_A */
+
+/* ─── VDP address-set prefixes ──────────────────────────────────── */
+#define VDP_VRAM_WRITE 0x40
+#define VDP_VRAM_READ  0x00
+#define VDP_REG_WRITE  0x80
+#define VDP_CRAM_WRITE 0xC0
+
+#endif

package/src/platforms/gg/lib/c/gg_music.c

@@ -0,0 +1,155 @@
+/* gg_music.c — Game Gear SN76489 PSG music driver.
+ *
+ * Plays a hand-authored note table on a dedicated PSG channel, one note
+ * per frame-tick. Companion to gg_sfx (which keeps ch 0/1 free for
+ * fire-and-forget sound effects and ch 3 for noise — we own ch 2).
+ *
+ * Protocol recap (port $7F, write-only):
+ *   Tone latch: bit7=1, bits6-5=channel, bit4=0, bits3-0=freq_low
+ *   Tone data : bit7=0, bits5-0=freq_high
+ *   Vol  latch: bit7=1, bits6-5=channel, bit4=1, bits3-0=attenuation
+ *
+ * Attenuation: 0=loudest, 15=silent (2 dB steps).
+ *
+ * Song table format (see gg_music.h music_note_t):
+ *   - .note = 10-bit PSG divider (0 = rest), .dur = frame count
+ *   - sentinel row {0, 0} marks end-of-song
+ *
+ * The note table IS the song — no compression, no compiler — you can
+ * read the melody right in this file. Add or edit songs by appending
+ * a music_note_t[] array and bumping music_song_count.
+ */
+
+#include "gg_music.h"
+#include "gg_hw.h"
+
+#define MUSIC_CHANNEL 2  /* PSG ch 2 — ch 0/1 reserved for gg_sfx */
+#define MUSIC_VOLUME  3  /* attenuation; lower = louder, 3 ≈ -6 dB */
+
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;            /* port $7F = PSG write port */
+}
+
+static void psg_set_tone(uint8_t ch, uint16_t freq) {
+  /* Two-byte latch+data for tone frequency. */
+  psg_write((uint8_t)(0x80 | (ch << 5) | (freq & 0x0F)));
+  psg_write((uint8_t)((freq >> 4) & 0x3F));
+}
+
+static void psg_set_attn(uint8_t ch, uint8_t attn) {
+  psg_write((uint8_t)(0x90 | (ch << 5) | (attn & 0x0F)));
+}
+
+/* ── Song 0: arpeggiated C-major motif ─────────────────────────────
+ * Source-visible: this IS the song. Each row = one note (or rest)
+ * and how many 60Hz frames to hold it. 30 frames = 0.5 s.
+ * Pattern: C major chord arpeggio up + down, then a melodic flourish.
+ */
+static const music_note_t song0[] = {
+  { NOTE_C4, 18 }, { NOTE_E4, 18 }, { NOTE_G4, 18 }, { NOTE_C5, 36 },
+  { NOTE_G4, 18 }, { NOTE_E4, 18 }, { NOTE_C4, 36 },
+  { NOTE_REST, 12 },
+  { NOTE_D4, 18 }, { NOTE_F4, 18 }, { NOTE_A4, 18 }, { NOTE_D5, 36 },
+  { NOTE_A4, 18 }, { NOTE_F4, 18 }, { NOTE_D4, 36 },
+  { NOTE_REST, 18 },
+  /* Melodic flourish — "shave and a haircut" feel */
+  { NOTE_G4, 18 }, { NOTE_C5, 18 }, { NOTE_C5, 18 },
+  { NOTE_D5, 18 }, { NOTE_C5, 36 }, { NOTE_REST, 12 },
+  { NOTE_E5, 18 }, { NOTE_C5, 36 },
+  { 0, 0 }, /* end-of-song sentinel */
+};
+
+/* ── Song 1: minor / spooky arpeggio (A minor) ────────────────────── */
+static const music_note_t song1[] = {
+  { NOTE_A3, 24 }, { NOTE_C4, 24 }, { NOTE_E4, 24 }, { NOTE_A4, 48 },
+  { NOTE_E4, 24 }, { NOTE_C4, 24 }, { NOTE_A3, 48 },
+  { NOTE_REST, 12 },
+  { NOTE_G3, 24 }, { NOTE_B3, 24 }, { NOTE_D4, 24 }, { NOTE_G4, 48 },
+  { NOTE_F4, 24 }, { NOTE_D4, 24 }, { NOTE_B3, 24 }, { NOTE_G3, 48 },
+  { 0, 0 },
+};
+
+/* ── Song 2: short jingle / fanfare ────────────────────────────────── */
+static const music_note_t song2[] = {
+  { NOTE_C5, 12 }, { NOTE_C5, 12 }, { NOTE_C5, 12 }, { NOTE_E5, 36 },
+  { NOTE_G4, 12 }, { NOTE_E4, 24 }, { NOTE_G4, 36 },
+  { NOTE_REST, 6 },
+  { NOTE_C5, 12 }, { NOTE_G4, 12 }, { NOTE_E4, 12 }, { NOTE_C4, 48 },
+  { 0, 0 },
+};
+
+static const music_song_t songs[] = {
+  { song0, 1 },  /* arpeggio — loops */
+  { song1, 1 },  /* minor — loops */
+  { song2, 0 },  /* fanfare — one-shot */
+};
+const uint8_t music_song_count = 3;
+
+/* ── Engine state ─────────────────────────────────────────────────── */
+static const music_note_t *cur_song;
+static uint8_t cur_song_loop;
+static uint16_t cur_pos;
+static uint8_t cur_remaining;  /* frames left on the current row */
+static uint8_t playing;
+
+void music_init(void) {
+  cur_song = 0;
+  cur_song_loop = 0;
+  cur_pos = 0;
+  cur_remaining = 0;
+  playing = 0;
+  /* Silence the music channel up front. */
+  psg_set_attn(MUSIC_CHANNEL, 0x0F);
+}
+
+static void start_row(void) {
+  uint16_t note = cur_song[cur_pos].note;
+  uint8_t dur  = cur_song[cur_pos].dur;
+  if (dur == 0) {
+    /* End sentinel. */
+    if (cur_song_loop) {
+      cur_pos = 0;
+      note = cur_song[0].note;
+      dur  = cur_song[0].dur;
+      if (dur == 0) {
+        /* Empty song — bail. */
+        music_stop();
+        return;
+      }
+    } else {
+      music_stop();
+      return;
+    }
+  }
+  if (note == NOTE_REST) {
+    psg_set_attn(MUSIC_CHANNEL, 0x0F);  /* silent rest */
+  } else {
+    psg_set_tone(MUSIC_CHANNEL, note);
+    psg_set_attn(MUSIC_CHANNEL, MUSIC_VOLUME);
+  }
+  cur_remaining = dur;
+}
+
+void music_play(uint8_t song_idx) {
+  if (song_idx >= music_song_count) return;
+  cur_song = songs[song_idx].notes;
+  cur_song_loop = songs[song_idx].loop;
+  cur_pos = 0;
+  playing = 1;
+  start_row();
+}
+
+void music_stop(void) {
+  playing = 0;
+  psg_set_attn(MUSIC_CHANNEL, 0x0F);
+}
+
+void music_update(void) {
+  if (!playing) return;
+  if (cur_remaining == 0) return;  /* defensive */
+  cur_remaining--;
+  if (cur_remaining == 0) {
+    cur_pos++;
+    start_row();
+  }
+}