romdev-mcp 0.1.1

package/src/platforms/gba/lib/sysbase/gba_iosupport.c

@@ -0,0 +1,138 @@
+// gba_iosupport.c — minimal libsysbase for GBA.
+//
+// newlib's stdio (printf/iprintf/puts/...) bottoms out in the reentrant
+// syscalls _write_r/_read_r/_close_r/etc. devkitPro routes those through a
+// per-fd "device operations table" (devoptab_list[]); a console library
+// (libtonc's tte_init_con / libgba's consoleInit) installs a devoptab whose
+// write_r renders text to the screen, so `iprintf("...")` Just Works.
+//
+// The full devkitPro libsysbase carries a whole VFS (dirs, stat, sockets, …).
+// A GBA homebrew only needs the stdout/stderr write path, so this is the
+// minimal, fully-from-source implementation of exactly that:
+//   - storage for devoptab_list[] (+ a default null device on every slot)
+//   - AddDevice / FindDevice / RemoveDevice / GetDeviceOpTab
+//   - the reentrant syscalls newlib calls, dispatched through devoptab_list[]
+//
+// This compiles with the bundled arm-none-eabi toolchain and links ahead of
+// the libnosys.a stubs (an object beats an archive member), so providing
+// _write_r here transparently replaces nosys's "_write always fails".
+
+#include <sys/iosupport.h>
+#include <sys/reent.h>
+#include <sys/stat.h>
+#include <errno.h>
+#include <string.h>
+#include <stdint.h>
+
+// ── Default "null" device ────────────────────────────────────────────────
+// Used for every fd until a real device is installed. Reads return EOF (0),
+// writes silently succeed (so a program that prints before consoleInit() does
+// not crash — it just goes nowhere, matching devkitPro behavior).
+static ssize_t null_write_r(struct _reent *r, void *fd, const char *p, size_t len) {
+  (void)r; (void)fd; (void)p; return (ssize_t)len;
+}
+static ssize_t null_read_r(struct _reent *r, void *fd, char *p, size_t len) {
+  (void)r; (void)fd; (void)p; (void)len; return 0;
+}
+
+static const devoptab_t dotab_null = {
+  .name = "null",
+  .write_r = null_write_r,
+  .read_r  = null_read_r,
+};
+
+// ── The device table ─────────────────────────────────────────────────────
+// STD_MAX slots (newlib max fd). Every slot defaults to the null device, so a
+// bare _write_r call before any console init is safe.
+const devoptab_t *devoptab_list[STD_MAX] = {
+  [0 ... STD_MAX - 1] = &dotab_null,
+};
+
+// ── Device registry ──────────────────────────────────────────────────────
+// exact name match against the chars before ':' in `name`.
+static int name_matches(const char *dev, const char *name, size_t namelen) {
+  if (strlen(dev) != namelen) return 0;
+  return strncmp(dev, name, namelen) == 0;
+}
+
+int FindDevice(const char *name) {
+  if (!name) return -1;
+  size_t namelen = strcspn(name, ":");
+  for (int i = 0; i < STD_MAX; i++) {
+    const devoptab_t *d = devoptab_list[i];
+    if (d && d != &dotab_null && d->name &&
+        name_matches(d->name, name, namelen)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+int AddDevice(const devoptab_t *device) {
+  if (!device) return -1;
+  for (int i = 3; i < STD_MAX; i++) {   // 0/1/2 reserved for stdin/out/err
+    if (devoptab_list[i] == &dotab_null) {
+      devoptab_list[i] = device;
+      return i;
+    }
+  }
+  return -1;
+}
+
+int RemoveDevice(const char *name) {
+  int i = FindDevice(name);
+  if (i >= 0) { devoptab_list[i] = &dotab_null; return 0; }
+  return -1;
+}
+
+const devoptab_t *GetDeviceOpTab(const char *name) {
+  int i = FindDevice(name);
+  return (i >= 0) ? devoptab_list[i] : NULL;
+}
+
+// ── newlib reentrant syscalls → devoptab dispatch ────────────────────────
+// newlib calls these with `fd` = file descriptor. We route to the device
+// installed in devoptab_list[fd]. (For real games that open files you'd carry
+// a richer fd→handle map; GBA homebrew only uses 0/1/2, which is all this
+// needs to make iprintf/printf reach the screen.)
+
+static const devoptab_t *dev_for(int fd) {
+  if (fd < 0 || fd >= STD_MAX) return &dotab_null;
+  const devoptab_t *d = devoptab_list[fd];
+  return d ? d : &dotab_null;
+}
+
+_ssize_t _write_r(struct _reent *r, int fd, const void *ptr, size_t len) {
+  const devoptab_t *d = dev_for(fd);
+  if (!d->write_r) { r->_errno = EBADF; return -1; }
+  return d->write_r(r, (void *)(intptr_t)fd, (const char *)ptr, len);
+}
+
+_ssize_t _read_r(struct _reent *r, int fd, void *ptr, size_t len) {
+  const devoptab_t *d = dev_for(fd);
+  if (!d->read_r) { r->_errno = EBADF; return -1; }
+  return d->read_r(r, (void *)(intptr_t)fd, (char *)ptr, len);
+}
+
+int _close_r(struct _reent *r, int fd) {
+  const devoptab_t *d = dev_for(fd);
+  if (d->close_r) return d->close_r(r, (void *)(intptr_t)fd);
+  return 0;
+}
+
+_off_t _lseek_r(struct _reent *r, int fd, _off_t pos, int dir) {
+  const devoptab_t *d = dev_for(fd);
+  if (d->seek_r) return d->seek_r(r, (void *)(intptr_t)fd, pos, dir);
+  (void)pos; (void)dir; return 0;
+}
+
+int _fstat_r(struct _reent *r, int fd, struct stat *st) {
+  // Report a character device so newlib treats stdout as unbuffered-ish.
+  (void)fd;
+  if (st) { memset(st, 0, sizeof(*st)); st->st_mode = S_IFCHR; }
+  (void)r; return 0;
+}
+
+int _isatty_r(struct _reent *r, int fd) {
+  (void)r; return (fd >= 0 && fd <= 2) ? 1 : 0;
+}

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -0,0 +1,165 @@
+# Game Boy Color — mental model
+
+The Game Boy Color is the DMG (original Game Boy) with **color
+extensions** layered on. Most of the hardware (CPU, instruction set,
+VRAM layout, OAM, sound) is identical to DMG. Color adds:
+
+## Five silent-failure footguns to know before you start (R26 + R27)
+
+These are GB-tree problems that bite identically on GBC because the
+runtime is the same SDCC sm83 port + same DMA hardware + same
+cartridge-header format. All five have shipped fixes in the bundled
+runtime + tools, but a custom build that bypasses them hits exactly
+the same wall.
+
+1. **Cartridge header must be FULLY patched, not just logo + checksums.**
+   `buildSource` / `runSource` do this for you at build time: every byte
+   at $0134..$014C is filled, and on `platform:"gbc"` the CGB flag at
+   $0143 is set to $80 (CGB-aware + DMG-compatible). You do **not** run
+   `patchGbHeader` on a freshly built ROM. Reach for `patchGbHeader` only
+   to fix up an existing / externally built ROM whose header was never
+   set, or to override a field — e.g. starting from a `.gb` ROM and
+   wanting CGB color, pass `cgb: true` explicitly.
+
+2. **OAM shadow buffer must be page-aligned.** `shadow_oam` is pinned
+   at $C100 in the bundled runtime via `__at (0xC100)`. If you roll
+   your own buffer, pick an address with `0x00` in the low byte. OAM
+   DMA reads only the high byte and copies 160 bytes from `$XX00`.
+
+3. **Raw VRAM stores can be optimized away.** Use `memcpy_vram(dst,
+   src, n)` from `gb_runtime.h` (volatile-safe by construction) or
+   cast through `volatile uint8_t *`. See `lib/c/SDCC_GOTCHAS.md`
+   § "Writes to VRAM".
+
+4. **OAM DMA must run from HRAM.** During the ~160 µs OAM DMA window
+   the CPU can ONLY fetch from HRAM ($FF80-$FFFE). The bundled
+   `oam_dma_copy()` installs a 9-byte stub at $FF80 and CALLs it; the
+   stub spins from HRAM where DMA can't conflict. Pre-r55 the spin
+   ran from ROM and fetched $FF for every instruction → `rst $38` →
+   stack corruption → intermittent LCDC = $FF, BG VRAM wiped, sprites
+   jump. `lcd_init_default()` auto-installs the stub; if you bypass
+   that helper, call `oam_dma_init_hram()` yourself before any DMA.
+
+5. **`gb_crt0.s` zeros BSS correctly.** Pre-r55's gsinit zeroed
+   `_INITIALIZED` (wrong section — gets overwritten by the copy loop)
+   instead of `_DATA` (actual BSS). Result: uninitialized statics
+   booted with WRAM garbage. The fixed crt0 zeros `_DATA` from
+   `s__DATA` for `l__DATA` bytes; bring-your-own crt0 should do the
+   same.
+
+- **Two VRAM banks** (switched via VBK at $FF4F) — bank 0 holds tile
+  pattern data, bank 1 holds per-tile BG attributes (palette index,
+  H/V flip, priority, tile bank).
+- **8 BG palettes × 4 colors** (indexed via BCPS/BCPD at $FF68/$FF69).
+- **8 sprite palettes × 4 colors** (indexed via OCPS/OCPD at
+  $FF6A/$FF6B).
+- **Each color is 15-bit BGR** (5+5+5), stored as two little-endian
+  bytes per entry.
+- **Double-speed mode** via KEY1 ($FF4D) — Z80 runs at ~8 MHz instead
+  of ~4 MHz. Most homebrew ignores this; lots of cycle-counted code
+  breaks under it.
+- **HDMA** ($FF51-$FF55) for fast block transfers during HBlank —
+  used for live tile streaming.
+
+## CGB vs DMG mode
+
+The CGB boot ROM checks header byte **`$0143`**:
+- `$00` → DMG mode (4 grays only, no color)
+- `$80` → CGB-enhanced mode (color works, DMG-compat fallback)
+- `$C0` → CGB-only mode (refuses to boot on a DMG)
+
+**Every bundled GBC scaffold is built with `$0143 = $80`** — `buildSource`
+/ `runSource` set this automatically at build time when `platform:"gbc"`,
+so a freshly built `.gbc` boots in color with no extra step. (Build it as
+`platform:"gb"` instead and the flag stays `$00` → DMG green-shade mode,
+and OCPS/BCPS writes do nothing.)
+
+## Palette setup
+
+```c
+/* Sprite palette 0, color 1 = red */
+OCPS = 0x80 | 0x01;        /* auto-increment + index = palette 0, color 1 */
+OCPD = (uint8_t)(0x001F & 0xFF);
+OCPD = (uint8_t)((0x001F >> 8) & 0xFF);
+/* Subsequent writes to OCPD advance the index. */
+
+/* Same shape for BG palette via BCPS/BCPD. */
+```
+
+15-bit BGR encoding:
+```
+bit 14..10  blue   (0..31)
+bit  9..5   green  (0..31)
+bit  4..0   red    (0..31)
+```
+
+White = `0x7FFF`. Black = `0x0000`. Bright red = `0x001F`.
+
+## Tile attributes (BG bank 1)
+
+To use the BG palettes you must:
+
+1. Switch VRAM bank: `VBK = 1`.
+2. Write attribute bytes to the same offsets as the tile-map ($9800+).
+3. Switch back: `VBK = 0`.
+
+Attribute byte layout:
+```
+bit 0..2  palette index (0..7)
+bit 3     tile bank (0 or 1)
+bit 4     unused
+bit 5     H-flip
+bit 6     V-flip
+bit 7     BG-over-OBJ priority
+```
+
+## Audio
+
+Identical to DMG — same 4-channel APU. `sound_init` / `sound_play_tone`
+/ `sound_play_noise` / `sound_off` from `gb_runtime.h` work unchanged
+on GBC. See the GB MENTAL_MODEL.md for the channel layout.
+
+## Frame heartbeat
+
+Same as DMG:
+
+```c
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+void main(void) {
+    sound_init();
+    /* setup palettes via BCPS/BCPD + OCPS/OCPD */
+    /* enable LCD */
+    while (1) {
+        wait_vblank();
+        /* update OAM, palettes, scroll */
+    }
+}
+```
+
+## Scaffolds
+
+All GB scaffolds (`shmup`, `platformer`, `puzzle`, `sports`, `racing`,
+`hello_sprite`, `tile_engine`) compile identically as GBC ROMs — the
+bundled GB runtime is already CGB-aware (writes OCPD/OCPS for color).
+The genre scaffolds inherit from GB via `TEMPLATES.gbc = TEMPLATES.gb`;
+the only differences at build time are:
+
+- ROM extension: `.gbc` (vs `.gb`)
+- the build sets `$0143 = $80` to flip CGB mode on (automatic when you
+  build with `platform:"gbc"` — no manual `patchGbHeader` step)
+- gambatte core accepts both DMG + CGB-mode ROMs
+
+For new GBC code that wants to be CGB-only (no DMG fallback) set the
+CGB byte to `$C0` instead of `$80` — `patchGbHeader({path, cgb:true})`
+on the built ROM can override it.
+
+## Horizontal scrolling (for side-scrollers)
+
+Identical to DMG: write `SCX` ($FF43) each frame for hardware scroll through
+the wrapping 32×32 BG map, and stream the next BG-map column (its tile IDs +,
+on CGB, its BG attribute byte in VRAM bank 1) each time the camera crosses an
+8-px boundary. Use the Window (LCDC bit 5) for a fixed HUD. CGB adds nothing
+that changes the scroll mechanism — just remember the per-tile attribute in
+bank 1 when you stream columns. See the GB MENTAL_MODEL for the full pattern.

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -0,0 +1,142 @@
+# Game Boy Color — troubleshooting
+
+Read MENTAL_MODEL.md first (`getPlatformDoc({platform:"gbc",
+name:"mental_model"})`). Most DMG-era troubleshooting from GB applies
+unchanged — including the **two SDCC sm83 codegen footguns below**, which are
+the #1 cause of a clean-building GBC C game that boots but never renders.
+
+## ⚠ "Sprites/tiles never show AND the CPU crashed (PC near $002B)" — the #1 SDCC footgun
+
+SDCC's sm83 backend **miscompiles a byte-copy loop through an `__xdata`
+pointer** — the "copy tiles into VRAM" pattern:
+```c
+uint8_t *dst = (uint8_t *)0x8000;
+for (uint8_t i = 0; i < 16; i++) dst[i] = src[i];   // ☠ writes to the return
+                                                    //   address → CPU crash
+```
+The build succeeds and the ROM boots, so it looks like a logic bug, but it's
+codegen — `PC` ends up stuck near `$002B`, sprites/tiles never appear, OAM
+stays zero. **Fix:** use the bundled `memcpy_vram(dst, src, n)` (in every
+project's `gb_runtime.c`) for ALL copies into VRAM/`__xdata`, never a raw
+for-loop. `buildSource` with `lint:"strict"` also flags the raw pattern.
+
+## ⚠ "Loop never ends / dead code after a loop" — uint8 loop-bound trap
+
+```c
+uint8_t i; for (i = 0; i < 32 * 32; i++) { ... }   // ☠ 255 < 1024 always true
+```
+A `uint8_t` can't reach a bound >255 → infinite loop, all later code dead. SDCC
+gives no warning. Use `uint16_t` for any bound that can exceed 255. (Linter
+flags it.) See [[sdcc-uint8-loop-bound-trap]].
+
+## ⚠ "Flat-color screen, no sprites, OAM reads all zero on the first frame(s)"
+
+Your sprites are staged in `shadow_oam` but never reached hardware OAM before
+the LCD turned on — so the first visible frame shows power-on garbage / nothing.
+Common when you enable the LCD, *then* enter a `wait_vblank()` loop that flushes
+OAM only after the wait (so frame 1 renders un-flushed), and especially when you
+use the `enable_vblank_irq()` HALT path (the first `wait_vblank()` sleeps the CPU
+before you'd flush).
+
+**Fix — DMA the first OAM frame BEFORE enabling the LCD:**
+```c
+oam_clear();
+oam_set(0, y, x, tile, attr);   /* stage your initial sprites */
+oam_dma_flush();                /* push to hardware while LCD is still off */
+LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;   /* THEN turn on */
+/* now the loop: wait_vblank(); oam_dma_flush(); ... */
+```
+Also make sure `oam_dma_init_hram()` ran (lcd_init_default does it) so the DMA
+routine executes from HRAM. The bundled `hello_sprite` template shows this exact
+order. Diagnose with `inspectSprites` / `getRenderingContext` if a screenshot is
+just flat color.
+
+## "ROM boots into green-shade DMG mode, not color"
+
+Header byte `$0143` isn't `$80`. The CGB boot ROM checks this byte
+and falls back to DMG mode when it's `$00`.
+
+When you build with `platform:"gbc"`, `buildSource` / `runSource`
+**auto-fix the header** — Nintendo logo, header + global checksums,
+and `$0143 = $80` (CGB-enhanced) — so a freshly built `.gbc` already
+boots in color. You do **not** call `patchGbHeader` for that.
+
+```js
+runSource({ platform: "gbc", language: "c", ... });  /* header auto-fixed */
+```
+
+If you instead see green-shade DMG mode, the ROM was almost certainly
+built with `platform:"gb"` (so the CGB flag stayed `$00`). Rebuild with
+`platform:"gbc"`. Reach for `patchGbHeader` only to fix up an existing /
+externally built `.gbc` whose header was never set, or to override a
+header field (e.g. force `cgb:false`).
+
+## "OCPS / OCPD writes don't change colors"
+
+You're in DMG mode (see above) — those registers don't exist on DMG.
+Rebuild with `platform:"gbc"` so the CGB flag is set. Once in CGB mode,
+`OCPS` is the sprite palette index (with auto-increment in bit 7),
+`OCPD` is the data write.
+
+To write sprite palette 0, color 1 = bright red:
+
+```c
+OCPS = 0x80 | (0 * 8) | (1 * 2);  /* auto-inc + palette 0 + color 1 */
+OCPD = 0x1F;                       /* low byte: red 31, green 0 */
+OCPD = 0x00;                       /* high byte: blue 0 */
+```
+
+The `* 8` and `* 2` reflect the BCPS/OCPS layout — 8 palettes × 4
+colors × 2 bytes per color = 64 byte index space.
+
+## "BG colors stuck on default — only sprites change"
+
+BG palettes live at BCPS/BCPD ($FF68/$FF69), not OCPS/OCPD. And you
+must also write per-tile attribute bytes to VRAM bank 1 selecting
+which BG palette (0-7) each tile uses:
+
+```c
+VBK = 1;
+*(uint8_t*)0x9800 = 0x01;  /* tile at top-left uses BG palette 1 */
+VBK = 0;
+```
+
+Without the attribute writes, every BG tile defaults to palette 0.
+
+## "Game ran on Game Boy emulator but not on Game Boy Color emulator"
+
+`loadMedia({platform:"gbc", path})` expects gambatte in CGB mode. If
+your ROM was built with `platform:"gb"` (no patchGbHeader) the file
+extension is `.gb` and the header CGB byte is $00, so gambatte starts
+in DMG mode. To switch a DMG ROM to CGB:
+
+1. Rename / re-extension to `.gbc`
+2. Run `patchGbHeader({path:"out.gbc"})` — also fixes the global
+   checksum that the boot ROM checks
+
+## "Sound is the same as DMG"
+
+That's correct — CGB has the **identical** 4-channel APU as DMG. The
+`sound_*` API from gb_runtime works unchanged. CGB does NOT add new
+sound channels or extra waveforms.
+
+## "ROM size > 32 KB needed"
+
+The bundled GBC scaffolds all fit in 32 KB (single bank, no MBC).
+For larger projects use an MBC (memory bank controller). MBC1 / MBC3
+work in gambatte; set the `$0147` cartridge type byte accordingly.
+patchGbHeader doesn't set this — you write it from your asm/C.
+
+## "Frame heartbeat feels janky / slow"
+
+Default GBC speed is the same as DMG (~4 MHz Z80). Double-speed mode
+via KEY1 ($FF4D) doubles CPU but halves audio sample rate + breaks
+cycle-counted code. Most homebrew leaves it off; if you need the
+extra clocks, change the GB scaffold pattern to:
+
+```c
+KEY1 = 1;            /* request speed switch */
+__asm__("stop");     /* arm the switch (compiler-specific syntax) */
+```
+
+Not bundled in any scaffold — use only if you've measured a need.

package/src/platforms/gbc/UPSTREAM_SOURCES.md

@@ -0,0 +1,60 @@
+# Game Boy Color — source you can read
+
+GBC shares its toolchain (SDCC sm83) + emulator (gambatte) + most
+of the runtime (`gb_runtime.c`, `gb_crt0.s`, `patch-header.js`,
+hUGEDriver) with DMG. The CGB tree (`src/platforms/gbc/`) holds
+the color-aware scaffolds; everything below is in lockstep with
+the GB tree.
+
+CGB-specific:
+- `patchGbHeader({cgb: true})` sets $0143 = $80 → gambatte boots
+  in CGB mode with color palette RAM active
+- VRAM bank 1 (selected via VBK = $FF4F) holds per-tile attribute
+  bytes (palette index, H/V flip, BG-OAM priority)
+- BCPS/BCPD ($FF68/$FF69) — 8 BG palettes × 4 colors × BGR555
+- OCPS/OCPD ($FF6A/$FF6B) — same shape, sprite palettes
+- DMG-only BGP/OBP* registers are ignored in CGB mode
+
+Reference: Pan Docs § "CGB Registers" + § "CGB Mode".
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/gbc/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/gb/lib/c/gb_runtime.c`,
+   `gb_crt0.s`, `patch-header.js`, `hUGEDriver.c` (full source).
+3. **SDCC sm83 port** — we ship the WASM compiler but NOT the SDCC
+   source tree. For SDCC bugs, see upstream below.
+4. **Upstream GitHub**:
+
+   | What | Upstream |
+   |---|---|
+   | SDCC | http://sdcc.sourceforge.net/ + https://sourceforge.net/projects/sdcc/ |
+   | hUGEDriver | https://github.com/SuperDisk/hUGEDriver |
+   | RGBDS (asm path) | https://github.com/gbdev/rgbds |
+   | gambatte libretro core | https://github.com/libretro/gambatte-libretro |
+   | gambatte proper | https://github.com/sinamas/gambatte |
+
+## GB hardware docs
+
+- **Pan Docs** (canonical, everything): https://gbdev.io/pandocs/
+- **GBDev community resources**: https://gbdev.io/
+- **opcode reference**: https://gbdev.io/gb-opcodes/optables/
+- **SDCC sm83 specifics**: see `src/platforms/gb/lib/c/SDCC_GOTCHAS.md`
+
+## hUGEDriver music format
+
+See `src/platforms/gb/lib/c/hUGEDriver.c` header comment + the
+upstream README. Songs are exported from hUGETracker
+(https://github.com/SuperDisk/hUGETracker) as `.c` files —
+`song_data.c` in our bundle is one such export.
+
+## When to use what
+
+- "OAM DMA wedges sprites" → see `MENTAL_MODEL.md` § R26 footguns +
+  `gb_runtime.c` `oam_dma_copy` implementation
+- "BGP write does nothing" → check $0143 (CGB flag) via
+  `patchGbHeader` + Pan Docs § "The Cartridge Header"
+- "How does hUGEDriver process a song row?" → `hUGEDriver.c`
+  `hUGE_dosound` body — fully readable
+- "Why is gambatte refusing my ROM?" → check the header, then
+  libretro-gambatte source for the load path

package/src/platforms/gbc/lib/c/LICENSE-HUGEDRIVER

@@ -0,0 +1,25 @@
+hUGEDriver and hUGETracker
+==========================
+
+Repository: https://github.com/SuperDisk/hUGEDriver
+Upstream README (`Quick start (GBDK)` + `License` sections) bundled as
+`hUGEDriver.upstream.asm` (the canonical RGBDS implementation, ~1900 lines).
+
+From the upstream README:
+
+> ## License
+>
+> hUGETracker and hUGEDriver are dedicated to the public domain.
+
+That is, hUGEDriver carries no encumbrance — distributed under CC0 / public
+domain dedication. We therefore include both:
+
+  - hUGEDriver.upstream.asm     The full RGBDS source-of-truth (CC0).
+  - hUGEDriver.{c,h}            A compact SDCC-native rewrite providing the
+                                hUGE_init / hUGE_dosound / hUGE_mute_channel
+                                surface against a simplified song format,
+                                authored from scratch for romdev.
+
+The compact rewrite is independently CC0-dedicated for the same reason —
+no upstream code is copied; it implements a documented public-domain
+interface against the public GB APU register set.

package/src/platforms/gbc/lib/c/README.md

@@ -0,0 +1,120 @@
+# GB / GBC C runtime + headers
+
+These are the source files that back the GB/GBC C templates. They're
+**not** auto-injected at build time — `createProject({platform:"gb"|"gbc",
+template:"..."})` copies them into your project directory so the
+project is self-describing. Build calls then point at your project's
+copy of these files via `sourcesPaths` / `includePaths` / `crt0Path`.
+
+| File           | Copied as | What's in it |
+|---|---|---|
+| `gb_hardware.h` | header `gb_hardware.h` in include path | Symbolic names for every GB / GBC I/O register (`LCDC`, `BGP`, `JOYP`, `BCPS`, etc.) plus LCDC bit masks. Uses SDCC's `__sfr __at 0xFFNN` form (full 16-bit address, not port number). |
+| `gb_runtime.h` | header `gb_runtime.h` in include path | Declarations for the helper functions below. |
+| `gb_runtime.c` | extra translation unit, linked automatically | `wait_vblank()`, `joypad_read()`, `oam_dma_copy()`, `memcpy_vram()`, `lcd_init_default()`, plus the OAM helpers `oam_clear()`, `oam_set(slot,y,x,tile,attr)`, `oam_dma_flush()` driving the 160-byte `shadow_oam[]` global. |
+| `gb_crt0.s` | replaces stock SDCC sm83 crt0 (assembled internally) | Lays out a real cartridge: reset/IRQ vectors at $0000-$0060, entry stub at $0100, reserves $0104-$014F as the header window, puts `init:` in `_CODE` at $0150. |
+| `unroll.h` | header `unroll.h` in include path | `UNROLL_2..UNROLL_64` macros for manual loop unrolling. Originally a workaround for the now-fixed sm83 register-allocator crash family; left in for code that still uses it. You don't need it for new code. |
+
+Just `#include "gb_hardware.h"` and (optionally) `#include "gb_runtime.h"` —
+both work in any GB/GBC C build the agent submits. Caller-supplied files
+of the same name win on collision, so you can override.
+
+**Cart header is auto-fixed at build time.** `buildSource` / `runSource`
+run rgbfix on the linked GB/GBC ROM — valid Nintendo logo at $0104,
+header checksum at $014D, global checksum at $014E, cartridge-type /
+RAM-size bytes, and the CGB flag at $0143 ($80/$C0 for `.gbc`, $00 for
+`.gb`). A freshly built ROM boots on hardware and strict cores with **no
+extra step** — you do not call `patchGbHeader` after a normal build.
+
+Reach for header tooling only when working with a ROM the build pipeline
+didn't produce, or to override a field:
+
+- `patchGbHeader({path: "out.gb"})` — MCP tool (loadCategory:"project").
+  Fixes up / overrides the header of an existing ROM on disk (title, cart
+  type, ROM/RAM size, CGB flag, etc.).
+- `node patch-header.js out.gb` — standalone Node script, copied into
+  every GB project by `createProject`. Same logic, no MCP needed.
+- `rgbfix -v -p 0 out.gb` — what the build pipeline runs under the hood;
+  RGBDS asm projects can invoke it directly.
+
+## Companion docs
+
+- **[`../../TROUBLESHOOTING.md`](../../TROUBLESHOOTING.md)** — symptom →
+  fix table. Start here when your ROM compiles but doesn't render right
+  ("screen blank", "sprite invisible", "wrong colors", "freezes").
+- **[`../../MENTAL_MODEL.md`](../../MENTAL_MODEL.md)** — one-page
+  architecture overview: VRAM banks, palettes (DMG vs CGB), sprite
+  hardware, OAM DMA timing, joypad layout. Read this before your first
+  GB/GBC project.
+
+## Project templates
+
+Bootstrap a working game-loop skeleton with `createProject`:
+
+```js
+createProject({
+  platform: "gbc",
+  template: "tile_engine",   // or "hello_sprite", or "default"
+  name:     "mygame",
+  path:     "/abs/path",
+})
+```
+
+Templates ship in `examples/{gb,gbc}/templates/`:
+
+| Template | What you get |
+|---|---|
+| `default` | Minimal palette-cycle hello-world. Use when you're not sure what to build yet. |
+| `hello_sprite` | LCD init + 16-byte tile upload + 4-color OBJ palette + sprite slot 0 + d-pad movement. ~80 lines, tested end-to-end. |
+| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the Adventure / Zelda-1 / Sokoban shape. |
+
+## SDCC 4.4.0 quirks
+
+**Read first: [`SDCC_GOTCHAS.md`](./SDCC_GOTCHAS.md).** Short doc —
+mostly covers C89 syntax requirements. The big "register allocator
+crash family" that motivated this whole document originally was
+diagnosed as an emscripten stack overflow on 2026-05-25; fixed at the
+build level. Patterns that used to require `unroll.h` workarounds
+compile cleanly now.
+
+`buildSource` runs a **pre-flight linter** that catches C89 violations
+(mid-block declarations, C99 inline for-loop counters) before SDCC's
+own misleading error messages. Hits come back as warnings in the
+`issues[]` array tagged `stage: "lint"`.
+
+Pass `lint: "strict"` to fail the build on any lint hit. Default is
+advisory.
+
+## Splitting into multiple `.c` files (optional)
+
+Not required for correctness anymore, but still useful for iteration
+speed: smaller TUs rebuild faster. Use `sourcesPaths` (or `sources` for
+inline text) when it helps:
+
+```js
+buildSource({
+  platform: "gbc",
+  language: "c",
+  sourcesPaths: {
+    "main.c":    "./src/main.c",      // game state, vblank loop
+    "render.c":  "./src/render.c",    // VRAM writes, sprite list
+    "objects.c": "./src/objects.c",   // game-object logic
+    "data.c":    "./src/data.c",      // const tables
+  },
+  outputPath: "./mygame.gbc",
+})
+```
+
+Each `.c` becomes its own SDCC translation unit. The linker glues
+them together; `extern` globals tie shared state across files.
+
+When a multi-TU build fails, the response includes `failedTU` (the
+file that died) and `compiledOK` (the TUs that compiled cleanly
+before the failure). That tells you exactly which file to bisect
+without grepping the log.
+
+## Stock GBDK alternative
+
+The bundled runtime is intentionally minimal (~10 helpers). If you
+need the full GBDK-2020 surface (sprites, tile sets, font, sound driver),
+write asm-level RGBDS code via `language: "asm"` or pull the runtime
+code you need into your project's `sources`.