romdev-mcp 0.1.1

package/src/platforms/gb/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/gb/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/gb/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/gb/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/gb/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/gb/lib/dma_oam.asm

@@ -0,0 +1,51 @@
+; Game Boy OAM DMA — single-cycle 160-byte copy from WRAM to OAM.
+;
+; The OAM DMA routine MUST live in HRAM ($FF80-$FFFE) because:
+;   - During DMA, the CPU can only execute from HRAM (the main bus is
+;     monopolized for the 160-cycle transfer).
+;   - The routine writes $XX to $FF46, then waits for the transfer to
+;     complete with a small busy-loop.
+;
+; Usage: copy this stub to HRAM at startup, then call it whenever you
+; want to upload shadow OAM from $XX00 (XX = (source >> 8)).
+;
+; Standard pattern: shadow OAM lives at $C000 (top of WRAM bank 0).
+;   ld a, $C0
+;   call OamDma
+;
+; The OAM DMA stops the CPU for 160 µs (~640 cycles); the only safe
+; bus activity during it is HRAM reads.
+
+SECTION "OamDmaSetup", ROM0
+; Copy the HRAM-resident routine into place. Call this once during init.
+oam_dma_setup::
+  ld hl, OamDmaSource
+  ld de, OamDma
+  ld bc, OamDmaEnd - OamDmaSource
+.loop
+  ld a, [hl+]
+  ld [de], a
+  inc de
+  dec bc
+  ld a, b
+  or c
+  jr nz, .loop
+  ret
+
+; Source code that gets copied to HRAM.
+OamDmaSource:
+  ldh [$46], a          ; trigger DMA — A holds high byte of source
+  ld a, $28             ; 40 × 4 byte sprite × ~1 cycle each ≈ 160 µs
+.wait
+  dec a
+  jr nz, .wait
+  ret
+OamDmaEnd:
+
+SECTION "OamDmaInHRAM", HRAM
+OamDma:: ds OamDmaEnd - OamDmaSource
+
+; Convenience location for shadow OAM in WRAM. Game code writes here;
+; OAM DMA copies the 160 bytes to actual OAM at $FE00 each vblank.
+SECTION "ShadowOAM", WRAM0[$C000]
+ShadowOAM:: ds 160

package/src/platforms/gb/lib/header.asm

@@ -0,0 +1,56 @@
+; Game Boy / Game Boy Color cartridge header.
+;
+; The boot ROM verifies the Nintendo logo bytes at $0104-$0133 and the
+; header checksum at $014D before handing off to $0150 — if either
+; doesn't match, the boot ROM hangs the console (locks up at the logo).
+;
+; rgbasm tip: use `rgbfix -v -p 0` after building to auto-compute the
+; header checksum + ROM size byte. Doing it by hand is tedious and
+; usually wrong; let the tool fix it.
+;
+;     rgbfix -v -p 0 -m MBC1 -t "MYGAME" out.gb
+;
+; This snippet provides the structural layout; rgbfix fills in the
+; computed fields.
+
+SECTION "Header", ROM0[$0100]
+
+  ; $0100-$0103: entry point — 4 bytes. Conventional pattern is nop+jp.
+  nop
+  jp Start
+
+  ; $0104-$0133: Nintendo logo bytes — DO NOT change. rgbfix injects.
+  ds $30, 0
+
+  ; $0134-$0143: 16-byte title (uppercase ASCII). rgbfix sets via -t.
+  ds $10, 0
+
+  ; $0144-$0145: licensee code (new-style 2-char ASCII).
+  db "00"
+
+  ; $0146: SGB flag — 0x00 = no SGB features, 0x03 = SGB.
+  db $00
+
+  ; $0147: cartridge type. rgbfix -m MBC1 / -m MBC5 / -m ROM_ONLY etc.
+  db $00
+
+  ; $0148: ROM size. rgbfix computes from final ROM size.
+  db $00
+
+  ; $0149: RAM size. 0=none, 1=2KB, 2=8KB, 3=32KB (4 banks), etc.
+  db $00
+
+  ; $014A: destination code. 0=Japan, 1=non-Japan.
+  db $01
+
+  ; $014B: old-style licensee code. $33 = use new code at $0144.
+  db $33
+
+  ; $014C: ROM version.
+  db $00
+
+  ; $014D: header checksum. rgbfix -v fills this in (sum of $0134-$014C).
+  db $00
+
+  ; $014E-$014F: global cart checksum. rgbfix -v fills this in.
+  dw $0000

package/src/platforms/gb/lib/joypad_read.asm

@@ -0,0 +1,47 @@
+; Game Boy joypad read.
+;
+; Port $FF00 (JOYP) layout:
+;   bit 5: select button group ($00 = buttons A/B/Sel/Start, $10 = D-pad)
+;   bit 4: select D-pad group  ($00 selects, $10 deselects)
+;   bits 0-3: 4 buttons in the selected group (ACTIVE LOW — pressed = 0)
+;
+; To read both groups, write the selector, read $FF00 twice (small wait
+; for the contacts to stabilize), combine into one byte. Result format:
+;   bit 0: A
+;   bit 1: B
+;   bit 2: Select
+;   bit 3: Start
+;   bit 4: Right
+;   bit 5: Left
+;   bit 6: Up
+;   bit 7: Down
+; (pressed = 1 after inversion)
+
+joypad_read::
+  ; Select button group: bit 5 = 0, bit 4 = 1.
+  ld a, $10
+  ld [$FF00], a
+  ld a, [$FF00]
+  ld a, [$FF00]       ; second read — bouncing tolerance
+  cpl                 ; invert: pressed = 1
+  and $0F             ; keep only the 4 button bits
+  swap a              ; move buttons to high nybble
+  ld b, a             ; stash in B
+
+  ; Select D-pad group: bit 4 = 0, bit 5 = 1.
+  ld a, $20
+  ld [$FF00], a
+  ld a, [$FF00]
+  ld a, [$FF00]
+  cpl
+  and $0F             ; D-pad bits in low nybble
+  or b                ; combine: high = buttons, low = D-pad
+  ld [JoypadState], a
+
+  ; Reset the matrix to inactive state.
+  ld a, $30
+  ld [$FF00], a
+  ret
+
+SECTION "JoypadState", HRAM
+JoypadState:: ds 1

package/src/platforms/gb/lib/lcd_init.asm

@@ -0,0 +1,44 @@
+; Game Boy LCD initialization.
+;
+; The LCD must be ON before sprites/BG draw, but you can't write VRAM
+; while it's on (PPU steals the bus). Typical init sequence:
+;
+;   1. Turn LCD OFF ($FF40 = 0)
+;   2. Upload tiles, name map, palettes
+;   3. Set LCDC to enable display + the layers you want
+;
+; LCDC bits (write to $FF40):
+;   0: BG/Window display (1 = on)
+;   1: Sprites display (1 = on)
+;   2: Sprite size (0 = 8x8, 1 = 8x16)
+;   3: BG tile map (0 = $9800, 1 = $9C00)
+;   4: BG tile data (0 = $8800 signed, 1 = $8000 unsigned)
+;   5: Window display (1 = on)
+;   6: Window tile map (0 = $9800, 1 = $9C00)
+;   7: LCD enable
+;
+; Standard "BG + sprites, $8000 data, $9800 map" = %10010011 = $93
+
+lcd_off::
+  ld a, [$FF40]
+  bit 7, a
+  ret z               ; already off
+  ; Wait for vblank before turning off — turning off mid-frame can
+  ; damage real DMG hardware (rare but documented).
+.wait
+  ld a, [$FF44]
+  cp 144
+  jr c, .wait
+  xor a
+  ldh [$40], a        ; LCDC = 0 — LCD off
+  ret
+
+lcd_on_bg_sprites::
+  ld a, %10010011     ; LCD + BG + sprites, $8000 tiles, $9800 BG map
+  ldh [$40], a
+  ret
+
+lcd_on_bg_only::
+  ld a, %10010001     ; LCD + BG (no sprites)
+  ldh [$40], a
+  ret

package/src/platforms/gb/lib/load_palette.asm

@@ -0,0 +1,25 @@
+; Game Boy palette setup.
+;
+; DMG palettes are 1-byte registers — 4 × 2-bit shade indices packed
+; into one byte. The shade map is hardware: 0=lightest, 3=darkest.
+;
+;   $FF47 = BGP  — background palette
+;   $FF48 = OBP0 — sprite palette 0 (used when OAM attr bit 4 = 0)
+;   $FF49 = OBP1 — sprite palette 1 (used when OAM attr bit 4 = 1)
+;
+; Byte layout: bits 0-1 = color 0, bits 2-3 = color 1, etc.
+; Standard "0=white, 3=black" mapping is %11_10_01_00 = $E4.
+; Sprite color 0 is ALWAYS transparent — its slot in OBP doesn't matter.
+;
+; CGB palette is different — write to $FF68 (BCPS) to set index +
+; auto-increment, then write 64 bytes (8 palettes × 4 colors × 2 BGR555)
+; to $FF69 (BCPD). See load_palette_gbc.asm for the GBC variant.
+
+load_palette_dmg::
+  ld a, $E4           ; 11 10 01 00 — white/lt-gray/dk-gray/black
+  ldh [$47], a        ; BGP
+  ld a, $1B           ; 00 01 10 11 — invert for OBP0 (just as an example)
+  ldh [$48], a        ; OBP0
+  ld a, $E4
+  ldh [$49], a        ; OBP1
+  ret

package/src/platforms/gb/lib/load_tiles.asm

@@ -0,0 +1,29 @@
+; Game Boy tile loader — bulk VRAM upload from ROM.
+;
+; GB tiles are 16 bytes each (2bpp interleaved). VRAM at $8000-$97FF
+; holds 384 tiles. The PPU is reading tiles continuously while the
+; LCD is on — writes during active scanlines are IGNORED by the bus.
+; You can only safely write VRAM during:
+;   - vblank (LY >= 144)
+;   - hblank (PPU mode 0, very short)
+;   - LCD off (R1 bit 7 = 0)
+;
+; The simplest pattern is: turn LCD off for big uploads. The example
+; below assumes display is OFF (caller responsibility). For runtime
+; uploads during gameplay, queue them and DMA in vblank.
+;
+; CALLING:
+;   HL = source bytes (ROM)
+;   DE = VRAM destination ($8000-$97FF range)
+;   BC = byte count (= tile_count * 16)
+
+load_tiles::
+.loop
+  ld a, [hl+]
+  ld [de], a
+  inc de
+  dec bc
+  ld a, b
+  or c
+  jr nz, .loop
+  ret

package/src/platforms/gb/lib/vblank_wait.asm

@@ -0,0 +1,31 @@
+; Game Boy vblank wait — polls the LY register.
+;
+; $FF44 = LY (current scanline). The PPU's vblank period is scanlines
+; 144..153. The cheapest reliable vblank wait is:
+;
+;   ld a, [$FF44]
+;   cp 144
+;   jr c, .wait     ; if LY < 144, still drawing — keep waiting
+;
+; But this returns when ANY part of vblank starts — could be 1 line in
+; or 9 lines in. For tighter sync, wait for LY == 144 explicitly.
+;
+; Better still: enable the vblank IRQ ($FF0F bit 0, $FFFF bit 0) and
+; have your ISR set a flag in HRAM, then `halt` until IRQ. Halt saves
+; battery on a real DMG. See vblank_irq.asm for that path.
+
+vblank_wait_poll::
+.wait
+  ld a, [$FF44]
+  cp 144
+  jr c, .wait
+  ret
+
+; Wait specifically until vblank STARTS (LY = 144). Use this if your
+; subsequent VRAM writes need maximum vblank time.
+vblank_wait_start::
+.wait
+  ld a, [$FF44]
+  cp 144
+  jr nz, .wait
+  ret