romdev-mcp 0.1.1

package/src/platforms/gba/MENTAL_MODEL.md

@@ -0,0 +1,203 @@
+# Game Boy Advance — mental model
+
+One page. Read once before you write your first GBA game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken;
+this is the "what's going on" version.
+
+## Runtimes (R28)
+
+Two C runtimes ship bundled. Pass `runtime:` to `buildSource` /
+`runSource` to pick:
+
+- **`"libtonc"` (default)** — Tonc-tutorial aligned. `#include <tonc.h>`,
+  TTE (Tonc Text Engine) for text via `tte_init_chr4c_default` +
+  `tte_write` / `tte_printf`, `tonccpy` / `toncset` for VRAM-safe copy,
+  `OBJ_ATTR` shadow buffer + `oam_copy` for sprite updates,
+  `key_poll` + `key_held`. Matches what every published tutorial at
+  gbadev.net teaches.
+- **`"libgba"`** — devkitPro's official SDK. `#include <gba.h>`,
+  `REG_DISPCNT`, `MODE3_FB`, `SPRITE_GFX`, `OAM`, `KEY_A`, etc. Opt in
+  with `runtime: "libgba"` (or legacy `libgba: true`).
+- **`"none"`** — bare gcc + newlib only. For people writing their own
+  abstractions or porting bare-metal code.
+
+Sound — both runtimes ship `gba_sfx.h` / `gba_sfx.c` (3 functions:
+`sfx_init` / `sfx_tone(channel, freq_period, length)` / `sfx_noise`)
+wrapping the DMG-compatible APU. Channels 3 (wave) + Direct Sound are
+left to user code (they need more setup than a one-call sfx helper).
+
+## CPU memory map (ARM7TDMI)
+
+```
+$00000000-$00003FFF  BIOS ROM (16 KB) — read-only firmware
+$02000000-$0203FFFF  EWRAM (256 KB) — slow but big main work RAM
+$03000000-$03007FFF  IWRAM (32 KB) — fast on-chip RAM
+$04000000-$040003FE  I/O registers (memory-mapped MMIO)
+$05000000-$050003FF  BG palette + OBJ palette (1 KB)
+$06000000-$06017FFF  VRAM (96 KB) — BG tile data, sprite tile data, framebuffer
+$07000000-$070003FF  OAM (1 KB) — sprite attributes
+$08000000-$09FFFFFF  Game Pak ROM (up to 32 MB) — your .gba lives here
+$0E000000-$0E00FFFF  Game Pak SRAM (64 KB) — battery-backed saves
+```
+
+The ARM7TDMI runs in two modes:
+- **ARM**: 32-bit instructions, 4 bytes each. Faster on the GBA's
+  32-bit IWRAM. Slower on 16-bit-wide ROM.
+- **Thumb**: 16-bit instructions, 2 bytes each. Significantly smaller
+  code. About the same speed as ARM on ROM (because ROM is 16-bit).
+  **Most GBA games default to Thumb** because ROM is the common case.
+
+`-mthumb` switches gcc into Thumb mode. `-mthumb-interwork` allows
+mixing ARM + Thumb in the same binary. libgba is built Thumb-interwork.
+
+## Display
+
+```
+240×160 pixels visible, 6 BG modes (0-5)
+
+Mode 0: 4 tile BGs, scrolling. The classic 2D Mario-style mode.
+Mode 1: 2 tile BGs + 1 affine BG (rotation/scale).
+Mode 2: 2 affine BGs only. Mode 7-style perspective.
+Mode 3: 240×160 BGR555 framebuffer at $06000000. 16-bit per pixel.
+Mode 4: 240×160 palettized 8bpp framebuffer + a back buffer. Faster.
+Mode 5: 160×128 BGR555 framebuffer + back buffer.
+```
+
+Most published GBA games use mode 0. The `MODE_3` path (used in our
+`gba_hello` template) is the simplest — write directly to the
+framebuffer like a modern game.
+
+## Sprites (OAM)
+
+128 sprite slots at $07000000. Each entry is 8 bytes:
+
+```
+attr0 (16 bits): Y position (8), affine flag, double-size, shape,
+                 256-color flag, mosaic, etc.
+attr1 (16 bits): X position (9), affine index OR hflip+vflip, size
+attr2 (16 bits): tile index (10), priority (2), palette (4)
+filler (16 bits)
+```
+
+Sprite tile data lives at $06010000-$06017FFF (32 KB = 1024 4bpp tiles
+or 512 8bpp tiles). Sprite palette at $05000200-$050003FF.
+
+libgba helpers: `SPRITE_GFX`, `OAM`, `SPRITE_PALETTE`. Compose attr
+fields via `OBJ_*` constants in `gba_sprites.h`.
+
+## Tile + map
+
+Mode 0 BG: each BG layer has a 32-tile-wide map at a configurable VRAM
+base (`REG_BGxCNT` selects). Tiles are 8x8 4bpp (or 8x8 8bpp); a map
+entry is 16 bits = 10-bit tile index + 4-bit palette + 2 flip bits.
+
+## Input
+
+```
+REG_KEYINPUT (read-only): bits ACTIVE-LOW (0 = pressed)
+  bit 0: A    bit 1: B     bit 2: Select  bit 3: Start
+  bit 4: R   bit 5: L      bit 6: U       bit 7: D
+  bit 8: R-shoulder         bit 9: L-shoulder
+```
+
+libgba wraps this: `KEY_A`, `KEY_B`, etc. masks; `REG_KEYS` returns
+the inverted byte so pressed = 1.
+
+## Sound
+
+Two parallel paths:
+
+1. **Tone channels** (4): identical to GBC — 2 squares + 1 wave + 1 noise.
+   Backwards-compatible with GBC games. Programmed via $04000060 +.
+2. **Direct Sound** (2): 8-bit PCM channels with DMA streaming. The
+   modern path for sample-based music. Programmed via $04000082 + DMA.
+
+libgba sound API in `gba_sound.h` covers the tone channels but the
+DMA-driven PCM streaming is something you'd typically pair with
+maxmod (separate library, not bundled here).
+
+**For scaffold-level sfx**, the libtonc runtime ships a minimal
+`gba_sfx.h` / `gba_sfx.c` pair (3 functions: `sfx_init`, `sfx_tone`,
+`sfx_noise`) that wraps the DMG-compatible APU directly. Same shape
+as the NES/GB scaffold sound API, so cross-platform game ports feel
+the same. All 5 GBA genre scaffolds (shmup/platformer/puzzle/sports/
+racing) use it.
+
+## Frame heartbeat
+
+```c
+/* libtonc setup — REQUIRED before any VBlankIntrWait() call. */
+irq_init(NULL);
+irq_add(II_VBLANK, NULL);
+
+while (1) {
+    VBlankIntrWait();    /* halts CPU until vblank IRQ fires */
+    /* update game state */
+    /* write to OAM / VRAM */
+}
+```
+
+`VBlankIntrWait()` calls a BIOS function that puts the CPU to sleep
+until the vblank IRQ fires. **You MUST install the IRQ table BEFORE
+the first call** (`irq_init(NULL)` + `irq_add(II_VBLANK, NULL)` with
+libtonc — `irqInit(NULL)` + `irqEnable(IRQ_VBLANK)` with libgba).
+Without this, the BIOS halts the CPU forever waiting for an IRQ that
+never fires. ROM appears to compile + load but freezes on frame 1 —
+single most common GBA gotcha. Every bundled scaffold does it; copy
+the pattern.
+
+## Cart header format
+
+```
+$00-$03  ARM 'b' instruction branching to your _start
+$04-$9F  Nintendo logo (156 bytes) — required for real-hardware boot
+$A0-$AB  Game title (12 ASCII chars)
+$AC-$AF  Game code
+$B0-$B1  Maker code
+$B2-$BB  Header bytes (unit code, device type, version, complement check)
+$BC-$BF  Reserved
+```
+
+mGBA does NOT enforce the Nintendo logo (which is good — bundling it
+would be a copyright issue). The `gba_crt0.s` we ship leaves it as
+zeros. Real-hardware ROMs need it; mGBA and our test pipeline run
+fine without it.
+
+## Build pipeline
+
+When you call `buildSource({platform:"gba", language:"c"})`:
+
+1. `cc1-arm` (gcc 14.2.0 C frontend, WASM) compiles your `.c` → `.s`
+   ARM assembly (Thumb-interwork mode, `-mcpu=arm7tdmi`).
+2. `arm-none-eabi-as` (binutils, WASM) assembles each `.s` → `.o`.
+3. `arm-none-eabi-ld` (binutils, WASM) links user `.o` + bundled
+   `gba_crt0.o` + `crti.o` + `crtbegin.o` + a tiny `fake_heap_end`
+   stub + `libgba.a` + `libgcc.a` + `libc.a` + `libnosys.a` +
+   `crtend.o` + `crtn.o` per `gba_cart.ld` → ELF.
+4. `arm-none-eabi-objcopy` (binutils, WASM) extracts the raw `.gba`
+   ROM from the ELF.
+
+Loadable via mGBA (`loadMedia`).
+
+## What's NOT bundled
+
+- **libgba's `console.c`** (iprintf-style stdio output). Pulls in
+  devkitPro's libsysbase header chain — not yet ported. See
+  TROUBLESHOOTING.md for the trade-off rationale and workarounds.
+- **maxmod** (sample-based music driver). Separate library; not
+  bundled. Add manually if you need it.
+- **devkitARM's `bin2s`** (binary → assembly converter for asset
+  pipelines). Not bundled; ship binary assets as C arrays for now.
+
+Everything else from a stock devkitARM install works.
+
+## Horizontal scrolling (for side-scrollers)
+
+GBA tiled BG modes (0-2) give each BG layer a hardware scroll register —
+`REG_BG0HOFS` / `REG_BG0VOFS` (and BG1/2/3). Write the camera offset each
+frame; scroll a second layer at a fraction of camX for parallax. BG maps are
+32×32 (or larger via screen-block size); for a wider world, stream the column
+entering view into the map's screen-blocks as the camera advances. A fixed HUD
+goes on its own BG layer left unscrolled (or via an HBlank IRQ that resets the
+offset for the HUD scanlines). Track camX in pixels; actor screen-X = worldX -
+camX.

package/src/platforms/gba/TROUBLESHOOTING.md

@@ -0,0 +1,250 @@
+# Game Boy Advance — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(via `getPlatformDoc({platform:"gba", name:"mental_model"})`).
+
+## ⚠️ ROM compiles + loads but the screen never updates (frozen on frame 1)
+
+**Single most common GBA gotcha.** Symptom: `runSource` returns a
+black screen (or only the very first frame's contents, never any
+sprite/animation update). You added `VBlankIntrWait()` to the main
+loop — but the BIOS function halts the CPU **forever** waiting for a
+vblank IRQ to fire. You forgot to install the IRQ handler table.
+
+Fix — call BEFORE the first `VBlankIntrWait()`:
+
+```c
+/* libtonc */
+irq_init(NULL);
+irq_add(II_VBLANK, NULL);
+```
+
+```c
+/* libgba */
+irqInit();
+irqEnable(IRQ_VBLANK);
+```
+
+Both runtimes provide BIOS-VBlank-handling. With libtonc, `irq_init`
+installs the master handler + `irq_add(II_VBLANK, NULL)` registers a
+no-op for vblank (just so the IRQ fires + the BIOS counter increments).
+With libgba, `irqInit()` does both steps.
+
+Every bundled R28 scaffold (`tonc_hello`, `tonc_hello_sprite`, `shmup`,
+`platformer`, `puzzle`, `sports`, `racing`) sets this up — copy the
+pattern.
+
+## Text on screen
+
+**Use TTE (Tonc Text Engine) — that's the default runtime's path.**
+libtonc is the default GBA C runtime as of R28 and TTE handles text
+rendering without needing libsysbase:
+
+```c
+#include <tonc.h>
+
+int main(void) {
+    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
+    tte_write("Hello, GBA!\n");
+    tte_printf("Score: %d", score);
+    while (1) { VBlankIntrWait(); }
+}
+```
+
+`tte_write` + `tte_printf` render directly into BG tile maps — no
+libsysbase, no devkitPro setup, works out of the box with the
+bundled runtime.
+
+## ⚠️ iprintf doesn't work on the libgba path. Why?
+
+**Only an issue if you opt into `runtime: "libgba"` (the devkitPro
+SDK path) — the default libtonc runtime sidesteps this entirely with
+TTE.** Most devkitARM tutorials show `iprintf("Hello\n")` as the
+hello-world pattern. **This will NOT compile against our libgba build.**
+
+### Why we excluded it
+
+libgba's `console.c` provides iprintf-style stdio routing: writes get
+captured by devkitPro's libsysbase and rendered as text on a
+tile-based BG. Implementing that requires `<sys/iosupport.h>` +
+`<sys/statvfs.h>` + `<sys/dir.h>` + ~a dozen more libsysbase headers
+that vanilla newlib does NOT ship. Porting devkitPro's libsysbase to
+our toolchain is multi-day work that is currently deferred.
+
+The trade-off: we got `#include <gba.h>` working end-to-end and 95% of
+the libgba API. iprintf is the 5% missing. R28 added libtonc as the
+default precisely because TTE provides the same capability without
+the libsysbase dependency.
+
+### Workarounds — pick the one that fits your case
+
+#### 0. Just use the default libtonc runtime (easiest)
+
+`tte_write("Hello\n")` works out of the box. Drop the `runtime: "libgba"`
+flag from your `buildSource` call and use `#include <tonc.h>` instead
+of `#include <gba.h>`.
+
+#### 1. mGBA's BIOS debug interface (works on either runtime)
+
+mGBA exposes BIOS addresses that route writes to its debug console:
+
+```c
+#define MGBA_DEBUG_ENABLE  (*(volatile u16*)0x4FFF780)
+#define MGBA_DEBUG_LEVEL   (*(volatile u16*)0x4FFF700)
+#define MGBA_DEBUG_FLAGS   (*(volatile u16*)0x4FFF702)
+#define MGBA_DEBUG_STRING  ((volatile char*)0x4FFF600)
+
+void mgba_log(const char *msg) {
+    MGBA_DEBUG_ENABLE = 0xC0DE;
+    if (MGBA_DEBUG_ENABLE != 0x1DEA) return;  /* not mGBA */
+    int i;
+    for (i = 0; i < 255 && msg[i]; i++) MGBA_DEBUG_STRING[i] = msg[i];
+    MGBA_DEBUG_STRING[i] = 0;
+    MGBA_DEBUG_FLAGS = 2 | 0x100;  /* level 2 = info, send */
+}
+```
+
+Works in our test pipeline + lets the agent inspect logs via mGBA's
+state. Won't work on real hardware but real hardware isn't usually
+the loop you're iterating in.
+
+#### 2. Hand-roll a tile-text renderer
+
+About 30 lines of C. Upload an 8x8 font into VRAM, set up a BG with a
+character map, write tile indices for the chars you want. Slower to
+write than iprintf the first time but works on real hardware AND mGBA.
+
+#### 3. Install devkitPro natively + use their libgba
+
+Apt-install devkitPro (`apt install devkitpro-pacman` + `dkp-pacman -S
+gba-dev`), then build your project against THAT libgba.a — which has
+console.c + libsysbase. Works as a fallback if you genuinely need
+iprintf and the above two don't cut it. You lose romdev's zero-
+install promise but everything else still works.
+
+A deferred enhancement is to port libsysbase into our build so
+iprintf "just works."
+
+## Adding sound to a scaffold
+
+Both runtimes bundle `gba_sfx.h` + `gba_sfx.c` next to your `main.c`
+(courtesy of `createProject`). The shape:
+
+```c
+#include "gba_sfx.h"
+
+int main(void) {
+    sfx_init();                    /* once at startup */
+    sfx_tone(1, 1900, 4);          /* ch1 square wave, pew */
+    sfx_tone(2, 1300, 6);          /* ch2 square wave, blip */
+    sfx_noise(8);                  /* ch4 noise, explosion */
+}
+```
+
+`freq_period` is the GBA 11-bit frequency code. Hz ≈ 131072 / (2048 -
+freq_period). Useful values: 1900 = pew, 1500 = boing, 1300 = blip,
+800 = low thump. `length_frames` is the 64-step countdown (~3.9ms
+each, max 63). Channels 3 (wave RAM) + Direct Sound (PCM via DMA) are
+NOT wrapped — that's a music-track concern, not a sfx concern, and
+needs more setup than a one-call helper provides. Reach for maxmod
+(separate library, not bundled) when you want music + samples.
+
+## BG0 tile data disappears after TTE init
+
+If your BG0 grid renders fine in isolation but vanishes when you also
+init TTE on BG1, you've got a VRAM region collision. TTE writes the
+default 4bpp font into its destination char-block — if your BG0
+char-block overlaps it, the font load wipes your tiles.
+
+Fix: put BG0's char-block + screen-block well away from TTE's. The
+bundled `puzzle.c` uses BG0 at `BG_CBB(3) | BG_SBB(28)` while TTE
+runs on BG1 at `BG_CBB(2) | BG_SBB(30)`. Each char-block is 16 KB
+(holds 512 4bpp tiles) and each screen-block is 2 KB (one 32×32
+tilemap). Char-blocks 0+1 partially overlap screen-blocks 24-31 in
+VRAM, which is fine as long as you don't try to use both at the same
+addresses.
+
+## "ROM builds but the screen is black"
+
+Three common modes:
+
+1. **You forgot `REG_DISPCNT = MODE_x | BGn_ON`.** After reset the
+   GBA's DISPCNT is in "forced blank" mode (bit 7 set). libgba's
+   crt0 doesn't unblank for you — that's your `main()`'s job. Set
+   a video mode and turn on at least one BG.
+2. **You used MODE_3 but wrote to VRAM as bytes.** Mode 3 framebuffer
+   is u16 per pixel (BGR555). Writing single bytes to odd addresses
+   silently drops data (VRAM has 16-bit-write hardware). Use
+   `MODE3_FB[row][col] = RGB5(r,g,b);` or `*(u16*)addr = ...`.
+3. **You ran a `while (1) { }` immediately after main without
+   `VBlankIntrWait`.** The screen DOES render — but with no input
+   updates, no animation, the user thinks "nothing's happening."
+   Add an input + animation loop with `VBlankIntrWait`.
+
+## "Build fails with `undefined reference to '_init'` or `'fake_heap_end'`"
+
+These are devkitARM startup-code symbols. Our build pipeline
+auto-links `crti.o`/`crtn.o` (for `_init`) and a generated
+`fake_heap_end` stub. If you're seeing these errors, you're probably
+running `buildGbaC` against an old cached version of the toolchain
+script. Restart the MCP server.
+
+## "Build fails with `int8_t not defined` or `stdint.h not found`"
+
+The GBA C build mounts newlib + libgcc headers into `/work/` for the
+cc1 invocation. If you see this, your build is somehow missing the
+sysinclude/ tree. Verify
+`src/platforms/gba/lib/libgba/sysinclude/stdint.h` exists; if not,
+re-run `scripts/build-libgba.sh` which fetches devkitPro's
+iosupport.h + ships the toolchain's newlib headers.
+
+## "GCC complains about `__syscall_prlimit64`"
+
+That's a warning (not an error) from cc1's emscripten host runtime —
+the WASM build of cc1 references `prlimit64` for memory limits, but
+emscripten libc doesn't implement it. cc1 falls back to a default and
+proceeds. Ignore.
+
+## "ROM works in mGBA but won't boot on real hardware"
+
+Real hardware checks the Nintendo logo at $04-$9F (156 bytes). Our
+`gba_crt0.s` leaves it zeroed because including the actual logo
+bytes would be a copyright issue. To boot on real hardware:
+
+1. Build with our toolchain.
+2. Run devkitARM's `gbafix` tool on the output `.gba` — it patches in
+   the logo + checksum bytes. devkitPro distributes `gbafix` as part
+   of their host tools; install separately when you're shipping to
+   real cartridges.
+3. The result is real-hardware compatible.
+
+mGBA, VBA-M, and most other emulators skip the logo check.
+
+## "OAM doesn't update / sprites stuck"
+
+OAM is at $07000000. The GBA hardware locks OAM during HBlank/VBlank
+of certain modes. Writes outside the right window get dropped. Safest
+pattern: write OAM during VBlank (via `VBlankIntrWait` + then OAM
+updates immediately after).
+
+libgba helpers don't auto-defer to vblank — `OAM[i]` writes whenever
+you call them. If you're writing during the visible region with
+"hblank-interval-free" disabled in DISPCNT, the GBA freezes OAM and
+your writes are lost.
+
+## "First C build is slow (~1-2 s) but later ones are fast"
+
+Expected. The cc1.wasm is 141 MB unstripped — first invocation mmaps
+it into a worker, instantiates the module. Subsequent builds reuse the
+warm worker pool (R12). Steady-state builds are sub-second.
+
+A future optimization (R28?): rebuild cc1.wasm with `-O3 --strip-debug`
+to get it down to ~17 MB like the m68k toolchain has. Functionality
+is identical either way; just smaller bundle.
+
+## "Save states don't work on `.gba` ROMs"
+
+mGBA save states work — `saveState` / `loadState` MCP tools should
+function on any loaded GBA ROM. If you find a specific game where they
+don't, file an issue — most likely a mGBA-side bug, not ours.

package/src/platforms/gba/UPSTREAM_SOURCES.md

@@ -0,0 +1,41 @@
+# GBA — source you can read
+
+Trust hierarchy (try in order before filing a feedback round):
+
+1. **Bundled examples** (`examples/gba/templates/*.c`) — verified
+   compile + run. Start here.
+2. **Bundled runtime source** (`src/platforms/gba/lib/c/gba_sfx.c`) —
+   our APU wrapper. Read when sfx isn't doing what you expect.
+3. **Bundled library source** — libtonc + libgba + maxmod (R58):
+
+   | Library | Local source | Read this when |
+   |---|---|---|
+   | libtonc | `src/platforms/gba/lib/libtonc/src/` | `tte_init_X` / `oam_copy` / TTE behavior |
+   | libgba | `src/platforms/gba/lib/libgba/src/` | `irqInit`/`irqEnable`/`VBlankIntrWait` |
+   | maxmod | `src/platforms/gba/lib/maxmod/` (.s files already there) | `mmFrame`/`mmStart` audio timing |
+
+4. **Upstream GitHub** (NOT bundled — fetch on demand):
+
+   | What | Upstream |
+   |---|---|
+   | libtonc (Tonc) | https://github.com/devkitPro/libtonc |
+   | libgba | https://github.com/devkitPro/libgba |
+   | maxmod | https://github.com/devkitPro/maxmod |
+   | mGBA libretro core | https://github.com/libretro/mgba |
+   | mGBA proper | https://github.com/mgba-emu/mgba |
+   | arm-none-eabi-gcc | https://gcc.gnu.org/ + https://github.com/bminor/binutils-gdb |
+
+## GBA hardware docs
+
+- Pan-style canonical: **GBATEK** at https://problemkaputt.de/gbatek.htm
+- Tonc tutorial (best practical guide): https://www.coranac.com/tonc/text/
+- Cowbite Spec (alt register reference): https://www.cs.rit.edu/~tjh8300/CowBite/CowBiteSpec.htm
+
+## When to use what
+
+- "How does `tte_write` lay out tile data?" → `libtonc/src/tte/`
+- "What does `irqInit` install?" → `libgba/src/interrupt.c` (gnu_as section)
+- "How does maxmod's IRQ-driven mixer work?" → `maxmod/asm/mp_mixer_gba.s`
+- "Why does my BG3 show garbage on mGBA?" → GBATEK section 8 (Video)
+- "Does the bundled `gba_sfx_tone` set the trigger bit?" → our
+  `gba_sfx.c` source (50 lines).

package/src/platforms/gba/lib/c/gba_sfx.c

@@ -0,0 +1,81 @@
+/* ── gba_sfx.c — minimal GBA sound-effects wrapper ──────────────────
+ *
+ * GBA APU register summary (Tonc names):
+ *   REG_SND1SWEEP   ch1 sweep (NR10 equivalent)
+ *   REG_SND1CNT     ch1 control: duty + length + envelope (NR11/NR12)
+ *   REG_SND1FREQ    ch1 frequency + trigger + length-enable (NR13/NR14)
+ *   REG_SND2CNT     ch2 control (NR21/NR22)
+ *   REG_SND2FREQ    ch2 frequency (NR23/NR24)
+ *   REG_SND4CNT     ch4 noise control (NR41/NR42)
+ *   REG_SND4FREQ    ch4 noise freq + trigger (NR43/NR44)
+ *   REG_SNDDMGCNT   master DMG routing (NR50/NR51 — volume + L/R)
+ *   REG_SNDDSCNT    Direct Sound + DMG-vs-DS master volume
+ *   REG_SNDSTAT     power on/off (NR52); BIT 7 = master enable
+ *
+ * Register layouts on GBA = DMG layouts shifted into u16 pairs. The
+ * .L half = first byte (NR_1), .H half = second byte (NR_2). Or treat
+ * as one u16 with low/high bytes.
+ */
+
+#include "gba_sfx.h"
+#include <tonc_memmap.h>
+
+void sfx_init(void) {
+    /* Power-up sequence per GBA TRM 14.0:
+     *   1. Turn on master enable.
+     *   2. Set DMG-vs-DS volume (we go 100% DMG, no DS).
+     *   3. Route all 4 DMG channels to both speakers at max volume. */
+    REG_SNDSTAT   = 0x0080;     /* master enable (bit 7) */
+    REG_SNDDSCNT  = 0x0002;     /* DMG vol = 100% (bits 0..1 = 0b10) */
+    REG_SNDDMGCNT = 0xFF77;     /* NR51 = 0xFF (all 4 chans on L+R),
+                                 * NR50 = 0x77 (max master vol L+R) */
+}
+
+void sfx_tone(u8 channel, u16 freq_period, u8 length_frames) {
+    /* Length register: 64-step countdown. 0 = full duration, 63 = ~3.9ms.
+     * NR11/NR21 low 6 bits = (64 - length_frames). */
+    u16 len_code = (length_frames >= 63) ? 0 : (u16)(64 - length_frames);
+    u16 freq_lo  = (u16)(freq_period & 0x07FF);
+
+    /* SNDxCNT layout:
+     *   bits 0..5  = length (NR11 low 6 = 64 - count)
+     *   bits 6..7  = duty cycle (0b10 = 50%)
+     *   bits 8..10 = envelope step time (0 = no decay)
+     *   bit  11    = envelope direction (0 = decrease, here moot)
+     *   bits 12..15= initial envelope volume (0xF = max)
+     *
+     * SNDxFREQ:
+     *   bits 0..10 = frequency code
+     *   bit  14    = length-enable (channel auto-stops on countdown)
+     *   bit  15    = trigger (set to start the note)
+     */
+    u16 cnt  = (u16)(0xF080 | len_code);      /* full vol + 50% duty + length */
+    u16 freq = (u16)(0xC000 | freq_lo);       /* trigger + length-enable + freq */
+
+    if (channel == 1) {
+        REG_SND1SWEEP = 0x0000;   /* no sweep */
+        REG_SND1CNT   = cnt;
+        REG_SND1FREQ  = freq;
+    } else if (channel == 2) {
+        REG_SND2CNT  = cnt;
+        REG_SND2FREQ = freq;
+    }
+}
+
+void sfx_noise(u8 length_frames) {
+    u16 len_code = (length_frames >= 63) ? 0 : (u16)(64 - length_frames);
+    /* SND4CNT: same layout as SND1CNT (no duty bits, but they're ignored). */
+    REG_SND4CNT  = (u16)(0xF000 | len_code);
+    /* SND4FREQ:
+     *   bits 0..2  = ratio of frequency divider (0..7)
+     *   bit  3     = counter step width (0 = 15-bit / 1 = 7-bit "tinnier")
+     *   bits 4..7  = shift clock frequency
+     *   bit  14    = length-enable
+     *   bit  15    = trigger
+     *  0xC033 = trigger + length-enable + mid-pitch white noise. */
+    REG_SND4FREQ = 0xC033;
+}
+
+void sfx_off(void) {
+    REG_SNDSTAT = 0x0000;
+}

package/src/platforms/gba/lib/c/gba_sfx.h

@@ -0,0 +1,48 @@
+/* ── gba_sfx.h — minimal GBA sound-effects wrapper ──────────────────
+ *
+ * Thin DMG-compatible APU wrapper for the GBA's 4 PSG channels. Mirrors
+ * the NES/GB scaffold pattern (sound_init + sound_play_tone + ...) so
+ * cross-platform scaffolds feel the same.
+ *
+ * Channel layout:
+ *   1, 2 = square waves (use sfx_tone)
+ *   4    = white noise   (use sfx_noise)
+ *
+ * Channel 3 (wave RAM) is not wrapped — it needs a user-supplied wave
+ * table. Direct Sound (PCM via DMA) is also not wrapped — that needs a
+ * timer + DMA setup + a sample buffer; out of scope for an sfx helper.
+ *
+ * All functions are non-blocking — they trigger the channel and return
+ * immediately. The hardware countdowns the length and silences the
+ * channel on its own. Calling sfx_tone again before the countdown
+ * finishes re-triggers (cuts the previous note).
+ */
+
+#ifndef GBA_SFX_H
+#define GBA_SFX_H
+
+#include <tonc_types.h>
+
+/* Call once near the start of main() before any sfx_*. Powers up the
+ * APU and routes all 4 channels at full volume to both speakers. */
+void sfx_init(void);
+
+/* Play a square-wave tone.
+ *   channel: 1 or 2 (others ignored)
+ *   freq_period: GBA 11-bit frequency code (lower=higher pitch).
+ *                Hz ≈ 131072 / (2048 - freq_period).
+ *                Useful range: 700..1900. Try 1900 for "pew",
+ *                1300 for "blip", 700 for "low thump".
+ *   length_frames: 1..63, scaled to GBA's 64-step length countdown
+ *                  (~3.9ms each, so 16 frames ≈ 62ms).
+ */
+void sfx_tone(u8 channel, u16 freq_period, u8 length_frames);
+
+/* Play a noise burst on channel 4.
+ *   length_frames: 1..63 (same scaling as sfx_tone). */
+void sfx_noise(u8 length_frames);
+
+/* Power down the APU. */
+void sfx_off(void);
+
+#endif