romdevtools 0.27.0 → 0.29.0

package/src/platforms/gb/lib/c/gb_crt0.s

@@ -86,11 +86,35 @@
         nop
         jp      init
 
-;; ─── Header bytes at $0104-$014F — host pipeline fills these ──────
+;; ─── Header bytes at $0104-$014F — host pipeline fills most of these ─
+;; The logo / title / checksums are patched post-link (rgbfix in the
+;; build pipeline, or patch-header.js when rebuilding outside romdev).
+;; The CART TYPE and RAM SIZE bytes are DECLARED HERE as real bytes so
+;; the build's header fixup can read and preserve them:
+;;
+;;   $0147 = $03  MBC1 + RAM + BATTERY
+;;   $0149 = $02  8 KB external cart RAM at $A000-$BFFF
+;;
+;; This is what makes battery saves (persistent hi-scores) work: the
+;; emulator sizes its SAVE_RAM from these two bytes. The RAM is gated —
+;; games must write $0A to $0000-$1FFF before touching $A000 and write
+;; $00 after (see the SRAM idiom in the shmup example). Games that never
+;; touch $A000 are completely unaffected by the mapper declaration: a
+;; 32 KB image fits in MBC1 banks 0-1 exactly as it does in a ROM-only
+;; cart, and the MBC registers only react to ROM-area WRITES (which
+;; normal code never performs).
+;;
+;; If you rebuild OUTSIDE romdev, keep these bytes: rgbfix flags are
+;; `-m 0x03 -r 0x02` (patch-header.js defaults to ROM-only — pass
+;; cartType/ramSize through patchGbHeader() if you script it).
         .area _HEADERe (ABS)
         .org    0x0104
-        ;; 76 bytes total: Nintendo logo (48) + title (16) + flags+checksums (12)
-        .ds     0x4C
+        .ds     0x43            ; $0104-$0146 logo/title/CGB flag/licensee/SGB (patched in)
+        .org    0x0147
+        .db     0x03            ; $0147 cart type: MBC1+RAM+BATTERY (see above)
+        .db     0x00            ; $0148 ROM size (rgbfix -p recomputes)
+        .db     0x02            ; $0149 RAM size: 8 KB
+        .ds     0x06            ; $014A-$014F dest/licensee/version/checksums (patched in)
 
 ;; ─── init: real boot code, lives in _CODE starting at $0150 ────────
         .area   _CODE

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

@@ -7,10 +7,13 @@
 //
 // 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.
+// whose header checksum at $014D doesn't validate.
+//
+// NOTE: romdev's own build pipeline DOES auto-patch the header now (it
+// runs a bundled rgbfix after every gb/gbc link — see the
+// "rgbfix (auto header fix)" line in build logs), so you only need this
+// script when rebuilding the project OUTSIDE romdev with stock SDCC and
+// no RGBDS installed. It's what keeps the forked project self-contained.
 //
 // The bundled gb_crt0.s reserves $0100-$014F for the header window,
 // so the bytes patched in here land on actual cartridge-header
@@ -148,7 +151,17 @@ if (isCli) {
   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 });
+  // Battery-cart passthrough: the bundled gb_crt0.s emits the cart-type and
+  // RAM-size bytes EXPLICITLY ($0147=$03 MBC1+RAM+BATTERY, $0149=$02 8KB) so
+  // battery hi-score saves work. Preserve a known battery-MBC declaration
+  // instead of stomping it back to ROM-only; unknown/garbage bytes (a crt0
+  // that left the header window as a .ds gap) still get the safe defaults.
+  const BATTERY_TYPES = new Set([0x03, 0x06, 0x0F, 0x10, 0x13, 0x1B, 0x1E]);
+  const declType = rom.length > 0x149 ? rom[0x147] : 0x00;
+  const declRam = rom.length > 0x149 ? rom[0x149] : 0x00;
+  const cartType = BATTERY_TYPES.has(declType) ? declType : 0x00;
+  const ramSize = cartType !== 0x00 && declRam >= 0x01 && declRam <= 0x05 ? declRam : 0x00;
+  patchGbHeader(rom, { cgb, cartType, ramSize });
   writeFileSync(outPath, rom);
-  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""})`);
+  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""}${cartType ? `, cart $${cartType.toString(16)}+RAM` : ""})`);
 }

package/src/platforms/gba/MENTAL_MODEL.md

@@ -129,11 +129,11 @@ Sound FIFO states. See "MCP debug & inspection tooling" below for the rest of
 the live-debug loop (sprites / palette / background / cpu / breakpoint + the
 memory regions and disasm pipeline).
 
-**For scaffold-level sfx**, the libtonc runtime ships a minimal
+**For starter-level sfx**, the libtonc runtime ships a minimal
 `gba_sfx.h` / `gba_sfx.c` pair (3 functions: `sfx_init`, `sfx_tone`,
 `sfx_noise`) that wraps the DMG-compatible APU directly. Same shape
-as the NES/GB scaffold sound API, so cross-platform game ports feel
-the same. All 5 GBA genre scaffolds (shmup/platformer/puzzle/sports/
+as the NES/GB example sound API, so cross-platform game ports feel
+the same. All 5 GBA genre example games (shmup/platformer/puzzle/sports/
 racing) use it.
 
 ## MCP debug & inspection tooling
@@ -210,7 +210,7 @@ the first call** (`irq_init(NULL)` + `irq_add(II_VBLANK, NULL)` with
 libtonc — `irqInit(NULL)` + `irqEnable(IRQ_VBLANK)` with libgba).
 Without this, the BIOS halts the CPU forever waiting for an IRQ that
 never fires. ROM appears to compile + load but freezes on frame 1 —
-single most common GBA gotcha. Every bundled scaffold does it; copy
+single most common GBA gotcha. Every bundled example does it; copy
 the pattern.
 
 ## Cart header format

package/src/platforms/gba/TROUBLESHOOTING.md

@@ -36,7 +36,7 @@ installs the master handler + `irq_add(II_VBLANK, NULL)` registers a
 no-op for vblank (just so the IRQ fires + the BIOS counter increments).
 With libgba, `irqInit()` does both steps.
 
-Every bundled R28 scaffold (`tonc_hello`, `tonc_hello_sprite`, `shmup`,
+Every bundled R28 example (`tonc_hello`, `tonc_hello_sprite`, `shmup`,
 `platformer`, `puzzle`, `sports`, `racing`) sets this up — copy the
 pattern.
 
@@ -132,10 +132,10 @@ install promise but everything else still works.
 A deferred enhancement is to port libsysbase into our build so
 iprintf "just works."
 
-## Adding sound to a scaffold
+## Adding sound to your game
 
 Both runtimes bundle `gba_sfx.h` + `gba_sfx.c` next to your `main.c`
-(courtesy of `scaffold({op:'project'})`). The shape:
+(courtesy of `examples({op:'fork'})`). The shape:
 
 ```c
 #include "gba_sfx.h"

package/src/platforms/gba/lib/c/gba_sfx.c

@@ -76,6 +76,46 @@ void sfx_noise(u8 length_frames) {
     REG_SND4FREQ = 0xC033;
 }
 
+/* ── background music: 16-step melody loop on channel 2 ─────────────
+ * Mirrors the Genesis/NES example pattern: games get continuous music
+ * for free by calling sfx_music_tick() once per frame. The melody is a
+ * gentle A-minor arpeggio at reduced envelope volume (0xA of 0xF) so
+ * one-shot SFX on channel 1 / noise on 4 read clearly over it.
+ * Note values are GBA 11-bit frequency codes: Hz = 131072/(2048-code),
+ * code = 2048 - 131072/Hz. 0 = rest. */
+static const u16 music_code[16] = {
+    1452, 1548, 1651, 1750,   /* A3 C4 E4 A4 */
+    1714, 1651, 1548, 0,      /* G4 E4 C4  - */
+    1452, 1546, 1620, 1714,   /* A3 C4 D4 G4 */
+    1651, 1548, 1452, 0,      /* E4 C4 A3  - */
+};
+static u8 music_enabled = 1;
+static u8 music_step, music_timer;
+
+void sfx_music(u8 on) {
+    music_enabled = on;
+    music_step = 0;
+    music_timer = 0;
+    if (!on) REG_SND2CNT = 0x0000;   /* zero envelope = silence now */
+}
+
+void sfx_music_tick(void) {
+    if (!music_enabled) return;
+    if (music_timer == 0) {
+        u16 code = music_code[music_step & 15];
+        if (code) {
+            /* vol 0xA, 50% duty, length 40/64 steps (~156ms) — the
+             * length-enable auto-silences before the next note so
+             * rests actually rest. */
+            REG_SND2CNT  = (u16)(0xA080 | (64 - 40));
+            REG_SND2FREQ = (u16)(0xC000 | (code & 0x07FF));
+        }
+        music_step++;
+    }
+    music_timer++;
+    if (music_timer >= 10) music_timer = 0;   /* 6 notes/sec at 60fps */
+}
+
 void sfx_off(void) {
     REG_SNDSTAT = 0x0000;
 }

package/src/platforms/gba/lib/c/gba_sfx.h

@@ -42,6 +42,16 @@ void sfx_tone(u8 channel, u16 freq_period, u8 length_frames);
  *   length_frames: 1..63 (same scaling as sfx_tone). */
 void sfx_noise(u8 length_frames);
 
+/* ── background music ────────────────────────────────────────────────
+ * A 16-step square-wave melody loop on channel 2 (so keep one-shot SFX
+ * on channel 1 + noise on 4 and nothing fights for the channel).
+ * Call sfx_music_tick() once per frame from your main loop — it steps
+ * the melody. ON by default after sfx_init(); sfx_music(0) silences it.
+ * "No sound" feedback in playtests is nearly always a missing per-frame
+ * tick, not broken registers. */
+void sfx_music(u8 on);
+void sfx_music_tick(void);
+
 /* Power down the APU. */
 void sfx_off(void);
 

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -31,6 +31,18 @@ the same wall.
    cast through `volatile uint8_t *`. See `lib/c/SDCC_GOTCHAS.md`
    § "Writes to VRAM".
 
+3b. **OAM DMA goes FIRST after `wait_vblank()` — before any staging work.**
+   The vblank window is ~10 scanlines (~1140 cycles) and SDCC call overhead
+   is brutal: even a few dozen `oam_set()` CALLS before the flush push the
+   DMA out of vblank into active display, where it tears the sprites on one
+   FIXED scanline every frame (the "horizontal line a third of the way down"
+   glitch). The robust frame shape is: stage OAM/BG writes into RAM any time
+   during the frame, then `wait_vblank(); oam_dma_flush();` as the very first
+   thing, then a small bounded batch of BG map writes. One frame of sprite
+   latency is imperceptible. Also: statics belong at `dataLoc 0xC200` or
+   above (the project recipe sets this) so they can't collide with
+   `shadow_oam` at $C100.
+
 4. **OAM DMA must run from HRAM.** During the ~160 µs OAM DMA window
    the CPU can ONLY fetch from HRAM ($FF80-$FFFE). The bundled
    `oam_dma_copy()` installs a 9-byte stub at $FF80 and CALLs it; the
@@ -102,7 +114,7 @@ The CGB boot ROM checks header byte **`$0143`**:
 - `$80` → CGB-enhanced mode (color works, DMG-compat fallback)
 - `$C0` → CGB-only mode (refuses to boot on a DMG)
 
-**Every bundled GBC scaffold is built with `$0143 = $80`** — `build({output:'rom'})`
+**Every bundled GBC example game is built with `$0143 = $80`** — `build({output:'rom'})`
 / `build({output:'run'})` set this automatically at build time when `platform:"gbc"`,
 so a freshly built `.gbc` boots in color with no extra step. (Build it as
 `platform:"gb"` instead and the flag stays `$00` → DMG green-shade mode,
@@ -185,12 +197,12 @@ inversion: `{a}`→A, `{b}`→B, `{start}`/`{select}`, plus the d-pad (spatial
 east→A, west→B). So `input({op:'set', a: true})` presses GBC A as expected — unlike
 the genesis_plus_gx platforms (Genesis/SMS/GG), there's no surprise here.
 
-## Scaffolds
+## Example games
 
-All GB scaffolds (`shmup`, `platformer`, `puzzle`, `sports`, `racing`,
+All GB example games (`shmup`, `platformer`, `puzzle`, `sports`, `racing`,
 `hello_sprite`, `tile_engine`) compile identically as GBC ROMs — the
 bundled GB runtime is already CGB-aware (writes OCPD/OCPS for color).
-The genre scaffolds inherit from GB via `TEMPLATES.gbc = TEMPLATES.gb`;
+The genre examples inherit from GB via `TEMPLATES.gbc = TEMPLATES.gb`;
 the only differences at build time are:
 
 - ROM extension: `.gbc` (vs `.gb`)

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -120,6 +120,27 @@ in DMG mode. To switch a DMG ROM to CGB:
 2. Run `romPatch({op:'gbHeader', path:"out.gbc"})` — also fixes the global
    checksum that the boot ROM checks
 
+## "BG map updates randomly don't stick" / a tile updates one frame late forever
+
+The core (like real hardware mid-frame) DROPS writes to VRAM ($8000-$9FFF)
+that land outside vblank while the LCD is on — silently. A game loop that
+pokes the BG map "whenever the state changes" will have SOME of those pokes
+land mid-frame and vanish: stale cells, a piece that visually lags the
+logical grid, glitches that move around as code timing shifts.
+
+The robust pattern (used by the bundled puzzle example games):
+
+1. **COLLECT** — during the frame, don't touch VRAM. Append (addr, tile)
+   pairs to a small RAM queue whenever game state changes a cell.
+2. **FLUSH** — immediately after `wait_vblank()` (right after the OAM DMA),
+   drain the queue with pure writes. No scanning, no logic — vblank is only
+   ~1140 cycles, so the flush must be writes only and bounded.
+3. **Scrub** — repaint one or two rows per frame round-robin as insurance,
+   so any cell that ever got dropped self-heals within a second.
+
+If you must write outside that structure, turn the LCD off first (only
+acceptable during init/load screens — mid-game it flashes white).
+
 ## "Sound is the same as DMG"
 
 That's correct — CGB has the **identical** 4-channel APU as DMG. The
@@ -128,7 +149,7 @@ sound channels or extra waveforms.
 
 ## "ROM size > 32 KB needed"
 
-The bundled GBC scaffolds all fit in 32 KB (single bank, no MBC).
+The bundled GBC example games all fit in 32 KB (single bank, no MBC).
 For larger projects use an MBC (memory bank controller). MBC1 / MBC3
 work in gambatte; set the `$0147` cartridge type byte accordingly.
 romPatch({op:'gbHeader'}) doesn't set this — you write it from your asm/C.
@@ -138,11 +159,11 @@ romPatch({op:'gbHeader'}) doesn't set this — you write it from your asm/C.
 Default GBC speed is the same as DMG (~4 MHz Z80). Double-speed mode
 via KEY1 ($FF4D) doubles CPU but halves audio sample rate + breaks
 cycle-counted code. Most homebrew leaves it off; if you need the
-extra clocks, change the GB scaffold pattern to:
+extra clocks, change the GB example pattern to:
 
 ```c
 KEY1 = 1;            /* request speed switch */
 __asm__("stop");     /* arm the switch (compiler-specific syntax) */
 ```
 
-Not bundled in any scaffold — use only if you've measured a need.
+Not bundled in any example — use only if you've measured a need.

package/src/platforms/gbc/UPSTREAM_SOURCES.md

@@ -3,7 +3,7 @@
 GBC shares its toolchain (SDCC sm83) + emulator (gambatte) + most
 of the runtime (`gb_runtime.c`, `gb_crt0.s`, `patch-header.js`,
 hUGEDriver) with DMG. The CGB tree (`src/platforms/gbc/`) holds
-the color-aware scaffolds; everything below is in lockstep with
+the color-aware example games; everything below is in lockstep with
 the GB tree.
 
 CGB-specific:

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

@@ -1,8 +1,8 @@
 # GB / GBC C runtime + headers
 
 These are the source files that back the GB/GBC C templates. They're
-**not** auto-injected at build time — `scaffold({op:'project', platform:"gb"|"gbc",
-template:"..."})` copies them into your project directory so the
+**not** auto-injected at build time — `examples({op:'fork', example:"gb/<name>" or
+"gbc/<name>", name, path})` copies them into your project directory so the
 project is self-describing. Build calls then point at your project's
 copy of these files via `sourcesPaths` / `includePaths` / `crt0Path`.
 
@@ -32,7 +32,7 @@ didn't produce, or to override a field:
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into
-  every GB project by `scaffold({op:'project'})`. Same logic, no MCP needed.
+  every GB project by `examples({op:'fork'})`. Same logic, no MCP needed.
 - `rgbfix -v -p 0 out.gb` — what the build pipeline runs under the hood;
   RGBDS asm projects can invoke it directly.
 
@@ -46,17 +46,16 @@ didn't produce, or to override a field:
   hardware, OAM DMA timing, joypad layout. Read this before your first
   GB/GBC project.
 
-## Project templates
+## Forking an example
 
-Bootstrap a working game-loop skeleton with `scaffold({op:'project'})`:
+Bootstrap a working game-loop skeleton by forking an example with `examples({op:'fork'})`:
 
 ```js
-scaffold({
-  op:       'project',
-  platform: "gbc",
-  template: "tile_engine",   // or "hello_sprite", or "default"
-  name:     "mygame",
-  path:     "/abs/path",
+examples({
+  op:      'fork',
+  example: "gbc/tile_engine",   // or "gbc/hello_sprite", or "gbc/default"
+  name:    "mygame",
+  path:    "/abs/path",
 })
 ```
 

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

@@ -0,0 +1,43 @@
+/* AUTO-GENERATED by gen_font.py — 5x7 font, GB 2bpp, ink=value 3. */
+#ifndef FONT_H
+#define FONT_H
+#define FONT_GLYPHS 36
+static const uint8_t font_data[576] = {
+    0x38, 0x38, 0x44, 0x44, 0x4C, 0x4C, 0x54, 0x54, 0x64, 0x64, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 0 */
+    0x10, 0x10, 0x30, 0x30, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x38, 0x38, 0x00, 0x00,  /* 1 */
+    0x38, 0x38, 0x44, 0x44, 0x04, 0x04, 0x08, 0x08, 0x10, 0x10, 0x20, 0x20, 0x7C, 0x7C, 0x00, 0x00,  /* 2 */
+    0x7C, 0x7C, 0x08, 0x08, 0x10, 0x10, 0x08, 0x08, 0x04, 0x04, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 3 */
+    0x08, 0x08, 0x18, 0x18, 0x28, 0x28, 0x48, 0x48, 0x7C, 0x7C, 0x08, 0x08, 0x08, 0x08, 0x00, 0x00,  /* 4 */
+    0x7C, 0x7C, 0x40, 0x40, 0x78, 0x78, 0x04, 0x04, 0x04, 0x04, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 5 */
+    0x18, 0x18, 0x20, 0x20, 0x40, 0x40, 0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 6 */
+    0x7C, 0x7C, 0x04, 0x04, 0x08, 0x08, 0x10, 0x10, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x00, 0x00,  /* 7 */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* 8 */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x3C, 0x3C, 0x04, 0x04, 0x08, 0x08, 0x30, 0x30, 0x00, 0x00,  /* 9 */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x7C, 0x7C, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* A */
+    0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x00, 0x00,  /* B */
+    0x38, 0x38, 0x44, 0x44, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* C */
+    0x70, 0x70, 0x48, 0x48, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x48, 0x48, 0x70, 0x70, 0x00, 0x00,  /* D */
+    0x7C, 0x7C, 0x40, 0x40, 0x40, 0x40, 0x78, 0x78, 0x40, 0x40, 0x40, 0x40, 0x7C, 0x7C, 0x00, 0x00,  /* E */
+    0x7C, 0x7C, 0x40, 0x40, 0x40, 0x40, 0x78, 0x78, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x00, 0x00,  /* F */
+    0x38, 0x38, 0x44, 0x44, 0x40, 0x40, 0x5C, 0x5C, 0x44, 0x44, 0x44, 0x44, 0x3C, 0x3C, 0x00, 0x00,  /* G */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x7C, 0x7C, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* H */
+    0x38, 0x38, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x38, 0x38, 0x00, 0x00,  /* I */
+    0x1C, 0x1C, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x48, 0x48, 0x30, 0x30, 0x00, 0x00,  /* J */
+    0x44, 0x44, 0x48, 0x48, 0x50, 0x50, 0x60, 0x60, 0x50, 0x50, 0x48, 0x48, 0x44, 0x44, 0x00, 0x00,  /* K */
+    0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x7C, 0x7C, 0x00, 0x00,  /* L */
+    0x44, 0x44, 0x6C, 0x6C, 0x54, 0x54, 0x54, 0x54, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* M */
+    0x44, 0x44, 0x44, 0x44, 0x64, 0x64, 0x54, 0x54, 0x4C, 0x4C, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* N */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* O */
+    0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x00, 0x00,  /* P */
+    0x38, 0x38, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x54, 0x54, 0x48, 0x48, 0x34, 0x34, 0x00, 0x00,  /* Q */
+    0x78, 0x78, 0x44, 0x44, 0x44, 0x44, 0x78, 0x78, 0x50, 0x50, 0x48, 0x48, 0x44, 0x44, 0x00, 0x00,  /* R */
+    0x3C, 0x3C, 0x40, 0x40, 0x40, 0x40, 0x38, 0x38, 0x04, 0x04, 0x04, 0x04, 0x78, 0x78, 0x00, 0x00,  /* S */
+    0x7C, 0x7C, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x00, 0x00,  /* T */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x38, 0x38, 0x00, 0x00,  /* U */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x28, 0x28, 0x10, 0x10, 0x00, 0x00,  /* V */
+    0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x54, 0x54, 0x54, 0x54, 0x6C, 0x6C, 0x44, 0x44, 0x00, 0x00,  /* W */
+    0x44, 0x44, 0x44, 0x44, 0x28, 0x28, 0x10, 0x10, 0x28, 0x28, 0x44, 0x44, 0x44, 0x44, 0x00, 0x00,  /* X */
+    0x44, 0x44, 0x44, 0x44, 0x28, 0x28, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x00, 0x00,  /* Y */
+    0x7C, 0x7C, 0x04, 0x04, 0x08, 0x08, 0x10, 0x10, 0x20, 0x20, 0x40, 0x40, 0x7C, 0x7C, 0x00, 0x00,  /* Z */
+};
+#endif

package/src/platforms/gbc/lib/c/gb_crt0.s

@@ -86,11 +86,34 @@
         nop
         jp      init
 
-;; ─── Header bytes at $0104-$014F — host pipeline fills these ──────
+;; ─── Header bytes at $0104-$014F — host pipeline fills most of these ──
         .area _HEADERe (ABS)
         .org    0x0104
-        ;; 76 bytes total: Nintendo logo (48) + title (16) + flags+checksums (12)
-        .ds     0x4C
+        ;; Nintendo logo ($0104-$0133, 48 bytes) + title/manufacturer/CGB
+        ;; flag ($0134-$0143) + licensee/SGB ($0144-$0146): left as a gap —
+        ;; the post-link header fix (bundled rgbfix, or patch-header.js when
+        ;; rebuilding outside romdev) writes the canonical logo, the CGB
+        ;; flag, and both checksums.
+        .ds     0x43
+        ;; Cartridge TYPE + RAM size ($0147-$0149) are emitted EXPLICITLY so
+        ;; the post-link fix can preserve them (it reads these bytes and
+        ;; passes them through; unknown/garbage values fall back to ROM-only).
+        ;; This is the GB equivalent of the NES crt0's iNES BATTERY bit:
+        ;; declaring the cart in the boot file makes battery saves part of
+        ;; the project source, not a build flag someone has to remember.
+        ;;
+        ;;   $0147 = $03  MBC1 + RAM + BATTERY  → the core exposes the 8KB
+        ;;                at $A000-$BFFF as persistent SAVE_RAM (.srm).
+        ;;                Writes only stick after the $0A enable sequence —
+        ;;                see the SRAM HARDWARE IDIOM in the puzzle example.
+        ;;   $0148 = $00  32 KB ROM (2 banks — no banking needed)
+        ;;   $0149 = $02  8 KB cart RAM (one bank at $A000)
+        .org    0x0147
+        .db     0x03            ; cart type: MBC1+RAM+BATTERY
+        .db     0x00            ; ROM size: 32 KB
+        .db     0x02            ; RAM size: 8 KB
+        ;; $014A-$014F (destination/licensee/version/checksums): host fills.
+        .ds     0x06
 
 ;; ─── init: real boot code, lives in _CODE starting at $0150 ────────
         .area   _CODE

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

@@ -7,10 +7,13 @@
 //
 // 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.
+// whose header checksum at $014D doesn't validate.
+//
+// NOTE: romdev's own build pipeline DOES auto-patch the header now (it
+// runs a bundled rgbfix after every gb/gbc link — see the
+// "rgbfix (auto header fix)" line in build logs), so you only need this
+// script when rebuilding the project OUTSIDE romdev with stock SDCC and
+// no RGBDS installed. It's what keeps the forked project self-contained.
 //
 // The bundled gb_crt0.s reserves $0100-$014F for the header window,
 // so the bytes patched in here land on actual cartridge-header
@@ -148,7 +151,17 @@ if (isCli) {
   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 });
+  // Battery-cart passthrough: the bundled gb_crt0.s emits the cart-type and
+  // RAM-size bytes EXPLICITLY ($0147=$03 MBC1+RAM+BATTERY, $0149=$02 8KB) so
+  // battery hi-score saves work. Preserve a known battery-MBC declaration
+  // instead of stomping it back to ROM-only; unknown/garbage bytes (a crt0
+  // that left the header window as a .ds gap) still get the safe defaults.
+  const BATTERY_TYPES = new Set([0x03, 0x06, 0x0F, 0x10, 0x13, 0x1B, 0x1E]);
+  const declType = rom.length > 0x149 ? rom[0x147] : 0x00;
+  const declRam = rom.length > 0x149 ? rom[0x149] : 0x00;
+  const cartType = BATTERY_TYPES.has(declType) ? declType : 0x00;
+  const ramSize = cartType !== 0x00 && declRam >= 0x01 && declRam <= 0x05 ? declRam : 0x00;
+  patchGbHeader(rom, { cgb, cartType, ramSize });
   writeFileSync(outPath, rom);
-  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""})`);
+  console.log(`patched ${inPath}${outPath !== inPath ? ` → ${outPath}` : ""} (${rom.length} bytes${cgb ? ", CGB" : ""}${cartType ? `, cart $${cartType.toString(16)}+RAM` : ""})`);
 }

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -50,9 +50,13 @@ memory({op:'read', region:'system_ram', offset: sym.ramOffset, length:2})
 - **`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.
+- **WRAM (`system_ram`) is normalized to CPU byte order** — offset X is the
+  byte the 68k sees at $FF0000+X, words read big-endian as expected, and
+  offsets line up with disassembly addresses and cheat-DB maps. (gpgx stores
+  work RAM host-LE word-swapped internally; the host un-swaps it. Before
+  0.28.0 the raw swapped layout leaked through — value-search/diff loops were
+  self-consistent, but any offset cross-referenced against a `move.b $FFxxxx`
+  in a disassembly was off-by-XOR-1.)
 - **PC → which function?** `symbols({op:'addr', pc, symbolsText: b.mapText})` maps
   a live `cpu({op:'read'}).pc` to the enclosing C function.
 
@@ -174,7 +178,7 @@ software mistake, not a hardware limit:
 > burst or a per-frame DMA), you overrun vblank, drop frames, and the
 > scroll judders. **Paint the planes ONCE at setup; the loop only nudges
 > scroll registers and re-stages sprites.** Use the
-> `template:"two_plane_parallax"` scaffold as the known-good shape.
+> `two_plane_parallax` example as the known-good shape.
 
 ### Hardware scroll, the whole loop
 
@@ -237,7 +241,7 @@ if (newTileCol != lastTileCol) {
 ```
 
 That's ~28 tile writes per 8 px of travel, not a 1792-cell plane redraw.
-The `template:"platformer"` scaffold scrolls within one plane (no
+The `platformer` example scrolls within one plane (no
 streaming); add the column-stream above to go wider. (Real Sonic also
 splits the screen with H-blank raster effects for independent strips —
 that's an IRQ/raster topic, see the `asm` template.)
@@ -427,10 +431,40 @@ Video is deeply readable; the FM audio chip is only partially exposed:
   `getPsgState` decodes the SN76489 (3 tone + 1 noise channels).
 - **Memory regions:** `memory({op:'read'})` exposes CRAM, VSRAM, VDP_REGS,
   Z80_RAM (the sound CPU's RAM), M68K work RAM, YM2612, PSG, and VRAM.
-  Remember the gpgx byte-swap quirk: VRAM and WRAM read host-LE
+  Remember the gpgx byte-swap quirk for VRAM: it reads host-LE
   word-byte-swapped (a 16-bit value's two bytes are swapped at the offset)
-  — account for it or read single bytes (see "Reading your C globals
-  headlessly").
+  — use tiles({op:'pixels'}) to decode in render order. M68K work RAM
+  (`system_ram`) is NOT affected: it's normalized to CPU byte order (see
+  "Reading your C globals headlessly").
+
+## Break-instant truth: registersAtHit + pure calls (0.28.0)
+
+gpgx schedules its CPUs per scanline, so a `breakpoint` hit mid-frame used to
+leave the LIVE register file hundreds of instructions past the hit by the time
+you could read it — chasing pointer registers read that way burned a real
+session for ~2h. Fixed two ways:
+
+- **`registersAtHit`** — `breakpoint({on:'pc'|'write'|'read'})` hits now carry
+  the FULL register file (d0-d7/a0-a7/pc/sr/sp) frozen by the core at the hit
+  instant. Use it, never a follow-up `cpu({op:'read'})`. The reported `pc` for
+  write/read hits is the EXECUTING instruction's first byte (pre-0.28.0 it was
+  the post-prefetch PC — one instruction late). On a pc-break the 68k also
+  stays FROZEN for the rest of the frame, so even live reads agree.
+- **`cpu({op:'call', pure:true})`** — steps ONLY the 68k: no VDP lines, no
+  Z80, no interrupts raised. Without it, a driven routine that spans frames
+  runs the game's own VBlank logic concurrently — which can stomp the output
+  buffer you're capturing (a real session diffed a CORRECT codec
+  reimplementation against that poisoned "ground truth" for hours). Prefer
+  `pure:true` for every decompressor/codec call; non-pure results carry a ⚠
+  caveat when frame logic ran. (SMS/GG get the same via the shared core; the
+  OTHER platforms get the same guarantee via interrupt blocking —
+  `pureMode:'irq-blocked'` — so the technique transfers everywhere.)
+- **`watch({on:'copy'})`** — the CPU-port complement of `watch({on:'dma'})`:
+  logs every data-port write landing in a VRAM window with the executing
+  instruction's PC. Use `dma` when the upload is DMA'd (most Genesis
+  graphics), `copy` when the game pokes the data port directly (the
+  "video_ram writes don't reach the renderer" class of confusion — `copy`
+  shows you who's writing and where).
 
 ## ROM layout
 
@@ -447,7 +481,7 @@ 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
+`examples({op:'fork'})` (any Genesis example) 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/`:

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -239,8 +239,8 @@ Genesis scrolls in HARDWARE — moving the world is two register writes
 plane every frame (a `VDP_fillTileMapRect` / `VDP_loadTileMap` / big
 `DMA_*` each frame), you overrun the vblank DMA budget and drop frames →
 judder. Fix: paint the planes ONCE at setup; the loop only nudges scroll
-registers + re-stages sprites. The `template:"two_plane_parallax"`
-scaffold is the known-good shape.
+registers + re-stages sprites. The `two_plane_parallax`
+example is the known-good shape.
 
 Diagnose it without guessing (no core rebuild):
 

package/src/platforms/genesis/lib/c/genesis_sfx.c

@@ -32,6 +32,42 @@ void sfx_noise(u8 length_frames) {
     sfx_remaining[3] = length_frames;
 }
 
+/* ── background music: a 16-step melody loop on PSG channel 2 ───────
+ * Ticked from sfx_update(), so every scaffold that already calls
+ * sfx_init() + sfx_update() gets continuous music for free ("no sound"
+ * was the #1 playtest complaint — a lone 6-frame blip on a rare event
+ * reads as silence). sfx_music(0) turns it off. SFX own channels 0-1 +
+ * noise, so effects always cut through. */
+static const u16 music_hz[16] = {
+    262, 330, 392, 523, 392, 330, 262, 0,     /* C4 E4 G4 C5 G4 E4 C4 -  */
+    220, 262, 330, 440, 330, 262, 220, 0,     /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static u8 music_enabled = 1;
+static u8 music_step, music_timer;
+
+void sfx_music(u8 on) {
+    music_enabled = on;
+    music_step = 0;
+    music_timer = 0;
+    if (!on) PSG_setEnvelope(2, PSG_ENVELOPE_MIN);
+}
+
+static void music_tick(void) {
+    if (!music_enabled) return;
+    if (music_timer == 0) {
+        u16 hz = music_hz[music_step & 15];
+        if (hz) {
+            PSG_setFrequency(2, hz);
+            PSG_setEnvelope(2, 5);            /* moderate, under the SFX */
+        } else {
+            PSG_setEnvelope(2, PSG_ENVELOPE_MIN);
+        }
+        music_step++;
+    }
+    music_timer++;
+    if (music_timer >= 9) music_timer = 0;    /* ~6.6 notes/sec */
+}
+
 void sfx_update(void) {
     for (u8 i = 0; i < 4; i++) {
         if (sfx_remaining[i] > 0) {
@@ -41,6 +77,7 @@ void sfx_update(void) {
             }
         }
     }
+    music_tick();
 }
 
 void sfx_off(void) {

package/src/platforms/genesis/lib/c/genesis_sfx.h

@@ -42,6 +42,7 @@ void sfx_noise(u8 length_frames);
  * decrement the auto-silence countdown. Without this, notes never
  * stop ringing. */
 void sfx_update(void);
+void sfx_music(u8 on);   /* background melody loop on PSG ch2 — ON by default; 0 = off */
 
 /* Power down all PSG channels immediately. */
 void sfx_off(void);