romdevtools 0.28.0 → 0.30.0

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.
 

package/src/platforms/pce/TROUBLESHOOTING.md

@@ -66,4 +66,4 @@ 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` scaffold helper and the music ticker default loud.)
+(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. */

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.
 
@@ -325,7 +325,7 @@ 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/snes/MENTAL_MODEL.md

@@ -253,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/`:
@@ -296,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

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.cfg

@@ -19,13 +19,15 @@
 #   3. Write CHR data from C at runtime: PPUADDR = 0x00; PPUDATA = byte; etc.
 
 SYMBOLS {
-    # Stack is $0200 (512 B) so the top RAM page ($0700-$07FF) can be
-    # reserved below for a music driver's scratch RAM (FamiTone2 et al.),
-    # which needs a dedicated, page-aligned block that the C BSS/DATA
-    # region must NOT overlap. Tiny NROM scaffolds use far less than 512 B
-    # of stack, so this is safe; scaffolds with no music driver simply
-    # leave the reserved page unused.
-    __STACKSIZE__: type = weak, value = $0200;
+    # C parameter stack is ONE page ($0600-$06FF, grows down from $0700).
+    # NROM-sized C games use far less than 256 B of it (shallow call
+    # depth, mostly static data), and shrinking it frees $0500-$05FF as
+    # the USER SCRATCH PAGE: game code may place absolute-addressed
+    # arrays there (e.g. `#define BOARD ((unsigned char*)0x0500)`) when
+    # BSS ($0300-$04FF) is full — the puzzle example game does exactly
+    # this. The top page ($0700-$07FF) stays reserved for a music
+    # driver's scratch RAM (FamiTone2 et al.).
+    __STACKSIZE__: type = weak, value = $0100;
 }
 MEMORY {
     ZP:     file = "", start = $0002, size = $001A, type = rw, define = yes;
@@ -41,7 +43,10 @@ MEMORY {
 
     # NO ROM2 / CHARS — this is the whole point of the CHR-RAM preset.
 
-    SRAM:   file = "", start = $0500, size = __STACKSIZE__, define = yes;
+    # $0500-$05FF: user scratch page (see SYMBOLS note) — NOT a segment;
+    # game code addresses it absolutely so the linker never places
+    # anything here.
+    SRAM:   file = "", start = $0600, size = __STACKSIZE__, define = yes;
 
     # Reserved page for a sound-driver's RAM scratch ($0700-$07FF). The
     # bundled FamiTone2 engine (music_demo scaffold) pins FT_BASE_ADR here

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.crt0.s

@@ -28,7 +28,12 @@
         .import         _main, zerobss, copydata
         .import         __RAM_START__, __RAM_SIZE__
         .import         __SRAM_START__, __SRAM_SIZE__
-        .import         _vram_queue_flush
+        .import         _vram_q_hi, _vram_q_lo, _vram_q_val
+        .import         _vram_queue_head, _vram_queue_len, _vram_queue_lock
+
+; Must match nes_runtime.c (QUEUE_MAX 32 ring buffer).
+QUEUE_MASK   = 31
+FLUSH_BUDGET = 16
         .import         _scroll_x, _scroll_y, _ppuctrl_value, _nmi_counter
         .importzp       c_sp
 
@@ -39,7 +44,12 @@
         .byte   $4e, $45, $53, $1a   ; "NES" + EOF
         .byte   2                    ; PRG-ROM banks (16K each) → 32K
         .byte   0                    ; CHR-ROM banks (8K each)  → 0 = CHR-RAM
-        .byte   %00000001            ; flags6 — vertical mirroring
+        .byte   %00000011            ; flags6 — vertical mirroring + BATTERY.
+                                     ; The battery bit maps persistent 8KB
+                                     ; PRG-RAM at $6000 (the save_ram region)
+                                     ; — hiscore_load/save in nes_runtime use
+                                     ; it. Benign when unused; without it,
+                                     ; $6000-$7FFF is OPEN BUS on NROM.
         .byte   %00000000            ; flags7 — mapper hi nybble
         .byte   0, 0, 0, 0, 0, 0, 0, 0
 
@@ -129,9 +139,46 @@ nmi:
         lda     #$02            ; high byte of $0200
         sta     $4014           ; PPU OAMDMA — kicks off the copy
 
-        ; Flush the VRAM queue (writes anything game code stashed via
-        ; vram_set / tile_set / tile_set_palette). PPU is unlocked here.
-        jsr     _vram_queue_flush
+        ; ── Drain the VRAM queue — IN ASSEMBLY, on purpose ──────────────
+        ; Vblank is ~2273 CPU cycles and the OAM DMA above just spent 513.
+        ; Compiled C costs 200+ cycles per queue entry, so a C flush blows
+        ; past the end of vblank — and PPUDATA writes during ACTIVE
+        ; RENDERING land at corrupted addresses (the PPU's internal v
+        ; register is busy fetching tiles; its coarse-X/fine-Y counters
+        ; shear every late write). This loop costs ~40 cycles per entry,
+        ; so FLUSH_BUDGET entries always finish safely inside vblank.
+        ; QUEUE_MASK/FLUSH_BUDGET must match nes_runtime.c's ring buffer.
+        lda     _vram_queue_lock
+        bne     @flush_done     ; a push is mid-flight — skip this vblank
+        lda     _vram_queue_len
+        beq     @flush_done
+        cmp     #FLUSH_BUDGET
+        bcc     @flush_n_ok
+        lda     #FLUSH_BUDGET
+@flush_n_ok:
+        sta     nmi_drain       ; loop counter
+        sta     nmi_drained     ; remembered for the length update
+        bit     $2002           ; reset the PPUADDR write latch
+        ldx     _vram_queue_head
+@flush_loop:
+        lda     _vram_q_hi,x
+        sta     $2006
+        lda     _vram_q_lo,x
+        sta     $2006
+        lda     _vram_q_val,x
+        sta     $2007
+        inx
+        txa
+        and     #QUEUE_MASK     ; ring wrap
+        tax
+        dec     nmi_drain
+        bne     @flush_loop
+        stx     _vram_queue_head
+        lda     _vram_queue_len
+        sec
+        sbc     nmi_drained
+        sta     _vram_queue_len
+@flush_done:
 
         ; Reset PPUADDR to $2000 (otherwise the queue's last $2006 write
         ; leaves it dangling and the PPU samples random VRAM as the BG).
@@ -172,6 +219,12 @@ irq:    rti
 _shadow_oam: .res 256
 
 ; ------------------------------------------------------------------------
+; NMI-private temporaries — deliberately NOT cc65's zp tmp1-4 (the NMI
+; would corrupt them under interrupted C code).
+.segment "BSS"
+nmi_drain:   .res 1
+nmi_drained: .res 1
+
 .segment "VECTORS"
         .word   nmi             ; $FFFA
         .word   start           ; $FFFC

package/src/toolchains/cc65/presets/nes/chr-rom.crt0.s

@@ -22,7 +22,12 @@
         .import         _main, zerobss, copydata
         .import         __RAM_START__, __RAM_SIZE__
         .import         __SRAM_START__, __SRAM_SIZE__
-        .import         _vram_queue_flush
+        .import         _vram_q_hi, _vram_q_lo, _vram_q_val
+        .import         _vram_queue_head, _vram_queue_len, _vram_queue_lock
+
+; Must match nes_runtime.c (QUEUE_MAX 32 ring buffer).
+QUEUE_MASK   = 31
+FLUSH_BUDGET = 16
         .import         _scroll_x, _scroll_y, _ppuctrl_value, _nmi_counter
         .importzp       c_sp
 
@@ -109,8 +114,46 @@ nmi:
         lda     #$02            ; high byte of $0200
         sta     $4014           ; PPU OAMDMA — kicks off the copy
 
-        ; Flush the VRAM queue (nametable/palette writes game code stashed).
-        jsr     _vram_queue_flush
+        ; ── Drain the VRAM queue — IN ASSEMBLY, on purpose ──────────────
+        ; Vblank is ~2273 CPU cycles and the OAM DMA above just spent 513.
+        ; Compiled C costs 200+ cycles per queue entry, so a C flush blows
+        ; past the end of vblank — and PPUDATA writes during ACTIVE
+        ; RENDERING land at corrupted addresses (the PPU's internal v
+        ; register is busy fetching tiles; its coarse-X/fine-Y counters
+        ; shear every late write). This loop costs ~40 cycles per entry,
+        ; so FLUSH_BUDGET entries always finish safely inside vblank.
+        ; QUEUE_MASK/FLUSH_BUDGET must match nes_runtime.c's ring buffer.
+        lda     _vram_queue_lock
+        bne     @flush_done     ; a push is mid-flight — skip this vblank
+        lda     _vram_queue_len
+        beq     @flush_done
+        cmp     #FLUSH_BUDGET
+        bcc     @flush_n_ok
+        lda     #FLUSH_BUDGET
+@flush_n_ok:
+        sta     nmi_drain       ; loop counter
+        sta     nmi_drained     ; remembered for the length update
+        bit     $2002           ; reset the PPUADDR write latch
+        ldx     _vram_queue_head
+@flush_loop:
+        lda     _vram_q_hi,x
+        sta     $2006
+        lda     _vram_q_lo,x
+        sta     $2006
+        lda     _vram_q_val,x
+        sta     $2007
+        inx
+        txa
+        and     #QUEUE_MASK     ; ring wrap
+        tax
+        dec     nmi_drain
+        bne     @flush_loop
+        stx     _vram_queue_head
+        lda     _vram_queue_len
+        sec
+        sbc     nmi_drained
+        sta     _vram_queue_len
+@flush_done:
 
         ; Reset PPUADDR to $2000 so the PPU doesn't sample random VRAM as BG.
         bit     $2002
@@ -147,6 +190,12 @@ irq:    rti
 _shadow_oam: .res 256
 
 ; ------------------------------------------------------------------------
+; NMI-private temporaries — deliberately NOT cc65's zp tmp1-4 (the NMI
+; would corrupt them under interrupted C code).
+.segment "BSS"
+nmi_drain:   .res 1
+nmi_drained: .res 1
+
 .segment "VECTORS"
         .word   nmi             ; $FFFA
         .word   start           ; $FFFC

package/src/toolchains/cc65/presets/pce/rom32k.cfg

@@ -0,0 +1,52 @@
+# PC Engine 32KB HuCard ld65 config (romdev 'rom32k' preset).
+#
+# WHY THIS EXISTS: cc65's stock pce.cfg defaults to an 8KB image, and its
+# documented 16K/32K option ($CARTSIZE) places STARTUP/VECTORS at the END of
+# the file — but a HuCard maps file offset 0 as bank 0, and the HuC6280 reset
+# maps MPR7 (=$E000-$FFFF, where the vectors live) to BANK 0. So a stock-cfg
+# 32K image boots to a black screen (verified on geargrafx). This config puts
+# bank 0 (STARTUP/VECTORS + hot code) FIRST in the file, at $E000, and the
+# remaining 24KB of banks 1-3 at $8000-$DFFF — exactly where cc65's pce crt0
+# TAMs them (MPR4=bank1, MPR5=bank2, MPR6=bank3) before calling main().
+SYMBOLS {
+    __CARTSIZE__:  type = weak, value = $8000; # crt0 compares >$8000 vs this
+    __STACKSIZE__: type = weak, value = $0300; # 3 pages stack
+}
+MEMORY {
+    ZP:   file = "", start = $0000, define = yes, size = $0100;
+    # RAM bank ($F8 at MPR1)
+    MAIN: file = "", start = $2200, define = yes, size = $1E00 - __STACKSIZE__;
+    # HuCard bank 0 — hardware maps it at $E000 (MPR7) at reset. File offset 0.
+    ROM0: file = %O, start = $E000, size = $2000, fill = yes, fillval = $FF;
+    # HuCard banks 1-3 — crt0 maps them at $8000/$A000/$C000 (MPR4/5/6).
+    ROM:  file = %O, start = $8000, size = $6000, fill = yes, fillval = $FF;
+}
+SEGMENTS {
+    ZEROPAGE: load = ZP,   type = zp;
+    EXTZP:    load = ZP,   type = zp, optional = yes;
+    APPZP:    load = ZP,   type = zp, optional = yes;
+    DATA:     load = ROM0, run = MAIN, type = rw,  define = yes;
+    INIT:     load = MAIN, type = bss, optional = yes;
+    BSS:      load = MAIN, type = bss,             define = yes;
+    LOWCODE:  load = ROM0, type = ro,  optional = yes;
+    ONCE:     load = ROM0, type = ro,  optional = yes;
+    CODE:     load = ROM,  type = ro;
+    RODATA:   load = ROM,  type = ro;
+    STARTUP:  load = ROM0, type = ro,  start = $FFF6 - $0066;
+    VECTORS:  load = ROM0, type = ro,  start = $FFF6;
+}
+FEATURES {
+    CONDES: type    = constructor,
+            label   = __CONSTRUCTOR_TABLE__,
+            count   = __CONSTRUCTOR_COUNT__,
+            segment = ONCE;
+    CONDES: type    = destructor,
+            label   = __DESTRUCTOR_TABLE__,
+            count   = __DESTRUCTOR_COUNT__,
+            segment = RODATA;
+    CONDES: type    = interruptor,
+            label   = __INTERRUPTOR_TABLE__,
+            count   = __INTERRUPTOR_COUNT__,
+            segment = RODATA,
+            import  = __CALLIRQ__;
+}

package/src/toolchains/index.js

@@ -37,7 +37,7 @@ const CC65_TARGET = {
 const LANGUAGE_TOOLCHAIN = {
   atari2600: {
     asm:    { toolchain: "dasm",         available: true },
-    basic:  { toolchain: "batariBasic",  available: false, note: "BASIC for 2600 via batariBasic — not bundled. bB's transpiler is written in Perl, which we don't ship as WASM. A port to C or JS would be a multi-day project. For now, write 2600 games in 6507 asm via dasm — the bundled scaffolds (default, paddle, single_screen) show the canonical race-the-beam pattern, and an LLM agent writes 2600 asm fluently." },
+    basic:  { toolchain: "batariBasic",  available: false, note: "BASIC for 2600 via batariBasic — not bundled. bB's transpiler is written in Perl, which we don't ship as WASM. A port to C or JS would be a multi-day project. For now, write 2600 games in 6507 asm via dasm — the bundled example games (default, paddle, single_screen) show the canonical race-the-beam pattern, and an LLM agent writes 2600 asm fluently." },
   },
   nes: {
     asm: { toolchain: "cc65",  available: true },
@@ -65,11 +65,11 @@ const LANGUAGE_TOOLCHAIN = {
   },
   snes: {
     asm: { toolchain: "asar",       available: true },
-    c:   { toolchain: "tcc816+wladx", available: true, note: "C for SNES via tcc-65816 + wla-65816 + wlalink. The PVSnesLib runtime IS bundled (built from source) and auto-linked — #include <snes.h> gives you consoleDrawText, setMode, oamSet, WaitForVBlank, etc. out of the box. `createGame`/`createProject` scaffold a complete PVSnesLib C project. Pass options.pvsneslib:false for the bare-main minimum-viable path." },
+    c:   { toolchain: "tcc816+wladx", available: true, note: "C for SNES via tcc-65816 + wla-65816 + wlalink. The PVSnesLib runtime IS bundled (built from source) and auto-linked — #include <snes.h> gives you consoleDrawText, setMode, oamSet, WaitForVBlank, etc. out of the box. `examples({op:'fork'})` gives you a complete working PVSnesLib C project. Pass options.pvsneslib:false for the bare-main minimum-viable path." },
   },
   genesis: {
     asm: { toolchain: "vasm68k",      available: true },
-    c:   { toolchain: "m68k-elf-gcc", available: true, note: "C for Genesis via gcc 14.2.0 + binutils + newlib, all compiled to WASM. The SGDK runtime IS bundled (built from source) and auto-linked — sprite engine, VDP, controller, PSG/Z80 sound, resource helpers all work; #include <genesis.h>. `createGame`/`createProject` scaffold a complete SGDK C project (the recommended path). Pass options.sgdk:false for the bare-gcc minimum-viable path." },
+    c:   { toolchain: "m68k-elf-gcc", available: true, note: "C for Genesis via gcc 14.2.0 + binutils + newlib, all compiled to WASM. The SGDK runtime IS bundled (built from source) and auto-linked — sprite engine, VDP, controller, PSG/Z80 sound, resource helpers all work; #include <genesis.h>. `examples({op:'fork'})` gives you a complete working SGDK C project (the recommended path). Pass options.sgdk:false for the bare-gcc minimum-viable path." },
   },
   gba: {
     c: { toolchain: "arm-none-eabi-gcc", available: true, note: "C for GBA via gcc 14.2.0 + binutils + newlib + libtonc 1.4.5 (default) OR libgba 0.5.4 (opt-in via runtime:\"libgba\"), all compiled to WASM (R24 + R28). #include <tonc.h> + tte_write/tte_printf works out of the box — that's the canonical Tonc-tutorial API every published GBA C resource uses. Caveat: tte_iohook (libtonc) and console.c (libgba) — the libsysbase-backed iprintf bridges — are NOT bundled. Use tte_printf directly, which is what the Tonc tutorial actually does." },
@@ -91,7 +91,7 @@ const LANGUAGE_TOOLCHAIN = {
  * Default language per platform. The choice reflects what's fastest /
  * smallest / best-matched to LLM fluency. Every platform that has a bundled
  * C compiler + runtime defaults to C — that's the canonical, productive path
- * and what `createGame`/`createProject` scaffold (cc65 for NES/C64/Atari7800/
+ * and what `examples({op:'fork'})` projects use (cc65 for NES/C64/Atari7800/
  * Lynx, SDCC for GB/GBC/SMS/GG, gcc+SGDK for Genesis, tcc+PVSnesLib for SNES,
  * gcc+libtonc for GBA). Platforms whose only bundled toolchain is an assembler
  * default to asm (Atari 2600 → dasm; SNES/Genesis keep an asm option too, but
@@ -743,10 +743,9 @@ export async function buildForPlatform(args) {
     // crt0 + headers + sources come straight from the caller. The build
     // pipeline does NOT auto-inject platform runtimes, custom crt0s,
     // or post-link header patches. Every byte that compiles is visible
-    // to the caller's repo. Use `createProject({platform, template})`
-    // to scaffold a self-contained project with the runtime files
-    // copied in, or call `getStarterSnippet` / `getAllStarterSnippets`
-    // to fetch individual pieces.
+    // to the caller's repo. Use `examples({op:'fork'})` to get a
+    // self-contained project with the runtime files copied in, or
+    // `examples({op:'snippets'/'copySnippets'})` to fetch individual pieces.
     const crt0 = args.crt0;
 
     // Pre-flight lint: scan the C sources for known SDCC C89 violations
@@ -787,10 +786,27 @@ export async function buildForPlatform(args) {
       // and RAM-size ($0149) bytes — without -m/-r, -v leaves them at the
       // linker's garbage pad (e.g. type $3C), and emulators/hardware reject
       // an unknown MBC type with "retro_load_game failed". -m 0x00 = ROM ONLY
-      // (no mapper), -r 0x00 = no cart RAM — correct for these 32KB scaffolds.
+      // (no mapper), -r 0x00 = no cart RAM — correct for plain 32KB builds.
+      //
+      // Battery-cart passthrough (0.29.0 examples): a crt0 may DECLARE the
+      // cart in the header window (the GB equivalent of the NES crt0's iNES
+      // BATTERY bit — see the gbc lib gb_crt0.s, which emits $0147=$03 /
+      // $0149=$02 for MBC1+RAM+BATTERY so hi-scores persist in SAVE_RAM).
+      // If the linked image carries a KNOWN battery-MBC type byte with a
+      // sane RAM size, pass those through to rgbfix instead of stomping
+      // them to ROM-only; anything unrecognized (linker pad garbage) still
+      // falls back to the safe ROM-only default, so crt0s that don't
+      // declare a cart behave exactly as before.
+      const BATTERY_CART_TYPES = new Set([0x03, 0x06, 0x0F, 0x10, 0x13, 0x1B, 0x1E]); // MBC1/2/3/5 +BATTERY variants
+      const declType = binary.length > 0x149 ? binary[0x147] : 0x00;
+      const declRam = binary.length > 0x149 ? binary[0x149] : 0x00;
+      const cartByte = BATTERY_CART_TYPES.has(declType) ? declType : 0x00;
+      const ramByte = cartByte !== 0x00 && declRam >= 0x01 && declRam <= 0x05 ? declRam : 0x00;
+      const mArg = "0x" + cartByte.toString(16).padStart(2, "0").toUpperCase();
+      const rArg = "0x" + ramByte.toString(16).padStart(2, "0").toUpperCase();
       const fixOpts = args.platform === "gbc"
-        ? ["-v", "-p", "0xFF", "-C", "-m", "0x00", "-r", "0x00"]
-        : ["-v", "-p", "0xFF", "-m", "0x00", "-r", "0x00"];
+        ? ["-v", "-p", "0xFF", "-C", "-m", mArg, "-r", rArg]
+        : ["-v", "-p", "0xFF", "-m", mArg, "-r", rArg];
       const fix = await runRgbfix({ rom: binary, options: fixOpts });
       if (fix.exitCode === 0 && fix.binary) {
         binary = fix.binary;