romdevtools 0.28.0 → 0.30.0

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/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

@@ -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/genesis/MENTAL_MODEL.md

@@ -178,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
 
@@ -241,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.)
@@ -481,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/gg/MENTAL_MODEL.md

@@ -14,7 +14,7 @@ $E000-$FFFB  Work RAM mirror
 $FFFC-$FFFF  Mapper control registers
 ```
 
-Most 32 KB scaffolds fit in banks 0+1 and never touch the mapper.
+Most 32 KB example games fit in banks 0+1 and never touch the mapper.
 
 ## VDP (display)
 
@@ -36,7 +36,7 @@ GG VDP = SMS VDP in Mode 4, smaller visible viewport.
   OR draw the text via the BG name table (no per-line limit).
 
 **Always render gameplay content inside (48, 24)..(207, 167)** so it's
-visible on real hardware. The bundled scaffolds work without this
+visible on real hardware. The bundled example games work without this
 because gpgx shows the full framebuffer.
 
 ### Sprite coords are hardware-space, NOT visible-space
@@ -78,9 +78,9 @@ on its own anymore.
 `gg_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`, in their **own bank** separate from BG tiles at
-$0000. This is the baseline because every bundled scaffold uploads
+$0000. This is the baseline because every bundled example uploads
 its sprite tiles to `$2000` (`gg_load_tiles(0x2000, …)`) — the
-default and the scaffolds match, so sprites Just Show Up.
+default and the examples match, so sprites Just Show Up.
 
 Watch the bit: 0xFB has SA13 **CLEAR** = sprite tiles at $0000
 (sharing the BG bank). If you ever set R6=0xFB you MUST also upload

package/src/platforms/gg/TROUBLESHOOTING.md

@@ -16,7 +16,7 @@ Anything you draw outside `(48, 24)..(207, 167)` is in the border —
 visible in headless emulator screenshots (gpgx shows the whole frame)
 but invisible on real hardware.
 
-The bundled scaffolds are direct ports of the SMS scaffolds and target
+The bundled example games are direct ports of the SMS examples and target
 the full 256×192 area. Works fine for development under gpgx; for
 shipping to a real GG, reposition sprite + tilemap content to the
 visible center.
@@ -28,7 +28,7 @@ active low), separate from the D-pad/A/B which are on `$DC` like
 SMS. `gg_joypad_read()` already merges them — START shows up in bit 7
 of the returned byte (`JOY_START` mask).
 
-If you copied an SMS scaffold that uses PAUSE-as-START semantics
+If you copied an SMS example that uses PAUSE-as-START semantics
 (SMS pause button is at port $DD bit 4 IIRC), it won't work on GG;
 swap to JOY_START.
 
@@ -85,7 +85,7 @@ two-byte little-endian CRAM entry.
 
 ## "Linking error: undefined reference to sms_joypad_read_p2"
 
-GG only has one controller. The SMS scaffolds use `sms_joypad_read_p2`
+GG only has one controller. The SMS examples use `sms_joypad_read_p2`
 for the two-controller patterns (Pong, 2P shmup). When porting, drop
 the P2 read + force `p2 = 0` so the AI fallback always engages.
 

package/src/platforms/gg/UPSTREAM_SOURCES.md

@@ -3,7 +3,7 @@
 GG shares its toolchain (SDCC z80) + emulator (genesis_plus_gx) +
 most of the runtime with SMS (`sms_crt0.s` ≡ `gg_crt0.s` byte-for-
 byte; PSG protocol identical). The GG tree at `src/platforms/gg/`
-holds the GG-specific scaffolds and runtime helpers; SMS docs apply
+holds the GG-specific example games and runtime helpers; SMS docs apply
 for everything else.
 
 GG-specific:

package/src/platforms/gg/lib/c/joypad_read.c

@@ -20,3 +20,32 @@ uint8_t gg_joypad_read(void) {
   uint8_t start = ~PORT_GG_INPUT; /* GG-specific port bit 7 = START */
   return (uint8_t)((a & 0x3F) | (start & 0x80));
 }
+
+/*
+ * Player 2 read — for ALTERNATING-TURNS or 2-controller play.
+ *
+ * HONEST NOTE: a real Game Gear has only ONE controller port on the unit; its
+ * 2P story is the Gear-to-Gear LINK CABLE (a second console). But the GG VDP
+ * and I/O chip are the SMS's, and gpgx wires the SMS's full split-across-
+ * $DC/$DD second-controller layout for GG too — so a SECOND PAD does drive
+ * port B in the emulator (and on an SMS-pad adapter), which is exactly what an
+ * alternating-turns 2P platformer needs (the two players never play at once).
+ *
+ * The hardware layout is the SMS's awkward split:
+ *   PORT_JOY_A bits 6-7  = P2 UP, P2 DOWN
+ *   PORT_JOY_B bits 0-3  = P2 LEFT, P2 RIGHT, P2 B1, P2 B2
+ * Reassembled into the same bit layout P1 uses:
+ *   bit 0 = UP, 1 = DOWN, 2 = LEFT, 3 = RIGHT, 4 = B1, 5 = B2.
+ * Returns 0 when no P2 pad is present (all bits high = released after invert).
+ */
+uint8_t gg_joypad_read_p2(void) {
+  uint8_t a = ~PORT_JOY_A;          /* P2 UP in bit 6, DOWN in bit 7 */
+  uint8_t b = ~PORT_JOY_B;          /* P2 LEFT bit 0, RIGHT 1, B1 2, B2 3 */
+  uint8_t up    = (a >> 6) & 0x01;  /* bit 6 -> bit 0 */
+  uint8_t down  = (a >> 6) & 0x02;  /* bit 7 -> bit 1 */
+  uint8_t left  = (b << 2) & 0x04;  /* bit 0 -> bit 2 */
+  uint8_t right = (b << 2) & 0x08;  /* bit 1 -> bit 3 */
+  uint8_t b1    = (b << 2) & 0x10;  /* bit 2 -> bit 4 */
+  uint8_t b2    = (b << 2) & 0x20;  /* bit 3 -> bit 5 */
+  return (uint8_t)(up | down | left | right | b1 | b2);
+}

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -96,7 +96,7 @@ void main(void) {
 `tgi_updatedisplay()` is the frame heartbeat — it ping-pongs the
 double-buffered display and waits for vblank.
 
-## Drawing many rectangles in one frame (game scaffold pattern)
+## Drawing many rectangles in one frame (example-game pattern)
 
 The minimal example above draws "one rect per frame." For an actual
 game with HUD + background + sprites you'll do many tgi_bar / tgi_setcolor

package/src/platforms/lynx/TROUBLESHOOTING.md

@@ -44,7 +44,7 @@ Two things that trip agents up:
   Skipping it is the #1 "Lynx is blank" trap.
 - **Don't rely on `tgi_clear()`** to blank the screen in this
   toolchain/emulator path — use a full-screen `tgi_bar(0,0,maxx,maxy)`
-  in the background colour instead. The bundled `shmup` scaffold uses
+  in the background colour instead. The bundled `shmup` example uses
   this exact loop; copy it.
 
 ## "tgi_outtextxy renders nothing"
@@ -54,7 +54,7 @@ cc65's default TGI on Lynx ships without a font. Either:
    live in `$cc65_share/target/lynx/fonts/`.
 2. Draw your own glyphs with `tgi_bar`/`tgi_line`.
 
-The bundled scaffolds work around this by using simple rectangles
+The bundled example games work around this by using simple rectangles
 for game content + only short text strings. For game UI text, embed
 a bitmap font directly in your code.
 
@@ -93,7 +93,7 @@ cc65 is C89. No mixed declarations + code, no inline `for (uint8_t i
 = 0; ...)`, no compound literals, no // comments in some configs.
 Declare all variables at the top of each block.
 
-The bundled Lynx scaffolds are C89-clean — copy that pattern.
+The bundled Lynx example games are C89-clean — copy that pattern.
 
 ## "Compile fails: no rule to make target lynx-bll.cfg"
 

package/src/platforms/msx/MENTAL_MODEL.md

@@ -12,13 +12,13 @@ romdev ships a **hardware helper library** (`src/platforms/msx/lib/c/`:
 `msx_psg_tone()` in plain C. It uses DIRECT Z80 I/O ports (the reliable path —
 NOT fragile inline-asm BIOS wrappers).
 
-The fastest way to a working game: **`scaffold({op:'game', platform: "msx", genre:
-"shmup"})`** — or any of `platformer` / `puzzle` / `sports` / `racing`, the full
-genre set. For a smaller starting point use **`scaffold({op:'project', platform:
-"msx", 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:"msx/shmup", name, path})`** — or any
+of `platformer` / `puzzle` / `sports` / `racing`, the full genre set. For a smaller
+starting point fork `msx/sprite_move` (also `music_sfx`, `catch_game`). Either drops
 a complete, *building* project — a verified playable example + the helper lib +
 the cart crt0 + docs. Read the example's `main.c`, then change it. Examples live in
-`examples/msx/`. The `platformer` scaffold column-streams the SCREEN 2 name table
+`examples/msx/`. The `platformer` example column-streams the SCREEN 2 name table
 for a tile-by-tile side-scroll. **Gotcha:** read joystick **port 1**
 (`msx_read_joystick(1)`) — port 0 is the keyboard, which an emulator's gamepad
 doesn't drive.

package/src/platforms/msx/TROUBLESHOOTING.md

@@ -85,5 +85,5 @@ ticker) already do this; copy the pattern for any direct PSG access you write.
 The old `msx_crt0.s` placed the SDCC `_INITIALIZER` area in RAM, so the boot
 copy duplicated uninitialised RAM onto itself: every value-initialised static
 read 0 and BSS was never zeroed. The bundled crt0 has been fixed (ROM-placed
-`_INITIALIZER` + a BSS-zero loop). If a project scaffolded before 2026-06-09
-shows ghost zeros, refresh its `msx_crt0.s` from a new scaffold.
+`_INITIALIZER` + a BSS-zero loop). If a project forked before 2026-06-09
+shows ghost zeros, refresh its `msx_crt0.s` from a freshly forked example.

package/src/platforms/msx/lib/c/msx_hw.h

@@ -87,6 +87,7 @@ void    msx_clear_sprites(void);
 void    msx_vblank_wait(void);
 uint8_t msx_read_joystick(uint8_t stick);
 void    msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol);
+void    msx_psg_noise(uint8_t chan, uint8_t rate, uint8_t vol); /* vol 0 = off */
 void    msx_music(uint8_t on);   /* background melody on channel C — ON by default; 0 = off */
 void    msx_music_tick(void);    /* call once per frame (scaffolds do) */
 void    msx_psg_off(uint8_t chan);

package/src/platforms/msx/lib/c/msx_vdp.c

@@ -146,6 +146,31 @@ void msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol) {
     __asm__("ei");
 }
 
+/* Play NOISE on PSG channel 0/1/2: the AY's one shared noise generator
+ * (reg 6, 5-bit period — bigger = lower rumble) routed into this channel by
+ * clearing its noise-disable mixer bit (reg 7 bits 3-5) while setting its
+ * tone-disable bit. The classic explosion/impact voice.
+ * msx_psg_noise(chan, rate, 0) silences the channel and re-masks its noise
+ * bit (msx_psg_off only re-masks TONE — it doesn't know about noise). */
+void msx_psg_noise(uint8_t chan, uint8_t rate, uint8_t vol) {
+    uint8_t mixer;
+    __asm__("di");                                /* same KEYINT race as above */
+    if (vol) {
+        PSGADDR = 6;                              /* noise period (shared)     */
+        PSGWRITE = (uint8_t)(rate & 0x1F);
+    }
+    PSGADDR = (uint8_t)(8 + chan);
+    PSGWRITE = (uint8_t)(vol & 0x0F);
+    PSGADDR = 7;
+    mixer = PSGREAD;
+    mixer |= (uint8_t)(1 << chan);                /* tone OFF for this channel */
+    if (vol) mixer &= (uint8_t)~(1 << (3 + chan)); /* noise ON  */
+    else     mixer |= (uint8_t)(1 << (3 + chan));  /* noise OFF */
+    PSGADDR = 7;
+    PSGWRITE = mixer;
+    __asm__("ei");
+}
+
 /* Silence a PSG channel: zero its volume and re-disable its tone bit. */
 void msx_psg_off(uint8_t chan) {
     uint8_t mixer;

package/src/platforms/nes/MENTAL_MODEL.md

@@ -207,9 +207,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.
 
-## What `scaffold({op:'project'})` copies into your project
+## What `examples({op:'fork'})` copies into your project
 
-`scaffold({op:'project', platform:"nes", template:"hello_sprite"|"tile_engine"|"default"})`
+`examples({op:'fork', example:"nes/hello_sprite"|"nes/tile_engine"|"nes/default", 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.

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 ──────────────────────────────────────────────── */
@@ -408,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

@@ -146,10 +146,43 @@ void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t
 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 (scaffolds do) */
+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 */