romdev-mcp 0.1.1

package/src/platforms/snes/lib/audio/spc_driver.asm

@@ -0,0 +1,241 @@
+; SPC700 driver — command-driven SFX + music dispatcher.
+;
+; R46 extension: adds continuous music playback on voice 1 layered on
+; top of the R31 two-sample sfx system (voice 0). Voices 2-7 are free.
+;
+; Commands (sent by SNES via STA $2140 -> SPC reads $F4):
+;   $00 = no-op / release (resets edge detector)
+;   $01 = play sample 0 on voice 0 (shoot — sfx)
+;   $02 = play sample 1 on voice 0 (explosion — sfx)
+;   $03 = music start  (begin walking the song table at $5000)
+;   $04 = music stop   (silence voice 1, halt the row walker)
+;
+; Strategy for repeat triggers: SNES side writes $00 to $2140 first,
+; then the real command byte one frame later. Driver caches prev_cmd
+; in ARAM $00 and only dispatches on edge (new != prev). $00 acts as
+; the "release" that resets the edge detector.
+;
+; Music engine:
+;   - Song table starts at ARAM $5000. Each row is 3 bytes:
+;       db duration_ticks, pitch_lo, pitch_hi
+;     duration $00 = end-of-song marker → rewind to $5000 (looping).
+;   - Driver state at ARAM $01..$05:
+;       $01 music_on   (0/1)
+;       $02 song_ptr_lo
+;       $03 song_ptr_hi
+;       $04 tick_counter (counts SPC Timer 0 ticks down to 0 → next row)
+;   - Timing source: SPC Timer 0 at 62.5 Hz (target $80, base 8 kHz).
+;     Read $FD per loop pass; nonzero means at least one tick elapsed.
+;     We treat each $FD read as "advance tick_counter by 1" (loose but
+;     fine — at 62.5 Hz vs main loop spin rate we'll never miss many).
+;
+; CRITICAL: DSP $6C = FLG (not $5C — that's KOFF). Power-on FLG = $E0
+; (reset+mute set); must be cleared. Same hard-won lesson from R31.
+
+arch spc700
+norom
+org $0000
+base $0200
+
+start:
+  ; ── DSP init ────────────────────────────────────────────────────
+  ; Clear FLG (the real one at $6C)
+  mov $f2, #$6c
+  mov $f3, #$20
+
+  ; Zero echo regs
+  mov $f2, #$0d
+  mov $f3, #$00
+  mov $f2, #$2c
+  mov $f3, #$00
+  mov $f2, #$3c
+  mov $f3, #$00
+  mov $f2, #$4d
+  mov $f3, #$00
+  mov $f2, #$6d
+  mov $f3, #$00
+  mov $f2, #$7d
+  mov $f3, #$00
+
+  ; Sample directory $1000 → DIR=$10
+  mov $f2, #$5d
+  mov $f3, #$10
+
+  ; Master vol
+  mov $f2, #$0c
+  mov $f3, #$7f
+  mov $f2, #$1c
+  mov $f3, #$7f
+
+  ; Voice 0 vol (sfx)
+  mov $f2, #$00
+  mov $f3, #$7f
+  mov $f2, #$01
+  mov $f3, #$7f
+
+  ; Voice 0 pitch $1000 (sfx)
+  mov $f2, #$02
+  mov $f3, #$00
+  mov $f2, #$03
+  mov $f3, #$10
+
+  ; Voice 0 ADSR off, GAIN $7F
+  mov $f2, #$05
+  mov $f3, #$00
+  mov $f2, #$06
+  mov $f3, #$00
+  mov $f2, #$07
+  mov $f3, #$7f
+
+  ; Voice 1 vol (music) — slightly quieter so sfx still cuts through
+  mov $f2, #$10
+  mov $f3, #$50
+  mov $f2, #$11
+  mov $f3, #$50
+
+  ; Voice 1 ADSR off, GAIN $5F
+  mov $f2, #$15
+  mov $f3, #$00
+  mov $f2, #$16
+  mov $f3, #$00
+  mov $f2, #$17
+  mov $f3, #$5f
+
+  ; ── Timer 0 setup ───────────────────────────────────────────────
+  ; T0 target = $80 → 8000 Hz / 128 = 62.5 Hz ticks
+  mov $fa, #$80
+  ; Enable T0 (bit 0 of CONTROL $F1)
+  mov $f1, #$01
+  ; Prime the read register (any pending count is discarded)
+  mov a, $fd
+
+  ; ── State init ──────────────────────────────────────────────────
+  ; previous-command cache at ARAM $00 — seed with whatever $F4 has now
+  ; so we don't mistake the leftover upload-protocol byte as a command.
+  mov a, $f4
+  mov $00, a
+
+  ; music_on = 0
+  mov $01, #$00
+  ; song_ptr = $5000
+  mov $02, #$00
+  mov $03, #$50
+  ; tick_counter = 0 (forces immediate row load on first start)
+  mov $04, #$00
+
+main_loop:
+  ; ── 1. Command dispatch (edge-detected) ─────────────────────────
+  mov a, $f4
+  cmp a, $00
+  beq cmd_done           ; no change since last poll
+  mov $00, a             ; cache the new value
+  cmp a, #$01
+  beq play_shoot
+  cmp a, #$02
+  beq play_explosion
+  cmp a, #$03
+  beq music_start
+  cmp a, #$04
+  beq music_stop
+  ; fall through for $00 (release) — just cache, no action
+
+cmd_done:
+  ; ── 2. Music tick ───────────────────────────────────────────────
+  ; Skip music processing entirely if not playing.
+  mov a, $01
+  beq main_loop
+
+  ; Did Timer 0 fire? $FD auto-clears on read; nonzero = ≥1 tick.
+  mov a, $fd
+  beq main_loop
+
+  ; Advance tick_counter down by 1. When it hits 0, load next row.
+  mov a, $04
+  beq music_next_row
+  dec a
+  mov $04, a
+  bra main_loop
+
+; ── SFX handlers ──────────────────────────────────────────────────
+play_shoot:
+  mov $f2, #$04          ; SRCN for voice 0
+  mov $f3, #$00
+  mov $f2, #$4c          ; KON
+  mov $f3, #$01
+  bra cmd_done
+
+play_explosion:
+  mov $f2, #$04
+  mov $f3, #$01
+  mov $f2, #$4c
+  mov $f3, #$01
+  bra cmd_done
+
+; ── Music control ─────────────────────────────────────────────────
+music_start:
+  ; Reset song pointer to $5000, force immediate row fetch.
+  mov $02, #$00
+  mov $03, #$50
+  mov $04, #$00          ; tick_counter = 0 → next pass loads row 0
+  mov $01, #$01          ; music_on
+  bra cmd_done
+
+music_stop:
+  mov $01, #$00          ; music_on = 0
+  ; Key-off voice 1 (KOF bit 1 set in $5C; KOF is sticky until cleared)
+  mov $f2, #$5c
+  mov $f3, #$02
+  ; Then clear KOF so future KON triggers actually retrigger.
+  mov $f2, #$5c
+  mov $f3, #$00
+  bra cmd_done
+
+; ── Row loader ────────────────────────────────────────────────────
+; Reads 3 bytes [duration, pitch_lo, pitch_hi] from (song_ptr),
+; advances song_ptr by 3, programs voice 1, key-ons.
+; Duration of $00 → end-of-song; rewind to $5000 and reload row 0.
+;
+; Uses `mov a,[dp]+y` (direct-page indirect indexed by Y) where dp
+; = $02 (the pair $02/$03 holds the 16-bit ARAM song pointer).
+music_next_row:
+  mov y, #$00
+  mov a, ($02)+y         ; a = duration
+  cmp a, #$00
+  beq music_loop_end     ; duration 0 → end-of-song, rewind
+  mov $04, a             ; tick_counter = duration
+
+  ; pitch_lo at offset 1
+  mov y, #$01
+  mov a, ($02)+y
+  mov $f2, #$12          ; voice 1 PITCHL
+  mov $f3, a
+
+  ; pitch_hi at offset 2
+  mov y, #$02
+  mov a, ($02)+y
+  mov $f2, #$13          ; voice 1 PITCHH
+  mov $f3, a
+
+  ; SRCN for voice 1 = 0 (reuse shoot.brr as instrument waveform)
+  mov $f2, #$14
+  mov $f3, #$00
+
+  ; Key-on voice 1 (bit 1 of KON $4C)
+  mov $f2, #$4c
+  mov $f3, #$02
+
+  ; Advance song_ptr by 3
+  mov a, $02
+  clrc
+  adc a, #$03
+  mov $02, a
+  mov a, $03
+  adc a, #$00
+  mov $03, a
+  jmp main_loop
+
+music_loop_end:
+  ; Rewind song_ptr to $5000 and re-enter row loader.
+  mov $02, #$00
+  mov $03, #$50
+  jmp music_next_row

package/src/platforms/snes/lib/audio_pipeline.asm

@@ -0,0 +1,62 @@
+; SNES — audio pipeline overview (this is a doc snippet, not asm to .include).
+;
+; The SNES has a separate Sony SPC700 coprocessor that handles ALL sound.
+; The main 65816 CPU cannot make a beep — it can only upload a program +
+; sample data to the SPC700, then send commands telling it what to play.
+;
+; You write TWO programs:
+;   1. An SPC700 driver (arch spc700) — lives in ARAM, polls $F4 for
+;      command bytes from the main CPU, pokes DSP registers ($00-$7F)
+;      to start/stop voices.
+;   2. The 65816 uploader — runs once at boot. Walks the $BBAA handshake
+;      protocol at $2140-$2143 to copy your SPC driver bytes into ARAM,
+;      then jumps it.
+;
+; This MCP server provides:
+;   - `buildSource({platform:"spc700", source})` — assembles standalone
+;     SPC700 code to a flat raw binary (no SNES header, no padding).
+;     Write your driver in arch-spc700 .asm, build separately, then
+;     `.incbin` the resulting .bin into your SNES main.asm.
+;   - `pcmToBrr({pcmPath, outputPath, loop})` — encodes raw 16-bit signed
+;     PCM (mono, little-endian) into SNES BRR format. Generate the PCM
+;     yourself (sox, ffmpeg, mathematical square wave, AI-generated wav
+;     with the header stripped) and run it through this.
+;
+; What you write yourself:
+;   - The SPC driver (~150-300 bytes typical). Polls $F4 for command byte,
+;     reads sample index, pokes DSP $4C (KON) to trigger voice. See
+;     snesdev wiki "SPC700 reference" and "DSP" pages for register layout.
+;   - The 65816 IPL upload routine (~100-150 bytes). Sends $CC to $2140 to
+;     start the handshake, then streams the SPC blob byte-by-byte via the
+;     $BBAA/$BB+1 protocol described on the snesdev wiki "APU I/O" page.
+;   - Your `play_sfx N` API on the 65816 side: typically just `lda #N /
+;     sta $2140` and let the SPC driver react.
+;
+; What you put in your main.asm:
+;
+;   ; Late in ROM, the asset blobs.
+;   spc_image:
+;     incbin "spc_driver.bin"      ; from buildSource(platform:"spc700")
+;   spc_image_end:
+;
+;   brr_shoot:
+;     incbin "shoot.brr"           ; from pcmToBrr(pcmPath:"shoot.pcm")
+;   brr_shoot_end:
+;
+;   brr_hit:
+;     incbin "hit.brr"
+;   brr_hit_end:
+;
+;   ; Tables the IPL routine and SPC driver share by convention.
+;   spc_image_size: dw spc_image_end - spc_image
+;   spc_load_addr:  dw $0200       ; ARAM address the driver runs at
+;
+; Where to put samples in ARAM: typically right after the driver code,
+; aligned on a 9-byte boundary (BRR blocks). The driver should know
+; (compile-time or runtime) where samples start so it can build the
+; DSP sample directory ($XX00 = 4-byte entries, start addr + loop addr).
+;
+; Helpful references — the snesdev wiki pages "APU I/O", "SPC700 reference",
+; "BRR sample format", "DSP". These are the canonical specs. The actual
+; protocol is short (a 4-page wiki article); the trick is just getting all
+; four pieces aligned.

package/src/platforms/snes/lib/c/crt0.asm

@@ -0,0 +1,125 @@
+; crt0.asm — minimum boot stub for tcc-65816 C programs on SNES.
+;
+; What this does (in order):
+;   1. Reset vector lands here from hdr.asm. CPU starts in emulation mode.
+;   2. Switch to native 65816 mode (clc / xce). Stack at $1FFF.
+;   3. Set direct-page register to where tcc__r* registers live (page 0).
+;   4. Copy initialized C globals from ROM (.glob.data) → RAM (.globram.data).
+;   5. Zero the .bss segment.
+;   6. JSL into main() (the C entry point).
+;   7. Park CPU forever after main returns (stp).
+;
+; The "tcc__r*" naming is what tcc-65816 emits in its codegen — those
+; addresses must be in zero page so tcc's `sta.b tcc__r0` works as a
+; direct-page write (saves a byte on every reg-to-reg move).
+
+.include "hdr.asm"
+
+; ── Direct-page registers tcc-65816 reads/writes ────────────────────
+; Must live at BANK 0 SLOT 1 ORGA 0 so direct-page math works out.
+; ORGA 0 PRIORITY 1000 forces this RAMSECTION to live at $0000 and win
+; any address collision.
+.RAMSECTION ".registers" BANK 0 SLOT 1 ORGA 0 FORCE PRIORITY 1000
+tcc__registers dsb 0
+tcc__r0  dsb 2
+tcc__r0h dsb 2
+tcc__r1  dsb 2
+tcc__r1h dsb 2
+tcc__r2  dsb 2
+tcc__r2h dsb 2
+tcc__r3  dsb 2
+tcc__r3h dsb 2
+tcc__r4  dsb 2
+tcc__r4h dsb 2
+tcc__r5  dsb 2
+tcc__r5h dsb 2
+tcc__r9  dsb 2
+tcc__r9h dsb 2
+tcc__r10  dsb 2
+tcc__r10h dsb 2
+tcc__f2  dsb 2
+tcc__f2h dsb 2
+tcc__f3  dsb 2
+tcc__f3h dsb 2
+.ENDS
+
+; ── RAM section sentinels ──────────────────────────────────────────
+; tcc emits its globals into "globram.data" (RAM) and "glob.data" (ROM
+; init image). The crt0 copies one to the other at boot. Place both
+; sections so wlalink can compute SECTIONSTART/SECTIONEND symbols.
+.RAMSECTION "globram.data" BANK $7F SLOT 3 KEEP
+.ENDS
+
+.RAMSECTION ".bss" BANK $7E SLOT 2
+.ENDS
+
+.BANK 0
+.SECTION "glob.data" SEMIFREE ORG 0 KEEP
+.ENDS
+
+; ── Boot handlers ───────────────────────────────────────────────────
+.SECTION "EmptyVectors" SEMIFREE ORG 0
+EmptyHandler:
+    rti
+.ENDS
+
+.EMPTYFILL $00   ; pad unused ROM with $00 = BRK (will crash, which is louder than NOP)
+
+; ── tcc__start ─ the actual reset handler ─────────────────────────
+.SECTION ".start" SEMIFREE ORG 0
+
+.accu 16
+.index 16
+.16bit
+
+tcc__start:
+    sei                  ; disable interrupts until init is done
+    clc                  ; clear carry…
+    xce                  ; …then xchg to switch to native mode
+    rep   #$18           ; binary mode, X/Y 16-bit
+    ldx   #$1FFF
+    txs                  ; stack at $1FFF
+
+    rep   #$30           ; all registers 16-bit
+    ; direct page = tcc register file
+    lda.w #tcc__registers
+    tad
+
+    ; ── Copy initialized globals from ROM → RAM ───────────────────
+    ; SECTIONSTART/END_<name> are auto-defined by wlalink.
+    ldx   #0
+data_copy_loop:
+    cpx   #(SECTIONEND_glob.data-SECTIONSTART_glob.data)
+    bcs   data_copy_done
+    lda.l SECTIONSTART_glob.data,x
+    sta.l SECTIONSTART_globram.data,x
+    inx
+    inx
+    bra   data_copy_loop
+data_copy_done:
+
+    ; ── Zero the .bss section ────────────────────────────────────
+    ; Data bank to $7E so .bss writes hit the right address space.
+    pea   $7e7e
+    plb
+    plb
+
+    ldx   #(((SECTIONEND_.bss-SECTIONSTART_.bss) & $fffe) + 2)
+    beq   bss_clear_done
+bss_clear_loop:
+    dex
+    dex
+    stz.w $2000, x
+    bne   bss_clear_loop
+bss_clear_done:
+
+    ; ── Zero tcc's first two pseudo-registers (some codegen relies on this) ─
+    stz.b tcc__r0
+    stz.b tcc__r1
+
+    ; ── Call main ─────────────────────────────────────────────────
+    jsl   main
+
+    ; ── Park forever — exit code in tcc__r0 ──────────────────────
+    stp
+.ENDS

package/src/platforms/snes/lib/c/hdr.asm

@@ -0,0 +1,50 @@
+; hdr.asm — minimum SNES memory map + ROM header + interrupt vectors
+;          for tcc-65816 + wla-65816 + wlalink builds.
+;
+; This file is auto-included by tcc's emitted assembly (every translation
+; unit starts with `.include "hdr.asm"`). It defines the wla-dx memory
+; layout, the SNES cartridge header, and the interrupt vector table.
+;
+; LoROM, 32 KB ROM, SlowROM. No FASTROM / HIROM variants — those add
+; complexity that the minimum-viable C-on-SNES build doesn't need yet.
+
+.MEMORYMAP
+  SLOTSIZE $8000
+  DEFAULTSLOT 0
+  SLOT 0 $8000           ; PRG ROM mapped at $00:8000..$00:FFFF (LoROM mirror)
+  SLOT 1 $0000 $2000     ; direct page region — tcc__registers lives here
+  SLOT 2 $2000 $E000     ; scratch RAM region
+  SLOT 3 $0000 $10000    ; full BANK $7F (work RAM high)
+.ENDME
+
+.ROMBANKSIZE $8000
+.ROMBANKS 1
+
+.SNESHEADER
+  ID "ROMD"                   ; 4-char cart id
+  NAME "ROM-DEV-MCP C BUILD  " ; 21-char title — padded with spaces
+  SLOWROM
+  LOROM
+  CARTRIDGETYPE $00           ; ROM only
+  ROMSIZE $08                 ; 2 Mbits (1 × 32KB bank — header field uses log2 megs)
+  SRAMSIZE $00
+  COUNTRY $01                 ; USA
+  LICENSEECODE $00
+  VERSION $00
+.ENDSNES
+
+.SNESNATIVEVECTOR              ; Native-mode 65816 interrupt vectors
+  COP   EmptyHandler
+  BRK   EmptyHandler
+  ABORT EmptyHandler
+  NMI   EmptyHandler
+  IRQ   EmptyHandler
+.ENDNATIVEVECTOR
+
+.SNESEMUVECTOR                 ; Emulation-mode (6502-compatible) vectors
+  COP    EmptyHandler
+  ABORT  EmptyHandler
+  NMI    EmptyHandler
+  RESET  tcc__start             ; cold-boot entry point — defined in crt0
+  IRQBRK EmptyHandler
+.ENDEMUVECTOR

package/src/platforms/snes/lib/c/snes_sfx.c

@@ -0,0 +1,116 @@
+/* ── snes_sfx.c — SPC driver uploader + sfx + music dispatch ────────
+ *
+ * Direct C port of the apu_upload routine from
+ * rom-games/snes/invaders/main.asm. The protocol is well-known but
+ * timing-sensitive — every byte transfer requires a handshake with
+ * the SPC700 driver, which is why it's spelled out byte-by-byte here.
+ *
+ * Upload protocol (from Nintendo's "Audio Programming Manual"):
+ *   1. Wait for SPC to write $AA $BB into ports 0+1 (its boot ROM
+ *      handshake — says "I'm ready"). $2140 = $AA, $2141 = $BB.
+ *   2. Write destination ARAM address into ports 2+3 ($2142/$2143).
+ *   3. Write $01 to $2141 (kick command).
+ *   4. Write $CC to $2140 and wait for SPC to echo it back. Now
+ *      we're in upload mode.
+ *   5. For each byte: write byte to $2141, write index (mod 256) to
+ *      $2140, wait for SPC to echo the index.
+ *   6. To finish: write final destination into $2142/$2143, $00 into
+ *      $2141, then a "kick+2" command into $2140 telling SPC to
+ *      jump to the new code.
+ *
+ * The driver, once running, watches $F4 (= main side's $2140) and
+ * dispatches on edge-detected command changes.
+ *
+ * R46 update: payload size is now read from the linker-defined
+ * `apu_blob_end` symbol so the song table can grow without touching
+ * this file. The R46 driver added music engine state + an extra
+ * voice config (voice 1), bumping the driver from ~150 to ~230 bytes,
+ * and song data lives at ARAM $5000 — so the upload payload jumped
+ * from 9240 to ~20 KB.
+ */
+
+#include "snes_sfx.h"
+#include <snes/sound.h>
+
+/* The prebuilt SPC driver + sample bank + song table. Defined in
+ * snes_sfx_data.asm via `.incbin "apu_blob.bin"`; the matching end
+ * symbol lets us size the upload at runtime. */
+extern const u8 apu_blob[];
+extern const u8 apu_blob_end[];
+
+#define APU_LOAD_ADDR  0x0200
+
+/* EVERY wait below is BOUNDED. A wedged SPC (bad previous state, flaky
+ * boot) must NEVER hang the main CPU here — pre-R7 the kick/per-byte/jump
+ * waits were unbounded `while` spins, so a stalled upload froze the whole
+ * game with a black screen (build succeeds, ROM boots, video never starts).
+ * Now each spin times out and sfx_init returns a distinct nonzero code so
+ * the caller can keep rendering (sound just won't play). ALWAYS call
+ * sfx_init AFTER setScreenOn() and check the return — see snes_sfx.h. */
+#define SFX_SPIN_LIMIT 0x8000u
+
+u8 sfx_init(void) {
+    u16 i;
+    u16 to;
+    u8 jmp_cmd;
+    u16 blob_size = (u16)(apu_blob_end - apu_blob);
+    /* Wait for SPC700 boot handshake — it writes $AA into $2140 and
+     * $BB into $2141 once its internal ROM finishes initializing. */
+    u16 timeout = 0xFFFF;
+    while (REG_APU0001 != 0xBBAA) {
+        if (--timeout == 0) return 1;
+    }
+
+    /* Set destination address, kick command. */
+    REG_APU0203 = APU_LOAD_ADDR;
+    REG_APU01 = 0x01;
+
+    /* Kick handshake — write $CC to $2140 and wait for echo (bounded). */
+    REG_APU00 = 0xCC;
+    to = SFX_SPIN_LIMIT;
+    while (REG_APU00 != 0xCC) { if (--to == 0) return 2; }
+
+    /* Transfer apu_blob byte by byte. Index in $2140 doubles as the
+     * SPC's "ready for next byte" handshake (bounded per byte). */
+    for (i = 0; i < blob_size; i++) {
+        REG_APU01 = apu_blob[i];
+        REG_APU00 = (u8)(i & 0xFF);
+        to = SFX_SPIN_LIMIT;
+        while (REG_APU00 != (u8)(i & 0xFF)) { if (--to == 0) return 3; }
+    }
+
+    /* Finish: set entry-point address, $00 in $2141, then "index + 2"
+     * in $2140 (must be nonzero — if it would be zero, bump it). */
+    REG_APU0203 = APU_LOAD_ADDR;
+    REG_APU01 = 0x00;
+    jmp_cmd = (u8)((i + 2) & 0xFF);
+    if (jmp_cmd == 0) jmp_cmd = 1;
+    REG_APU00 = jmp_cmd;
+    to = SFX_SPIN_LIMIT;
+    while (REG_APU00 != jmp_cmd) { if (--to == 0) return 4; }
+
+    return 0;
+}
+
+void sfx_release(void) {
+    REG_APU00 = 0;
+}
+
+void sfx_play(u8 cmd) {
+    /* Release first so the driver's edge-detector sees a new event
+     * even if the same cmd was sent last call. */
+    REG_APU00 = 0;
+    REG_APU00 = cmd;
+}
+
+void sfx_music_play(void) {
+    /* Cmd 3 = start music. Release first for edge-detector. */
+    REG_APU00 = 0;
+    REG_APU00 = 3;
+}
+
+void sfx_music_stop(void) {
+    /* Cmd 4 = stop music. */
+    REG_APU00 = 0;
+    REG_APU00 = 4;
+}

package/src/platforms/snes/lib/c/snes_sfx.h

@@ -0,0 +1,96 @@
+/* ── snes_sfx.h — minimal SNES sound + music wrapper ────────────────
+ *
+ * SNES audio = SPC700 (separate CPU + 64 KB ARAM + 8-channel DSP).
+ * The 65816 main CPU has NO direct DSP access — it can ONLY talk to
+ * the SPC700 via four I/O ports at $2140-$2143 (also known as
+ * APUIO0-3 / REG_APU00-03).
+ *
+ * To make sound on SNES you need TWO things:
+ *   1. An SPC driver program (running on the SPC700, in ARAM).
+ *   2. Sample data (BRR-encoded) loaded into ARAM where the driver
+ *      knows to look for it.
+ *
+ * This wrapper takes the simpler path: ship a prebuilt "apu_blob"
+ * (driver + sample bank + song table) that gets uploaded to ARAM at
+ * $0200 during sfx_init(). Then to trigger sound you write a command
+ * byte to $2140 and the driver dispatches.
+ *
+ * Commands (matching the bundled spc_driver.asm):
+ *   0 = no-op / release         (call sfx_release between repeats)
+ *   1 = play sample 0 (shoot)   — sfx_play(1)
+ *   2 = play sample 1 (explosion) — sfx_play(2)
+ *   3 = start music              — sfx_music_play()
+ *   4 = stop  music              — sfx_music_stop()
+ *
+ * Voice assignment in the driver:
+ *   Voice 0 = sfx slot (one-shot, retriggered on cmds 1/2)
+ *   Voice 1 = music melody (driven by the song table walker, retriggers
+ *             on each row at the row's pitch)
+ *   Voices 2-7 = unused (room to extend the driver with more channels)
+ *
+ * The driver uses edge-detection on the command byte — to trigger
+ * the same command twice in a row you MUST send 0 (release) first
+ * then the real command. All wrapper helpers below handle that for you.
+ *
+ * Music engine details:
+ *   - The bundled song is a 16-step C-major-ish arpeggio (4 bars at
+ *     ~115 BPM) hand-authored in apu_blob.asm. It loops forever once
+ *     sfx_music_play() is called.
+ *   - To replace the song, edit apu_blob.asm's `song:` table (each row
+ *     is 3 bytes: duration_ticks at 62.5 Hz, pitch_lo, pitch_hi) and
+ *     re-run `node scripts/build-apu-blob.js`.
+ *
+ * Source files alongside this header:
+ *   apu_blob.bin        prebuilt SPC driver + sample bank + song
+ *   apu_blob.asm        asar source for the whole payload (driver +
+ *                       music engine + song table)
+ *   spc_driver.asm      reference copy of the driver only
+ *   shoot.brr           BRR-encoded "shoot" sample (also used as the
+ *                       instrument waveform for music voice 1)
+ *   explosion.brr       BRR-encoded "explosion" sample
+ *   sample_bank.bin     directory + samples assembled together
+ */
+
+#ifndef SNES_SFX_H
+#define SNES_SFX_H
+
+#include <snes/snestypes.h>
+
+/* Upload the bundled SPC driver + sample bank + song table into ARAM
+ * and kick it off. Takes ~60 ms (~20 KB transferred one byte at a time
+ * over the APUIO ports — the SPC's max rate).
+ *
+ * ⚠ CALL THIS *AFTER* setScreenOn(), AND CHECK THE RETURN. Every wait
+ * inside is bounded — a wedged SPC can no longer hang the main CPU — but
+ * if it returns nonzero, sound init failed and you should just keep
+ * running (the game renders fine without sound). Calling it BEFORE the
+ * screen is on, or spinning on it, is the classic "black screen, OAM
+ * stays zero, video never starts" footgun.
+ *
+ * Returns 0 on success; nonzero = failed (sound unavailable, keep going):
+ *   1 = SPC boot handshake timed out (weird SPC state from a prior run)
+ *   2 = kick-command echo timed out
+ *   3 = byte-transfer echo timed out (mid-upload)
+ *   4 = jump-command echo timed out */
+u8 sfx_init(void);
+
+/* Trigger a sound effect. cmd = 1 (shoot) or 2 (explosion); other
+ * values are no-ops. The driver auto-resets on cmd=0; this wrapper
+ * sends 0 before each non-zero command so back-to-back triggers work. */
+void sfx_play(u8 cmd);
+
+/* Send the explicit "release" / no-op (cmd 0). Useful if you've sent
+ * a play and want to allow a re-trigger of the SAME sound on the
+ * next frame. Most callers won't need this — sfx_play does it
+ * automatically. */
+void sfx_release(void);
+
+/* Start the bundled music loop on voice 1. Safe to call repeatedly —
+ * each call rewinds the song to row 0. */
+void sfx_music_play(void);
+
+/* Stop the music (key-off voice 1, halt the row walker). Safe to
+ * call when music isn't playing. */
+void sfx_music_stop(void);
+
+#endif