romdev-mcp 0.1.1

package/examples/c64/templates/sports.c

@@ -0,0 +1,109 @@
+// ── sports.c — Commodore 64 Pong scaffold ────────────────────────────
+//
+// Two-paddle Pong using 3 hardware sprites (left paddle, right paddle,
+// ball). Joystick port 2 = P1 left paddle. P2 (port 1) AI tracks the ball
+// since port 1 conflicts with the keyboard matrix in headless mode.
+
+#include "c64_registers.h"
+#include "c64_sfx.h"
+#include <stdint.h>
+
+#define POKE(addr, val) (*(volatile uint8_t*)(addr) = (val))
+#define PEEK(addr)      (*(volatile uint8_t*)(addr))
+
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+
+#define SPRITE_POINTERS ((volatile uint8_t*)0x07F8)
+
+/* 8x21 tall thin paddle. */
+static const uint8_t paddle_sprite[64] = {
+  0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00,
+  0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00,
+  0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00,
+  0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00,
+  0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00, 0xFF,0x00,0x00,
+  0xFF,0x00,0x00, 0,
+};
+/* 8x8 ball. */
+static const uint8_t ball_sprite[64] = {
+  0x3C,0,0, 0x7E,0,0, 0xFF,0,0, 0xFF,0,0,
+  0xFF,0,0, 0xFF,0,0, 0x7E,0,0, 0x3C,0,0,
+  0,0,0, 0,0,0, 0,0,0, 0,0,0, 0,0,0, 0,0,0,
+  0,0,0, 0,0,0, 0,0,0, 0,0,0, 0,0,0, 0,0,0,
+  0,0,0, 0,
+};
+
+static void wait_vblank(void) {
+  while (PEEK(VIC_RASTER) < 250) { }
+  while (PEEK(VIC_RASTER) >= 250) { }
+}
+
+static void copy_sprite(uint8_t slot, const uint8_t *data) {
+  uint8_t i;
+  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  for (i = 0; i < 64; i++) dst[i] = data[i];
+}
+
+void main(void) {
+  uint8_t p1y = 130, p2y = 130;
+  int16_t bx = 150, by = 130;
+  int8_t bdx = 2, bdy = 1;
+  uint8_t pad;
+  uint8_t p1_score = 0, p2_score = 0;
+
+  POKE(VIC_SPR_ENA, 0);
+  copy_sprite(0, paddle_sprite);
+  copy_sprite(1, paddle_sprite);
+  copy_sprite(2, ball_sprite);
+  SPRITE_POINTERS[0] = 0x20;
+  SPRITE_POINTERS[1] = 0x21;
+  SPRITE_POINTERS[2] = 0x22;
+  POKE(VIC_SPR_COL(0), 0x01);  /* white */
+  POKE(VIC_SPR_COL(1), 0x01);
+  POKE(VIC_SPR_COL(2), 0x07);  /* yellow ball */
+
+  POKE(VIC_BORDER, 0x00);
+  POKE(VIC_BG0,    0x00);
+
+  /* P1 paddle on left, P2 on right. */
+  POKE(VIC_SPRITE_X(0), 30);
+  POKE(VIC_SPRITE_X(1), 240);
+
+  sfx_init();
+  POKE(VIC_SPR_ENA, 0x07);
+
+  for (;;) {
+    pad = (uint8_t)(~PEEK(CIA1_PRA) & 0x1F);
+    wait_vblank();
+    sfx_update();
+
+    if (pad & JOY_UP   && p1y > 60)  p1y -= 3;
+    if (pad & JOY_DOWN && p1y < 220) p1y += 3;
+
+    /* AI right paddle tracks ball. */
+    if (p2y + 10 < by && p2y < 220) p2y += 2;
+    else if (p2y + 10 > by && p2y > 60) p2y -= 2;
+
+    bx += bdx;
+    by += bdy;
+    if (by < 55)  { by = 55;  bdy = -bdy; sfx_tone(2, 0x80, 0x18, 2); }
+    if (by > 240) { by = 240; bdy = -bdy; sfx_tone(2, 0x80, 0x18, 2); }
+    /* Paddle 1 collision */
+    if (bdx < 0 && bx < 40 && bx > 24 && by > p1y - 8 && by < p1y + 22) {
+      bdx = -bdx; sfx_tone(0, 0x40, 0x20, 3);
+    }
+    /* Paddle 2 collision */
+    if (bdx > 0 && bx > 232 && bx < 248 && by > p2y - 8 && by < p2y + 22) {
+      bdx = -bdx; sfx_tone(0, 0x40, 0x20, 3);
+    }
+    /* Score */
+    if (bx < 5)   { p2_score++; if (p2_score > 9) p2_score = 0; sfx_noise(20); bx = 150; by = 130; bdx = 2; }
+    if (bx > 250) { p1_score++; if (p1_score > 9) p1_score = 0; sfx_tone(0, 0x80, 0x10, 16); bx = 150; by = 130; bdx = -2; }
+
+    POKE(VIC_SPRITE_Y(0), p1y);
+    POKE(VIC_SPRITE_Y(1), p2y);
+    POKE(VIC_SPRITE_X(2), (uint8_t)bx);
+    POKE(VIC_SPRITE_Y(2), (uint8_t)by);
+  }
+}

package/examples/c64/templates/tile_engine.c

@@ -0,0 +1,174 @@
+// ── tile_engine.c — Commodore 64 character-map walking demo ─────────
+//
+// C64 doesn't have "tiles" in the NES/SNES sense — it has a 40×25
+// CHARACTER MATRIX (screen RAM at $0400, color RAM at $D800) where
+// each cell selects one of 256 8×8 character glyphs from the
+// character-set ROM at $D000 (or RAM you point VIC at).
+//
+// This template builds a simple walking-demo:
+//   - 40×25 world drawn via screen-RAM character codes
+//   - Solid tiles (a "block" PETSCII = $A0) form a perimeter wall +
+//     a couple of interior platforms
+//   - A VIC-II hardware sprite walks across the world; AABB collision
+//     against character cells with the block code
+//
+// The sprite is driven by joystick port 2 (CIA1_PRA at $DC00 —
+// reading port 1 / CIA1_PRB conflicts with the keyboard scan).
+//
+// Hardware references:
+//   SCREEN      $0400..$07E7   40*25 character codes
+//   COLORS       $D800..$DBE7   40*25 color nibbles (low 4 bits)
+//   VIC_BORDER      $D020          border color
+//   VIC_BG0         $D021          background color
+//   VIC_SPRITE_X(N) / Y(N)         per-sprite position
+//   VIC_SPR_ENA     $D015          enable bitmask
+//   VIC_SPR_COL(N)  $D027+N        per-sprite color
+
+#include "c64_registers.h"
+#include <stdint.h>
+
+/* cc65 stdlib already defines POKE/PEEK in cc65/include/peekpoke.h
+ * with a different shape (no volatile, address as integer). Use the
+ * volatile-cast shape but under different names so we don't clash. */
+#define WR(addr, val)  (*(volatile uint8_t*)(addr) = (val))
+#define RD(addr)       (*(volatile uint8_t*)(addr))
+
+/* cc65 also predefines SCREEN / COLORS via cbm.h (it pulls in
+ * even without explicit include because cc65 wires conio etc). Use
+ * local names for clarity. */
+#define SCREEN          ((volatile uint8_t*)0x0400)
+#define COLORS          ((volatile uint8_t*)0xD800)
+#define SPRITE_POINTERS ((volatile uint8_t*)0x07F8)
+#define SPRITE_DATA     ((volatile uint8_t*)0x0800)
+
+#define COLS 40
+#define ROWS 25
+
+#define CHAR_BLANK 0x20  /* space */
+#define CHAR_BLOCK 0xA0  /* PETSCII solid block */
+
+#define COL_BLACK  0x00
+#define COL_WHITE  0x01
+#define COL_RED    0x02
+#define COL_CYAN   0x03
+#define COL_GREEN  0x05
+#define COL_BLUE   0x06
+
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+#define JOY_LEFT  0x04
+#define JOY_RIGHT 0x08
+
+// Small filled-square sprite (24×21, single-color).
+static const uint8_t sprite_data[64] = {
+  0x00,0x00,0x00,
+  0x00,0x7E,0x00,
+  0x00,0xFF,0x00,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x01,0xFF,0x80,
+  0x00,0xFF,0x00,
+  0x00,0x7E,0x00,
+  0,
+};
+
+static uint8_t world[ROWS][COLS];
+
+static void world_build(void) {
+  uint8_t r, c;
+  for (r = 0; r < ROWS; r++) {
+    for (c = 0; c < COLS; c++) {
+      world[r][c] =
+        (r == 0 || r == ROWS - 1 || c == 0 || c == COLS - 1)
+          ? CHAR_BLOCK : CHAR_BLANK;
+    }
+  }
+  // Two interior platforms.
+  for (c = 6;  c < 14; c++) world[10][c] = CHAR_BLOCK;
+  for (c = 22; c < 34; c++) world[16][c] = CHAR_BLOCK;
+}
+
+static void world_draw(void) {
+  uint8_t r, c;
+  for (r = 0; r < ROWS; r++) {
+    for (c = 0; c < COLS; c++) {
+      SCREEN[r * COLS + c] = world[r][c];
+      COLORS[r * COLS + c] = world[r][c] == CHAR_BLOCK ? COL_CYAN : COL_BLACK;
+    }
+  }
+}
+
+// Convert sprite (px, py) → character cell. C64 sprite coords are
+// offset 24 px (X) and 50 px (Y) from the visible top-left.
+static uint8_t solid_at(uint16_t px, uint16_t py) {
+  uint16_t cx = (px - 24) >> 3;
+  uint16_t cy = (py - 50) >> 3;
+  if (cx >= COLS || cy >= ROWS) return 1;
+  return world[cy][cx] == CHAR_BLOCK;
+}
+
+static void wait_vblank(void) {
+  while (RD(VIC_RASTER) < 250) { }
+  while (RD(VIC_RASTER) >= 250) { }
+}
+
+static void copy_sprite(void) {
+  uint8_t i;
+  for (i = 0; i < 64; i++) SPRITE_DATA[i] = sprite_data[i];
+}
+
+void main(void) {
+  uint16_t sx = 100, sy = 100;
+  uint8_t pad;
+
+  copy_sprite();
+  SPRITE_POINTERS[0] = 0x20;  /* $0800 / $40 */
+
+  WR(VIC_BORDER, 0x00);
+  WR(VIC_BG0,    0x00);
+  WR(VIC_SPR_COL(0), COL_RED);
+
+  world_build();
+  world_draw();
+
+  WR(VIC_SPRITE_X(0), (uint8_t)(sx & 0xFF));
+  WR(VIC_SPRITE_Y(0), (uint8_t)sy);
+  WR(VIC_SPR_ENA, 0x01);
+
+  for (;;) {
+    uint16_t nx = sx, ny = sy;
+    wait_vblank();
+
+    pad = ~RD(CIA1_PRA) & 0x0F;
+    if (pad & JOY_UP    && sy > 52)  ny--;
+    if (pad & JOY_DOWN  && sy < 240) ny++;
+    if (pad & JOY_LEFT  && sx > 26)  nx--;
+    if (pad & JOY_RIGHT && sx < 320) nx++;
+
+    // Per-axis movement with collision against the character map.
+    if (!solid_at(nx, sy) && !solid_at(nx + 16, sy) && !solid_at(nx + 16, sy + 16)) {
+      sx = nx;
+    }
+    if (!solid_at(sx, ny) && !solid_at(sx + 16, ny) && !solid_at(sx + 16, ny + 16)) {
+      sy = ny;
+    }
+
+    WR(VIC_SPRITE_X(0), (uint8_t)(sx & 0xFF));
+    WR(VIC_SPRITE_Y(0), (uint8_t)sy);
+    // Sprite X high bit (for sx >= 256)
+    WR(VIC_SPRITES_X8, sx >= 256 ? 0x01 : 0x00);
+  }
+}

package/examples/gb/main.asm

@@ -0,0 +1,106 @@
+; Game Boy hello-world — yellow 'H' on a dark BG, scrollable with A.
+;
+; Boots into ROM0 at $0100, sets up the LCD, uploads one tile + writes
+; it to the BG map, enables the LCD, then loops reading joypad and
+; scrolling the BG. Build with:
+;
+;   buildSource({platform:"gb", source: <this>})
+;
+; rgbfix gets applied automatically by buildForPlatform so the header
+; checksum is valid.
+
+SECTION "Entry", ROM0[$0100]
+  nop
+  jp Start
+
+  ; Nintendo logo + header bytes are filled in by rgbfix. We just pad.
+  ds $150 - @, 0
+
+SECTION "Main", ROM0[$0150]
+
+Start:
+  ; ── 1. Turn LCD off so we can write VRAM unrestricted ───────────
+.wait_vblank
+  ld a, [$FF44]              ; LY register
+  cp 144
+  jr c, .wait_vblank
+  xor a
+  ldh [$FF40], a               ; LCDC = 0 (LCD off)
+
+  ; ── 2. Reset stack pointer ──────────────────────────────────────
+  ld sp, $DFF0
+
+  ; ── 3. Set palette: BGP = $E4 (white / lt-gray / dk-gray / black) ─
+  ld a, $E4
+  ldh [$FF47], a               ; BGP
+
+  ; ── 4. Upload one 'H' tile to VRAM tile 1 at $8000 + 16 = $8010 ──
+  ld hl, $8010
+  ld de, TileH
+  ld bc, 16
+.upload_loop
+  ld a, [de]
+  inc de
+  ld [hl+], a
+  dec bc
+  ld a, b
+  or c
+  jr nz, .upload_loop
+
+  ; ── 5. Clear BG tile map ($9800-$9BFF) to tile 0 ─────────────────
+  ld hl, $9800
+  ld bc, $400
+.clear_map
+  xor a
+  ld [hl+], a
+  dec bc
+  ld a, b
+  or c
+  jr nz, .clear_map
+
+  ; ── 6. Write tile 1 to the center cell (row 8, col 9) ───────────
+  ld hl, $9800 + (8 * 32) + 9
+  ld a, $01
+  ld [hl], a
+
+  ; ── 7. Enable LCD: BG on, $8000 tile data, $9800 BG map, LCD on ──
+  ld a, %10010001
+  ldh [$FF40], a               ; LCDC
+
+  ; ── 8. Main loop: hold A to scroll BG ───────────────────────────
+  xor a
+  ld c, a                    ; C = scroll value
+
+MainLoop:
+.wait
+  ld a, [$FF44]
+  cp 144
+  jr c, .wait                ; wait for vblank
+
+  ; Read joypad: select button group, check A pressed.
+  ld a, $10                  ; bit 5=0 (buttons), bit 4=1 (deselect dpad)
+  ld [$FF00], a
+  ld a, [$FF00]
+  ld a, [$FF00]              ; bounce-tolerance read
+  and $01                    ; bit 0 = A button (active LOW)
+  jr nz, .skip_scroll        ; A not pressed → no scroll
+
+  inc c
+  ld a, c
+  ldh [$FF43], a               ; SCX = scroll value
+
+.skip_scroll
+  jr MainLoop
+
+; ── Tile data: yellow-on-dark 'H' (color index 3 = darkest in BGP $E4) ─
+; 2bpp interleaved: row N = byte 2N (low plane) + byte 2N+1 (high plane).
+; This pattern sets both planes for the 'X' bits → color index 3.
+TileH:
+  db $66, $66                ; row 0: . X X . . X X .
+  db $66, $66                ; row 1
+  db $66, $66                ; row 2
+  db $7E, $7E                ; row 3: . X X X X X X .
+  db $7E, $7E                ; row 4
+  db $66, $66                ; row 5
+  db $66, $66                ; row 6
+  db $00, $00                ; row 7: blank

package/examples/gb/main.c

@@ -0,0 +1,49 @@
+/* ── Hello, Game Boy in C — SDCC sm83 port ─────────────────────────
+ * Minimal: cycle the BG palette on every vblank.
+ *
+ * Build: buildSource({ platform: "gb", source: <this file>, language: "c" })
+ *
+ * SDCC 4.4.0 codegen quirks to avoid in `__sfr __at` register-heavy
+ * code:
+ *   - `for (;;) { switch (x) { ... } }`  → crashes the register allocator.
+ *     Workaround: do { ... } while (1).
+ *   - `if (cond) { switch (x) { ... write to __sfr } }` → same crash.
+ *     Workaround: lift the writes into a small lookup-table read
+ *     (`BGP = palettes[idx]`) so there's no branching-into-sfr-write.
+ *
+ * The workaround is what this example uses; it cycles BGP through 4
+ * preset values continuously rather than via a frame-counter `if`.
+ */
+
+__sfr __at 0xFF40 LCDC;
+__sfr __at 0xFF42 SCY;
+__sfr __at 0xFF43 SCX;
+__sfr __at 0xFF44 LY;
+__sfr __at 0xFF47 BGP;
+
+static const unsigned char palettes[4] = { 0xE4, 0xB1, 0x6C, 0x1B };
+
+void main(void) {
+  unsigned char idx;
+  unsigned char vblank_count;
+  idx = 0;
+  vblank_count = 0;
+
+  /* Wait for safe LCD-off. */
+  while (LY < 144) { }
+  LCDC = 0;
+  BGP  = 0xE4;
+  SCY  = 0;
+  SCX  = 0;
+  LCDC = 0x91;                 /* LCD on + BG on, tile data $8000 */
+
+  do {
+    /* Wait one full vblank period. */
+    while (LY <  144) { }
+    while (LY >= 144) { }
+    vblank_count++;
+    /* Cycle palette every 32 frames — leaves the eye time to register. */
+    idx = (vblank_count >> 5) & 0x03;
+    BGP = palettes[idx];
+  } while (1);
+}

package/examples/gb/templates/default.c

@@ -0,0 +1,58 @@
+/* ── default.c — minimal Game Boy (DMG) starter ───────────────────
+ *
+ * Boots the LCD, cycles the DMG background palette through 4 shade
+ * arrangements via BGP ($FF47). Smallest possible "ROM that does
+ * something visible" — use this as the starting point when you're
+ * not yet sure what you want to build.
+ *
+ * GB-specific notes for the agent:
+ *   - DMG uses the BGP/OBP0/OBP1 registers — NOT the CGB BCPS/BCPD
+ *     palette RAM. The GBC tree's default uses BCPS; don't copy that
+ *     into a DMG project or your screen will stay one shade.
+ *   - patchGbHeader writes $0143 = $00 by default on .gb files (DMG-
+ *     only). If your ROM ever shows up white in gambatte, check that
+ *     header byte first — $FF or $80 there forces CGB mode which
+ *     silently ignores BGP/OBP*.
+ *   - lcd_init_default() (from gb_runtime.c) sets BGP = 0xE4 (the
+ *     "normal" arrangement: 11=black 10=dark 01=light 00=white) and
+ *     turns the LCD on. We override BGP each shade tick to demonstrate
+ *     the palette is alive.
+ *
+ * For something more game-shaped, peek at other templates in this dir:
+ *   - hello_sprite — sprite + d-pad movement
+ *   - tile_engine  — multi-room tile map with collision + transitions
+ *   - shmup / platformer / puzzle / sports / racing — genre scaffolds
+ *   - music_demo   — bundled hUGEDriver music driver demo
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+/* Four BGP arrangements; each byte packs 4 color indices, 2 bits each:
+ *   bits 7-6 = color for tile-index 3 (darkest source)
+ *   bits 5-4 = color for tile-index 2
+ *   bits 3-2 = color for tile-index 1
+ *   bits 1-0 = color for tile-index 0 (lightest source)
+ * Color: 0 = white, 1 = light grey, 2 = dark grey, 3 = black. */
+static const uint8_t bgp_shades[4] = {
+  0xE4,   /* normal:       3=black 2=dark  1=light 0=white */
+  0x90,   /* inverted-ish: 3=dark  2=light 1=white 0=white */
+  0x39,   /* shifted:      3=white 2=dark  1=dark  0=light */
+  0x00,   /* all-white (DMG visible: "off"-looking screen) */
+};
+
+void main(void) {
+  uint8_t shade = 0;
+  uint16_t frame = 0;
+
+  lcd_init_default();   /* turns LCD on with BGP=0xE4, BG+OBJ enabled */
+
+  for (;;) {
+    wait_vblank();
+    frame++;
+    if ((frame & 0x1F) == 0) {       /* every 32 frames */
+      shade = (uint8_t)((shade + 1) & 0x03);
+      BGP = bgp_shades[shade];
+    }
+  }
+}

package/examples/gb/templates/hello_sprite.c

@@ -0,0 +1,130 @@
+/* ── hello_sprite.c — GBC starter (works on plain GB too) ──────────
+ *
+ * A complete, tested, boots-from-cold game-loop skeleton:
+ *   - Turns the LCD off safely (handles "LCD already off at boot")
+ *   - Uploads one 16-byte tile to VRAM tile slot 1
+ *   - Writes a 4-color object palette (CGB BCPD path; harmless on DMG)
+ *   - Places sprite 0 in the middle of the screen
+ *   - Reads d-pad each vblank and moves the sprite
+ *   - Uses shadow_oam + oam_dma_flush so writes are clean
+ *
+ * Edit FROM this baseline rather than building from scratch — the
+ * boot order below is the GBC pitfall that costs new ports the most
+ * time (see TROUBLESHOOTING.md "screen is blank").
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+/* A simple 8×8 tile, 2bpp. Each row is 2 bytes; 8 rows × 2 = 16 bytes.
+ * Layout: row N's low-bits come from byte 2N, high-bits from byte 2N+1.
+ * This makes a hollow square (color 3 outline, color 0 fill). */
+static const uint8_t tile_data[16] = {
+  0xFF, 0xFF,   /* row 0: all color 3 */
+  0x81, 0x81,   /* row 1: outline only */
+  0x81, 0x81,
+  0x81, 0x81,
+  0x81, 0x81,
+  0x81, 0x81,
+  0x81, 0x81,
+  0xFF, 0xFF,   /* row 7: all color 3 */
+};
+
+/* CGB object palette 0 in BGR555. Color 0 must be transparent for sprites,
+ * but the value is still written (the hardware ignores it). */
+static const uint16_t obj_palette[4] = {
+  0x7FFF,  /* color 0 — transparent (any value) */
+  0x001F,  /* color 1 — red */
+  0x03E0,  /* color 2 — green */
+  0x7C00,  /* color 3 — blue */
+};
+
+void main(void) {
+  uint8_t pad = 0;
+  uint8_t prev_pad = 0;
+  uint8_t x = 80;       /* hardware X = screen X + 8 */
+  uint8_t y = 80;       /* hardware Y = screen Y + 16 */
+  uint8_t i;
+  uint8_t *vram_dst;
+  const uint8_t *src;
+
+  /* ── 1. LCD off (safe whether it was on or off) ──────────────────
+   * lcd_init_default() checks LCDC.7 and only waits for vblank if the
+   * LCD is on; otherwise LY is frozen at 0 and a blind wait would hang
+   * the entire boot. */
+  lcd_init_default();
+  LCDC = 0;             /* turn off again so we can write VRAM freely */
+
+  /* ── 2. Upload our tile to VRAM slot 1 ($8010) ───────────────────
+   * Slot 0 ($8000) is reserved for "blank" by convention so we don't
+   * accidentally render garbage tiles that point to it. */
+  vram_dst = (uint8_t *)0x8010;
+  src = tile_data;
+  for (i = 0; i < 16; i++) {
+    vram_dst[i] = src[i];
+  }
+
+  /* ── 3. Object palette 0 (CGB path) ──────────────────────────────
+   * OCPS bit 7 = auto-increment after each write; bits 5..3 = palette
+   * index (0..7); bits 2..1 = color index (0..3); bit 0 = MSB select.
+   * Setting OCPS = 0x80 means "palette 0, color 0, low byte, then
+   * auto-advance". 8 byte writes = 4 colors × 2 bytes (BGR555).
+   *
+   * On DMG, OCPS/OCPD don't exist — the writes are silently dropped
+   * and DMG uses OBP0 instead, which lcd_init_default already set. */
+  OCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    OCPD = (uint8_t)(obj_palette[i] & 0xFF);        /* low byte */
+    OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF); /* high byte */
+  }
+
+  /* ── 4. Build initial OAM, then DMA IT TO HARDWARE *BEFORE* LCD-on ──
+   * Clear all 40 slots, write our sprite into slot 0, then flush. The
+   * flush-before-LCD-on is the important bit: it guarantees the very
+   * FIRST visible frame shows your sprite instead of power-on garbage /
+   * an all-zero OAM. (oam_dma_flush is VRAM/OAM-safe while the LCD is
+   * off.) Skipping this is the classic GB/GBC "flat screen, OAM reads
+   * zero on frame 1" trap — especially if you also use the
+   * enable_vblank_irq() HALT path, where the first wait_vblank() sleeps
+   * before you'd otherwise get a chance to flush. */
+  oam_clear();
+  oam_set(0, y, x, /* tile= */ 1, /* attr= */ 0);
+  oam_dma_flush();      /* first OAM live before the screen turns on */
+
+  /* ── 5. Turn the LCD back on with BG + OBJ enabled. ──────────────
+   * LCDC bits: 0x80=LCD on, 0x02=OBJ on, 0x10=tile data at $8000.
+   * (BG remains off — we have no BG map set up.) */
+  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+
+  /* ── 6. APU on — let the player beep ──────────────────────────── */
+  sound_init();
+
+  /* ── 7. Game loop ────────────────────────────────────────────────
+   * Order matters:
+   *   wait for vblank  → safe time to flush OAM
+   *   flush OAM        → push shadow_oam to hardware
+   *   read input       → for next frame's update
+   *   update           → mutate game state
+   * Then loop. */
+  for (;;) {
+    wait_vblank();
+    oam_dma_flush();
+    prev_pad = pad;
+    pad = joypad_read();
+
+    /* D-pad lives in the HIGH nybble of joypad_read's packed byte. */
+    if (pad & PAD_LEFT)  x--;
+    if (pad & PAD_RIGHT) x++;
+    if (pad & PAD_UP)    y--;
+    if (pad & PAD_DOWN)  y++;
+
+    /* Beep on the rising edge of A (one-shot, not held). */
+    if ((pad & PAD_A) && !(prev_pad & PAD_A)) {
+      /* C5-ish note on channel 2 (~261 Hz, ~120ms). */
+      sound_play_tone(2, 1798, 30);
+    }
+
+    /* Re-stage the sprite at its new position. */
+    oam_set(0, y, x, 1, 0);
+  }
+}

package/examples/gb/templates/music_demo.c

@@ -0,0 +1,52 @@
+/* ── music_demo.c — hUGEDriver music player demo (GB) ────────────────
+ *
+ * Plays the bundled sample_song (see song_data.c) on the GB APU.
+ *
+ * The driver shipped here is a compact SDCC-native music player whose
+ * function surface (hUGE_init / hUGE_dosound) matches the upstream
+ * hUGEDriver project (https://github.com/SuperDisk/hUGEDriver, public
+ * domain). The upstream RGBDS asm source is bundled in source-visible
+ * form as `hUGEDriver.upstream.asm` so an agent can later port to it.
+ *
+ * Wiring:
+ *   - sound_init()         power-on the APU (NR52 master enable)
+ *   - hUGE_init(&song)     load the song descriptor
+ *   - hUGE_dosound()       advance one tick; call once per vblank
+ *
+ * What you should hear: a short looping 4-pattern, two-channel tune in
+ * C-major. Melody on CH1 (square 1), bass on CH2 (square 2). Drops
+ * back to the start of the song after ~8 seconds.
+ *
+ * Visual: BGP cycles through 4 shades so you can also SEE the driver
+ * is alive even if you have audio muted in your emulator.
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+#include "hUGEDriver.h"
+
+/* The song descriptor is defined in song_data.c (linked in by the
+ * project template). */
+extern const huge_song_t sample_song;
+
+void main(void) {
+  uint8_t  shade = 0;
+  uint16_t frame = 0;
+
+  lcd_init_default();
+  sound_init();
+
+  hUGE_init(&sample_song);
+
+  for (;;) {
+    wait_vblank();
+    hUGE_dosound();         /* one driver tick per frame */
+    frame++;
+    if ((frame & 0x1F) == 0) {
+      shade = (uint8_t)((shade + 1) & 0x03);
+      /* DMG palette cycle — every 32 frames shift the BG shade.
+       * On GBC this writes through to the legacy DMG-compat palette. */
+      BGP = (uint8_t)(0xE4u ^ (uint8_t)(shade * 0x55u));
+    }
+  }
+}