romdevtools 0.27.0 → 0.29.0

package/src/platforms/nes/lib/c/nes_runtime.c

@@ -59,44 +59,60 @@ static uint8_t oam_index = 0;
 static void oam_hide_unused(void);  /* fwd decl — used by ppu_wait_nmi (NES-1) */
 
 /* ── VRAM write queue ─────────────────────────────────────────────
- * Each entry is { hi, lo, byte }. NMI walks the queue, writes
- * PPUADDR(hi); PPUADDR(lo); PPUDATA(byte) for each, then clears the
- * length. Length is capped at QUEUE_MAX entries; if game code overflows
- * it, we busy-wait for an NMI to flush and continue. */
-#define QUEUE_MAX 24
-static struct {
-  uint8_t addr_hi;
-  uint8_t addr_lo;
-  uint8_t value;
-} vram_queue[QUEUE_MAX];
-static uint8_t vram_queue_len = 0;
-
-/* Called from the NMI handler in chr-ram.crt0.s. PPU is unlocked
- * (we're in vblank), so writes to $2006/$2007 are safe. */
-void __fastcall__ vram_queue_flush(void) {
-  uint8_t i;
-  if (vram_queue_len == 0) return;
-  /* Reset the address latch by reading $2002 — even though the NMI
-   * trampoline already did this when it ran the scroll-reset
-   * sequence, that came AFTER we ran. Cheap insurance. */
-  (void)PPUSTATUS;
-  for (i = 0; i < vram_queue_len; i++) {
-    PPUADDR = vram_queue[i].addr_hi;
-    PPUADDR = vram_queue[i].addr_lo;
-    PPUDATA = vram_queue[i].value;
-  }
-  vram_queue_len = 0;
-}
-
-/* Queue one byte. If full, wait for NMI to drain then enqueue. */
+ * A ring buffer of { hi, lo, byte } entries. The NMI drains it with
+ * PPUADDR(hi); PPUADDR(lo); PPUDATA(byte) per entry — but only up to
+ * FLUSH_BUDGET entries per vblank (see the idiom note below). Game code
+ * that outruns the drain just blocks in vram_queue_push until a slot
+ * frees up; a big batch appears over 2-3 frames, invisible to a human.
+ *
+ * ── HARDWARE IDIOM (load-bearing) — the VBLANK BUDGET ──
+ * Vblank is ~2273 CPU cycles and OAM DMA already spends 513 of them.
+ * A flush that keeps writing past the end of vblank writes PPUDATA
+ * while RENDERING IS ACTIVE — the PPU's internal address register is
+ * busy fetching tiles, so those writes land at corrupted addresses.
+ * Symptom: a long batch of queued tiles where MOST land correctly but
+ * the tail is shifted or missing, identically every run. The budget
+ * caps the per-vblank drain so the flush always finishes inside vblank.
+ * The drain itself lives in the crt0's NMI handler IN ASSEMBLY (~40
+ * cycles/entry); compiled C spends 200+ cycles per entry, which blows
+ * the budget even for small batches — measured, not theoretical.
+ *
+ * ── HARDWARE IDIOM (load-bearing) — the NMI/main-thread race ──
+ * The NMI fires asynchronously; if it drained the queue WHILE
+ * vram_queue_push was mid-update, the in-flight entry would be lost
+ * and a stale slot replayed. The lock byte makes the flush skip any
+ * vblank that catches a push in progress (the queue drains a frame
+ * later). Symptom without it: HUD text with characters missing or
+ * shifted, coming and going with timing. */
+#define QUEUE_MAX     32            /* power of two — indices wrap via & */
+#define QUEUE_MASK    (QUEUE_MAX - 1)
+#define FLUSH_BUDGET  16            /* keep in sync with the crt0 asm */
+/* NOT static — the crt0's NMI drains the ring in assembly (see the
+ * vblank-budget idiom above; symbol names are part of the crt0 contract). */
+uint8_t vram_q_hi[QUEUE_MAX];
+uint8_t vram_q_lo[QUEUE_MAX];
+uint8_t vram_q_val[QUEUE_MAX];
+uint8_t vram_queue_head = 0;
+volatile uint8_t vram_queue_len = 0;
+volatile uint8_t vram_queue_lock = 0;
+
+/* Queue one byte. If full, wait for the NMI to drain a slot (lock
+ * RELEASED while waiting — holding it would deadlock), then enqueue
+ * under the lock. */
 static void vram_queue_push(uint16_t ppu_addr, uint8_t v) {
-  while (vram_queue_len >= QUEUE_MAX) {
+  uint8_t slot;
+  for (;;) {
+    vram_queue_lock = 1;
+    if (vram_queue_len < QUEUE_MAX) break;
+    vram_queue_lock = 0;
     ppu_wait_nmi();
   }
-  vram_queue[vram_queue_len].addr_hi = (uint8_t)(ppu_addr >> 8);
-  vram_queue[vram_queue_len].addr_lo = (uint8_t)(ppu_addr & 0xFF);
-  vram_queue[vram_queue_len].value = v;
+  slot = (uint8_t)((vram_queue_head + vram_queue_len) & QUEUE_MASK);
+  vram_q_hi[slot] = (uint8_t)(ppu_addr >> 8);
+  vram_q_lo[slot] = (uint8_t)(ppu_addr & 0xFF);
+  vram_q_val[slot] = v;
   ++vram_queue_len;
+  vram_queue_lock = 0;
 }
 
 /* ── PPU control ──────────────────────────────────────────────── */
@@ -330,6 +346,47 @@ void sound_init(void) {
   APUFRAMECTR = 0x40;      /* 4-step frame counter, disable frame IRQ */
 }
 
+/* ── background music: 16-step melody on the TRIANGLE channel ───────
+ * The pulse channels + noise stay free for sound_play_tone/noise SFX.
+ * Call sound_music_tick() once per frame (after ppu_wait_nmi); the
+ * scaffolds wire it in. sound_music(0) silences it. ("No sound" was
+ * the dominant NES playtest complaint — a rare 6-frame blip isn't
+ * enough; continuous triangle gives every scaffold a musical floor.)
+ * NTSC triangle period for note f ≈ 1789773/(32*f) - 1. */
+static const uint16_t music_period_tbl[16] = {
+    213, 168, 141, 106, 141, 168, 213, 0,   /* C4 E4 G4 C5 G4 E4 C4 -  */
+    253, 213, 168, 126, 168, 213, 253, 0,   /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static uint8_t music_enabled = 1;
+static uint8_t music_step;
+static uint8_t music_timer;
+
+void sound_music(uint8_t on) {
+  music_enabled = on;
+  music_step = 0;
+  music_timer = 0;
+  if (!on) { TRI_LINEAR = 0x00; TRI_HI = 0x08; }   /* reload 0 linear → silent */
+}
+
+void sound_music_tick(void) {
+  uint16_t p;
+  if (!music_enabled) return;
+  if (music_timer == 0) {
+    p = music_period_tbl[music_step & 15];
+    if (p) {
+      TRI_LINEAR = 0xFF;                       /* halt flag + max linear: sustain */
+      TRI_LO     = (uint8_t)(p & 0xFF);
+      TRI_HI     = (uint8_t)((p >> 8) & 0x07); /* also reloads the linear counter */
+    } else {
+      TRI_LINEAR = 0x00;                       /* rest */
+      TRI_HI     = 0x08;
+    }
+    ++music_step;
+  }
+  ++music_timer;
+  if (music_timer >= 9) music_timer = 0;
+}
+
 void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t length_frames) {
   uint8_t len5 = length_frames & 0x1F;
   uint8_t v = vol_4bit & 0x0F;
@@ -367,3 +424,102 @@ void sound_play_noise(uint8_t period_4bit, uint8_t vol_4bit, uint8_t length_fram
 void sound_off(void) {
   APUSTATUS = 0x00;
 }
+
+
+/* ════════════════════════════════════════════════════════════════════
+ * Text + font (0.29.0 examples contract)
+ * ════════════════════════════════════════════════════════════════════ */
+
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * Font glyphs are 1bpp (plane 0 only → colour index 1 of the BG palette).
+ * They upload into the BACKGROUND pattern table at $1400+ — tile ids $40+ —
+ * NOT the sprite table at $0000 (the runtime maps BG to $1000, sprites to
+ * $0000 via PPUCTRL). Requires: PPU rendering OFF during font_upload (raw
+ * $2007 writes), 37*16 = 592 bytes of CHR-RAM free at $1400-$164F. */
+static const uint8_t font8[37][8] = {
+  /* 0-9 */
+  {0x3C,0x66,0x6E,0x76,0x66,0x66,0x3C,0x00}, {0x18,0x38,0x18,0x18,0x18,0x18,0x7E,0x00},
+  {0x3C,0x66,0x06,0x0C,0x18,0x30,0x7E,0x00}, {0x3C,0x66,0x06,0x1C,0x06,0x66,0x3C,0x00},
+  {0x0C,0x1C,0x3C,0x6C,0x7E,0x0C,0x0C,0x00}, {0x7E,0x60,0x7C,0x06,0x06,0x66,0x3C,0x00},
+  {0x1C,0x30,0x60,0x7C,0x66,0x66,0x3C,0x00}, {0x7E,0x06,0x0C,0x18,0x30,0x30,0x30,0x00},
+  {0x3C,0x66,0x66,0x3C,0x66,0x66,0x3C,0x00}, {0x3C,0x66,0x66,0x3E,0x06,0x0C,0x38,0x00},
+  /* A-Z */
+  {0x18,0x3C,0x66,0x66,0x7E,0x66,0x66,0x00}, {0x7C,0x66,0x66,0x7C,0x66,0x66,0x7C,0x00},
+  {0x3C,0x66,0x60,0x60,0x60,0x66,0x3C,0x00}, {0x78,0x6C,0x66,0x66,0x66,0x6C,0x78,0x00},
+  {0x7E,0x60,0x60,0x7C,0x60,0x60,0x7E,0x00}, {0x7E,0x60,0x60,0x7C,0x60,0x60,0x60,0x00},
+  {0x3C,0x66,0x60,0x6E,0x66,0x66,0x3E,0x00}, {0x66,0x66,0x66,0x7E,0x66,0x66,0x66,0x00},
+  {0x7E,0x18,0x18,0x18,0x18,0x18,0x7E,0x00}, {0x06,0x06,0x06,0x06,0x66,0x66,0x3C,0x00},
+  {0x66,0x6C,0x78,0x70,0x78,0x6C,0x66,0x00}, {0x60,0x60,0x60,0x60,0x60,0x60,0x7E,0x00},
+  {0x63,0x77,0x7F,0x6B,0x63,0x63,0x63,0x00}, {0x66,0x76,0x7E,0x7E,0x6E,0x66,0x66,0x00},
+  {0x3C,0x66,0x66,0x66,0x66,0x66,0x3C,0x00}, {0x7C,0x66,0x66,0x7C,0x60,0x60,0x60,0x00},
+  {0x3C,0x66,0x66,0x66,0x6A,0x6C,0x36,0x00}, {0x7C,0x66,0x66,0x7C,0x6C,0x66,0x66,0x00},
+  {0x3C,0x66,0x60,0x3C,0x06,0x66,0x3C,0x00}, {0x7E,0x18,0x18,0x18,0x18,0x18,0x18,0x00},
+  {0x66,0x66,0x66,0x66,0x66,0x66,0x3C,0x00}, {0x66,0x66,0x66,0x66,0x66,0x3C,0x18,0x00},
+  {0x63,0x63,0x63,0x6B,0x7F,0x77,0x63,0x00}, {0x66,0x66,0x3C,0x18,0x3C,0x66,0x66,0x00},
+  {0x66,0x66,0x66,0x3C,0x18,0x18,0x18,0x00}, {0x7E,0x06,0x0C,0x18,0x30,0x60,0x7E,0x00},
+  /* '-' */
+  {0x00,0x00,0x00,0x7E,0x00,0x00,0x00,0x00},
+};
+#define FONT_BASE_TILE 0x40
+
+void font_upload(void) {
+  uint8_t g, r;
+  uint8_t tile[16];
+  for (r = 8; r < 16; r++) tile[r] = 0;           /* plane 1 = 0 (colour 1) */
+  for (g = 0; g < 37; g++) {
+    for (r = 0; r < 8; r++) tile[r] = font8[g][r];
+    chr_ram_upload((uint16_t)(0x1000 + ((FONT_BASE_TILE + g) << 4)), tile, 16);
+  }
+}
+
+/* char → BG tile id (space → tile 0 = blank). */
+static uint8_t font_tile(char ch) {
+  if (ch >= '0' && ch <= '9') return (uint8_t)(FONT_BASE_TILE + (ch - '0'));
+  if (ch >= 'A' && ch <= 'Z') return (uint8_t)(FONT_BASE_TILE + 10 + (ch - 'A'));
+  if (ch >= 'a' && ch <= 'z') return (uint8_t)(FONT_BASE_TILE + 10 + (ch - 'a'));
+  if (ch == '-') return (uint8_t)(FONT_BASE_TILE + 36);
+  return 0;
+}
+
+void text_draw_unsafe(uint16_t ppu_addr, const char *s) {
+  while (*s) vram_unsafe_set(ppu_addr++, font_tile(*s++));
+}
+
+void text_draw(uint8_t nt, uint8_t x, uint8_t y, const char *s) {
+  while (*s) tile_set(nt, x++, y, font_tile(*s++));
+}
+
+void text_draw_u16(uint8_t nt, uint8_t x, uint8_t y, uint16_t v) {
+  uint8_t d[5];
+  uint8_t i;
+  for (i = 0; i < 5; i++) { d[i] = v % 10; v /= 10; }
+  for (i = 0; i < 5; i++) tile_set(nt, (uint8_t)(x + i), y, (uint8_t)(FONT_BASE_TILE + d[4 - i]));
+}
+
+/* ════════════════════════════════════════════════════════════════════
+ * Hi-score persistence (battery PRG-RAM at $6000)
+ * ════════════════════════════════════════════════════════════════════ */
+
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * Requires: the iNES BATTERY flag in the crt0 header (flags6 bit 1 — the
+ * bundled chr-ram-runtime crt0 sets it). Without it, NROM leaves
+ * $6000-$7FFF UNMAPPED: reads return open bus (looks like data, isn't),
+ * writes vanish, and nothing persists. With it the emulator maps 8KB
+ * persistent PRG-RAM there (the save_ram region) like a real battery cart.
+ * First boot is GARBAGE, not zeros — that's why the magic + checksum. */
+#define SRAM ((volatile uint8_t *)0x6000)
+
+uint16_t hiscore_load(void) {
+  uint16_t v;
+  if (SRAM[0] != 'H' || SRAM[1] != 'S') return 0;
+  v = (uint16_t)SRAM[2] | ((uint16_t)SRAM[3] << 8);
+  if (SRAM[4] != (uint8_t)(SRAM[2] ^ SRAM[3] ^ 0xA5)) return 0;
+  return v;
+}
+
+void hiscore_save(uint16_t v) {
+  SRAM[0] = 'H'; SRAM[1] = 'S';
+  SRAM[2] = (uint8_t)(v & 0xFF);
+  SRAM[3] = (uint8_t)(v >> 8);
+  SRAM[4] = (uint8_t)(SRAM[2] ^ SRAM[3] ^ 0xA5);
+}

package/src/platforms/nes/lib/c/nes_runtime.h

@@ -145,9 +145,44 @@ void sound_init(void);
 void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t length_frames);
 void sound_play_noise(uint8_t period_4bit, uint8_t vol_4bit, uint8_t length_frames);
 void sound_off(void);
+void sound_music(uint8_t on);      /* background triangle melody — ON by default; 0 = off */
+void sound_music_tick(void);       /* call once per frame (the example games do) */
 
 /* ── Globals ──────────────────────────────────────────────────── */
 extern uint8_t shadow_oam[256];       /* at $0200, DMA'd by NMI */
 extern volatile uint8_t nmi_counter;  /* increments each NMI */
 
+/* ── Text + font (0.29.0 examples contract) ─────────────────────── */
+/*
+ * font_upload()
+ *     Upload the built-in 8x8 font (digits 0-9, A-Z, space, dash) into the
+ *     BACKGROUND pattern table at tile $40+ ('0'-'9' = $40-$49, 'A'-'Z' =
+ *     $4A-$63, '-' = $64; space maps to tile 0). Call once during init
+ *     (PPU off), after your other CHR uploads.
+ *
+ * text_draw_unsafe(ppu_addr, s)   — PPU OFF only (init/title paint).
+ * text_draw(nt, x, y, s)          — queued, safe during rendering (NMI
+ *                                   commits next vblank; 16-entry queue).
+ * text_draw_u16(nt, x, y, v)      — 5 right-aligned decimal digits (queued).
+ */
+void font_upload(void);
+void text_draw_unsafe(uint16_t ppu_addr, const char *s);
+void text_draw(uint8_t nt, uint8_t x, uint8_t y, const char *s);
+void text_draw_u16(uint8_t nt, uint8_t x, uint8_t y, uint16_t v);
+
+/* ── Hi-score persistence (battery PRG-RAM at $6000) ────────────── */
+/*
+ * The bundled chr-ram-runtime crt0 sets the iNES BATTERY flag, so the
+ * emulator maps 8KB persistent PRG-RAM at $6000-$7FFF (the save_ram
+ * region) and persists it like a real battery cart. Layout used here:
+ * $6000-$6001 magic "HS", $6002-$6003 score (LE), $6004 checksum
+ * (score lo ^ score hi ^ $A5).
+ *
+ * hiscore_load() → the saved score, or 0 when the SRAM is empty/corrupt
+ * (first boot reads open-bus-like garbage — the magic+checksum reject it).
+ * hiscore_save(v) → store v. Call when a run ends with a new record.
+ */
+uint16_t hiscore_load(void);
+void hiscore_save(uint16_t v);
+
 #endif /* NES_RUNTIME_H */

package/src/platforms/pce/MENTAL_MODEL.md

@@ -12,13 +12,13 @@ romdev ships a **hardware helper library** (`src/platforms/pce/lib/c/`:
 `psg_tone()` instead of poking VDC/VCE registers by hand. cc65 has **no** sprite
 library, so this lib is how you get pixels on screen.
 
-The fastest way to a working game: **`scaffold({op:'game', platform: "pce", genre:
-"shmup"})`** — or any of `platformer` / `puzzle` / `sports` / `racing`, the full
-genre set. For a smaller starting point use **`scaffold({op:'project', platform:
-"pce", template: "sprite_move"})`** (also `music_sfx`, `catch_game`). Either drops
+The fastest way to a working game: **fork the example game whose core loop is
+nearest yours — `examples({op:'fork', example:"pce/shmup", name, path})`** — or any
+of `platformer` / `puzzle` / `sports` / `racing`, the full genre set. For a smaller
+starting point fork `pce/sprite_move` (also `music_sfx`, `catch_game`). Either drops
 a complete, *building* project — a verified playable example + the helper lib +
 docs. Read the example's `main.c`, then change it. The examples live in
-`examples/pce/`. The genre scaffolds fill the BAT (32×32 virtual screen); the
+`examples/pce/`. The genre examples fill the BAT (32×32 virtual screen); the
 `platformer` smooth-scrolls the background via the VDC BXR (R7) register.
 **Gotcha:** `#include <stdint.h>` for int8/16/32_t — `pce.h` only typedefs u8/u16.
 
@@ -101,3 +101,12 @@ screen. Keep at least one (2+ byte) global. See TROUBLESHOOTING.md.
   + LFO.
 - `memory({op:'read'})` regions: `pce_vdc_vram`, `pce_vdc_satb`, `pce_vdc_regs`,
   `pce_vce_palette`, `pce_cpu_regs`, `pce_psg_regs`.
+- `disasm({target:'rom'|'references'|'project'})` — da65's native `huc6280`
+  CPU mode. HuCards >32 KB are handled per 8 KB page (page 0 at `$E000`,
+  where MPR7 maps it at reset — the vectors live there; pages 1+ at `$8000`,
+  an assumed window since the game's MPR writes decide at runtime).
+  `references` tags refs with `romBank`; `disasm({target:'project'})` emits
+  per-page regions + segment wrappers + a generated `.cfg`, and — because the
+  PCE asm toolchain IS cc65/ca65 — a **one-call byte-identical `build()`
+  rebuild** via `rebuild.json` (flat and banked; a 512-byte copier header is
+  split out and re-emitted as a HEADER segment).

package/src/platforms/pce/TROUBLESHOOTING.md

@@ -58,3 +58,12 @@ you likely hit a BRK or an unhandled IRQ — check that you didn't enable a VDC
 `clrscr()` must run before `cputs()` (it inits the font + VDC). Also confirm
 `.bss` is non-empty (see the first entry) — a broken crt0 means conio's font
 upload never happened.
+
+
+## PSG tone plays but is nearly inaudible
+
+The 5-bit channel volume (`PSG_CHAN_CTRL` low bits, 0-31) is roughly an
+ATTENUATOR: each step below 31 costs ~1.5 dB. A "middle" value like 13 is
+about -27 dB — effectively silence on real hardware and most cores. Use
+**29-31 for SFX/music** and treat anything under ~20 as a deliberate whisper.
+(The bundled `psg_tone` example helper and the music ticker default loud.)

package/src/platforms/pce/lib/c/pce_hw.h

@@ -103,8 +103,19 @@ void disp_enable(void);   /* VDC R5: BG + SPR + VBlank IRQ on at once
 void vblank_irq_enable(void); /* just the VBlank IRQ bit (waitvsync needs it)        */
 void load_tiles(u16 vram, const u16 *src, u16 n);  /* alias of vram_write (tiles) */
 void set_sprite(u8 slot, u16 x, u16 y, u16 pattern, u8 palette); /* fill shadow SATB */
+void set_sprite_ex(u8 slot, u16 x, u16 y, u16 pattern, u8 palette, u16 attr_ex);
 void satb_dma(void);                            /* DMA shadow SATB -> VDC (R19)    */
 
+/* attr_ex bits for set_sprite_ex() — the HuC6270 large-sprite size + flip
+ * bits in SATB word3. A 32-wide sprite needs a 2-aligned pattern code, 32x32
+ * needs 4-aligned, 32x64 needs 8-aligned; the data is consecutive 16x16 cells
+ * (left-to-right, then down). See the set_sprite_ex() comment in pce_video.c. */
+#define SPR_CGX_32  0x0100  /* width 32px  (two cells side by side)        */
+#define SPR_CGY_32  0x1000  /* height 32px (two cell rows)                 */
+#define SPR_CGY_64  0x3000  /* height 64px (four cell rows)                */
+#define SPR_XFLIP   0x0800  /* mirror horizontally                          */
+#define SPR_YFLIP   0x8000  /* mirror vertically                            */
+
 /* The shadow SATB lives in VRAM at this word address; satb_dma() points the VDC
  * SATB-DMA source (R19) here. Pattern base for tiles is your choice; sprites
  * default to using the same VRAM you load_tiles() into. */
@@ -126,6 +137,7 @@ u8   pce_joy_read(void);   /* read pad 1 -> clean bitmask (PCE_JOY_* below)  */
 
 /* ---- sound helpers (pce_sound.c) ----------------------------------------- */
 void psg_tone(u8 chan, u16 freq, u8 vol); /* play a wavetable tone (vol 0..31) */
-void psg_off(u8 chan);                    /* silence + disable a channel        */
+void psg_off(u8 chan);
+void psg_music_tick(void);    /* call once per frame (scaffolds do) */                    /* silence + disable a channel        */
 
 #endif /* PCE_HW_H */

package/src/platforms/pce/lib/c/pce_sound.c

@@ -51,3 +51,25 @@ void psg_off(u8 chan) {
     PSG_CHAN_SELECT = chan;
     PSG_CHAN_CTRL   = 0x00;   /* bit7 clear = channel off, volume 0 */
 }
+
+/* ── background music: 8-step melody loop on channel 5 ─────────────
+ * Call psg_music_tick() once per frame (the scaffolds wire it in after
+ * their vsync wait). Deliberately MINIMAL — the PCE boot bank is 8KB
+ * and the puzzle scaffold sits within ~100 bytes of the ceiling, so
+ * there's no on/off toggle and no rests (re-trigger every note).
+ * SFX use channels 0-3; the melody never fights an effect.
+ * PCE freq is a DIVIDER: pitch ~= 3.58MHz / (32 * freq). */
+static const u16 _music_div[8] = {
+    427, 339, 285, 214, 508, 427, 339, 254,  /* C4 E4 G4 C5 A3 C4 E4 A4 */
+};
+static u8 _music_step;
+static u8 _music_timer;
+
+void psg_music_tick(void) {
+    if (_music_timer == 0) {
+        psg_tone(5, _music_div[_music_step & 7], 29);  /* PCE vol is ~-1.5dB/step from 31 — 13 was -27dB, inaudible */
+        ++_music_step;
+    }
+    ++_music_timer;
+    if (_music_timer >= 9) _music_timer = 0;
+}

package/src/platforms/pce/lib/c/pce_video.c

@@ -131,6 +131,38 @@ void set_sprite(u8 slot, u16 x, u16 y, u16 pattern, u8 palette) {
     e[3] = (u16)(0x0080 | (palette & 0x0F));       /* word3: SPBG-front + pal  */
 }
 
+/* set_sprite() with the HuC6270's LARGE-SPRITE size bits — the PCE's signature
+ * trick (sprites up to 32x64 from ONE SATB entry, where the NES needs 8+).
+ *
+ * SATB word3 (the attribute word) layout:
+ *   bit 15    Y-flip
+ *   bits13:12 CGY — sprite HEIGHT: 00=16px, 01=32px, 11=64px (10 is invalid)
+ *   bit 11    X-flip
+ *   bit  8    CGX — sprite WIDTH:  0=16px, 1=32px
+ *   bit  7    SPBG — 1 = sprite in front of background
+ *   bits 3:0  sprite sub-palette (0-15)
+ *
+ * `attr_ex` is OR'd into word3 — pass the SPR_* constants from pce_hw.h
+ * (e.g. SPR_CGX_32 | SPR_CGY_32 for a 32x32 sprite). SPBG-front is still set
+ * for you, same as set_sprite().
+ *
+ * PATTERN LAYOUT for large sprites: the hardware ignores the low bit(s) of the
+ * pattern code and fetches consecutive 16x16 cells (64 words each) instead:
+ *   32 wide:  cell N = left,  N+1 = right            (N multiple of 2)
+ *   32 tall:  row r adds 2*r:  N, N+1 / N+2, N+3     (N multiple of 4)
+ *   64 tall:  rows 0-3 add 2*r: N .. N+7             (N multiple of 8)
+ * So a 32x32 sprite's VRAM data is FOUR cells in TL, TR, BL, BR order, and
+ * its pattern code must be 4-aligned (pattern = VRAM>>6 like set_sprite). */
+void set_sprite_ex(u8 slot, u16 x, u16 y, u16 pattern, u8 palette, u16 attr_ex) {
+    u16 *e;
+    if (slot >= 64) return;
+    e = &_pce_satb[slot * 4];
+    e[0] = (u16)(y + 64);                          /* word0: Y (biased)        */
+    e[1] = (u16)(x + 32);                          /* word1: X (biased)        */
+    e[2] = (u16)((pattern & 0x3FF) << 1);          /* word2: pattern (cell<<1) */
+    e[3] = (u16)(0x0080 | (palette & 0x0F) | attr_ex); /* word3: size/flip + SPBG + pal */
+}
+
 /* Copy the shadow SATB into VRAM at PCE_SATB_VRAM, then tell the VDC to DMA it
  * into its internal sprite table (R19 = SATB source). */
 void satb_dma(void) {

package/src/platforms/sms/MENTAL_MODEL.md

@@ -78,7 +78,7 @@ R1 = 0x80   display OFF, vblank IRQ off, 192-line
 R2 = 0xFF   name table at $3800
 R4 = 0xFF   BG tile data at $0000
 R5 = 0xFF   sprite attr table at $3F00
-R6 = 0xFF   sprite tile data at $2000 (own bank; scaffolds upload here)
+R6 = 0xFF   sprite tile data at $2000 (own bank; the example games upload here)
 R7 = 0x00   border colour
 ```
 
@@ -114,7 +114,7 @@ So Y bytes and X/tile pairs are split into TWO regions of the SAT.
 `src/platforms/sms/lib/c/sprite_table.c` keeps a 256-byte shadow
 buffer in WRAM and uploads it to the SAT each vblank.
 
-### Two footguns the bundled scaffolds keep hitting
+### Two footguns the bundled example games keep hitting
 
 1. **8 sprites per scanline limit.** The VDP draws up to 8 sprites per
    scanline; the 9th+ are silently dropped. If you draw a "CATCH THE
@@ -147,9 +147,9 @@ buffer in WRAM and uploads it to the SAT each vblank.
 `sms_vdp_init()` sets R6 = 0xFF. R6 bit 2 is the SA13 select for
 sprite tile data — bit 2 is **SET** in 0xFF, so sprite tiles read
 from `$2000-$3FFF`, their **own bank** separate from BG tiles at
-$0000. This matches every bundled scaffold, which uploads sprite
+$0000. This matches every bundled example, which uploads sprite
 tiles to `$2000` (`sms_load_tiles(0x2000, …)`) — default and
-scaffolds agree, so sprites render.
+examples agree, so sprites render.
 
 Watch the bit: 0xFB has SA13 **CLEAR** = sprite tiles at $0000
 (shared with the BG bank). If you set R6=0xFB you MUST upload your
@@ -222,7 +222,7 @@ PSG (SN76489) on port $7F. 4 channels: 3 square waves + 1 noise.
 Writes are byte-wise; the high bit selects "latch register" vs
 "continue previous register".
 
-A full driver is beyond the scope of these scaffolds. For
+A full driver is beyond the scope of these example games. For
 playable SFX, manually pulse $7F with the latch-register byte
 followed by data bytes. Real games ship a music driver in WRAM.
 
@@ -318,9 +318,14 @@ CB/ED/DD/FD/DDCB/FDCB — and feeds the same auto-label, register-annotation,
 file-offset, and `untilReturn` pipeline used by the NES and SNES
 disassemblers.
 
+Sega-mapper banked carts (>48 KB) are handled per-bank: `references` scans
+every 16 KB bank (bank 0 @ `$0000`, bank 1 @ `$4000`, banks 2+ @ their slot-2
+window `$8000`), refs tagged `romBank`; `disasm({target:'project'})` emits one
+region per bank with a bank-by-bank native rebuild recipe in `BUILD.md`.
+
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. To make it a side-scroller:
+The `platformer` example is single-screen. To make it a side-scroller:
 
 - **Hardware scroll:** write VDP register 8 (horizontal scroll) each frame =
   `-camX & 0xFF` (the reg scrolls the screen; the name table is 32×28 and

package/src/platforms/sms/TROUBLESHOOTING.md

@@ -118,6 +118,12 @@ If you ported an SMS ROM straight to `.gg` it'll boot and run, but
 the colours will be very dark (2-bit values reinterpreted as 4-bit)
 and the visible area is in the top-left corner.
 
+Also check the header region byte at `$7FFF` (high nibble = region,
+low nibble = size): romdev stamps `$7C` (GG international) on `.gg`
+builds, but an SMS nibble there (`$4x`) makes gpgx boot the file in
+SMS compatibility mode — wrong resolution and palette depth no matter
+what your code does.
+
 ## "ROM > 32 KB doesn't run"
 
 The default template is single-bank (32 KB). To use the Sega

package/src/platforms/sms/lib/c/sms_crt0.s

@@ -28,10 +28,13 @@
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
         .org    0x0000
+        ;; ONLY 8 BYTES fit before the RST $08 vector. The old block here
+        ;; (di/im 1/ld sp/jp = 9 bytes) overflowed into .org 0x0008, whose
+        ;; `ret` stomped the jp's high target byte -> boot jumped into
+        ;; garbage. di+im 1+jp = 6 bytes; SP setup moved to _boot below.
         di                          ; interrupts off until we're ready
         im      1                   ; mode 1 — IRQs jump to $0038
-        ld      sp, #0xDFF0         ; SMS stack (top of WRAM minus 16)
-        jp      gsinit              ; skip the interrupt vector table
+        jp      _boot               ; continue past the vector table
 
 ;; ─── RST handlers (default = return) ──────────────────────────────
         .org    0x0008
@@ -69,6 +72,15 @@
         .org    0x0066
         retn
 
+;; ─── Boot continuation (right after the NMI vector) ───────────────
+;; SP first, then the C runtime init. Lives in the ABS header area so
+;; it exists at a known address regardless of where _CODE is linked
+;; (_CODE must start at >= $0100 so it can't overwrite this table).
+        .org    0x0068
+_boot:
+        ld      sp, #0xDFF0         ; stack at top of WRAM minus 16
+        jp      gsinit
+
 ;; ─── crt0 body ────────────────────────────────────────────────────
 ;; Standard SDCC pattern: jump to a code area, run initializers, then
 ;; call main. The initializer area is filled by sdcc when it sees

package/src/platforms/snes/MENTAL_MODEL.md

@@ -222,6 +222,11 @@ video are fully readable, so you assert live state instead of guessing:
   cpu:'spc700'})` for the sound CPU.
 - **Audio:** the S-DSP is fully decodable — full per-voice state plus the
   master mixer (see "Debugging sound" above for `audioDebug`).
+- **`disasm({target:'references'})`** scans EVERY 32 KB LoROM bank (refs
+  tagged `romBank`) — a hit in bank 12 of a 1 MB cart shows up, not just
+  bank 0. `disasm({target:'project'})` likewise splits per-bank with a
+  native ca65/ld65 rebuild recipe (build() is asar, which can't consume
+  the disasm's ca65 output).
 - **Memory regions:** `memory({op:'read'})` exposes OAM, CGRAM, ARAM (SPC700
   audio RAM), and **FillRAM**. Note the FillRAM quirk: snes9x mirrors the
   PPU registers $2100-$213F (OBSEL/BGMODE/TM/TS/color-math, etc.) into
@@ -248,7 +253,7 @@ PVSnesLib's `hdr.asm` fills these in.
 
 ## Where the SDK lives (and how to read it)
 
-`scaffold({op:'project', platform:"snes"})` ships the FULL PVSnesLib source +
+`examples({op:'fork'})` (any SNES example) ships the FULL PVSnesLib source +
 header tree into the new project at `vendor/pvsneslib/`. So when
 your code does `#include <snes.h>`, those headers come from
 `vendor/pvsneslib/include/`:
@@ -291,7 +296,7 @@ Loadable via snes9x (`loadMedia`).
 
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. SNES scrolling is the easiest of
+The `platformer` example is single-screen. SNES scrolling is the easiest of
 the tile platforms because each BG layer has its own hardware scroll register
 and parallax is nearly free.
 

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -160,6 +160,45 @@ Three layers:
 PVSnesLib's API is the path of least resistance. Roll your own SPC
 driver only when you really need the control.
 
+## "Music never starts (sfx works, sfx_init returned 0)"
+
+A command sent to the bundled snes_sfx driver IMMEDIATELY after
+`sfx_init()` returns can be silently swallowed. `sfx_init` returns the
+instant the SPC echoes the jump command, but the driver then spends
+~50 DSP port writes initialising before it seeds its command
+edge-detector from $2140. A `sfx_music_play()` issued inside that
+window becomes the SEED — no edge, no dispatch, music never starts.
+
+Symptoms via the debug tools: `getAudioState({chip:'dsp'})` shows
+voice 1 with pitch 0 / env 0; ARAM $00 (prev_cmd) already equals your
+command byte while ARAM $01 (music_on) is 0.
+
+Fix: put one `WaitForVBlank()` between `sfx_init()` and the first
+`sfx_play`/`sfx_music_play` — a frame is thousands of SPC cycles, the
+driver is guaranteed to be in its command loop. The racing example does
+exactly this (see its `sfx_init` call site).
+
+## "My HDMA table stops landing / OAM gets corrupted" (HDMA channel fights the OAM DMA)
+
+A DMA channel cannot serve general-purpose DMA and HDMA in the same
+frame — and PVSnesLib's runtime OWNS two channels for GP-DMA:
+
+- **channel 0** — `dmaCopyVram` and friends (console text upload,
+  `oamInitGfxSet`, `consoleVblank`)
+- **channel 7** — the VBlank ISR's OAM upload (vblank.asm rewrites
+  $4370-$4375 EVERY NMI)
+
+Park an HDMA effect on channel 7 and it works for exactly zero frames:
+each NMI silently rewrites the channel's DMAP/BBAD/A1T with OAM-DMA
+parameters, so your per-scanline writes stop landing — and worse, the
+HDMA unit then feeds your table bytes into $2104 (OAM data). The
+failure is maddeningly partial: channels 1-6 keep working, so a
+multi-channel effect (e.g. a Mode 7 split) comes up ALMOST right with
+one register mysteriously stuck at a stale value.
+
+Fix: keep HDMA on channels 1-6. The Mode 7 racing example uses 2-6 and
+documents the assignment at its `road_hdma_on()`.
+
 ## "consoleDrawText output is corrupt / shifted"
 
 `consoleInitText(palnum, palsize, tilfont, palfont)` configures the
@@ -220,7 +259,7 @@ synthesizes a fallback `issues[]` entry with a hint. The idioms to avoid:
   crossed a bank boundary and the layout is wrong. Native interrupt vectors live
   at `$FFE4-$FFEE`, emulation vectors at `$FFF4-$FFFF` — keep your header/vector
   block where the layout expects it. Use
-  `scaffold({op:'snippets', platform:"snes", mode:"get", name:"lorom_header.asm"})`
+  `examples({op:'snippets', platform:"snes", mode:"get", snippetName:"lorom_header.asm"})`
   for the canonical layout (and `lorom_multibank.asm` for multi-bank).
 
 (This is the asar/asm path. The default PVSnesLib **C** path goes through