romdevtools 0.28.0 → 0.30.0

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -65,6 +65,14 @@ thousands of bytes and you'll drown).
 
 This is the Cheat-Engine/RetroArch loop. It is THE bread-and-butter primitive.
 
+**Don't know the value? (lives/timer/ammo not on the HUD)** Use the
+unknown-initial-value hunt: `memory({op:'searchUnknown', region, size})` seeds
+the WHOLE region with no value, then narrow across events with
+`searchNext({compare:'dec'|'inc'|'unchanged'|'changed'|'gt'|'lt'})` — e.g.
+`searchUnknown` → lose a life → `searchNext({compare:'dec'})` → repeat until 1–2
+remain. `op:'search'` needs a value; `op:'searchUnknown'` is for when you can't
+see the number.
+
 **Stored ≠ displayed.** When a correct-looking seed returns 0, the byte usually isn't the
 raw number: seed `as:'bcd'` for packed-BCD scores (2 decimal digits per byte — very common
 on NES), or `as:'digits'` for one byte per ON-SCREEN digit at any constant tile base (HUD
@@ -78,7 +86,13 @@ not for value hunting. `memory({op:'diff'})` defaults to a **clustered summary**
 stride) so it won't flood you — a reported stride (e.g. "islands at 0x80") is
 usually a struct/entity array, each island one record. Small clusters (≤8 bytes) carry
 `before`/`after` hex inline, and `minDelta:N` drops |after−before| < N so RNG/counter
-wiggle disappears from the report.
+wiggle disappears from the report. For the locate-value-via-diff case, predicate
+filters cut a 500-byte death-window diff to the ~3 rows you want in one call:
+`changeDir:'dec'|'inc'` (direction), `deltaEq:N` (signed exact delta — `deltaEq:-1`
+= "lost one life"), and `beforeMin/Max` + `afterMin/Max` (value-range gates, e.g.
+`beforeMax:9` = a small counter, not a coordinate). `outputPath` writes the full
+diff JSON to your path regardless of size (`echo:false` returns just the
+counts+path so a big diff never streams through context).
 
 **"Which byte does this INPUT drive?" → `memory({op:'diffRuns'})`** — runs the same start
 state twice (savestate restore in between) under two different held inputs (`portsA` vs
@@ -136,8 +150,11 @@ a string — find a terminator / font map before treating the bytes as values.
 platforms (Genesis/Mega Drive, GB/GBC, SMS/GG, PCE, Lynx) the **file offset IS
 the CPU ROM address** — `memory({op:'readCart', offset:0x21FF00})` answers "does the
 running ROM have my bytes at 0x21FF00?" in one call. (NES/SNES: bytes are
-correct but mapper-banked — `mapped:true` in the response; map a CPU PC→offset
-via `breakpoint({on:'write'})`'s prgOffset/bank.)
+correct but mapper-banked — `mapped:true` in the response.) For a BANKED CPU
+address, read it directly: `memory({op:'readCart', cpuAddress:0x8654, bank:6})`
+maps the bank→PRG offset for you (NES/SNES) — the inverse of the breakpoint
+result's bank/prgOffset, so you stop hand-computing `cpuAddr−0x8000+bank*0x4000`.
+A NES `$C000+` address resolves to the fixed top bank automatically.
 
 When a write "doesn't show up", check the ROM here before assuming the patch
 failed — it's usually live and the bug is elsewhere (wrong source, see §2/§5).
@@ -170,6 +187,18 @@ can pass `{startAddress, bank}` to `disasm({target:'rom'})`. The lighter
 and returns a frame-boundary PC — a lead, not a guarantee under interrupts; use it for the
 value timeline or when you just want the change history, and cross-check the value trace.
 
+**Stop on the MEANINGFUL write, not the churn.** `breakpoint({on:'write'})` runs
+to END OF FRAME and reports the LAST matching write that frame (with `hits` =
+the count of all matching writes) — so a frequent **restoring** write (a pointer-
+arithmetic `inc`/`dec` that touches the byte every frame, a re-arm) can mask the
+write you actually want. Filter to the real change with `condition` (all 14
+platforms): `condition:'decrease'` / `'increase'` stop only when the stored byte
+actually went down/up (a real lives−1, not a restore), and `condition:'equals',
+conditionValue:N` stops on the byte becoming N (e.g. a $00→$01 respawn re-arm).
+The hit then reports `oldValueByte`→`valueByte` so you see the exact transition.
+This is the difference between pinning a genuine decrement instantly and chasing
+net-zero restoring churn.
+
 ---
 
 ## 5b. To READ a register at an instruction — execution breakpoints (all 14)

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -58,7 +58,7 @@ and DLL; you do NOT poke pixels into a framebuffer.**
   and (worse) burns enough cycles that the CPU stops getting time.
 - **Y position = which zone the object lives in.** Each zone covers
   N scanlines. To move an object up/down, you move it between
-  zones. (Or — in our scaffolds — you stamp the same sprite at
+  zones. (Or — in our example games — you stamp the same sprite at
   different row offsets within ONE zone's data block, which fakes
   Y movement.)
 - **Each DL header can pick a palette per object** (one of 8
@@ -136,7 +136,7 @@ The "loop continues" mask is `0x5F` (bits 0-4 + bit 6). Bit 5
 (indirect flag) and bit 7 (write-mode) do NOT keep the loop going
 by themselves.
 
-### 5-byte extended form (the bundled scaffolds use this)
+### 5-byte extended form (the bundled example games use this)
 
 ```
 +0  pixel-data LOW byte
@@ -195,7 +195,7 @@ scanlines for the ENTIRE display area (243 scanlines on NTSC,
 including 10 lines of top overscan before the visible area).
 
 If your DLL is shorter than 243 entries, MARIA reads past the end
-into random memory and renders garbage zones. The bundled scaffold
+into random memory and renders garbage zones. The bundled example
 allocates 243 entries × 3 bytes = 729 bytes (fits easily in 4 KB
 internal RAM) and points every zone with no objects at a shared
 `dl_empty[2] = {0, 0}` terminator.
@@ -213,11 +213,11 @@ for an 8-row sprite) unless you pack many sprites per page.
 **Easy work-around:** make every zone 1 scanline tall (offset=0)
 and use one DL entry per sprite ROW. Then `offset` is always 0, the
 address quirk goes away, and you can store sprite rows back-to-back.
-The bundled scaffold uses this pattern.
+The bundled example uses this pattern.
 
 The cost is more DLL entries (one per scanline), but at 3 bytes each
 across 243 lines = 729 bytes total — trivial RAM cost. Worth it for
-the simpler mental model on a starter scaffold.
+the simpler mental model on a starter example.
 
 ## Colour bytes (Atari NTSC palette)
 

package/src/platforms/atari7800/TROUBLESHOOTING.md

@@ -56,14 +56,14 @@ you have to:
 2. Place the sprite's DL entry into the zone covering its Y range.
 3. Per-frame, move the entry's bytes from old-zone DL → new-zone DL.
 
-Our scaffolds use a single-zone DLL for simplicity. Vertical
+Our example games use a single-zone DLL for simplicity. Vertical
 movement is faked by stamping the sprite at different row offsets
 within the canvas data — only works if the canvas is tall enough.
 
 ## "Memory overflow during link (RAM1 by N bytes)"
 
 The 7800 has **4 KB of RAM**. The `default.c` and `hello_sprite.c`
-scaffolds use very little; the `shmup.c` puzzle (and the older
+example games use very little; the `shmup.c` puzzle (and the older
 canvas-buffer approach) easily blow past it.
 
 Symptoms:
@@ -77,7 +77,7 @@ Fixes:
 - Use ROM constants (`const uint8_t` at file scope) instead of
   RAM globals.
 - Replace canvas-buffer rendering with per-object DLs (see
-  `shmup.c` scaffold for the canonical pattern).
+  `shmup.c` example for the canonical pattern).
 - Avoid per-frame `memset(canvas, 0, ...)` — instead, only stamp
   changed cells.
 
@@ -126,7 +126,7 @@ DL during active rendering; safe modification windows:
 Build a "next-frame" DL during the game-state update phase and
 swap pointers (DPPL/DPPH) at vblank — double-buffered.
 
-Our scaffolds rebuild the DL during vblank, which works for small
+Our example games rebuild the DL during vblank, which works for small
 DLs (< ~100 bytes). Large DLs that take ~1 ms to rebuild may
 exceed vblank time and start corrupting the active frame.
 
@@ -197,5 +197,5 @@ Fix options (in order of how much they shrink BSS):
   if you only need one sprite at a time — see `default.c` and
   `hello_sprite.c`. No per-scanline pool needed.
 
-The bundled scaffolds size their pools to fit; if you scale up
+The bundled example games size their pools to fit; if you scale up
 (more objects, taller play area), watch the build log.

package/src/platforms/c64/MENTAL_MODEL.md

@@ -115,9 +115,16 @@ which is what the KERNAL's IRQ uses to update key state every
 
 **Joystick.** One fire button. Press it with `input({op:'set', b: true})` (or
 spatial `south`) — both clear `$DC00` bit 4 (verified live). `a` is a **no-op**
-(no second button). Drive fire with `b`/`south` + the d-pad. The joystick reads
-**port 2** by default; switch with `input({op:'joyport', joyport:1})` /
-`input({op:'joyport'})` to read it.
+(no second button). Drive fire with `b`/`south` + the d-pad.
+
+**Two players.** BOTH C64 control ports are live at once, so 2P games just work:
+**host port 0 = player 1** (control port 2, `$DC00`) and **host port 1 = player
+2** (control port 1, `$DC01`) — the universal "port 0 = P1" convention. Pass two
+port entries: `input({op:'set', ports:[{up:true}, {down:true}]})` moves P1 up and
+P2 down independently. (Under the hood the host enables the VICE userport-adapter
+mapping so both ports route, and swaps them so P1 lands on control port 2 where
+the games read it.) The legacy `input({op:'joyport', joyport:1|2})` still selects
+which single port a ONE-stick setup drives, but you rarely need it now.
 
 **Keyboard (the C64-specific part — many games NEED it).** Unlike consoles, most
 C64 games (and cracktros) gate gameplay behind a KEYBOARD setup screen — **F1**
@@ -311,7 +318,7 @@ loads games, wrap the `.prg` into a `.d64`: `cart({op:'packDisk', prgPath})`
 
 ## Horizontal scrolling (for side-scrollers)
 
-The `platformer` scaffold is single-screen. C64 scrolling is the fiddliest of
+The `platformer` example is single-screen. C64 scrolling is the fiddliest of
 the platforms because the VIC-II only does a 0-7 px *fine* scroll in hardware;
 moving further is a software char-cell shift.
 

package/src/platforms/c64/TROUBLESHOOTING.md

@@ -83,6 +83,19 @@ KERNAL last selected. Result: ghost input.
 
 **Use port 2 (CIA1_PRA) by default.** All bundled C64 templates do.
 
+## "Player 2 input does nothing"
+
+Both C64 control ports ARE live over MCP, so 2P works — the mapping is just
+non-obvious: **host port 0 → control port 2 ($DC00) = player 1**, **host port 1
+→ control port 1 ($DC01) = player 2** (the universal "port 0 = P1" convention).
+So a 2P game reads P1 from $DC00 and P2 from $DC01, and you drive them with two
+port entries: `input({op:'set', ports:[{up:true},{down:true}]})` moves P1 up,
+P2 down. If P2 seems dead, check you passed a SECOND `ports` entry (not just
+port 0) and that the game actually entered 2P mode (its title pick, e.g. "PORT 1
+FIRE = 2P"). The host enables the VICE userport-adapter mapping + swaps the two
+RetroPad ports under the hood so this convention holds — you don't configure
+anything.
+
 ## "Audio is silent / SID doesn't play"
 
 Three things to check:

package/src/platforms/gb/MENTAL_MODEL.md

@@ -280,9 +280,9 @@ names also resolve (east→A, west→B). So `input({op:'set', a: true})` presses
 expected — unlike the genesis_plus_gx platforms (Genesis/SMS/GG), there's no
 surprise here. (Same for **GBC** — it shares the gambatte core.)
 
-## What `scaffold({op:'project'})` copies into your project
+## What `examples({op:'fork'})` copies into your project
 
-`scaffold({op:'project', platform:"gb"|"gbc", template:...})` writes these files
+`examples({op:'fork', example:"gb/..."|"gbc/...", name, path})` writes these files
 into your project directory. **They're yours** — every byte that compiles
 is in the repo. Edit, fork, replace; nothing is auto-injected at build time.
 
@@ -340,7 +340,7 @@ Most game patterns DON'T need any of this. Try the C path first.
 
 ## 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 `SCX` (`$FF43`) each frame = camera X mod 256.
   The BG is a 32×32 tile map (256×256 px) that wraps, so `SCX` alone scrolls

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -174,7 +174,7 @@ 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 scaffolds):
+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.
@@ -195,7 +195,7 @@ 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 scaffolds):
+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.
@@ -208,6 +208,60 @@ The robust pattern (used by the bundled puzzle scaffolds):
 If you must write outside that structure, turn the LCD off first (only
 acceptable during init/load screens — mid-game it flashes white).
 
+## "My HUD scrolls with the background" / "the window ate the bottom of my screen"
+
+The window layer (WX/WY + LCDC bit 5) is the GB's fixed-HUD mechanism: it has
+no scroll registers, always draws its own map from (0,0) pinned to the screen,
+on top of the BG. Three rules, all demonstrated in the shmup example
+(`examples/gb/templates/shmup.c`, "HARDWARE IDIOM: window-layer HUD"):
+
+- **WX is screen X plus 7.** `WX=7` is the left edge. WX 0-6 produces real
+  DMG pixel-pipeline glitches; WX ≥ 167 pushes the window off-screen.
+- **The window has no height register.** From the first line it covers (WY)
+  it owns EVERY line to the bottom of the frame, full width from WX. That's
+  why GB HUDs live at the BOTTOM of the screen (`WY = 128` → lines 128-143 =
+  HUD, lines 0-127 = scrolling playfield). A top HUD needs a mid-frame
+  STAT/LYC interrupt to turn LCDC bit 5 back off — a different, fragile
+  idiom; don't fall into it by accident by setting WY=0.
+- **Sprites are NOT clipped by the window** — they draw on top of it. Despawn
+  (or Y-clamp) everything before the HUD line, or your enemies fly across
+  the score bar.
+
+Use a separate map for the window (LCDC bit 6 → $9C00) so it doesn't fight
+the BG's $9800 map.
+
+## "Hi-score doesn't persist" / save_ram is empty or all $FF
+
+Battery saves need BOTH halves:
+
+1. **The header must declare a battery cart.** The bundled `gb_crt0.s` emits
+   `$0147 = $03` (MBC1+RAM+BATTERY) and `$0149 = $02` (8 KB) as real bytes,
+   and the build's post-link header fix passes them through. The emulator
+   sizes its SAVE_RAM region from those two bytes — type $00 (ROM-only)
+   means no save_ram region at all, and writes to $A000 go nowhere.
+2. **Cart RAM is gated.** It boots DISABLED; writes are silently discarded
+   until you write `$0A` to $0000-$1FFF (any address there — it's a mapper
+   register, not memory). Write `$00` to the same range after saving
+   (battery hygiene: an enabled RAM bank can corrupt at power-off on real
+   hardware).
+
+Working pattern with magic + checksum (a fresh cart is $FF garbage — never
+trust raw bytes): shmup example, "HARDWARE IDIOM: battery SRAM". Verify
+headlessly: play to a score, force game over, `memory({op:'read',
+region:"save_ram"})` shows the record, and the hi-score still shows on the
+title after a hard reset (power cycle).
+
+## "Boot takes seconds" / a screen repaint visibly stalls the game
+
+The sm83 has no divide instruction. SDCC's software `%` / `/` costs ~700
+cycles per call — one `(r*7+c*5) % 11` in a 32×32 map fill is 2048 calls
+≈ 1.5 MILLION cycles ≈ a 1.5-second frozen boot (measured, not theoretical;
+the shmup example shipped exactly that for an hour). In any per-cell or
+per-frame loop, replace modulo patterns with running counters +
+subtract-on-overflow (see `paint_starfield` in the shmup example) and
+decimal score display with power-of-ten subtraction (`u16_to_tiles` there).
+A single `%` per event — e.g. per enemy spawn — is fine.
+
 ## Debug recipes
 
 A few high-leverage tools you might not know exist:
@@ -247,14 +301,13 @@ Boot order that always works for GBC:
    }
 ```
 
-Cribbed from `examples/gbc/templates/tile_engine.c` — start a fresh
-game from that template with:
+Cribbed from `examples/gbc/templates/tile_engine.c` — fork that
+example into a fresh game with:
 
 ```js
-scaffold({
-  op: 'project',
-  platform: "gbc",
-  template: "tile_engine",
+examples({
+  op: 'fork',
+  example: "gbc/tile_engine",
   name: "mygame",
   path: "/abs/path/to/dir",
 });

package/src/platforms/gb/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/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

@@ -13,7 +13,7 @@
 // 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 scaffold self-contained.
+// 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
@@ -151,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

@@ -114,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,
@@ -197,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

@@ -128,7 +128,7 @@ 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 scaffolds):
+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.
@@ -149,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.
@@ -159,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: