romdev-mcp 0.1.1

package/src/platforms/common/screenshot-sprite.js

@@ -0,0 +1,153 @@
+// extractSpriteFromScreenshot — crop a region of a PNG and isolate a sprite
+// from its background by flood-filling the background away. The LOSSY
+// fallback for when meta-sprite capture isn't possible (no clean SAT
+// composition, or the source is just a screenshot). Pure pixel work.
+//
+// Algorithm:
+//   1. Crop to {x,y,w,h}.
+//   2. Background detection:
+//      - "edge-flood" (default): flood-fill inward from every border pixel,
+//        marking pixels whose color is within `tolerance` of the border
+//        color they're reached from as background. This removes a connected
+//        background that touches the crop edges (the common case: sprite
+//        floating in a field of sky/floor color).
+//      - "color": treat all pixels within `tolerance` of an explicit
+//        `bgColor` as background, anywhere in the crop.
+//   3. If a `seed` is given, keep ONLY the connected non-background
+//      component containing the seed (drops other objects/platform bits).
+//   4. Emit a transparent PNG (background → alpha 0) + a debug PNG showing
+//      kept (original) vs rejected (magenta) pixels.
+
+import { PNG } from "pngjs";
+
+function colorDist(a, ai, b, bi) {
+  const dr = a[ai] - b[bi], dg = a[ai + 1] - b[bi + 1], db = a[ai + 2] - b[bi + 2];
+  return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+
+/**
+ * @param {object} args
+ * @param {Buffer|Uint8Array} args.pngBytes source PNG
+ * @param {{x,y,w,h}} args.crop
+ * @param {{x,y}} [args.seed] keep only the component containing this point
+ *   (in CROP-relative coords)
+ * @param {"edge-flood"|"color"} [args.backgroundMode="edge-flood"]
+ * @param {[number,number,number]} [args.bgColor] for "color" mode
+ * @param {number} [args.tolerance=24] color match tolerance (0-441)
+ * @param {number} [args.previewScale=1]
+ * @returns {{ png:Buffer, debugPng:Buffer, width:number, height:number,
+ *   keptPixels:number, totalPixels:number }}
+ */
+export function extractSpriteFromScreenshot(args) {
+  const src = PNG.sync.read(Buffer.from(args.pngBytes));
+  const { x, y, w, h } = args.crop;
+  if (x < 0 || y < 0 || x + w > src.width || y + h > src.height) {
+    throw new Error(`crop (${x},${y} ${w}×${h}) is outside the ${src.width}×${src.height} image.`);
+  }
+  const tol = args.tolerance ?? 24;
+  const mode = args.backgroundMode ?? "edge-flood";
+  const scale = Math.max(1, args.previewScale ?? 1);
+
+  // Crop into a w×h RGBA buffer.
+  const crop = new Uint8Array(w * h * 4);
+  for (let row = 0; row < h; row++) {
+    for (let col = 0; col < w; col++) {
+      const s = ((y + row) * src.width + (x + col)) * 4;
+      const d = (row * w + col) * 4;
+      crop[d] = src.data[s]; crop[d + 1] = src.data[s + 1]; crop[d + 2] = src.data[s + 2]; crop[d + 3] = src.data[s + 3];
+    }
+  }
+
+  // bg[i] = true if pixel i is background.
+  const bg = new Uint8Array(w * h);
+
+  if (mode === "color") {
+    const c = args.bgColor ?? [crop[0], crop[1], crop[2]];
+    const ref = [c[0], c[1], c[2]];
+    for (let i = 0; i < w * h; i++) if (colorDist(crop, i * 4, ref, 0) <= tol) bg[i] = 1;
+  } else {
+    // edge-flood: BFS from all border pixels; a pixel is background if it's
+    // reachable from the edge through pixels all within tol of the seed
+    // border color. We use each border pixel's own color as the local ref so
+    // gradients along the border still flood.
+    const q = [];
+    const push = (cx, cy, ref) => {
+      const i = cy * w + cx;
+      if (bg[i]) return;
+      if (colorDist(crop, i * 4, ref, 0) <= tol) { bg[i] = 1; q.push(i); }
+    };
+    for (let cx = 0; cx < w; cx++) {
+      push(cx, 0, [crop[(cx) * 4], crop[(cx) * 4 + 1], crop[(cx) * 4 + 2]]);
+      const bi = ((h - 1) * w + cx) * 4;
+      push(cx, h - 1, [crop[bi], crop[bi + 1], crop[bi + 2]]);
+    }
+    for (let cy = 0; cy < h; cy++) {
+      const li = (cy * w) * 4;
+      push(0, cy, [crop[li], crop[li + 1], crop[li + 2]]);
+      const ri = (cy * w + w - 1) * 4;
+      push(w - 1, cy, [crop[ri], crop[ri + 1], crop[ri + 2]]);
+    }
+    while (q.length) {
+      const i = q.pop();
+      const cx = i % w, cy = (i / w) | 0;
+      const ref = [crop[i * 4], crop[i * 4 + 1], crop[i * 4 + 2]];
+      if (cx > 0) push(cx - 1, cy, ref);
+      if (cx < w - 1) push(cx + 1, cy, ref);
+      if (cy > 0) push(cx, cy - 1, ref);
+      if (cy < h - 1) push(cx, cy + 1, ref);
+    }
+  }
+
+  // Optional: keep only the connected non-background component at `seed`.
+  if (args.seed) {
+    const sx = args.seed.x, sy = args.seed.y;
+    if (sx < 0 || sy < 0 || sx >= w || sy >= h) {
+      throw new Error(`seed (${sx},${sy}) is outside the crop (${w}×${h}); seed is crop-relative.`);
+    }
+    const seedI = sy * w + sx;
+    if (bg[seedI]) {
+      throw new Error(`seed pixel is classified as background — pick a seed on the sprite, or raise tolerance/switch backgroundMode.`);
+    }
+    const keep = new Uint8Array(w * h);
+    const q = [seedI]; keep[seedI] = 1;
+    while (q.length) {
+      const i = q.pop(); const cx = i % w, cy = (i / w) | 0;
+      const tryN = (nx, ny) => { const ni = ny * w + nx; if (!bg[ni] && !keep[ni]) { keep[ni] = 1; q.push(ni); } };
+      if (cx > 0) tryN(cx - 1, cy);
+      if (cx < w - 1) tryN(cx + 1, cy);
+      if (cy > 0) tryN(cx, cy - 1);
+      if (cy < h - 1) tryN(cx, cy + 1);
+    }
+    // Everything not in the kept component becomes background.
+    for (let i = 0; i < w * h; i++) if (!keep[i]) bg[i] = 1;
+  }
+
+  // Build the transparent output + debug image.
+  let kept = 0;
+  const out = new PNG({ width: w * scale, height: h * scale });
+  const dbg = new PNG({ width: w * scale, height: h * scale });
+  for (let row = 0; row < h; row++) {
+    for (let col = 0; col < w; col++) {
+      const i = row * w + col;
+      const isBg = !!bg[i];
+      if (!isBg) kept++;
+      for (let sy = 0; sy < scale; sy++) {
+        for (let sx = 0; sx < scale; sx++) {
+          const o = ((row * scale + sy) * (w * scale) + (col * scale + sx)) * 4;
+          // transparent output
+          out.data[o] = crop[i * 4]; out.data[o + 1] = crop[i * 4 + 1]; out.data[o + 2] = crop[i * 4 + 2];
+          out.data[o + 3] = isBg ? 0 : 0xFF;
+          // debug: kept = original, rejected = magenta
+          if (isBg) { dbg.data[o] = 0xFF; dbg.data[o + 1] = 0x00; dbg.data[o + 2] = 0xFF; dbg.data[o + 3] = 0xFF; }
+          else { dbg.data[o] = crop[i * 4]; dbg.data[o + 1] = crop[i * 4 + 1]; dbg.data[o + 2] = crop[i * 4 + 2]; dbg.data[o + 3] = 0xFF; }
+        }
+      }
+    }
+  }
+  return {
+    png: PNG.sync.write(out),
+    debugPng: PNG.sync.write(dbg),
+    width: w, height: h,
+    keptPixels: kept, totalPixels: w * h,
+  };
+}

package/src/platforms/common/tile-decode.js

@@ -0,0 +1,149 @@
+// Decode tile bytes back to 2D pixel index arrays.
+// Inverse of image-to-tiles encoders.
+//
+// All decoders return a Uint8Array of length 64 (one byte per pixel,
+// values 0..maxColors-1 according to the platform's bit depth).
+
+import { TILE_SPECS } from "./image-to-tiles.js";
+
+/**
+ * Decode a single tile from a buffer.
+ * @param {string} platform
+ * @param {Uint8Array} buf  source buffer (CHR / VRAM / wherever tiles live)
+ * @param {number} tileIndex
+ * @returns {Uint8Array} 64 bytes, row-major, top-left first
+ */
+export function decodeTile(platform, buf, tileIndex) {
+  const spec = TILE_SPECS[platform];
+  if (!spec) throw new Error(`unknown platform '${platform}'`);
+  const bytesPerTile = (8 * 8 * spec.bpp) / 8;
+  const off = tileIndex * bytesPerTile;
+  if (off + bytesPerTile > buf.length) {
+    throw new RangeError(`tile ${tileIndex} out of range (buf=${buf.length}, want ${off + bytesPerTile})`);
+  }
+  const pixels = new Uint8Array(64);
+
+  switch (spec.layout) {
+    case "planar": {
+      const planes = spec.bpp;
+      for (let y = 0; y < 8; y++) {
+        for (let x = 0; x < 8; x++) {
+          let v = 0;
+          for (let p = 0; p < planes; p++) {
+            const byte = buf[off + p * 8 + y];
+            v |= ((byte >> (7 - x)) & 1) << p;
+          }
+          pixels[y * 8 + x] = v;
+        }
+      }
+      return pixels;
+    }
+    case "interleaved": {
+      const planes = spec.bpp;
+      for (let y = 0; y < 8; y++) {
+        for (let x = 0; x < 8; x++) {
+          let v = 0;
+          for (let p = 0; p < planes; p++) {
+            const byte = buf[off + y * planes + p];
+            v |= ((byte >> (7 - x)) & 1) << p;
+          }
+          pixels[y * 8 + x] = v;
+        }
+      }
+      return pixels;
+    }
+    case "planar-pairs": {
+      // SNES: low 2 planes first 16 bytes, high 2 planes next 16.
+      for (let y = 0; y < 8; y++) {
+        const lo = buf[off + y * 2];
+        const hi = buf[off + y * 2 + 1];
+        const p2 = buf[off + 16 + y * 2];
+        const p3 = buf[off + 16 + y * 2 + 1];
+        for (let x = 0; x < 8; x++) {
+          const b = 7 - x;
+          let v = ((lo >> b) & 1) | (((hi >> b) & 1) << 1);
+          v |= ((p2 >> b) & 1) << 2;
+          v |= ((p3 >> b) & 1) << 3;
+          pixels[y * 8 + x] = v;
+        }
+      }
+      return pixels;
+    }
+    case "packed": {
+      const ppb = 8 / spec.bpp;
+      const mask = (1 << spec.bpp) - 1;
+      const bytesPerRow = 8 / ppb;
+      for (let y = 0; y < 8; y++) {
+        for (let x = 0; x < 8; x += ppb) {
+          const byte = buf[off + y * bytesPerRow + (x / ppb)];
+          for (let p = 0; p < ppb; p++) {
+            const shift = (ppb - 1 - p) * spec.bpp;
+            pixels[y * 8 + x + p] = (byte >> shift) & mask;
+          }
+        }
+      }
+      return pixels;
+    }
+    default:
+      throw new Error(`unknown layout '${spec.layout}'`);
+  }
+}
+
+/**
+ * Render a single tile as ASCII art. Each pixel becomes one character.
+ * Default mapping: " .+#" (0=empty, 3=solid) — works for 2bpp.
+ * For higher bit depths uses " .:-=+*#%@" (10 levels).
+ *
+ * @param {Uint8Array} pixels  64 bytes from decodeTile
+ * @param {number} [maxColors] for choosing character set
+ * @returns {string} 8-row ASCII art, newlines between rows
+ */
+export function tileToAscii(pixels, maxColors = 4) {
+  const chars = maxColors === 2 ? " #"
+    : maxColors === 4 ? " .+#"
+    : maxColors === 16 ? " .:-=+*#%@0123456789".slice(0, 16)
+    : " .,:;+*#%@".slice(0, maxColors);
+  let out = "";
+  for (let y = 0; y < 8; y++) {
+    for (let x = 0; x < 8; x++) {
+      const i = pixels[y * 8 + x];
+      out += chars[i] ?? "?";
+    }
+    if (y < 7) out += "\n";
+  }
+  return out;
+}
+
+/**
+ * Compute a short hash of a tile's pixels (for fast equality / change checks).
+ * FNV-1a over the pixel bytes.
+ */
+export function tileHash(pixels) {
+  let h = 0x811c9dc5 >>> 0;
+  for (let i = 0; i < pixels.length; i++) {
+    h ^= pixels[i];
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+/**
+ * Quick statistical summary of a tile.
+ * @param {Uint8Array} pixels
+ */
+export function tileStats(pixels) {
+  const counts = new Map();
+  let nonzero = 0;
+  for (const v of pixels) {
+    counts.set(v, (counts.get(v) ?? 0) + 1);
+    if (v !== 0) nonzero++;
+  }
+  const histogram = {};
+  for (const [k, v] of counts) histogram[k] = v;
+  return {
+    nonzero,
+    uniqueColors: counts.size,
+    histogram,
+    hash: tileHash(pixels),
+  };
+}

package/src/platforms/gb/MENTAL_MODEL.md

@@ -0,0 +1,252 @@
+# Game Boy / Game Boy Color — mental model
+
+One page. Read once before you write your first game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken;
+this is the "what's going on" version.
+
+## Five silent-failure footguns to know before you start (R26 + R27)
+
+If your ROM compiles cleanly but doesn't render — or sprites land in
+the wrong place, or VRAM stays empty, or "everything works for the
+no-input case but corrupts within ~100 frames when you press a button" —
+check these first. 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 (they run
+   rgbfix on the linked ROM): valid Nintendo logo, header + global
+   checksums, cart type / ROM-RAM size, and the CGB flag at $0143 — set
+   to $00 for `.gb` and $80/$C0 for `.gbc`. Getting $0143 wrong is the
+   classic white-screen: a stray $FF pad there trips CGB mode on a DMG
+   ROM so BGP/OBP* writes are ignored. Because the build sets it from the
+   platform you chose, a freshly built ROM is correct with **no manual
+   step**. Call `patchGbHeader` only to fix up an existing/external ROM
+   or override a field (title, cart type, ROM/RAM size, CGB flag).
+
+2. **OAM shadow buffer must be page-aligned.** OAM DMA copies 160 bytes
+   from `$XX00` — it reads ONLY the high byte of your source address.
+   The bundled `shadow_oam` in `gb_runtime.c` is pinned at $C100 with
+   `__at (0xC100)`; if you roll your own buffer, pick an address with
+   `0x00` in the low byte (e.g. $C200, $C300) and pass it directly to
+   `oam_dma_copy`. A plain `uint8_t my_oam[160]` may land at $C017 or
+   wherever the linker picks → DMA reads from $C000 → garbage in OAM.
+
+3. **Raw VRAM stores can be optimized away.** SDCC sm83 treats
+   `*((uint8_t*)0x8000) = x;` as dead code if the optimizer can't see
+   side effects. Use `memcpy_vram(dst, src, n)` from `gb_runtime.h`
+   (volatile-safe by construction) or cast through `volatile uint8_t *`.
+   See `gb_runtime/lib/c/SDCC_GOTCHAS.md` § "Writes to VRAM" for detail.
+
+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()` now 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 (the bus-conflict
+   default), which decodes as `rst $38` → stack corruption →
+   intermittent LCDC = $FF, BG VRAM wiped, sprites jump. Symptom
+   classically appeared as "works clean for 3000 frames with no input,
+   corrupts within 100 frames once a button is held" because the
+   gameplay code path's length / branches changed, shifting which DMAs
+   ran during which fetches. **The fix is in `lcd_init_default()` —
+   it auto-installs the stub.** Roll your own OAM DMA only if you
+   call `oam_dma_init_hram()` yourself first.
+
+5. **`gb_crt0.s` zeros BSS correctly.** Pre-r55's gsinit had a typo:
+   it zeroed `_INITIALIZED` (the runtime shadow of init-value data,
+   which gets overwritten anyway) instead of `_DATA` (the actual BSS
+   where uninitialized `static` globals land). Result: every
+   `static uint8_t counter;` started with whatever WRAM garbage was
+   there at boot — spurious "active" flags on game objects, etc. The
+   fixed crt0 zeros `_DATA` from `s__DATA` for `l__DATA` bytes, then
+   does the `_INITIALIZER → _INITIALIZED` copy for init-value statics.
+   If you use the bundled `gb_crt0.s` you're good; if you bring your
+   own, make sure gsinit zeros `_DATA`.
+
+## Memory map you actually care about
+
+```
+$0000-$014F  ROM cart header + reset vectors (crt0 territory)
+$0150-$7FFF  ROM code ($0150 is where init: lives — `_CODE` starts here)
+$8000-$97FF  VRAM tile data — 384 tiles × 16 bytes (CGB: dual-banked, 768 total)
+$9800-$9FFF  VRAM BG maps + CGB attribute map (in bank 1)
+$A000-$BFFF  Cart RAM (mappers only; not present in 32 KB ROM-only carts)
+$C000-$DFFF  WRAM (8 KB) — your variables, your stack
+$FE00-$FE9F  OAM (40 sprites × 4 bytes) — written via DMA
+$FF00       JOYP — joypad I/O
+$FF40-$FF4B I/O registers — LCDC, BGP, OBP0, OBP1, SCY, SCX, etc.
+$FF4D-$FF7F CGB-only registers — VBK, BCPS, BCPD, OCPS, OCPD, HDMA*, KEY1
+$FF80-$FFFE HRAM (127 bytes) — fast scratch, only place safe during DMA
+```
+
+## VRAM banks (CGB)
+
+DMG has one VRAM bank ($8000-$9FFF, 8 KB). CGB has **two**, switched
+via `VBK` ($FF4F).
+
+- **Bank 0:** tile data + BG tile map (default; what DMG sees)
+- **Bank 1:** BG attribute map (CGB-only — palette index + flip flags
+  per tile cell)
+
+To write a CGB BG attribute, set `VBK = 1`, write to $9800-$9FFF, then
+set `VBK = 0` so subsequent writes go back to bank 0.
+
+## Palettes
+
+DMG and CGB are **completely different palette systems**. On a CGB
+running a CGB-aware ROM, the DMG registers are ignored.
+
+**DMG:**
+- `BGP` ($FF47) — 1 byte, 4 colors × 2 bits = 4 grey shades.
+- `OBP0` ($FF48), `OBP1` ($FF49) — same shape, for sprites.
+
+**CGB (always for any `platform: "gbc"` build):**
+- Palette RAM is 64 bytes BG + 64 bytes OBJ — 8 palettes × 4 colors × 2 bytes (BGR555).
+- Written via the "auto-increment register pair" pattern:
+  ```c
+  BCPS = 0x80;   /* index 0, auto-advance, BG */
+  BCPD = lo; BCPD = hi;  /* color 0 of palette 0 */
+  BCPD = lo; BCPD = hi;  /* color 1 of palette 0 */
+  /* ... 32 BCPD writes total for all 8 BG palettes */
+  ```
+- `0x80` = bit 7 (auto-inc) + index 0. Without bit 7 set, every write
+  to BCPD overwrites the same byte.
+- `OCPS`/`OCPD` ($FF6A/$FF6B) are the same for sprites.
+
+## CGB header byte
+
+`$0143` controls CGB mode:
+- `0x00` = DMG-only — CGB ignores all the CGB registers
+- `0x80` = CGB-aware, DMG-compatible (recommended default)
+- `0xC0` = CGB-only (won't boot on DMG)
+
+You normally don't touch this byte by hand: `buildSource` / `runSource`
+set it from the platform you build for ($00 for `platform:"gb"`, $80/$C0
+for `platform:"gbc"`). To force a value, set it in your `gb_crt0.s`
+header section, or call `patchGbHeader({path, cgb:true})` on the built
+ROM (it auto-detects the `.gbc` extension; the standalone
+`patch-header.js` script does the same).
+
+## Sprite hardware quirks
+
+- OAM has 40 slots (160 bytes at $FE00-$FE9F). Each slot is
+  `{ Y, X, tile, attr }`.
+- **Y position is hardware-offset by 16.** Y=0 hides the sprite
+  off-screen; Y=16 is the top edge of the LCD.
+- **X position is hardware-offset by 8.** X=0 hides; X=8 is the left edge.
+- The hardware refreshes OAM from RAM every line; writing OAM mid-frame
+  glitches. **Always write OAM via DMA during vblank.**
+- `LCDC.1` (= 0x02) must be set to render sprites at all.
+- Per-line sprite limit is **10**. The hardware drops the 11th+ on
+  each scanline. Tall games use careful Y-staggering.
+
+## OAM DMA
+
+You don't write to $FE00 directly. You write to `DMA` ($FF46) — the
+high byte of a source address. The hardware copies 160 bytes from
+`source*0x100` to OAM. Takes 160 µs (~640 cycles). During the copy,
+**only HRAM ($FF80-$FFFE) is accessible**. The conventional trick is
+to call a tiny HRAM stub that sets DMA and spins until done; the
+`gb_runtime` `oam_dma_copy()` uses a simpler "spin in WRAM" version
+that works in vblank (you should only call it in vblank anyway).
+
+## Vblank timing
+
+- LCD is 154 scanlines tall (visible 0-143, vblank 144-153).
+- `LY` ($FF44) reads current scanline.
+- **When the LCD is off, LY is frozen at 0.** A blind `while (LY <
+  144)` deadlocks. `wait_vblank()` in the runtime checks `LCDC.7`
+  first and bails if LCD is off. Don't replace it with a hand-rolled
+  loop unless you know what you're doing.
+
+## Joypad
+
+`JOYP` ($FF00) is a multiplexed register. You write 0x10 or 0x20 to
+select which row (buttons or d-pad), then read the 4-bit result with
+each bit **active-low** (0 = pressed). `joypad_read()` does the
+multiplex + inversion + packing into one byte.
+
+Packed byte layout:
+- bits 7-4: d-pad (Down, Up, Left, Right)
+- bits 3-0: buttons (Start, Select, B, A)
+
+PAD_* masks in `gb_runtime.h` match this layout. Counter-intuitive
+because d-pad is in the HIGH nybble, but that's the layout that fell
+out of "row select bit determines nybble".
+
+## What `createProject` copies into your project
+
+`createProject({platform:"gb"|"gbc", template:...})` writes these files
+into your project directory. **They're yours** — every byte that compiles
+is in the repo. Edit, fork, replace; nothing is auto-injected at build time.
+
+| File | Provides |
+|---|---|
+| `main.c` | Your game's entry point (the template). |
+| `gb_hardware.h` | All SFR names (LCDC, BGP, BCPS, JOYP, VBK, ...) + LCDC_* bit masks. |
+| `gb_runtime.h` | Helper declarations + PAD_* masks + `shadow_oam[]`. |
+| `gb_runtime.c` | Helper implementations. Linked as an extra TU. |
+| `gb_crt0.s` | Custom crt0 that reserves $0100-$014F for the header window, puts `init:` at $0150. |
+| `patch-header.js` | Standalone Node script that patches the Nintendo logo + header/global checksums on a ROM — for fixing up an externally built ROM outside MCP. The normal build does this for you. |
+| `README.md` | Build invocation + "rebuild outside MCP" instructions. |
+
+Build calls explicitly reference these files via `sourcesPaths` /
+`includePaths` / `crt0Path` + `codeLoc: 0x150`. `buildSource` /
+`runSource` then fix up the cart header automatically (logo, checksums,
+CGB flag), so the ROM loads under gambatte with no extra step. Use
+`patchGbHeader({path})` (MCP tool) or `node patch-header.js <rom>` (CLI)
+only on a ROM the build pipeline didn't produce. See your project's
+README for the exact incantation.
+
+## What's NOT done for you
+
+- Music — `sound_init()` + `sound_play_tone(channel, freq_period, length)`
+  + `sound_play_noise(length)` + `sound_off()` cover the common
+  "beep on event" SFX pattern using the GB APU's 4 channels (2 square,
+  triangle/wave, noise). For sequenced multi-channel music, roll your own
+  or use raw `NR*` register names from `gb_hardware.h`.
+- Window layer — `LCDC.5` + `WX`/`WY` registers, no helpers.
+- MBC1/MBC3/MBC5 bank switching — every ROM bundled is 32 KB ROM-only.
+  For bigger games, write your own bank-switch macros and pass them
+  the right address.
+- Save RAM — same; cart RAM ($A000-$BFFF) requires mapper-specific
+  enable sequences. Not bundled.
+- Interrupts beyond vblank/halt — the default IRQ vectors are all
+  `reti`. To enable timer/serial/lcd-stat interrupts, you'll need to
+  write a custom handler.
+
+## When to break out of the runtime
+
+The bundled `gb_runtime.c` is intentionally minimal. It's the right
+choice for the first 80% of a game. When you hit one of these, you'll
+need to drop down:
+
+- **Cycle-accurate timing** (line-counter effects, raster split, etc.)
+  — needs hand-tuned asm, not C.
+- **Sound** — write raw register sequences from a music driver.
+- **OAM DMA during raster** — needs the HRAM-stub trick mentioned above.
+- **Multi-bank ROMs** — switch to `language: "asm"` and roll your own
+  layout via RGBDS.
+
+Most game patterns DON'T need any of this. Try the C path first.
+
+## Horizontal scrolling (for side-scrollers)
+
+The `platformer` scaffold is single-screen. To make it a side-scroller:
+
+- **Hardware scroll:** write `SCX` (`$FF43`) each frame = camera X mod 256.
+  The BG is a 32×32 tile map (256×256 px) that wraps, so `SCX` alone scrolls
+  smoothly through one map's worth.
+- **Streaming:** your world is wider than 256 px, so as the camera advances
+  you must rewrite the BG-map **column** that is about to scroll into view.
+  Track `camX`; each time `camX` crosses an 8-px boundary, write the next
+  world column's 18 (or 20) tile IDs into the off-screen BG-map column at
+  `(camX/8 + 20) & 31`. Do VRAM writes during vblank (or with the LCD off /
+  via `memcpy_vram`).
+- **Fixed HUD:** use the Window (`WX`/`WY`, LCDC bit 5) for a non-scrolling
+  status bar — it draws over the BG and ignores SCX/SCY.
+- **Vertical too?** `SCY` (`$FF42`) works the same; stream rows instead of
+  columns.
+
+Pattern: keep a `world_map[col][row]` array, a `camX` in pixels, convert
+actor world-X → screen-X as `worldX - camX`, and only ever touch the one
+column entering the screen per 8-px step.