romdevtools 0.13.0

package/src/platforms/gb/song.js

@@ -0,0 +1,140 @@
+// GB/GBC song compiler — a note/duration song → the hUGEDriver `huge_song_t`
+// C data the bundled driver (lib/c/hUGEDriver.c) plays.
+//
+// NOT a port of hUGETracker's converter (its .uge path is entangled with GB
+// Studio); this targets OUR bundled hUGEDriver + its compact source format
+// (lib/c/song_data.c). The driver reads, per channel, an array of 16-row
+// patterns; each row is huge_row_t = { note, flags }:
+//   note  = 0..71 (C3..B8), an index into hUGEDriver's hUGE_note_table.
+//           C3=0, C4=12, A4=21, C5=24 … (octave*12 + semitone, base C3).
+//   flags = 0 (re-trigger) | 0x80 (sustain — leave the APU alone)
+//           note 0xFF = rest (silence the channel).
+// A song = ticks_per_row + up to 4 channels, each { orders[], order_cnt, 1 }.
+//
+// Input mirrors the other romdev song compilers but is multi-channel:
+//   { ticksPerRow?, channels: [ { rows: [ "C4"|{note}|"-"(sustain)|"."(rest) ] }, ... ] }
+// Rows are flattened into 16-row patterns automatically; channels may differ in
+// length (each loops independently, like the driver).
+
+/** Semitone within an octave, C=0. */
+const NOTE_BASE = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+
+export const HUGE_ROWS_PER_PATTERN = 16;
+const REST = 0xff;
+
+/**
+ * Note name → hUGE note index (C3 = 0, so index = (octave-3)*12 + semitone).
+ * Range is 0..71 (C3..B8). Throws if out of range.
+ * @param {string} name  e.g. "C4", "A#3", "Gb5"
+ * @returns {number} 0..71
+ */
+export function noteToHugeIndex(name) {
+  const m = /^([A-Ga-g])([#b-]?)(-?\d+)$/.exec(String(name).trim());
+  if (!m) throw new Error(`GB song: bad note name "${name}" (expected like "C4", "A#3").`);
+  let semi = NOTE_BASE[m[1].toUpperCase()];
+  if (m[2] === '#') semi += 1;
+  else if (m[2] === 'b') semi -= 1;
+  const octave = parseInt(m[3], 10);
+  const idx = (octave - 3) * 12 + semi;
+  if (idx < 0 || idx > 71) throw new Error(`GB song: note "${name}" (index ${idx}) out of hUGE range C3..B8 (0..71).`);
+  return idx;
+}
+
+/**
+ * Resolve one row token to { note, flags }.
+ *   "C4" / {note:"C4"} → trigger that note
+ *   "-" / "_" / {sustain:true} → sustain (0x80)
+ *   "." / "rest" / null / {rest:true} → rest (note 0xFF)
+ * @param {string|object|null} tok
+ * @returns {{note:number, flags:number}}
+ */
+function resolveRow(tok) {
+  if (tok == null) return { note: REST, flags: 0 };
+  if (typeof tok === 'object') {
+    if (tok.rest) return { note: REST, flags: 0 };
+    if (tok.sustain) return { note: 0, flags: 0x80 };
+    if (tok.note != null) return { note: typeof tok.note === 'number' ? tok.note : noteToHugeIndex(tok.note), flags: 0 };
+    return { note: REST, flags: 0 };
+  }
+  const s = String(tok).trim();
+  if (s === '-' || s === '_' || s === '~') return { note: 0, flags: 0x80 };       // sustain
+  if (s === '.' || s === '' || s.toLowerCase() === 'rest') return { note: REST, flags: 0 }; // rest
+  return { note: noteToHugeIndex(s), flags: 0 };
+}
+
+const hex2 = (n) => '0x' + (n & 0xff).toString(16).padStart(2, '0').toUpperCase();
+
+/**
+ * Compile a multi-channel song to hUGEDriver C source + raw bytes.
+ *
+ * @param {object} song
+ * @param {number} [song.ticksPerRow=8]  hUGE_dosound calls per row.
+ * @param {Array<{rows: Array}>} song.channels  1..4 channels (CH1 sq, CH2 sq,
+ *   CH3 wave, CH4 noise). Each `rows` is the note token list; it's padded to a
+ *   multiple of 16 (with sustains) and split into 16-row patterns.
+ * @param {string} [song.name="song"]  C identifier base (emits `<name>` huge_song_t).
+ * @returns {{ bytes: Uint8Array, cSource: string, rows: number, channels: number }}
+ *   bytes = patterns concatenated per channel, 2 bytes/row [note, flags];
+ *   cSource = the full song_data.c-style C block (drop-in for song_data.c).
+ */
+export function compileSong(song) {
+  if (!song || !Array.isArray(song.channels) || song.channels.length === 0) {
+    throw new Error('GB song: expected { channels: [ { rows:[...] }, ... ] } (1..4 channels).');
+  }
+  if (song.channels.length > 4) throw new Error('GB song: at most 4 channels (CH1..CH4).');
+  const ticksPerRow = song.ticksPerRow ?? 8;
+  const name = song.name ?? 'song';
+  const chPrefixes = ['ch1', 'ch2', 'ch3', 'ch4'];
+
+  const allBytes = [];
+  const cParts = [
+    '/* generated by romdev encodeAudio({target:"gb"}) — hUGEDriver song data */',
+    '#include "hUGEDriver.h"',
+    '',
+  ];
+  /** per-channel descriptor lines for the huge_song_t */
+  const chanDescriptors = ['{ 0, 0, 0 }', '{ 0, 0, 0 }', '{ 0, 0, 0 }', '{ 0, 0, 0 }'];
+  let totalRows = 0;
+
+  song.channels.forEach((ch, ci) => {
+    const pfx = chPrefixes[ci];
+    const rows = (ch.rows || []).map(resolveRow);
+    if (rows.length === 0) return;
+    // Pad to a whole number of 16-row patterns (pad with sustains so the tail holds).
+    while (rows.length % HUGE_ROWS_PER_PATTERN !== 0) rows.push({ note: 0, flags: 0x80 });
+    const nPat = rows.length / HUGE_ROWS_PER_PATTERN;
+    totalRows = Math.max(totalRows, rows.length);
+
+    const patNames = [];
+    for (let p = 0; p < nPat; p++) {
+      const patName = `${pfx}_p${p}`;
+      patNames.push(patName);
+      const slice = rows.slice(p * HUGE_ROWS_PER_PATTERN, (p + 1) * HUGE_ROWS_PER_PATTERN);
+      const lines = slice.map((r) => `  { ${hex2(r.note)}, ${hex2(r.flags)} }`);
+      cParts.push(`static const huge_row_t ${patName}[HUGE_ROWS_PER_PATTERN] = {\n${lines.join(',\n')}\n};`);
+      for (const r of slice) allBytes.push(r.note & 0xff, r.flags & 0xff);
+    }
+    cParts.push(`static const huge_row_t * const ${pfx}_orders[] = { ${patNames.join(', ')} };`, '');
+    chanDescriptors[ci] = `{ ${pfx}_orders, ${nPat}, 1 }`;
+  });
+
+  cParts.push(
+    `const huge_song_t ${name} = {`,
+    `  /* ticks_per_row */ ${ticksPerRow},`,
+    `  /* ch1 */ ${chanDescriptors[0]},`,
+    `  /* ch2 */ ${chanDescriptors[1]},`,
+    `  /* ch3 */ ${chanDescriptors[2]},`,
+    `  /* ch4 */ ${chanDescriptors[3]},`,
+    `};`,
+    ''
+  );
+
+  return {
+    bytes: new Uint8Array(allBytes),
+    cSource: cParts.join('\n'),
+    rows: totalRows,
+    channels: song.channels.length,
+  };
+}
+
+export default compileSong;

package/src/platforms/gba/MENTAL_MODEL.md

@@ -0,0 +1,216 @@
+# 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 `build({output:'rom'})` /
+`build({output:'run'})` 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.
+
+### Driving input over MCP
+
+mGBA maps `input({op:'set'})` button names **straight through** — verified live, no
+inversion: `{a}`→A, `{b}`→B, `{l}`→L, `{r}`→R, `{start}`/`{select}`, plus the
+d-pad. So `input({op:'set', a: true})` presses GBA A as expected — unlike the
+genesis_plus_gx platforms (Genesis/SMS/GG), there's no surprise here.
+
+## 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).
+
+**Debugging sound:** `audioDebug({op:'inspect', chip:"gba"})` decodes the live APU —
+per-channel freq→note/duty/volume for the 4 tone channels plus the 2 Direct
+Sound FIFO states. Pair with `sprites({op:'inspect'})`/`palette({source:'live'})`/
+`background({view:'renderState'})`/`cpu({op:'read'})` (ARM7) and `breakpoint({on:'write'})` for the rest of the
+live-debug loop.
+
+**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 `build({output:'rom', 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 `platform({op:'doc', platform:"gba", name:"mental_model"})`).
+
+## ⚠️ ROM compiles + loads but the screen never updates (frozen on frame 1)
+
+**Single most common GBA gotcha.** Symptom: `build({output:'run'})` 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 `build({output:'rom'})` 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 `scaffold({op:'project'})`). 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 — `state({op:'save'})` / `state({op:'load'})` 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).