romdev-mcp 0.1.1

package/src/platforms/nes/lib/asm/famitone_bridge.s

@@ -0,0 +1,50 @@
+; famitone_bridge.s — tiny C-callable bridge around FamiTone2's asm entry
+; points. Exposes three cc65 __fastcall__ functions:
+;
+;   void __fastcall__ famitone_init(const uint8_t *music_data);
+;     A/X = lo/hi byte of pointer (cc65 fastcall: last arg in A:X).
+;     Calls FamiToneInit with NTSC = 1.
+;
+;   void __fastcall__ famitone_play(uint8_t song_index);
+;     A = song index. Calls FamiToneMusicPlay.
+;
+;   void __fastcall__ famitone_update(void);
+;     Calls FamiToneUpdate. Wire this once per frame, right after
+;     ppu_wait_nmi() returns.
+;
+; cc65 calling convention notes:
+;   - last arg lives in A (low) / X (high) for word-sized params
+;   - functions clobber A/X/Y freely
+;   - returns: byte in A, word in A:X; void returns ignored
+;
+; The C wrapper names are `_famitone_*` (cc65 prepends an underscore to
+; every C identifier).
+
+.export _famitone_init, _famitone_play, _famitone_update
+
+.import FamiToneInit, FamiToneMusicPlay, FamiToneUpdate
+
+.segment "CODE"
+
+; void __fastcall__ famitone_init(const uint8_t *music_data);
+; cc65 passes the pointer in A (low) / X (high). FamiToneInit wants
+; X (low) / Y (high), with A = 1 for NTSC, 0 for PAL.
+_famitone_init:
+        ; A = lo, X = hi (cc65 fastcall for a single pointer)
+        pha                ; save lo
+        txa
+        tay                ; Y = hi
+        pla
+        tax                ; X = lo
+        lda     #1         ; NTSC
+        jmp     FamiToneInit
+
+; void __fastcall__ famitone_play(uint8_t song);
+; cc65 fastcall passes the single byte in A. FamiToneMusicPlay also
+; takes A = song index, so this is a straight tail-call.
+_famitone_play:
+        jmp     FamiToneMusicPlay
+
+; void __fastcall__ famitone_update(void);
+_famitone_update:
+        jmp     FamiToneUpdate

package/src/platforms/nes/lib/asm/music_data.s

@@ -0,0 +1,238 @@
+;this file for FamiTone2 library generated by text2data tool
+
+; music_data: FamiTone2-format music data, generated by text2data from a
+; FamiTracker .txt export. Bundled as a public-domain example track
+; (Shiru's TestMusic3 from the famitone2d test suite — see LICENSE-FAMITONE).
+; To swap in your own song: run text2data on your .ftm export and replace
+; the bytes below (keep the `_music_data:` label + the RODATA segment).
+.export _music_data
+.segment "RODATA"
+_music_data:
+	.byte 2
+	.word @instruments
+	.word @samples-3
+	.word @song0ch0,@song0ch1,@song0ch2,@song0ch3,@song0ch4,307,256
+	.word @song1ch0,@song1ch1,@song1ch2,@song1ch3,@song1ch4,307,256
+
+@instruments:
+	.byte $b0 ;instrument $00
+	.word @env1,@env0,@env0
+	.byte $00
+	.byte $b0 ;instrument $01
+	.word @env2,@env0,@env0
+	.byte $00
+	.byte $b0 ;instrument $02
+	.word @env3,@env0,@env0
+	.byte $00
+	.byte $b0 ;instrument $03
+	.word @env4,@env0,@env0
+	.byte $00
+
+@samples:
+@env0:
+	.byte $c0,$00,$00
+@env1:
+	.byte $c6,$cf,$cc,$c9,$c7,$c6,$c5,$c4,$c2,$00,$08
+@env2:
+	.byte $c3,$c7,$c5,$c4,$c3,$c2,$c1,$c1,$c0,$00,$08
+@env3:
+	.byte $c4,$c3,$c2,$c1,$c0,$00,$04
+@env4:
+	.byte $c2,$06,$c1,$00,$02
+
+
+@song0ch0:
+	.byte $fb,$07
+@song0ch0loop:
+@ref0:
+	.byte $80,$3a,$85,$84,$30,$80,$32,$83,$2c,$91,$2d,$33,$37,$38,$87,$36
+	.byte $83
+@ref1:
+	.byte $3a,$85,$84,$30,$80,$32,$83,$2c,$91,$33,$33,$33,$30,$30,$83,$30
+	.byte $85
+@ref2:
+	.byte $3a,$85,$84,$30,$80,$32,$83,$2c,$91,$2d,$33,$37,$38,$87,$36,$83
+@ref3:
+	.byte $81,$32,$33,$33,$33,$30,$85,$31,$29,$36,$37,$37,$37,$32,$83,$31
+	.byte $29,$30,$81
+@ref4:
+	.byte $33,$00,$85,$31,$33,$00,$85,$31,$33,$00,$85,$31,$32,$85,$36,$85
+@ref5:
+	.byte $33,$00,$85,$31,$33,$00,$85,$31,$33,$00,$85,$31,$33,$29,$29,$82
+	.byte $28,$81
+	.byte $ff,$0e
+	.word @ref0
+	.byte $ff,$0f
+	.word @ref1
+	.byte $ff,$0e
+	.word @ref2
+	.byte $ff,$13
+	.word @ref3
+	.byte $ff,$10
+	.word @ref4
+	.byte $ff,$11
+	.word @ref5
+	.byte $fd
+	.word @song0ch0loop
+
+@song0ch1:
+@song0ch1loop:
+@ref12:
+	.byte $00,$85,$82,$14,$85,$00,$85,$15,$00,$89,$14,$85,$1b,$01,$1f,$00
+	.byte $81
+@ref13:
+	.byte $00,$85,$14,$85,$00,$85,$15,$00,$89,$14,$85,$1b,$01,$1f,$00,$81
+	.byte $ff,$10
+	.word @ref13
+	.byte $ff,$10
+	.word @ref13
+	.byte $ff,$10
+	.word @ref13
+	.byte $ff,$10
+	.word @ref13
+@ref18:
+	.byte $81,$84,$52,$87,$4a,$83,$52,$87,$4a,$83,$52,$87,$4a,$83,$4e,$87
+	.byte $4e,$81
+@ref19:
+	.byte $81,$52,$87,$4a,$83,$52,$87,$4a,$83,$52,$87,$4a,$85,$49,$48,$85
+@ref20:
+	.byte $81,$52,$87,$4a,$83,$52,$87,$4a,$83,$52,$87,$4a,$83,$4e,$87,$4e
+	.byte $81
+@ref21:
+	.byte $81,$52,$53,$53,$53,$4e,$85,$4f,$49,$4e,$4f,$4f,$4f,$48,$83,$49
+	.byte $40,$85
+	.byte $ff,$10
+	.word @ref12
+	.byte $ff,$10
+	.word @ref13
+	.byte $fd
+	.word @song0ch1loop
+
+@song0ch2:
+@song0ch2loop:
+@ref24:
+	.byte $80,$4b,$3b,$01,$3b,$4b,$3b,$01,$3b,$4b,$3b,$01,$3b,$4b,$3b,$01
+	.byte $3a,$81
+@ref25:
+	.byte $4b,$3b,$01,$3b,$4b,$3b,$01,$3b,$4b,$3b,$01,$3b,$4b,$3b,$01,$3a
+	.byte $81
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $ff,$11
+	.word @ref25
+	.byte $fd
+	.word @song0ch2loop
+
+@song0ch3:
+@song0ch3loop:
+@ref36:
+	.byte $84,$13,$13,$00,$82,$16,$86,$1b,$84,$13,$13,$00,$82,$16,$86,$1b
+	.byte $84,$13,$13,$00,$82,$16,$86,$1b,$84,$13,$13,$00,$82,$16,$86,$1a
+	.byte $81
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $ff,$15
+	.word @ref36
+	.byte $fd
+	.word @song0ch3loop
+
+@song0ch4:
+@song0ch4loop:
+@ref48:
+	.byte $bf
+@ref49:
+	.byte $bf
+@ref50:
+	.byte $bf
+@ref51:
+	.byte $bf
+@ref52:
+	.byte $bf
+@ref53:
+	.byte $bf
+@ref54:
+	.byte $bf
+@ref55:
+	.byte $bf
+@ref56:
+	.byte $bf
+@ref57:
+	.byte $bf
+@ref58:
+	.byte $bf
+@ref59:
+	.byte $bf
+	.byte $fd
+	.word @song0ch4loop
+
+
+@song1ch0:
+	.byte $fb,$06
+@song1ch0loop:
+@ref60:
+	.byte $bf
+	.byte $fd
+	.word @song1ch0loop
+
+@song1ch1:
+@song1ch1loop:
+@ref61:
+	.byte $bf
+	.byte $fd
+	.word @song1ch1loop
+
+@song1ch2:
+@song1ch2loop:
+@ref62:
+	.byte $82,$33,$00,$89,$33,$00,$89,$33,$00,$89,$2d,$01,$2c,$85
+	.byte $fd
+	.word @song1ch2loop
+
+@song1ch3:
+@song1ch3loop:
+@ref63:
+	.byte $84,$16,$00,$83,$16,$00,$83,$16,$00,$83,$12,$00,$83,$16,$00,$83
+	.byte $16,$00,$83,$16,$00,$83,$12,$00,$83
+	.byte $fd
+	.word @song1ch3loop
+
+@song1ch4:
+@song1ch4loop:
+@ref64:
+	.byte $bf
+	.byte $fd
+	.word @song1ch4loop

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

@@ -0,0 +1,81 @@
+/* chr_ram_runtime_hello_sprite.c — canonical NES sprite-render pattern.
+ *
+ * This is the "does my NES build pipeline work" sanity check. If
+ * this compiles and shows a moving square, your toolchain + runtime
+ * + linker preset are all wired correctly. Use as the starting
+ * point for any sprite-driven game.
+ *
+ * Build with:
+ *   buildSource({platform:"nes", linkerConfig:"chr-ram-runtime",
+ *                sources:{"main.c": <this>, "nes_runtime.c": <runtime>},
+ *                includes:{"nes_runtime.h": <header>}})
+ *
+ * What this demonstrates (each footgun cost a previous agent rounds):
+ *
+ * 1. Init order: ppu_off → upload CHR → upload palette → seed OAM
+ *    → ppu_on_all. CHR/palette uploads only land while rendering is
+ *    OFF. Inverting this order = "tiles never appear."
+ *
+ * 2. Loop order: stage shadow_oam → ppu_wait_nmi (NOT wait_nmi then
+ *    stage). The NMI handler DMAs shadow_oam at vblank start;
+ *    populate it BEFORE sleeping or you'll DMA stale data.
+ *
+ * 3. Sprite Y is screen-Y minus 1 (hardware off-by-one). oam_spr
+ *    handles this for you — pass screen Y directly.
+ *
+ * 4. Sprite pattern table is at $0000 by default (PPUCTRL bit 3 = 0).
+ *    Upload sprite tiles via chr_ram_upload(0x0000 + tile*16, ...),
+ *    NOT 0x1000 (that's the BG pattern table).
+ */
+#include "nes_runtime.h"
+
+/* 8x8 hollow-square sprite tile (2bpp NES format, two planes). */
+static const uint8_t sprite_tile[16] = {
+  /* plane 0 (low bit of each pixel — color 1 fills the outline) */
+  0xFF, 0x81, 0x81, 0x81, 0x81, 0x81, 0x81, 0xFF,
+  /* plane 1 (high bit — zero, so all pixels are color 1) */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+
+/* 32-byte palette. Sprite palette 0 (entries 16-19) defines the
+ * outline color. Color 0 of every palette is the universal backdrop
+ * — set $0F (black) to avoid the "wrong colour" footgun. */
+static const uint8_t palette[32] = {
+  /* BG palettes 0-3 */
+  0x0F, 0x30, 0x10, 0x00,
+  0x0F, 0x21, 0x11, 0x01,
+  0x0F, 0x27, 0x17, 0x07,
+  0x0F, 0x2A, 0x1A, 0x0A,
+  /* Sprite palettes 0-3 — palette 0 colour 1 = light blue */
+  0x0F, 0x2C, 0x12, 0x32,
+  0x0F, 0x21, 0x11, 0x01,
+  0x0F, 0x27, 0x17, 0x07,
+  0x0F, 0x2A, 0x1A, 0x0A,
+};
+
+void main(void) {
+  uint8_t px = 124;       /* mid-screen X */
+  uint8_t py = 110;       /* mid-screen Y (avoid row 0 — see footgun #1) */
+  uint8_t pad;
+
+  /* ── 1. Init (rendering OFF — safe to write VRAM) ─────────── */
+  ppu_off();
+  chr_ram_upload(0x0010, sprite_tile, 16);    /* tile 1 of sprite pattern table */
+  palette_load(palette);
+  oam_clear();
+  oam_spr(px, py, /* tile */ 1, /* attr */ 0);
+  ppu_on_all();
+
+  /* ── 2. Game loop — stage FIRST, then wait ──────────────────── */
+  for (;;) {
+    oam_clear();
+    oam_spr(px, py, 1, 0);          /* stage sprite at current px/py */
+    ppu_wait_nmi();                  /* NMI DMAs the sprite we just staged */
+
+    pad = pad_poll(0);
+    if (pad & PAD_LEFT)  --px;
+    if (pad & PAD_RIGHT) ++px;
+    if (pad & PAD_UP)    --py;
+    if (pad & PAD_DOWN)  ++py;
+  }
+}

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

@@ -0,0 +1,101 @@
+/* chr_ram_runtime_hud_row.c — BG-layer HUD: score + label at row 2.
+ *
+ * Demonstrates the queued-VRAM-writes pattern for updating BG
+ * during gameplay. Use as the starting point for any game that
+ * needs a score display, lives counter, or persistent on-screen
+ * text.
+ *
+ * Build with:
+ *   buildSource({platform:"nes", linkerConfig:"chr-ram-runtime",
+ *                sources:{"main.c": <this>, "nes_runtime.c": <runtime>},
+ *                includes:{"nes_runtime.h": <header>}})
+ *
+ * Footguns this avoids:
+ *
+ * 1. HUD at row 2, not row 0. Framebuffer is 256×224 — top 8 px
+ *    (nametable row 0, PPU $2000-$201F) are cropped by overscan.
+ *    Always position visible BG at rows 2-27.
+ *
+ * 2. BG pattern table is at $1000 (PPUCTRL bit 4 = 1 by default).
+ *    Upload BG tiles via chr_ram_upload(0x1000 + tile*16, ...),
+ *    NOT 0x0000 (that's the sprite pattern table).
+ *
+ * 3. Updates use tile_set() which queues into vram_queue. The NMI
+ *    handler flushes the queue during vblank — writes during
+ *    rendering would corrupt the PPUADDR latch.
+ *
+ * 4. Decimal-digit rendering goes high-to-low (left-to-right on
+ *    screen) so a "012" score shows as "012" not "210".
+ */
+#include "nes_runtime.h"
+
+/* Tile patterns for digits 0-9, each 16 bytes (2bpp NES format).
+ * Plane 0 = outline, plane 1 = 0. So digits render in color 1. */
+static const uint8_t digit_tiles[10][16] = {
+  /* '0' */ { 0x3C,0x66,0x66,0x66,0x66,0x66,0x66,0x3C, 0,0,0,0,0,0,0,0 },
+  /* '1' */ { 0x18,0x38,0x18,0x18,0x18,0x18,0x18,0x7E, 0,0,0,0,0,0,0,0 },
+  /* '2' */ { 0x3C,0x66,0x06,0x0C,0x18,0x30,0x60,0x7E, 0,0,0,0,0,0,0,0 },
+  /* '3' */ { 0x3C,0x66,0x06,0x1C,0x06,0x06,0x66,0x3C, 0,0,0,0,0,0,0,0 },
+  /* '4' */ { 0x0C,0x1C,0x3C,0x6C,0x7E,0x0C,0x0C,0x0C, 0,0,0,0,0,0,0,0 },
+  /* '5' */ { 0x7E,0x60,0x60,0x7C,0x06,0x06,0x66,0x3C, 0,0,0,0,0,0,0,0 },
+  /* '6' */ { 0x3C,0x66,0x60,0x7C,0x66,0x66,0x66,0x3C, 0,0,0,0,0,0,0,0 },
+  /* '7' */ { 0x7E,0x06,0x0C,0x18,0x18,0x18,0x18,0x18, 0,0,0,0,0,0,0,0 },
+  /* '8' */ { 0x3C,0x66,0x66,0x3C,0x66,0x66,0x66,0x3C, 0,0,0,0,0,0,0,0 },
+  /* '9' */ { 0x3C,0x66,0x66,0x66,0x3E,0x06,0x66,0x3C, 0,0,0,0,0,0,0,0 },
+};
+
+static const uint8_t palette[32] = {
+  0x0F, 0x30, 0x16, 0x00,    /* BG pal 0: backdrop / white / red / black */
+  0x0F, 0x30, 0x16, 0x00,
+  0x0F, 0x30, 0x16, 0x00,
+  0x0F, 0x30, 0x16, 0x00,
+  0x0F, 0x30, 0x16, 0x00,    /* sprite pals (unused here) */
+  0x0F, 0x30, 0x16, 0x00,
+  0x0F, 0x30, 0x16, 0x00,
+  0x0F, 0x30, 0x16, 0x00,
+};
+
+/* Draw a 3-digit decimal number at nametable (x, 2). High digit on
+ * the LEFT (canonical reading order). */
+static void draw_score(uint8_t x, uint16_t value) {
+  uint8_t hundreds = (uint8_t)((value / 100) % 10);
+  uint8_t tens     = (uint8_t)((value / 10)  % 10);
+  uint8_t ones     = (uint8_t)(value % 10);
+  /* Tiles 0x10..0x19 hold digits 0..9 in BG pattern table.
+   * tile_set queues — NMI flushes during vblank. */
+  tile_set(0, x,     2, (uint8_t)(0x10 + hundreds));
+  tile_set(0, x + 1, 2, (uint8_t)(0x10 + tens));
+  tile_set(0, x + 2, 2, (uint8_t)(0x10 + ones));
+}
+
+void main(void) {
+  uint16_t score = 0;
+  uint8_t frame = 0;
+
+  /* ── 1. Init (PPU off) ────────────────────────────────────── */
+  ppu_off();
+
+  /* Upload digit tiles into BG pattern table at $1100 = tile slot $10.
+   * 10 digits × 16 bytes = 160 bytes total. */
+  chr_ram_upload(0x1100, &digit_tiles[0][0], 160);
+
+  palette_load(palette);
+
+  /* Initial score render — queued, will flush at next NMI. Since
+   * rendering is OFF now, the queued writes happen in the first
+   * NMI after ppu_on_all (which is when NMI fires for the first time). */
+  draw_score(/* col */ 14, score);
+
+  ppu_on_all();
+
+  /* ── 2. Game loop ────────────────────────────────────────── */
+  for (;;) {
+    ++frame;
+    if (frame == 0) {            /* every 256 frames (~4 seconds) */
+      ++score;
+      if (score > 999) score = 0;
+      draw_score(14, score);     /* re-queue the 3 digit cells */
+    }
+    ppu_wait_nmi();              /* NMI flushes the queue + DMAs OAM */
+  }
+}