romdevtools 0.13.0

package/src/platforms/gbc/lib/c/lcd_init.c

@@ -0,0 +1,19 @@
+/* ── lcd_init — turn the LCD on with sensible DMG defaults ─────────
+ * BG ON, OBJ ON, tile data $8000-$8FFF (unsigned), BG map $9800.
+ * Default DMG grayscale palette (BGP=$E4 = 3-2-1-0).
+ *
+ * Call once from main() before doing anything else.
+ */
+#include "gb_hardware.h"
+
+void lcd_init(void) {
+  /* Wait for vblank before touching the LCD control reg. */
+  while (LY < 144) { }
+  LCDC = 0;                          /* turn off so we can safely write VRAM */
+  BGP  = 0xE4;                       /* 11 10 01 00 — darkest first */
+  OBP0 = 0xE0;
+  OBP1 = 0xE0;
+  SCY  = 0;
+  SCX  = 0;
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+}

package/src/platforms/gbc/lib/c/patch-header.js

@@ -0,0 +1,154 @@
+// patch-header.js — patch a Game Boy / GBC ROM with the canonical
+// Nintendo boot logo + valid header + global checksums.
+//
+// USAGE:
+//   node patch-header.js <rom-file>           # patches in place
+//   node patch-header.js <in.gb> <out.gb>    # writes to new file
+//
+// WHY: most libretro GB cores (gambatte) refuse to load a ROM whose
+// Nintendo logo at $0104-$0133 doesn't match the canonical bytes or
+// whose header checksum at $014D doesn't validate. RGBDS's `rgbfix`
+// does this in the asm-build path; for SDCC-built C ROMs (which our
+// pipeline does NOT auto-patch — every byte that compiles is yours),
+// this script does the same job.
+//
+// The bundled gb_crt0.s reserves $0100-$014F for the header window,
+// so the bytes patched in here land on actual cartridge-header
+// territory, not on code.
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+const NINTENDO_LOGO = [
+  0xCE, 0xED, 0x66, 0x66, 0xCC, 0x0D, 0x00, 0x0B,
+  0x03, 0x73, 0x00, 0x83, 0x00, 0x0C, 0x00, 0x0D,
+  0x00, 0x08, 0x11, 0x1F, 0x88, 0x89, 0x00, 0x0E,
+  0xDC, 0xCC, 0x6E, 0xE6, 0xDD, 0xDD, 0xD9, 0x99,
+  0xBB, 0xBB, 0x67, 0x63, 0x6E, 0x0E, 0xEC, 0xCC,
+  0xDD, 0xDC, 0x99, 0x9F, 0xBB, 0xB9, 0x33, 0x3E,
+];
+
+/**
+ * Patch a GB/GBC ROM buffer in place. Returns the same buffer.
+ *
+ * Fills EVERY cartridge-header byte the boot ROM and gambatte care
+ * about — not just the Nintendo logo + checksums.
+ *
+ * Why this matters (round 26 friction report): an agent shipped a
+ * working C ROM that booted into a WHITE SCREEN on gambatte. Root
+ * cause: `gb_crt0.s` allocates `.ds 0x4C` at $0104 to reserve the
+ * header window. The ld65 sm83 linker fills the unused part with
+ * the pad byte ($FF). $0143 (CGB flag) = $FF means "CGB-aware" →
+ * gambatte enters CGB mode → DMG BGP/OBP0/OBP1 register writes are
+ * silently ignored → white screen. Patching ONLY the logo + checksums
+ * (the pre-round-26 behaviour) left $0143 = $FF intact.
+ *
+ * Now we fill the whole $0134..$014C window with ROM-only DMG cart
+ * defaults (or CGB-aware defaults when `cgb` is set). Caller can
+ * still override with `cartType` / `romSize` / `ramSize` for mapper-
+ * specific carts; the defaults cover the vast majority of homebrew.
+ *
+ * @param {Uint8Array} rom
+ * @param {object} [opts]
+ * @param {boolean} [opts.cgb]       Set $0143 = $80 (CGB-aware + DMG-compat). Default false → $0143 = $00 (DMG-only).
+ * @param {string}  [opts.title]     Up to 11 ASCII chars at $0134..$013E (uppercase, padded with $00). Default ""=zero-fill.
+ * @param {number}  [opts.cartType]  Cart type byte at $0147. Default 0x00 = ROM-only.
+ * @param {number}  [opts.romSize]   ROM size byte at $0148. Default 0x00 = 32 KB.
+ * @param {number}  [opts.ramSize]   RAM size byte at $0149. Default 0x00 = none.
+ * @param {number}  [opts.destination] Destination code at $014A. Default 0x01 = non-Japan.
+ */
+export function patchGbHeader(rom, opts = {}) {
+  if (rom.length < 0x150) {
+    throw new Error(`ROM too small to patch (got ${rom.length} bytes, need ≥ 336)`);
+  }
+  // Nintendo logo at $0104-$0133.
+  for (let i = 0; i < NINTENDO_LOGO.length; i++) {
+    rom[0x0104 + i] = NINTENDO_LOGO[i];
+  }
+
+  // ─── Title field $0134..$013E (11 bytes ASCII, zero-padded). ──
+  // On CGB carts, $013F-$0142 is the manufacturer code (4 ASCII) and
+  // $0143 is the CGB flag. We zero-fill everything not covered by an
+  // explicit option so the agent doesn't have to think about it.
+  for (let i = 0x0134; i <= 0x0142; i++) rom[i] = 0x00;
+  if (opts.title) {
+    const t = String(opts.title).toUpperCase().slice(0, 11);
+    for (let i = 0; i < t.length; i++) {
+      rom[0x0134 + i] = t.charCodeAt(i) & 0xFF;
+    }
+  }
+
+  // ─── CGB flag $0143 ── $00 = DMG-only, $80 = CGB-aware + DMG-compat,
+  // $C0 = CGB-only (rejected by DMG). Default DMG-only since that's
+  // what `createProject({platform:"gb"})` should produce; the GBC
+  // tree overrides via patchGbHeader({cgb: true}).
+  rom[0x0143] = opts.cgb ? 0x80 : 0x00;
+
+  // ─── New licensee code $0144..$0145 ── two ASCII chars. We don't
+  // self-publish, so $00 $00 is fine; the boot ROM checks this against
+  // the old licensee byte ($014B) below.
+  rom[0x0144] = 0x00;
+  rom[0x0145] = 0x00;
+
+  // ─── SGB flag $0146 ── $00 = no SGB enhancement (we don't).
+  rom[0x0146] = 0x00;
+
+  // ─── Cart type $0147 ── $00 = ROM-only is the safe default.
+  // Common alternatives the caller can pass: $01 = MBC1, $03 = MBC1+RAM+BAT,
+  // $11 = MBC3, $13 = MBC3+RAM+BAT, $19 = MBC5.
+  rom[0x0147] = opts.cartType ?? 0x00;
+
+  // ─── ROM size $0148 ── 0 = 32 KB (2 banks). 1 = 64 KB, 2 = 128 KB, ...
+  // Default 0 matches the bundled 32 KB build size.
+  rom[0x0148] = opts.romSize ?? 0x00;
+
+  // ─── RAM size $0149 ── 0 = no RAM. Standard alternatives: $02 = 8 KB,
+  // $03 = 32 KB. Only meaningful when cartType selects a battery-backed MBC.
+  rom[0x0149] = opts.ramSize ?? 0x00;
+
+  // ─── Destination $014A ── 0 = Japan, 1 = non-Japan. Default 1.
+  rom[0x014A] = opts.destination ?? 0x01;
+
+  // ─── Old licensee $014B ── $33 means "see $0144..$0145" (new format).
+  // This is the canonical value modern homebrew uses.
+  rom[0x014B] = 0x33;
+
+  // ─── ROM version $014C ── $00 (first version).
+  rom[0x014C] = 0x00;
+
+  // Header checksum at $014D: sum -((byte+1)) for $0134..$014C.
+  let hcs = 0;
+  for (let i = 0x0134; i <= 0x014C; i++) {
+    hcs = (hcs - rom[i] - 1) & 0xFF;
+  }
+  rom[0x014D] = hcs;
+  // Global ROM checksum at $014E-$014F: 16-bit sum of all bytes
+  // except $014E/$014F themselves. Boot ROM doesn't actually check
+  // this on hardware, but emulators may.
+  let gcs = 0;
+  for (let i = 0; i < rom.length; i++) {
+    if (i === 0x014E || i === 0x014F) continue;
+    gcs = (gcs + rom[i]) & 0xFFFF;
+  }
+  rom[0x014E] = (gcs >> 8) & 0xFF;
+  rom[0x014F] = gcs & 0xFF;
+  return rom;
+}
+
+// CLI entry — only runs when invoked directly.
+const isCli = import.meta.url.startsWith("file:") &&
+              process.argv[1] &&
+              import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (isCli) {
+  const inPath = process.argv[2];
+  const outPath = process.argv[3] ?? inPath;
+  if (!inPath) {
+    console.error("usage: node patch-header.js <rom-file> [<out-file>]");
+    process.exit(1);
+  }
+  const rom = new Uint8Array(readFileSync(inPath));
+  // Auto-detect CGB based on file extension.
+  const cgb = /\.gbc$/i.test(inPath) || /\.gbc$/i.test(outPath);
+  patchGbHeader(rom, { cgb });
+  writeFileSync(outPath, rom);
+  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""})`);
+}

package/src/platforms/gbc/lib/c/song_data.c

@@ -0,0 +1,88 @@
+/* ── song_data.c — sample song for hUGEDriver.c (compact format) ────
+ *
+ * A short hand-authored two-channel tune in C-major. 4 patterns, 16
+ * rows each, ticks_per_row = 8 (~7.5 rows per second at 60 Hz).
+ *
+ * Pattern layout (per row): {note, flags}
+ *   note  = 0..71 (C3..B8). See hUGE_note_table in hUGEDriver.c.
+ *           Useful indices: C4=12 D4=14 E4=16 F4=17 G4=19 A4=21 B4=23
+ *                           C5=24 D5=26 E5=28 F5=29 G5=31 A5=33 B5=35
+ *                           C6=36
+ *           Octave below: C3=0 G3=7 C4=12.
+ *   flags = 0 (re-trigger) / 0x80 (sustain — leave APU alone)
+ *           0xFF as note = rest (silence channel)
+ *
+ * For agents: to author your own song, replace these arrays with your
+ * own pattern data. The format is intentionally simple — a 16-row
+ * pattern is 32 bytes. A 4-pattern song is 128 bytes per channel.
+ */
+
+#include "hUGEDriver.h"
+
+/* Convenience constants for readability. Match indices in
+ * hUGE_note_table[] (driver source). */
+#define R   { 0xFF, 0 }            /* rest */
+#define _S  { 0,    0x80 }         /* sustain (note byte ignored) */
+#define N(n) { (uint8_t)(n), 0 }
+
+/* ── CH1 (melody — square 1) ───────────────────────────────────────── */
+
+static const huge_row_t mel_p0[HUGE_ROWS_PER_PATTERN] = {
+  N(24), _S, N(28), _S, N(31), _S, N(36), _S,   /* C5 E5 G5 C6 */
+  N(31), _S, N(28), _S, N(24), _S, R, R
+};
+
+static const huge_row_t mel_p1[HUGE_ROWS_PER_PATTERN] = {
+  N(26), _S, N(29), _S, N(33), _S, N(38), _S,   /* D5 F5 A5 D6 */
+  N(33), _S, N(29), _S, N(26), _S, R, R
+};
+
+static const huge_row_t mel_p2[HUGE_ROWS_PER_PATTERN] = {
+  N(28), _S, N(31), _S, N(35), _S, N(40), _S,   /* E5 G5 B5 E6 */
+  N(35), _S, N(31), _S, N(28), _S, R, R
+};
+
+static const huge_row_t mel_p3[HUGE_ROWS_PER_PATTERN] = {
+  N(36), _S, N(35), _S, N(33), _S, N(31), _S,   /* C6 B5 A5 G5 */
+  N(29), _S, N(28), _S, N(26), _S, N(24), _S    /* F5 E5 D5 C5 */
+};
+
+static const huge_row_t * const mel_orders[] = {
+  mel_p0, mel_p1, mel_p2, mel_p3
+};
+
+/* ── CH2 (bass — square 2) ────────────────────────────────────────── */
+
+static const huge_row_t bas_p0[HUGE_ROWS_PER_PATTERN] = {
+  N(0),  _S, _S, _S, N(0),  _S, _S, _S,         /* C3 */
+  N(7),  _S, _S, _S, N(0),  _S, _S, _S          /* G3 / C3 */
+};
+
+static const huge_row_t bas_p1[HUGE_ROWS_PER_PATTERN] = {
+  N(2),  _S, _S, _S, N(2),  _S, _S, _S,         /* D3 */
+  N(9),  _S, _S, _S, N(2),  _S, _S, _S          /* A3 / D3 */
+};
+
+static const huge_row_t bas_p2[HUGE_ROWS_PER_PATTERN] = {
+  N(4),  _S, _S, _S, N(4),  _S, _S, _S,         /* E3 */
+  N(11), _S, _S, _S, N(4),  _S, _S, _S          /* B3 / E3 */
+};
+
+static const huge_row_t bas_p3[HUGE_ROWS_PER_PATTERN] = {
+  N(12), _S, _S, _S, N(7),  _S, _S, _S,         /* C4 / G3 */
+  N(4),  _S, _S, _S, N(0),  _S, _S, _S          /* E3 / C3 (resolve) */
+};
+
+static const huge_row_t * const bas_orders[] = {
+  bas_p0, bas_p1, bas_p2, bas_p3
+};
+
+/* ── Song descriptor ──────────────────────────────────────────────── */
+
+const huge_song_t sample_song = {
+  /* ticks_per_row */ 8,
+  /* ch1 */ { mel_orders, 4, 1 },
+  /* ch2 */ { bas_orders, 4, 1 },
+  /* ch3 */ { 0,          0, 0 },
+  /* ch4 */ { 0,          0, 0 },
+};

package/src/platforms/gbc/lib/c/unroll.h

@@ -0,0 +1,52 @@
+/* ── unroll.h — manual loop-unrolling macros for SDCC sm83 ──────────
+ * Auto-staged into every gb/gbc C build.
+ *
+ * SDCC 4.4.0 sm83 crashes on a wide family of `for (i ...) { ... f(i,
+ * ...); ... }` patterns (see SDCC_GOTCHAS.md #1-#9). The reliable
+ * workaround is manual unrolling — write N explicit statements
+ * instead of a loop. These macros automate that.
+ *
+ * Usage:
+ *
+ *   #define STORE_CELL(N) row_buf[N] = wall_at(room, N, ty);
+ *   UNROLL_20(STORE_CELL)
+ *
+ * expands to:
+ *   row_buf[0] = wall_at(room, 0, ty);
+ *   row_buf[1] = wall_at(room, 1, ty);
+ *   ... 18 more ...
+ *   row_buf[19] = wall_at(room, 19, ty);
+ *
+ * No for-loop, so SDCC's register allocator can't crash. Each
+ * statement is independent + the call returns before the next one
+ * starts — register pressure is one call's worth at a time, never
+ * accumulates across iterations.
+ *
+ * Common GB sizes covered: 2, 3, 4, 5, 6, 7, 8, 10, 12, 16, 18, 20,
+ * 24, 32, 40, 64. Compose larger sizes from smaller ones (e.g.
+ * UNROLL_40 = two UNROLL_20 blocks with index offset; not provided
+ * to keep the file readable, but trivial to write).
+ *
+ * The macro M takes a single argument: the integer index.
+ */
+#ifndef UNROLL_H
+#define UNROLL_H
+
+#define UNROLL_2(M)  M(0) M(1)
+#define UNROLL_3(M)  M(0) M(1) M(2)
+#define UNROLL_4(M)  M(0) M(1) M(2) M(3)
+#define UNROLL_5(M)  M(0) M(1) M(2) M(3) M(4)
+#define UNROLL_6(M)  M(0) M(1) M(2) M(3) M(4) M(5)
+#define UNROLL_7(M)  M(0) M(1) M(2) M(3) M(4) M(5) M(6)
+#define UNROLL_8(M)  M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7)
+#define UNROLL_10(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9)
+#define UNROLL_12(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11)
+#define UNROLL_16(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11) M(12) M(13) M(14) M(15)
+#define UNROLL_18(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11) M(12) M(13) M(14) M(15) M(16) M(17)
+#define UNROLL_20(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11) M(12) M(13) M(14) M(15) M(16) M(17) M(18) M(19)
+#define UNROLL_24(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11) M(12) M(13) M(14) M(15) M(16) M(17) M(18) M(19) M(20) M(21) M(22) M(23)
+#define UNROLL_32(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11) M(12) M(13) M(14) M(15) M(16) M(17) M(18) M(19) M(20) M(21) M(22) M(23) M(24) M(25) M(26) M(27) M(28) M(29) M(30) M(31)
+#define UNROLL_40(M) M(0) M(1) M(2) M(3) M(4) M(5) M(6) M(7) M(8) M(9) M(10) M(11) M(12) M(13) M(14) M(15) M(16) M(17) M(18) M(19) M(20) M(21) M(22) M(23) M(24) M(25) M(26) M(27) M(28) M(29) M(30) M(31) M(32) M(33) M(34) M(35) M(36) M(37) M(38) M(39)
+#define UNROLL_64(M) UNROLL_32(M) M(32) M(33) M(34) M(35) M(36) M(37) M(38) M(39) M(40) M(41) M(42) M(43) M(44) M(45) M(46) M(47) M(48) M(49) M(50) M(51) M(52) M(53) M(54) M(55) M(56) M(57) M(58) M(59) M(60) M(61) M(62) M(63)
+
+#endif /* UNROLL_H */

package/src/platforms/gbc/lib/c/wait_vblank.c

@@ -0,0 +1,14 @@
+/* ── wait_vblank — wait for the next vblank period ─────────────────
+ * Spin on LY until it hits 144 (start of vblank). Cheap, busy-wait.
+ * Per-frame sync point: pair with all your draw-state updates so they
+ * land while the LCD isn't fetching.
+ *
+ * #include "gb_hardware.h"
+ */
+#include "gb_hardware.h"
+
+void wait_vblank(void) {
+  /* If already in vblank, wait it out first so we catch the leading edge. */
+  while (LY >= 144) { }
+  while (LY <  144) { }
+}

package/src/platforms/gbc/song.js

@@ -0,0 +1,3 @@
+// GBC song compiler — GBC uses the same hUGEDriver as GB, so the song format and
+// note math are identical. Re-export the GB compiler.
+export { compileSong, noteToHugeIndex, HUGE_ROWS_PER_PATTERN, default } from "../gb/song.js";

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -0,0 +1,306 @@
+# Sega Genesis / Mega Drive — mental model
+
+One page. Read once before you write your first Genesis game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken;
+this is the "what's going on" version.
+
+## CPU memory map ($000000-$FFFFFF, 68000 24-bit)
+
+```
+$000000-$3FFFFF   cart ROM (4 MB max — typical homebrew cart is 256 KB - 4 MB)
+$A00000-$A0FFFF   Z80 sound CPU RAM (64 KB window when bus is granted)
+$A10000-$A1001F   IO ports (controllers, version, region)
+$A11100-$A11101   Z80 busreq + reset
+$A14000-$A14003   TMSS (lock-out — write "SEGA" to $A14000 on boot)
+$C00000-$C00007   VDP data + control + HV counter
+$C00011           PSG (SN76489) — write-only
+$FF0000-$FFFFFF   work RAM (64 KB, mirrored $00FF... via 16M layout)
+```
+
+A few quirks worth knowing:
+
+- **WRAM is at the TOP of the address space** ($FF0000-$FFFFFF), not the
+  bottom. The stack pointer initialises to $00FFE000 (top of WRAM,
+  minus 8 KB headroom).
+- **The 68000 must NEVER write to ROM space**, even by mistake. Writing
+  to $000000-$3FFFFF triggers a bus error.
+- **Z80 RAM is only visible when the 68000 has bus-grant**. SGDK
+  handles this for you when you use the sound API.
+- **TMSS:** on a TMSS-equipped console (model 2+) the 68000 must
+  write "SEGA" to $A14000 within the first few seconds, or the
+  console refuses to start the VDP. SGDK's sega.s does this.
+
+## Reading your C globals headlessly — assert state, don't screenshot ⭐
+
+Every "did the score go up / did HP drop / did the level change?" check is one
+byte of RAM, not a screenshot. Build with debug, resolve the symbol, read it:
+
+```
+b   = build({output:'romWithDebug', platform:'genesis', source, inline:true})
+sym = symbols({op:'resolve', map: b.mapText, name:'score'})
+// → { address:0xE0FF004A, ramOffset:0x4A, readHint:"... region:'system_ram', offset:0x4a ..." }
+memory({op:'read', region:'system_ram', offset: sym.ramOffset, length:2})
+```
+
+- **SGDK links work-RAM through the $E0FF0000 mirror** (hardware mirrors $FF0000
+  across the high bus). The emulator exposes that 64 KB as `system_ram`, indexed
+  by the **low 16 bits** of the symbol address — `symbols({op:'resolve'})` hands
+  you that `ramOffset` + the exact `memory({op:'read'})` recipe, so you never
+  compute the mirror by hand.
+- **`static` file-local globals resolve too** (SGDK emits per-symbol sections).
+  A non-`static` global that's never *read* can be optimised away at -O2 — mark
+  game-state vars you inspect `volatile` (you want that anyway).
+- **Genesis WRAM is host-LE word-byte-swapped** in gpgx, so a 16-bit value reads
+  with its two bytes swapped at the offset (0x1234 → bytes `34 12`). Read the
+  word and account for it, or read single bytes.
+- **PC → which function?** `symbols({op:'addr', pc, symbolsText: b.mapText})` maps
+  a live `cpu({op:'read'}).pc` to the enclosing C function.
+
+This replaces ~20 verification screenshots a session with 1-byte reads.
+`memory({op:'snapshot'})` + `memory({op:'diff'})` before/after an event answers
+"which bytes did this touch?" when you don't know the symbol yet.
+
+## VDP (Video Display Processor) — separate bus
+
+The VDP has its own VRAM (64 KB), CRAM (128 bytes), VSRAM (80 bytes).
+You don't address it directly; you talk to it through `$C00000`
+(data port) and `$C00004` (control port).
+
+```
+VRAM   64 KB   tile patterns + name-tables + sprite-attribute-table
+CRAM  128 B    4 palettes × 16 colors × 2 bytes (BGR, 9-bit)
+VSRAM  80 B    per-column vertical scroll values
+```
+
+The two display planes:
+
+- **Plane A** (foreground) — name-table address configurable via VDP
+  reg 2. SGDK puts the font here, so `VDP_drawText` writes plane A.
+- **Plane B** (background) — name-table address via VDP reg 4. Use
+  this for your world tile-map; it sits *behind* plane A.
+
+Plane sizes are configurable (32×32, 64×32, 32×64, 64×64 cells).
+Default H40 mode is 40 cells wide × 28 tall visible (320×224 px).
+
+## Sprites (sprite-attribute table — SAT)
+
+The SAT lives in VRAM at an address set by VDP reg 5. Up to 80 entries
+(64 displayable in H32 mode, 80 in H40), 8 bytes each:
+
+```
++0 Y position (10-bit, offset by 128 — Y=128 is top of screen)
++2 size (4 bits w × 4 bits h, in tiles)
++3 link (next sprite in chain — SAT is a linked list)
++4 attribute: palette (bits 13-14), priority (bit 15), HV flip, tile index
++6 X position (10-bit, offset by 128)
+```
+
+The VDP draws at most **20 sprites per scanline** (H40), **16 per
+scanline** (H32). Beyond that the rest are dropped.
+
+**SGDK convention:** don't poke the SAT yourself. Use either the
+sprite engine (`SPR_init`, `SPR_addSprite`, `SPR_update`) for
+animated sprites, or the lightweight `VDP_setSprite()` + `VDP_updateSprites()`
+direct-VDP path if you only need static images.
+
+**Lifting a character from another Genesis ROM:** a visible character is
+usually several SAT entries (multi-cell hardware sprites) referencing
+non-contiguous VRAM tiles in column-major order. Don't crop a screenshot
+or a tile sheet — use `sprites({op:'capture', platform:"genesis", slots|rect})`
+which reads the live SAT, copies the referenced tiles in hardware order,
+and emits tiles + palette + layout + an SGDK `_draw()` helper. Use
+`sprites({op:'group'})` first to find which slots form one character. See
+AGENTS.md → "Lifting a Genesis CHARACTER".
+
+## Tiles
+
+Tiles are 8×8 pixels, 4 bits per pixel (4bpp = 16 colors per tile).
+A tile is 32 bytes in VRAM. The VDP holds 2048 tiles max in 64 KB.
+
+SGDK reserves the low ~512 tiles for the system font + UI; user tile
+data starts at `TILE_USER_INDEX`. Upload tiles via `VDP_loadTileData()`
+(DMA or CPU push, depending on the `TransferMethod` arg).
+
+**Converting an image to tiles** (sprite sheet, or a full-screen
+splash/title image): use the `encodeArt({stage:'tilemap'})` MCP tool — it produces
+correct 4bpp packed tiles + tilemap + palette and a preview PNG in one
+call. **Do not hand-encode a full-screen picture** as `u32[8]` arrays;
+that's the #1 way to get a "right shapes, all-red, choppy" splash
+screen. See TROUBLESHOOTING.md → "My splash / title screen is the right
+shapes but all one color".
+
+## Palette
+
+CRAM holds 4 palettes × 16 colors × 2 bytes = 128 bytes. Colour 0
+of each palette is the transparent / backdrop colour. The colour
+encoding is BGR, 3 bits per channel, with 4-bit alignment:
+
+```
+$0BGR  → e.g. $0EEE = white, $000E = bright red, $0E00 = blue
+```
+
+(Yes — blue and red are reversed from the "usual" RGB order.)
+
+SGDK macros: `PAL0..PAL3` for palette indices, `PAL_setColor(absidx, val)`
+where `absidx = pal * 16 + col`.
+
+## Frame heartbeat
+
+```
+while (1) {
+    update_game_state();
+    draw_world_to_plane_b();
+    stage_sprites();
+    SYS_doVBlankProcess();   // blocks until vblank, drives DMA queue,
+                             // sprite-engine update, joypad poll,
+                             // sound driver tick.
+}
+```
+
+**Without `SYS_doVBlankProcess()`** SGDK's DMA queue never flushes →
+your sprite updates never appear on screen. It's the single most
+important call in any SGDK game loop.
+
+## Input
+
+`u16 pad = JOY_readJoypad(JOY_1)` returns a packed bitmask. The
+button bits are:
+
+```
+BUTTON_UP   = 0x0001    BUTTON_A     = 0x0040
+BUTTON_DOWN = 0x0002    BUTTON_B     = 0x0010
+BUTTON_LEFT = 0x0004    BUTTON_C     = 0x0020
+BUTTON_RIGHT= 0x0008    BUTTON_START = 0x0080
+                        BUTTON_X/Y/Z = 0x0400/0x0200/0x0100  (6-button pad)
+                        BUTTON_MODE  = 0x0800
+```
+
+`JOY_1` is the first controller, `JOY_2` the second. Edge-detect by
+xor-ing this frame against last frame and AND-ing with the new state.
+
+### Driving input over MCP — the Genesis button map is INVERTED ⚠
+
+When you drive the game headlessly with `input({op:'set'})`/`input({op:'press'})`, the raw
+libretro button names are **NOT** the Genesis A/B/C labels. genesis_plus_gx
+maps the printed Genesis buttons **A/B/C onto libretro y/b/a** (verified live
+against the core). So:
+
+| You want (SGDK)   | `input({op:'set'})`                    | spatial name |
+|-------------------|-------------------------------------|--------------|
+| `BUTTON_A`        | `{ y: true }`                       | `{ west: true }`  |
+| `BUTTON_B`        | `{ b: true }`                       | `{ south: true }` |
+| `BUTTON_C`        | `{ a: true }`                       | `{ east: true }`  |
+| `BUTTON_START`    | `{ start: true }`                   | —            |
+| X / Y / Z (6-btn) | `{ x: true }` / `{ north: true }` / `{ l: true }` | — |
+
+**The trap:** `input({op:'set'})` presses Genesis **C**, *not* A — so an
+SGDK jump bound to `BUTTON_A` won't fire from `{a:true}`. Use `{ y: true }` (or
+the spatial `{ west: true }`) for `BUTTON_A`. The **spatial names**
+(north/east/south/west) and `input({op:'press'})` resolve correctly per
+platform — prefer them over raw a/b/x/y. `input({op:'layout', platform:'genesis'})`
+returns the exact map in `faceButtons`. (This inversion is a genesis_plus_gx
+quirk shared by SMS + Game Gear; NES/SNES/GB/GBA/etc. are NOT inverted.)
+
+## Sound
+
+The Genesis has *two* sound chips:
+
+- **YM2612** — 6 FM operators + DAC. Goes through the M68000 → bus
+  to $A04000-$A04003 via Z80 (most idiomatic) or direct $C00011 for
+  the PSG-only path.
+- **SN76489** (PSG) — same chip as the SMS. 3 square + 1 noise.
+
+SGDK exposes both via the XGM2 driver. For music:
+
+```c
+extern const u8 my_music[];   // COMPILED XGM2 blob (.incbin'd) — NOT raw VGM
+XGM2_play(my_music);          // the R58 fn is XGM2_play (there is NO XGM2_startPlay)
+XGM2_stop();
+```
+
+**Genesis music how-to (the whole path):** author a `.vgm` (any tracker/VGM
+export), then **compile it to XGM2** — `XGM2_play()` needs a *compiled* blob
+(split FM/PSG streams + a sample table), not raw VGM. romdev does the compile
+for you with **`encodeAudio({target:'xgm2', vgmPath, name})`** → a ready-to-`#include`
+256-aligned C array + `<NAME>_LEN`. Then `XGM2_play(name)`. (The compiler is a
+pure-JS port of SGDK's `xgm2tool` — no Java/jar to install.) For PSG-only tunes
+this coexists with XGM2 *PCM* SFX (`encodeAudio({target:'xgm2pcm'})`); for FM
+music it uses the YM2612.
+
+NOTE: the legacy `xgmtool` / `.xgc` / `XGM_*` driver is a DIFFERENT, older format
+— don't feed an `.xgc` to `XGM2_load`/`XGM2_play`, it'll misparse. Use the XGM2
+path above. Hand-rolling YM2612 register pokes is possible but rarely worth it.
+
+**Sampled SFX (PCM):** XGM2 plays 8-bit signed PCM samples on its PCM channels
+(`XGM2_playPCM(sample, len, SOUND_PCM_CH1)` /
+`XGM2_playPCMEx(..., priority, halfRate, loop)`). The sample format is strict and
+easy to botch by hand — let **`encodeAudio({target:'xgm2pcm'})`** do it (path in → ready C array +
+`<NAME>_LEN` out). The rules it enforces:
+- **8-bit SIGNED** mono (not unsigned — a wrong sign is silent garbage).
+- **13.3 kHz** native, or **6.65 kHz** with `halfRate` (then play with
+  `XGM2_playPCMEx(..., TRUE, ...)`).
+- length padded to a **multiple of 256 bytes** (zero = silence).
+- the sample buffer must be **256-byte aligned** in ROM —
+  `__attribute__((aligned(256)))` (the emitted C does this for you).
+
+**Debugging sound:** `audioDebug({op:'inspect'})` returns a raw-blob snapshot
+of the FM chip (gpgx's struct isn't safely per-channel decodable — useful for
+frame-to-frame diffing), and `audioDebug({op:'inspect'})` decodes the SN76489
+(3 tone + 1 noise channel state, same chip as SMS/GG). To check a sample actually
+played, `audioDebug({op:'record'})` writes a WAV you (a human) can listen to — there is **no**
+headless per-PCM-channel "is it playing" readout for Genesis yet (it would need a
+core patch to expose the XGM2 Z80 driver state), so audio verification here is
+record-and-listen, not assert.
+
+## ROM layout
+
+```
+$000000-$0000FF   68000 vector table (64 entries × 4 bytes)
+$000100-$0001FF   ROM header (region, name, checksum, IO support, ROM range)
+$000200-          your code + data
+```
+
+The checksum lives at $18E and must be correct on a real console
+(emulators don't enforce it). SGDK's `rom_header.c` provides a
+template you fill in (game name, region codes, etc.) and the
+build pipeline computes the checksum on link.
+
+## Where the SDK lives (and how to read it)
+
+`scaffold({op:'project', platform:"genesis"})` ships the full SGDK include
+tree into the new project at `vendor/sgdk/`. So when your code does
+`#include <genesis.h>`, those headers come from
+`vendor/sgdk/include/`:
+
+```
+vendor/sgdk/include/genesis.h       ← top-level umbrella
+vendor/sgdk/include/vdp.h           VDP_*, VDP_setReg, VDP_setPalette
+vendor/sgdk/include/vdp_bg.h        VDP_drawText, VDP_setHorizontalScroll
+vendor/sgdk/include/sprite_eng.h    SPR_init, SPR_addSprite, SPR_update
+vendor/sgdk/include/sys.h           SYS_doVBlankProcess, SYS_disableInts
+vendor/sgdk/include/joy.h           JOY_init, JOY_readJoypad, BUTTON_*
+vendor/sgdk/include/sound.h         SND_startPlay_PCM, SND_isPlaying_PCM
+vendor/sgdk/include/xgm2.h          XGM2_play, XGM2_pause (music)
+vendor/sgdk/include/dma.h           DMA_doTransfer, DMA_queue
+```
+
+To find what an SGDK function does, GREP the vendor tree — the C
+source ships at `vendor/sgdk/src/`. Same pattern as the Lynx cc65
+vendor dir and SNES PVSnesLib: the agent reads the library it's
+calling instead of guessing from header comments.
+
+## Build pipeline
+
+When you call `build({output:'rom'})`:
+
+1. `cc1-m68k` (gcc 14.2.0 C frontend, WASM) compiles your `.c` →
+   `.s` assembly.
+2. `m68k-elf-as` (binutils, WASM) assembles each `.s` → `.o`.
+3. `m68k-elf-as` also assembles `rom_header.c` (via cc1 → as) →
+   raw 256-byte ROM header `.bin`.
+4. `m68k-elf-ld` (binutils, WASM) links all `.o` + `libmd.a` +
+   `libgcc.a` + `libc.a` per `md.ld` → ELF executable.
+5. `m68k-elf-objcopy` (binutils, WASM) extracts the raw binary
+   image from the ELF → `.bin` Genesis ROM.
+
+Loadable via genesis_plus_gx (`loadMedia`).