romdev-mcp 0.1.1

package/src/platforms/sms/lib/README.md

@@ -0,0 +1,117 @@
+# SMS / Game Gear — quickstart
+
+The compressed version of "everything I had to learn the hard way
+building an SMS ROM with romdev."
+
+## Language: C is the default
+
+SDCC 4.4.0 + the bundled SMS-specific crt0 (`c/sms_crt0.s`) give you a
+clean C development path. `buildSource({platform:"sms", source: <C>})`
+auto-injects the crt0 so your `main()` runs as the cartridge reset
+handler with a proper vector table + IM 1 + SP=$DFF0.
+
+C-side hardware access uses SDCC's `__sfr __at <port>` declarations —
+see `c/sms_hw.h` for the standard port set. Reading the variable
+compiles to `in a,(port)`; writing compiles to `out (port),a`.
+
+ASM is also first-class — pass a `.s` source and it routes through
+sdasz80. The asm snippets below are the canonical implementations the
+C helpers wrap.
+
+### SDCC 4.4.0 quirks
+
+SDCC sm83/z80 is **C89-only** — no inline `for (int i = 0; ...)`, no
+mid-block declarations, no compound literals. The pre-flight linter
+catches these with the right file:line before SDCC's own (misleading)
+error messages get a chance to confuse you. See
+[`../../gb/lib/c/SDCC_GOTCHAS.md`](../../gb/lib/c/SDCC_GOTCHAS.md).
+
+The previously-documented "register-allocator crash family"
+(`dbuf_append_str NULL` assertion on for-loops with function calls,
+parallel array writes, multi-array indexed reads, etc.) was diagnosed
+on 2026-05-25 as the emscripten 64 KB default stack overflowing past
+`__data_end` and zeroing out the static `sm83_regs[]` table. Fixed by
+bumping the WASM stack to 8 MB. Those patterns compile cleanly now —
+no workarounds needed.
+
+## Snippets shipped in this directory
+
+| File | Purpose |
+|---|---|
+| `header.s` | The 16-byte TMR SEGA cartridge header at $7FF0. Required on real hardware; most emulators forgive its absence. |
+| `vdp_init.s` | Mode 4, 192-line, display OFF baseline VDP setup. Call once after reset; then upload palette/tiles/map, then enable display. |
+| `vblank_wait.s` | Two flavors: polling on `in a,($BF)` bit 7, and an IM 1 IRQ pattern with a WRAM flag. |
+| `joypad_read.s` | Reads ports $DC + $DD, inverts so pressed=1, stores in `_p1_state`/`_p2_state`. Includes button masks. |
+| `load_palette.s` | Bulk OTIR of 32 CRAM bytes (16 BG + 16 sprite) via the control-port $C0 prefix. |
+| `load_tiles.s` | Bulk OTIR into VRAM at an arbitrary destination. Handles >256 byte transfers (loops on outer page count). |
+| `sprite_table.s` | Uploads shadow OAM (256 bytes WRAM) → SAT VRAM region. Includes the (X,tile) pairs layout at $3F80. |
+
+Fetch any with `getStarterSnippet({platform:"sms", name:"<file>"})`.
+Pull them all at once with `getAllStarterSnippets({platform:"sms"})`.
+
+## The five gotchas that cost the most time
+
+### 1. VDP register writes need TWO out-of-order bytes
+
+To write VDP register `R`, you send a 16-bit value to control port $BF
+as two bytes:
+- FIRST byte = the value
+- SECOND byte = `$80 | R` (high bit signals "register write")
+
+If you reverse them you'll set the VRAM address pointer instead — a
+subtle bug that produces "the display works but later writes go to the
+wrong place." Always: `out ($BF), value` then `out ($BF), $80 | reg`.
+
+### 2. CRAM address-set prefix is $C0, VRAM is $40
+
+The VDP control port distinguishes destinations via the high bits of
+the second byte:
+- `$40 | hi` → VRAM write
+- `$00 | hi` → VRAM read
+- `$80 | reg` → register write
+- `$C0` → CRAM write (the LOW byte first must be the CRAM offset)
+
+Mixing these is the most common cause of "I uploaded my palette but the
+screen is still black" — you probably wrote to VRAM by accident.
+
+### 3. SAT terminator $D0
+
+If any Y byte in the sprite attribute table is $D0, the VDP stops
+processing sprites at that index and renders only the ones before it.
+Hide unused sprites with `Y = $D0`, not by setting them off-screen.
+Setting `Y = $FF` won't terminate, just put the sprite somewhere
+invisible — you waste a sprite slot.
+
+### 4. SMS palette is 6-bit, not 8-bit
+
+CRAM bytes are 2-2-2 BGR. So $3F is white (all channels max), $3 is
+pure red, $C is pure green, $30 is pure blue. Don't pass 0xFFFFFF and
+expect white — it'll truncate to $3F. Use `getPlatformPalettePng({platform:"sms"})`
+to see all 64 distinct colors and dither input art against them with
+imagemagick.
+
+### 5. Game Gear CRAM is 4-4-4 (12-bit BGR), 2 bytes per entry
+
+GG palettes are NOT swappable with SMS palettes. If you're writing
+cross-target code, use a `#ifdef GG` / `#ifdef SMS` switch in your
+asset pipeline. The image-to-tilemap tool dispatches on platform, but
+hand-authored palette tables need the platform-correct encoding.
+
+## VDP register reference (the 11 that matter)
+
+| Reg | Purpose | Common value |
+|---|---|---|
+| R0 | Mode control 1 | $36 (M4 on, line IRQ off, mask col 0) |
+| R1 | Mode control 2 | $E0 to enable display ($80 disables, bit 6 enables, bit 5 enables vblank IRQ) |
+| R2 | Name table base | $FF → $3800 (formula: `(reg & 0x0E) << 10`) |
+| R3 | Color table (M4 ignored) | $FF |
+| R4 | BG tile data base | $FF → $0000 (bit 2 selects $0000 vs $2000) |
+| R5 | Sprite attribute table | $7E → $3F00 (formula: `(reg & 0x7E) << 7`) |
+| R6 | Sprite tile data base | $FB → $2000 (bit 2 selects $0000 vs $2000) |
+| R7 | Border color | $00 = sprite palette entry 0 |
+| R8 | BG X scroll | 0 = no scroll |
+| R9 | BG Y scroll | 0 = no scroll |
+| R10 | Line IRQ counter | $FF = disabled |
+
+Decode the live values via `getRenderingContext({})` — it returns the
+fully-shifted base addresses so you don't redo the math.

package/src/platforms/sms/lib/c/joypad_read.c

@@ -0,0 +1,33 @@
+/* SMS joypad read — port $DC + $DD, inverted so pressed=1.
+ *
+ *     uint8_t p1 = sms_joypad_read();
+ *     if (p1 & JOY_RIGHT) { ... }
+ *     if (p1 & JOY_B1)    { fire(); }
+ */
+#include "sms_hw.h"
+
+uint8_t sms_joypad_read(void) {
+  uint8_t a = ~PORT_JOY_A;
+  return a & 0x3F;            /* low 6 bits = P1 D-pad + B1 + B2 */
+}
+
+/*
+ * Player 2's hardware layout is awkward — SMS splits P2 across two ports:
+ *   PORT_JOY_A bits 6-7  = P2 UP, P2 DOWN
+ *   PORT_JOY_B bits 0-3  = P2 LEFT, P2 RIGHT, P2 B1, P2 B2
+ * We reassemble into the same bit layout the agent already knows for P1:
+ *   bit 0 = UP, 1 = DOWN, 2 = LEFT, 3 = RIGHT, 4 = B1, 5 = B2.
+ * Returns 0 when no P2 controller is plugged in (all bits read high =
+ * "released" = 0 after inversion).
+ */
+uint8_t sms_joypad_read_p2(void) {
+  uint8_t a = ~PORT_JOY_A;          /* P2 UP in bit 6, DOWN in bit 7 */
+  uint8_t b = ~PORT_JOY_B;          /* P2 LEFT bit 0, RIGHT 1, B1 2, B2 3 */
+  uint8_t up    = (a >> 6) & 0x01;  /* bit 6 -> bit 0 */
+  uint8_t down  = (a >> 6) & 0x02;  /* bit 7 -> bit 1 */
+  uint8_t left  = (b << 2) & 0x04;  /* bit 0 -> bit 2 */
+  uint8_t right = (b << 2) & 0x08;  /* bit 1 -> bit 3 */
+  uint8_t b1    = (b << 2) & 0x10;  /* bit 2 -> bit 4 */
+  uint8_t b2    = (b << 2) & 0x20;  /* bit 3 -> bit 5 */
+  return (uint8_t)(up | down | left | right | b1 | b2);
+}

package/src/platforms/sms/lib/c/load_palette.c

@@ -0,0 +1,24 @@
+/* SMS palette loader — bulk upload to CRAM.
+ *
+ * SMS CRAM: 32 entries × 1 byte (2-2-2 BGR). White = 0x3F.
+ * GG CRAM:  32 entries × 2 bytes (4-4-4 BGR LE).
+ *
+ *     extern const uint8_t my_palette[32];
+ *     sms_load_palette(my_palette);
+ */
+#include "sms_hw.h"
+
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void sms_load_palette(const uint8_t *palette) {
+  uint8_t i;
+  sms_vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = palette[i];
+}
+
+/* Game Gear variant — uploads 64 bytes (32 entries × 2). */
+void gg_load_palette(const uint8_t *palette) {
+  uint8_t i;
+  sms_vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = palette[i];
+}

package/src/platforms/sms/lib/c/load_tiles.c

@@ -0,0 +1,32 @@
+/* SMS tile loader — upload bytes to VRAM at any destination.
+ *
+ * SMS tiles are 32 bytes each (4bpp interleaved). VRAM is 16 KB at
+ * $0000-$3FFF. Tile N lives at VRAM offset (N * 32).
+ *
+ *     extern const uint8_t my_tiles[];
+ *     sms_load_tiles(0x0000, my_tiles, sizeof(my_tiles));  // sprite bank
+ *
+ * Default R6=0xFB → sprite tiles read from $0000 (shared with BG tiles).
+ * If you want sprite tiles in their own bank at $2000, set R6=0xFF AND
+ * upload to $2000. Don't pick the address without checking R6.
+ */
+#include "sms_hw.h"
+
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count) {
+  uint16_t i;
+  sms_vdp_set_addr(vram_dest, VDP_VRAM_WRITE);
+  for (i = 0; i < byte_count; i++) PORT_VDP_DATA = src[i];
+}
+
+/* Write a single name-table cell. Default name table at $3800.
+ *   tile_idx: 0..511 (low 9 bits)
+ *   attr:     hflip = bit 1, vflip = bit 2, palette = bit 3, priority = bit 4
+ */
+void sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr) {
+  uint16_t addr = 0x3800 + ((uint16_t)row * 32 + col) * 2;
+  sms_vdp_set_addr(addr, VDP_VRAM_WRITE);
+  PORT_VDP_DATA = tile_idx;
+  PORT_VDP_DATA = attr;
+}

package/src/platforms/sms/lib/c/sms_crt0.s

@@ -0,0 +1,101 @@
+;; SMS / Game Gear crt0 for SDCC.
+;;
+;; Replaces SDCC's stock z80 crt0 (which assumes a host runtime that
+;; handles I/O via rst $08 — not what an SMS cartridge needs). This
+;; one boots cleanly into a real cartridge: vector table at $0000,
+;; standard SMS interrupt vectors, sets SP to $DFF0, calls main().
+;;
+;; Use via:
+;;   buildSource({
+;;     platform: "sms",
+;;     sources: {
+;;       "main.c": ...,
+;;       "sms_crt0.s": ...this file...,
+;;     },
+;;     crt0: ".module empty\n",  // <-- empty stock crt0
+;;   })
+;;
+;; OR pass the contents of this file as `crt0` to runSdld.
+
+        .module sms_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         ; 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) ───────────────────────────────────
+;; SMS 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 (Pause button on SMS) ────────────────────
+        .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/sms/lib/c/sms_hw.h

@@ -0,0 +1,53 @@
+/* SMS / Game Gear hardware register declarations for SDCC.
+ *
+ * SDCC's __sfr __at <PORT> declares a Z80 I/O port. Reading the variable
+ * compiles to `in a,(port)`; writing compiles to `out (port),a`. So you
+ * can write port I/O as plain C assignments:
+ *
+ *     PORT_VDP_CTRL = 0x80;       // out ($BF), a   ; reg-write prefix
+ *     uint8_t status = PORT_VDP_CTRL;  // in a, ($BF)
+ *
+ * Include this from your main.c. The declarations are __sfr — they don't
+ * allocate storage, just bind a name to a port number. Multiple translation
+ * units including this header is safe.
+ */
+#ifndef SMS_HW_H
+#define SMS_HW_H
+
+#include <stdint.h>
+
+/* ─── VDP ───────────────────────────────────────────────────────── */
+__sfr __at 0xBE PORT_VDP_DATA;   /* data port — read VRAM/CRAM, write VRAM/CRAM/REG */
+__sfr __at 0xBF PORT_VDP_CTRL;   /* control port — address-set + register write */
+
+/* ─── PSG / counters ────────────────────────────────────────────── */
+__sfr __at 0x7E PORT_V_COUNTER;  /* read = V-counter */
+__sfr __at 0x7F PORT_H_COUNTER;  /* read = H-counter; write = PSG (overloaded) */
+
+/* ─── Controllers ───────────────────────────────────────────────── */
+__sfr __at 0xDC PORT_JOY_A;      /* P1 D-pad + buttons 1+2, P2 D-pad */
+__sfr __at 0xDD PORT_JOY_B;      /* P2 buttons + reset/cart inserted */
+
+/* ─── Memory / cart control ─────────────────────────────────────── */
+__sfr __at 0x3E PORT_MEMORY_CTRL;
+__sfr __at 0x3F PORT_IO_CTRL;
+
+/* ─── Game Gear extras ($00-$06 + $C0..) ────────────────────────── */
+__sfr __at 0x00 PORT_GG_INPUT;
+__sfr __at 0x06 PORT_GG_PSG_STEREO;
+
+/* ─── Joypad bit masks (active LOW on the port — 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
+
+/* ─── VDP address-set high-byte prefixes ────────────────────────── */
+#define VDP_VRAM_WRITE 0x40
+#define VDP_VRAM_READ  0x00
+#define VDP_REG_WRITE  0x80
+#define VDP_CRAM_WRITE 0xC0
+
+#endif /* SMS_HW_H */

package/src/platforms/sms/lib/c/sms_music.c

@@ -0,0 +1,178 @@
+/* sms_music.c — 3-voice PSG tracker for SMS.
+ *
+ * Hand-authored song: a relaxed C-major arpeggio loop. Voice 0 carries
+ * the melody (octave-5/4 line), voice 1 plays a slower harmony, voice 2
+ * drives a walking bass. Each voice has its own independent step cursor
+ * + per-step countdown, so the three tracks can be different lengths
+ * and they'll polyrhythm naturally — voice 2 (bass) loops every 16
+ * steps, voice 1 (harmony) every 8, voice 0 (melody) every 16. The
+ * common period is 16 steps so the song lines up cleanly on the loop.
+ *
+ * Playback is purely time-driven: when a voice's frame counter hits 0
+ * we (a) advance the step cursor (wrapping at the track length), (b)
+ * write the new divider to the PSG via the SN76489 latch+data protocol,
+ * and (c) reload the frame counter from the new step's duration. We
+ * keep the volume latched at "loud" (attenuation 0) for tone channels
+ * while a note is held, and write attenuation 0xF (silent) on rests.
+ *
+ * Why not reuse sms_sfx.c's psg_write?
+ *   sms_sfx.c keeps psg_write static — its API is the high-level sfx_*.
+ *   We write the same byte directly to PORT_H_COUNTER ourselves so the
+ *   music driver is self-contained and doesn't entangle the two layers
+ *   (sfx auto-silences after N frames; music doesn't want that).
+ *
+ * Z80 / SDCC notes:
+ *   - C89 only: all locals declared at top of block (see SDCC_GOTCHAS).
+ *   - uint16_t divider table is in const ROM (declared `const`) — fine.
+ *   - All state in static RAM, no malloc.
+ */
+
+#include "sms_music.h"
+#include "sms_hw.h"
+
+/* ─── Note dividers (NTSC, 3.58MHz / 32) ───────────────────────────── */
+#define D_REST  0
+#define D_C3    855
+#define D_G3    570
+#define D_A3    509
+#define D_C4    427
+#define D_D4    381
+#define D_E4    339
+#define D_F4    320
+#define D_G4    285
+#define D_A4    254
+#define D_B4    226
+#define D_C5    214
+#define D_D5    191
+#define D_E5    170
+
+/* ─── Song data — parallel per-voice tracks ────────────────────────── */
+/* 60 fps; quarter ≈ 18 frames, half ≈ 36, eighth ≈ 9. */
+#define Q  18
+#define H  36
+#define E  9
+
+/* Voice 0 — melody (16 steps, ~3.2 sec/loop). Mary-had-a-little-lamb
+ * style line transposed to feel like a chiptune arpeggio. */
+static const uint16_t mel0_freq[16] = {
+  D_E5, D_D5, D_C5, D_D5, D_E5, D_E5, D_E5, D_REST,
+  D_D5, D_D5, D_D5, D_REST, D_E5, D_G4, D_G4, D_REST,
+};
+static const uint8_t  mel0_len[16] = {
+  Q, Q, Q, Q,  Q, Q, H, E,
+  Q, Q, H, E,  Q, Q, H, E,
+};
+
+/* Voice 1 — harmony / countermelody (8 steps, ~2.4 sec/loop). Holds
+ * thirds + fifths under the melody. */
+static const uint16_t mel1_freq[8] = {
+  D_G4, D_E4, D_F4, D_E4,
+  D_G4, D_C4, D_D4, D_E4,
+};
+static const uint8_t  mel1_len[8] = {
+  H, H, H, H,
+  H, H, H, H,
+};
+
+/* Voice 2 — bass (8 steps, ~3.2 sec/loop). Walking C/G/A/F pattern. */
+static const uint16_t mel2_freq[8] = {
+  D_C3, D_C3, D_G3, D_G3,
+  D_A3, D_A3, D_F4, D_G3,
+};
+static const uint8_t  mel2_len[8] = {
+  H, H, H, H,
+  H, H, H, H,
+};
+
+/* ─── Playback state ────────────────────────────────────────────────── */
+static uint8_t  cursor[3];      /* current step index per voice */
+static uint8_t  remaining[3];   /* frames left on current step */
+static uint8_t  playing;        /* nonzero = music_update() drives PSG */
+
+/* Track length per voice — kept as a tiny lookup so the step-advance
+ * code can stay branch-free across voices. */
+static const uint8_t track_len[3] = { 16, 8, 8 };
+
+/* ─── PSG write primitive (same byte to port $7F as sms_sfx.c) ────── */
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;
+}
+
+static void psg_silence(uint8_t channel) {
+  psg_write(0x90 | (channel << 5) | 0x0F);
+}
+
+static void psg_tone(uint8_t channel, uint16_t divider) {
+  psg_write(0x80 | (channel << 5) | (divider & 0x0F));
+  psg_write((divider >> 4) & 0x3F);
+  psg_write(0x90 | (channel << 5) | 0x00);   /* volume max */
+}
+
+/* Fetch the (freq, len) at step `s` of voice `v`. We keep the song
+ * tables typed individually for clarity rather than a 3-row 2D array;
+ * the compiler folds this switch into a jump table just fine. */
+static void fetch_step(uint8_t v, uint8_t s, uint16_t *freq_out, uint8_t *len_out) {
+  if (v == 0) {
+    *freq_out = mel0_freq[s];
+    *len_out  = mel0_len[s];
+  } else if (v == 1) {
+    *freq_out = mel1_freq[s];
+    *len_out  = mel1_len[s];
+  } else {
+    *freq_out = mel2_freq[s];
+    *len_out  = mel2_len[s];
+  }
+}
+
+static void start_step(uint8_t v) {
+  uint16_t f;
+  uint8_t  len;
+  fetch_step(v, cursor[v], &f, &len);
+  if (f == D_REST) {
+    psg_silence(v);
+  } else {
+    psg_tone(v, f);
+  }
+  remaining[v] = len;
+}
+
+void music_init(void) {
+  uint8_t i;
+  for (i = 0; i < 3; i++) {
+    cursor[i] = 0;
+    remaining[i] = 0;
+    psg_silence(i);
+  }
+  playing = 0;
+}
+
+void music_play(uint8_t song_idx) {
+  uint8_t i;
+  (void)song_idx;          /* one bundled song for now — future banks */
+  for (i = 0; i < 3; i++) {
+    cursor[i] = 0;
+    start_step(i);
+  }
+  playing = 1;
+}
+
+void music_update(void) {
+  uint8_t v;
+  if (!playing) return;
+  for (v = 0; v < 3; v++) {
+    if (remaining[v] > 0) {
+      remaining[v]--;
+    }
+    if (remaining[v] == 0) {
+      cursor[v]++;
+      if (cursor[v] >= track_len[v]) cursor[v] = 0;
+      start_step(v);
+    }
+  }
+}
+
+void music_stop(void) {
+  uint8_t i;
+  playing = 0;
+  for (i = 0; i < 3; i++) psg_silence(i);
+}

package/src/platforms/sms/lib/c/sms_music.h

@@ -0,0 +1,50 @@
+/* sms_music.h — tiny 3-voice tracker for the SMS SN76489 PSG.
+ *
+ * Sits on top of sms_sfx.{h,c}'s raw PSG write path. The "song" is a
+ * pair of parallel arrays: a list of (divider, duration_frames) events
+ * per voice, played back step-by-step. When the per-voice cursor hits
+ * the end of its track it loops back to step 0 — instant continuous
+ * music with no need for an asset pipeline.
+ *
+ * Three tone voices (ch 0/1/2). The noise channel (ch 3) is left alone
+ * so a game's sfx layer can keep using sfx_noise for hit/explosion FX.
+ *
+ * SN76489 frequency divider math (NTSC SMS):
+ *   Hz = 3579545 / 32 / divider     →    divider = 111861 / Hz
+ *
+ *   note    Hz       divider
+ *   C3      130.81   855
+ *   G3      196.00   570
+ *   C4      261.63   427
+ *   D4      293.66   381
+ *   E4      329.63   339
+ *   F4      349.23   320
+ *   G4      392.00   285
+ *   A4      440.00   254
+ *   B4      493.88   226
+ *   C5      523.25   214
+ *
+ * Use divider 0 to mean "rest" — the driver skips the PSG write and
+ * just counts the duration down before advancing to the next step.
+ *
+ * API mirrors sfx_*:
+ *
+ *   music_init()              — clear state, silence tone channels
+ *   music_play(song_idx)      — start playback at song step 0
+ *                               (song_idx reserved for future multi-song
+ *                                 banks; current build has one song)
+ *   music_update()            — call ONCE per frame from the vblank loop
+ *   music_stop()              — silence the 3 tone channels, halt playback
+ */
+
+#ifndef SMS_MUSIC_H
+#define SMS_MUSIC_H
+
+#include <stdint.h>
+
+void music_init(void);
+void music_play(uint8_t song_idx);
+void music_update(void);
+void music_stop(void);
+
+#endif

package/src/platforms/sms/lib/c/sms_sfx.c

@@ -0,0 +1,82 @@
+/* sms_sfx.c — SN76489 PSG driver for SMS / Game Gear.
+ *
+ * SN76489 latch protocol (write-only via port $7F):
+ *   Latch byte (bit 7 = 1):
+ *     bit 7    = 1 (latch)
+ *     bits 6-5 = channel (00=ch0, 01=ch1, 10=ch2, 11=ch3-noise)
+ *     bit 4    = 0 (frequency) | 1 (volume/attenuation)
+ *     bits 3-0 = low 4 bits of frequency, OR 4-bit attenuation (0=loud, 15=silent)
+ *   Data byte (bit 7 = 0):
+ *     bits 5-0 = high 6 bits of frequency
+ *
+ * To play a tone:
+ *   1. Latch: $80|chan<<5|0|(freq & 0x0F)
+ *   2. Data:  (freq >> 4) & 0x3F
+ *   3. Latch volume: $90|chan<<5|attenuation
+ *
+ * Noise uses a different latch (low 3 bits select shift rate / source):
+ *   $E0 | (mode_bit << 2) | rate
+ *   rate 0=clock/512, 1=clock/1024, 2=clock/2048, 3=use ch2 freq
+ *
+ * Attenuation is in 2 dB steps: 0=loudest, 15=off.
+ *
+ * Per-channel "frames-left" countdown drives auto-silence. sfx_update
+ * runs once per frame and silences a channel whose counter hits 0.
+ */
+
+#include "sms_sfx.h"
+#include "sms_hw.h"
+
+static uint8_t sfx_remaining[4];
+
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;            /* port $7F is the PSG write port */
+}
+
+void sfx_init(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    sfx_remaining[i] = 0;
+    /* Silence channel i (latch volume = 0xF = off). */
+    psg_write(0x90 | (i << 5) | 0x0F);
+  }
+}
+
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames) {
+  if (channel > 2) return;
+  /* Latch + data byte for frequency. */
+  psg_write(0x80 | (channel << 5) | (freq & 0x0F));
+  psg_write((freq >> 4) & 0x3F);
+  /* Volume at max (attenuation 0). */
+  psg_write(0x90 | (channel << 5) | 0x00);
+  sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* White noise, rate = clock/1024 (mid frequency). */
+  psg_write(0xE0 | 0x04 | 0x01);
+  /* Volume at max (channel 3 attenuation = 0). */
+  psg_write(0xF0);
+  sfx_remaining[3] = length_frames;
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        /* Silence channel i. */
+        psg_write(0x90 | (i << 5) | 0x0F);
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    psg_write(0x90 | (i << 5) | 0x0F);
+    sfx_remaining[i] = 0;
+  }
+}