romdevtools 0.28.0 → 0.29.0

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;