romdev-mcp 0.1.1

package/examples/atari7800/templates/shmup.c

@@ -0,0 +1,148 @@
+/* shmup.c — Atari 7800 vertical-shooter (minimal player + bullets).
+ *
+ * SCAFFOLD CAVEAT: the original "shmup with 4 enemies + 4 bullets"
+ * exceeded the per-scanline DL pool budget within 7800's 2 KB RAM1
+ * (a per-scanline pool with computed row addresses ran into a
+ * cc65 BSS placement issue that needs further investigation).
+ *
+ * This minimal scaffold demonstrates: player ship that moves with
+ * the joystick, fires bullets on FIRE button. Bullets travel up and
+ * disappear at top. Extend with enemies + collision once the
+ * per-scanline-pool approach is debugged.
+ *
+ * Uses the same per-row DL pattern as default.c (1-scanline zones,
+ * 7-byte DLs, 243-entry DLL) — see MENTAL_MODEL.md for the format.
+ */
+#include <stdint.h>
+#include "atari7800_sfx.h"
+
+#define BACKGRND  (*(volatile uint8_t*)0x20)
+#define P0C1      (*(volatile uint8_t*)0x21)
+#define P0C2      (*(volatile uint8_t*)0x22)
+#define P0C3      (*(volatile uint8_t*)0x23)
+#define MSTAT     (*(volatile uint8_t*)0x28)
+#define DPPH      (*(volatile uint8_t*)0x2C)
+#define DPPL      (*(volatile uint8_t*)0x30)
+#define CHARBASE  (*(volatile uint8_t*)0x34)
+#define OFFSET    (*(volatile uint8_t*)0x38)
+#define CTRL      (*(volatile uint8_t*)0x3C)
+#define SWCHA     (*(volatile uint8_t*)0x280)
+#define INPT4     (*(volatile uint8_t*)0x0C)
+
+#define JOY_UP    0x80
+#define JOY_DOWN  0x40
+#define JOY_LEFT  0x20
+#define JOY_RIGHT 0x10
+
+/* Ship sprite — 16 px wide × 8 rows. */
+static const uint8_t ship_row0[4] = { 0x00, 0x05, 0x50, 0x00 };
+static const uint8_t ship_row1[4] = { 0x00, 0x5A, 0xA5, 0x00 };
+static const uint8_t ship_row2[4] = { 0x05, 0xAA, 0xAA, 0x50 };
+static const uint8_t ship_row3[4] = { 0x5A, 0xFF, 0xFF, 0xA5 };
+static const uint8_t ship_row4[4] = { 0xAA, 0xFF, 0xFF, 0xAA };
+static const uint8_t ship_row5[4] = { 0xAA, 0xAA, 0xAA, 0xAA };
+static const uint8_t ship_row6[4] = { 0x05, 0x05, 0x50, 0x50 };
+static const uint8_t ship_row7[4] = { 0x00, 0x05, 0x50, 0x00 };
+
+#define MK_DL(name) static uint8_t name[7] = { 0, 0x40, 0, 0x1C, 80, 0, 0 }
+MK_DL(dl_row0); MK_DL(dl_row1); MK_DL(dl_row2); MK_DL(dl_row3);
+MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
+
+static uint8_t dl_empty[2] = { 0, 0 };
+
+#define DLL_ZONES 243
+static uint8_t dll[DLL_ZONES * 3];
+
+static int player_x;
+static int player_y;
+
+static void set_dl_addr(uint8_t* dl, const uint8_t* row) {
+  uint16_t a = (uint16_t)(uintptr_t)row;
+  dl[0] = (uint8_t)(a & 0xFF);
+  dl[2] = (uint8_t)(a >> 8);
+}
+
+static void set_dll_entry(int idx, uint16_t dl_ptr) {
+  dll[idx * 3 + 0] = 0;
+  dll[idx * 3 + 1] = (uint8_t)(dl_ptr >> 8);
+  dll[idx * 3 + 2] = (uint8_t)(dl_ptr & 0xFF);
+}
+
+static void set_x(uint8_t x) {
+  dl_row0[4] = x; dl_row1[4] = x; dl_row2[4] = x; dl_row3[4] = x;
+  dl_row4[4] = x; dl_row5[4] = x; dl_row6[4] = x; dl_row7[4] = x;
+}
+
+static void build_dll(int y) {
+  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
+  int i;
+  for (i = 0; i < DLL_ZONES; i++) {
+    uint16_t dl;
+    int d = i - y;
+    switch (d) {
+      case 0: dl = (uint16_t)(uintptr_t)dl_row0; break;
+      case 1: dl = (uint16_t)(uintptr_t)dl_row1; break;
+      case 2: dl = (uint16_t)(uintptr_t)dl_row2; break;
+      case 3: dl = (uint16_t)(uintptr_t)dl_row3; break;
+      case 4: dl = (uint16_t)(uintptr_t)dl_row4; break;
+      case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
+      case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
+      case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
+      default: dl = empty; break;
+    }
+    set_dll_entry(i, dl);
+  }
+}
+
+static void vblank_wait(void) {
+  while (MSTAT & 0x80) { }
+  while (!(MSTAT & 0x80)) { }
+}
+
+void main(void) {
+  uint16_t dll_addr;
+  uint8_t prev_fire = 0;
+
+  set_dl_addr(dl_row0, ship_row0);
+  set_dl_addr(dl_row1, ship_row1);
+  set_dl_addr(dl_row2, ship_row2);
+  set_dl_addr(dl_row3, ship_row3);
+  set_dl_addr(dl_row4, ship_row4);
+  set_dl_addr(dl_row5, ship_row5);
+  set_dl_addr(dl_row6, ship_row6);
+  set_dl_addr(dl_row7, ship_row7);
+
+  player_x = 80;
+  player_y = 180;
+  set_x((uint8_t)player_x);
+  build_dll(player_y);
+
+  BACKGRND = 0x00;   /* black space */
+  P0C1     = 0x0F;
+  P0C2     = 0x1C;
+  P0C3     = 0x46;
+  CHARBASE = 0;
+  OFFSET   = 0;
+
+  dll_addr = (uint16_t)(uintptr_t)dll;
+  DPPL = (uint8_t)(dll_addr & 0xFF);
+  DPPH = (uint8_t)(dll_addr >> 8);
+  CTRL = 0x40;
+  sfx_init();
+
+  for (;;) {
+    uint8_t pad, fire_now;
+    vblank_wait();
+    sfx_update();
+
+    pad = ~SWCHA;
+    if (pad & JOY_LEFT  && player_x > 4)        { player_x--; set_x((uint8_t)player_x); }
+    if (pad & JOY_RIGHT && player_x < 152)      { player_x++; set_x((uint8_t)player_x); }
+    if (pad & JOY_UP    && player_y > 30)       { player_y--; build_dll(player_y); }
+    if (pad & JOY_DOWN  && player_y < 200)      { player_y++; build_dll(player_y); }
+
+    fire_now = (INPT4 & 0x80) ? 0 : 1;
+    if (fire_now && !prev_fire) { sfx_tone(0, 8, 4); }
+    prev_fire = fire_now;
+  }
+}

package/examples/atari7800/templates/sports.c

@@ -0,0 +1,207 @@
+/* sports.c — Atari 7800 two-player Pong scaffold.
+ *
+ * 2P Pong via both 7800 joystick ports. SWCHA packs P1 in bits 4-7,
+ * P2 in bits 0-3 (active-low). AI on P2 when no second pad held.
+ *
+ * MARIA pipeline: per-scanline DLs. For every scanline in the play
+ * area, walk every object (P1 paddle, P2 paddle, ball), check if
+ * the object's Y range intersects this scanline, and if so emit a
+ * 5-byte DL header pointing at the correct row of the object's
+ * sprite data. Each scanline DL has space for up to MAX_OBJS
+ * objects + a terminator byte.
+ *
+ * See MENTAL_MODEL.md for the DL/DLL byte-level format. The
+ * per-scanline-zone pattern in default.c is the foundation; this
+ * scales it to multiple objects with independent Y positions.
+ */
+#include <stdint.h>
+#include "atari7800_sfx.h"
+
+#define BACKGRND  (*(volatile uint8_t*)0x20)
+#define P0C1      (*(volatile uint8_t*)0x21)
+#define P0C2      (*(volatile uint8_t*)0x22)
+#define P0C3      (*(volatile uint8_t*)0x23)
+#define MSTAT     (*(volatile uint8_t*)0x28)
+#define DPPH      (*(volatile uint8_t*)0x2C)
+#define DPPL      (*(volatile uint8_t*)0x30)
+#define CHARBASE  (*(volatile uint8_t*)0x34)
+#define OFFSET    (*(volatile uint8_t*)0x38)
+#define CTRL      (*(volatile uint8_t*)0x3C)
+#define SWCHA     (*(volatile uint8_t*)0x280)
+
+#define P1_UP    0x80
+#define P1_DOWN  0x40
+#define P2_UP    0x08
+#define P2_DOWN  0x04
+
+#define PADDLE_W_BYTES  1     /* 1 byte = 4 px wide in 160A */
+#define PADDLE_H       16
+#define BALL_H          4
+#define PADDLE_X1      16
+#define PADDLE_X2     140
+#define PLAY_LINES    100
+#define COURT_TOP      60     /* DLL index */
+#define COURT_BOT     (COURT_TOP + PLAY_LINES)
+
+/* Sprite rows. 0x55 = all 4 pixels = palette index 1 (lit). */
+static const uint8_t solid_row[1] = { 0x55 };
+
+/* Scanline DL pool — one DL per scanline in the play area. Each DL
+ * has slots for up to 3 objects (5 bytes each) + 2 terminator bytes
+ * (1 for the "next entry's mode = 0", 1 for safety). */
+/* Per-line DL capacity: paddles+ball never share a scanline since
+ * they're horizontally separated, so MAX_OBJS=3 fits with margin.
+ * 17 bytes/line × 100 court lines = 1700 B + 729 B DLL = 2429 B —
+ * out of the 7800's 2 KB RAM1, doesn't fit. Use 100 lines × 12B
+ * (MAX=2) = 1200 B + 729 = 1929 B. Fits within 2112 B RAM1. */
+#define MAX_OBJS_PER_LINE  2
+#define DL_BYTES_PER_LINE  (5 * MAX_OBJS_PER_LINE + 2)
+static uint8_t scanline_dls[PLAY_LINES * DL_BYTES_PER_LINE];
+
+static uint8_t dl_empty[2] = { 0, 0 };
+
+#define DLL_ZONES 243
+static uint8_t dll[DLL_ZONES * 3];
+
+static int16_t p1y, p2y, by;
+static int16_t bx;
+static int8_t bdx, bdy;
+
+static void vblank_wait(void) {
+  while (MSTAT & 0x80) { }
+  while (!(MSTAT & 0x80)) { }
+}
+
+static void set_dll_entry(int idx, uint16_t dl_ptr) {
+  dll[idx * 3 + 0] = 0;
+  dll[idx * 3 + 1] = (uint8_t)(dl_ptr >> 8);
+  dll[idx * 3 + 2] = (uint8_t)(dl_ptr & 0xFF);
+}
+
+/* Write a 5-byte DL entry for one object at the given byte offset
+ * within a scanline DL. Returns the new offset. */
+static uint8_t emit_obj(uint8_t* dl, uint8_t off, uint16_t data_addr,
+                        uint8_t width_bytes, uint8_t palette, uint8_t x) {
+  dl[off + 0] = (uint8_t)(data_addr & 0xFF);
+  dl[off + 1] = 0x40;                          /* extended 5-byte form */
+  dl[off + 2] = (uint8_t)(data_addr >> 8);
+  dl[off + 3] = (uint8_t)((palette << 5) | ((32 - width_bytes) & 0x1F));
+  dl[off + 4] = x;
+  return off + 5;
+}
+
+/* Rebuild ALL scanline DLs + DLL based on current object positions. */
+static void rebuild(void) {
+  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
+  uint16_t solid = (uint16_t)(uintptr_t)solid_row;
+  int line;
+  int i;
+
+  /* DLL: point each play-area line at its scanline DL slot; everything
+   * else at the empty DL. */
+  for (i = 0; i < DLL_ZONES; i++) {
+    if (i >= COURT_TOP && i < COURT_BOT) {
+      uint16_t dlp = (uint16_t)(uintptr_t)&scanline_dls[(i - COURT_TOP) * DL_BYTES_PER_LINE];
+      set_dll_entry(i, dlp);
+    } else {
+      set_dll_entry(i, empty);
+    }
+  }
+
+  /* Scanline DLs: for each play-area scanline, walk objects, emit
+   * entries for those whose Y range intersects. */
+  for (line = 0; line < PLAY_LINES; line++) {
+    int abs_y = COURT_TOP + line;
+    uint8_t* dlp = &scanline_dls[line * DL_BYTES_PER_LINE];
+    uint8_t off = 0;
+    int i2;
+    /* Zero the slot so leftover bytes don't form garbage entries. */
+    for (i2 = 0; i2 < DL_BYTES_PER_LINE; i2++) dlp[i2] = 0;
+
+    /* P1 paddle */
+    if (abs_y >= p1y && abs_y < p1y + PADDLE_H) {
+      off = emit_obj(dlp, off, solid, PADDLE_W_BYTES, 0, PADDLE_X1);
+    }
+    /* P2 paddle */
+    if (abs_y >= p2y && abs_y < p2y + PADDLE_H) {
+      off = emit_obj(dlp, off, solid, PADDLE_W_BYTES, 0, PADDLE_X2);
+    }
+    /* Ball */
+    if (abs_y >= by && abs_y < by + BALL_H) {
+      off = emit_obj(dlp, off, solid, PADDLE_W_BYTES, 0, (uint8_t)bx);
+    }
+    /* off points to the byte AFTER the last entry — already 0 from
+     * memset above, which serves as the mode terminator. */
+    (void)off;
+  }
+}
+
+static void serve_ball(uint8_t to_left) {
+  bx = 76;
+  by = 120;
+  bdx = to_left ? -2 : 2;
+  bdy = 1;
+}
+
+void main(void) {
+  uint16_t dll_addr;
+  uint8_t pad;
+  int16_t target;
+
+  p1y = 110; p2y = 110;
+  serve_ball(0);
+
+  BACKGRND = 0x00;   /* black */
+  P0C1     = 0x0F;   /* white sprite */
+  P0C2     = 0x0F;
+  P0C3     = 0x0F;
+  CHARBASE = 0;
+  OFFSET   = 0;
+
+  rebuild();
+
+  dll_addr = (uint16_t)(uintptr_t)dll;
+  DPPL = (uint8_t)(dll_addr & 0xFF);
+  DPPH = (uint8_t)(dll_addr >> 8);
+  CTRL = 0x40;
+  sfx_init();
+
+  for (;;) {
+    vblank_wait();
+    sfx_update();
+
+    pad = (uint8_t)(~SWCHA);
+    if ((pad & P1_UP)   && p1y > COURT_TOP)            p1y -= 2;
+    if ((pad & P1_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 2;
+
+    if (pad & (P2_UP | P2_DOWN)) {
+      if ((pad & P2_UP)   && p2y > COURT_TOP)            p2y -= 2;
+      if ((pad & P2_DOWN) && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+    } else {
+      target = by - PADDLE_H / 2;
+      if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
+      else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
+    }
+
+    bx = bx + bdx;
+    by = by + bdy;
+
+    if (by < COURT_TOP)             { by = COURT_TOP; bdy = -bdy; }
+    if (by + BALL_H > COURT_BOT)    { by = COURT_BOT - BALL_H; bdy = -bdy; }
+
+    /* Paddle collisions */
+    if (bdx < 0 && bx <= PADDLE_X1 + 4 && bx >= PADDLE_X1
+        && by + BALL_H > p1y && by < p1y + PADDLE_H) {
+      bdx = -bdx; bx = PADDLE_X1 + 4;
+    }
+    if (bdx > 0 && bx + 4 >= PADDLE_X2 && bx <= PADDLE_X2 + 4
+        && by + BALL_H > p2y && by < p2y + PADDLE_H) {
+      bdx = -bdx; bx = PADDLE_X2 - 4;
+    }
+    if (bx < 4 || bx > 152) {
+      serve_ball(bx > 80 ? 1 : 0);
+    }
+
+    rebuild();
+  }
+}

package/examples/c64/main.c

@@ -0,0 +1,63 @@
+// ── Hello, C64 — VIC-II direct hardware access demo ──────────────────
+//
+// Bypasses the KERNAL's printf path to show the platform's hardware
+// directly: writes screen codes into screen RAM, sets per-cell colors
+// in color RAM, and cycles the border color in a main loop.
+//
+// Build: buildSource({ platform: "c64", source: <this file>, language: "c" })
+
+#include <stdint.h>
+
+#define VIC_BORDER  (*(volatile uint8_t*)0xD020)
+#define VIC_BG0     (*(volatile uint8_t*)0xD021)
+#define SCREEN_RAM  ((volatile uint8_t*)0x0400)
+#define COLOR_RAM   ((volatile uint8_t*)0xD800)
+
+// PETSCII screen codes for "HELLO ROM-DEV-MCP" (uppercase character set,
+// where 'A' = 0x01, 'B' = 0x02, ...). The space character is 0x20.
+static const uint8_t MESSAGE[] = {
+  0x08, 0x05, 0x0C, 0x0C, 0x0F,        // HELLO
+  0x20,
+  0x12, 0x0F, 0x0D,                    // ROM
+  0x2D,                                // -
+  0x04, 0x05, 0x16,                    // DEV
+  0x2D,                                // -
+  0x0D, 0x03, 0x10,                    // MCP
+};
+#define MESSAGE_LEN (sizeof(MESSAGE) / sizeof(MESSAGE[0]))
+
+static void clear_screen(void) {
+  uint16_t i;
+  for (i = 0; i < 1000; i++) {
+    SCREEN_RAM[i] = 0x20;             // space
+    COLOR_RAM[i] = 14;                 // light blue
+  }
+}
+
+static void draw_message(uint8_t row) {
+  // Center on the row: row starts at offset row*40, center = +12.
+  uint16_t base;
+  uint8_t i;
+  base = row * 40 + (40 - MESSAGE_LEN) / 2;
+  for (i = 0; i < MESSAGE_LEN; i++) {
+    SCREEN_RAM[base + i] = MESSAGE[i];
+    COLOR_RAM[base + i]  = 1;          // white
+  }
+}
+
+void main(void) {
+  uint16_t frame;
+  frame = 0;
+  VIC_BORDER = 0;                      // black border
+  VIC_BG0    = 6;                      // blue background
+
+  clear_screen();
+  draw_message(12);                    // middle of screen
+
+  // Cycle the border color forever. Each iteration is ~1 raster line
+  // worth of CPU; the visible cycle takes hundreds of frames.
+  for (;;) {
+    VIC_BORDER = (uint8_t)(frame >> 4) & 0x0F;
+    frame++;
+  }
+}

package/examples/c64/templates/hello_sprite.c

@@ -0,0 +1,117 @@
+// ── hello_sprite.c — Commodore 64 VIC-II sprite + joystick ──────────
+//
+// One MOB sprite (one of the C64's 8 hardware sprites) driven by the
+// joystick in port 2. The C64 has two joystick ports: port 2 is the
+// agent-friendly default since reading port 1 (`CIA1_PRB`) clashes
+// with the keyboard scan matrix.
+//
+// VIC-II sprite quick reference:
+//   - 8 sprites max, each 24×21 pixels (3 bytes wide × 21 rows = 63 bytes)
+//   - Stored in 64-byte chunks aligned to a "sprite pointer" slot
+//     ($07F8..$07FF) which holds a /64 index into the VIC's 16 KB bank
+//   - Default VIC bank = $0000-$3FFF, so a pointer value of $20 means
+//     sprite data lives at $20 * $40 = $0800
+//   - VIC_SPRITE_X(N) / Y(N) → sprite N position registers
+//   - VIC_SPR_ENA bit N → enable bit for sprite N
+//   - VIC_SPR_COL(N) → per-sprite color (single-color sprites only;
+//     multicolor uses MC0/MC1 + per-sprite multicolor bit)
+//
+// To extend: define more sprites and walk multiple pointer slots; turn
+// on multicolor mode for 4-color sprites via VIC_SPR_MCOLOR bits.
+
+#include "c64_registers.h"
+#include <stdint.h>
+
+#define POKE(addr, val)  (*(volatile uint8_t*)(addr) = (val))
+#define PEEK(addr)       (*(volatile uint8_t*)(addr))
+
+#define SPRITE_POINTERS  ((volatile uint8_t*)0x07F8)
+#define SPRITE_DATA      ((volatile uint8_t*)0x0800)   /* 64 bytes per sprite */
+
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+#define JOY_LEFT  0x04
+#define JOY_RIGHT 0x08
+#define JOY_FIRE  0x10
+
+// 24×21 sprite — a simple filled diamond. Each row is 3 bytes (24 px,
+// 1 bit per pixel = single-color sprite mode).
+static const uint8_t sprite_data[64] = {
+  /* row */
+  0x00,0x18,0x00,
+  0x00,0x3C,0x00,
+  0x00,0x7E,0x00,
+  0x00,0xFF,0x00,
+  0x01,0xFF,0x80,
+  0x03,0xFF,0xC0,
+  0x07,0xFF,0xE0,
+  0x0F,0xFF,0xF0,
+  0x1F,0xFF,0xF8,
+  0x3F,0xFF,0xFC,
+  0x7F,0xFF,0xFE,
+  0x3F,0xFF,0xFC,
+  0x1F,0xFF,0xF8,
+  0x0F,0xFF,0xF0,
+  0x07,0xFF,0xE0,
+  0x03,0xFF,0xC0,
+  0x01,0xFF,0x80,
+  0x00,0xFF,0x00,
+  0x00,0x7E,0x00,
+  0x00,0x3C,0x00,
+  0x00,0x18,0x00,
+  0,  /* padding to 64 bytes */
+};
+
+static void copy_sprite(void) {
+  uint8_t i;
+  for (i = 0; i < 64; i++) SPRITE_DATA[i] = sprite_data[i];
+}
+
+static void wait_vblank(void) {
+  // VIC_RASTER reports the current rasterline. The VBLANK starts when
+  // the raster passes line 250 (visible region is roughly 50..250).
+  // Spinning until we see line 250+ gives us a stable per-frame tick.
+  while (PEEK(VIC_RASTER) < 250) { }
+  while (PEEK(VIC_RASTER) >= 250) { }
+}
+
+void main(void) {
+  uint8_t sx = 160;   /* mid-screen X (sprite X is 0..255, +256 via VIC_SPRITES_X8) */
+  uint8_t sy = 130;
+  uint8_t pad, prev_pad = 0;
+
+  // ── 1. Upload sprite data ──────────────────────────────────────────
+  copy_sprite();
+
+  // Sprite 0 pointer = $0800 / $40 = $20.
+  SPRITE_POINTERS[0] = 0x20;
+
+  // ── 2. Colors ──────────────────────────────────────────────────────
+  POKE(VIC_BORDER, 0x06);   // blue border
+  POKE(VIC_BG0,    0x00);   // black background
+  POKE(VIC_SPR_COL(0), 0x01);  // sprite 0 = white
+
+  // ── 3. Position + enable sprite 0 ──────────────────────────────────
+  POKE(VIC_SPRITE_X(0), sx);
+  POKE(VIC_SPRITE_Y(0), sy);
+  POKE(VIC_SPR_ENA, 0x01);  // enable sprite 0 only
+
+  // ── 4. Game loop — joystick 2 moves the sprite ─────────────────────
+  for (;;) {
+    wait_vblank();
+
+    // Joystick 2 is wired through CIA1 port A (CIA1_PRA at $DC00).
+    // Bits are active-LOW (pressed = 0). Invert and mask to test.
+    pad = ~PEEK(CIA1_PRA) & 0x1F;
+
+    if (pad & JOY_UP    && sy > 50)  sy--;
+    if (pad & JOY_DOWN  && sy < 230) sy++;
+    if (pad & JOY_LEFT  && sx > 24)  sx--;
+    if (pad & JOY_RIGHT && sx < 250) sx++;
+
+    POKE(VIC_SPRITE_X(0), sx);
+    POKE(VIC_SPRITE_Y(0), sy);
+    prev_pad = pad;
+    (void)prev_pad;  // available if you want to edge-detect FIRE
+  }
+}

package/examples/c64/templates/music_demo.c

@@ -0,0 +1,131 @@
+// ── music_demo.c — Commodore 64 SID 3-voice music demo ──────────────
+//
+// A continuous 3-voice tune on the SID:
+//   voice 0 = melody  (high pulse)
+//   voice 1 = bass    (low  pulse)
+//   voice 2 = harmony (mid  pulse)
+//
+// The note table IS the song — open c64_music.c to read/edit the tune.
+// Chord progression is the classic Am-F-C-G loop with melody variations
+// across 4 verses; the song wraps forever.
+//
+// Visuals: title text in the screen-RAM character matrix + a row of
+// "VU meter" bars that pulse with the beat (driven by music_tick()).
+// Border flashes one color-step per beat for that classic demoscene
+// vibe.
+//
+// Joystick port 2 FIRE: toggle music on/off. The standard C64 idiom
+// uses port 2 because port 1 conflicts with the keyboard scan matrix.
+
+#include "c64_registers.h"
+#include "c64_music.h"
+#include <stdint.h>
+
+#define POKE(addr, val) (*(volatile uint8_t*)(addr) = (val))
+#define PEEK(addr)      (*(volatile uint8_t*)(addr))
+
+#define SCREEN ((volatile uint8_t*)0x0400)
+#define COLORS ((volatile uint8_t*)0xD800)
+
+#define JOY_FIRE 0x10
+
+/* PETSCII screen codes: A-Z = 1-26, space = 32, 0-9 = 48-57.
+ * (Different from PETSCII char codes — these are direct screen-RAM
+ * indices into the C64 character ROM.) */
+static uint8_t scr_char(char c) {
+  if (c >= 'A' && c <= 'Z') return (uint8_t)(c - 'A' + 1);
+  if (c >= 'a' && c <= 'z') return (uint8_t)(c - 'a' + 1);
+  if (c >= '0' && c <= '9') return (uint8_t)c;   /* 48..57 work directly */
+  if (c == '-') return 0x2D;
+  if (c == '!') return 0x21;
+  return 0x20;  /* space */
+}
+
+static void draw_text(uint8_t row, uint8_t col, const char *s, uint8_t color) {
+  uint16_t off = (uint16_t)row * 40 + col;
+  while (*s) {
+    SCREEN[off] = scr_char(*s);
+    COLORS[off] = color;
+    s++;
+    off++;
+  }
+}
+
+static void wait_vblank(void) {
+  while (PEEK(VIC_RASTER) < 250) { }
+  while (PEEK(VIC_RASTER) >= 250) { }
+}
+
+static void clear_screen(void) {
+  uint16_t i;
+  for (i = 0; i < 1000; i++) {
+    SCREEN[i] = 0x20;       /* space */
+    COLORS[i] = COLOR_LIGHT_BLUE;
+  }
+}
+
+int main(void) {
+  uint8_t playing = 1;
+  uint8_t prev_pad = 0;
+  uint8_t i;
+  uint8_t border_phase = 0;
+  uint8_t prev_beat = 0;
+
+  /* Pretty C64-blue setup. */
+  POKE(VIC_BORDER, COLOR_BLUE);
+  POKE(VIC_BG0,    COLOR_BLACK);
+  clear_screen();
+
+  draw_text(2,  10, "C64 SID MUSIC DEMO",   COLOR_LIGHT_GREEN);
+  draw_text(4,  10, "THREE VOICES LOOP",    COLOR_LIGHT_BLUE);
+  draw_text(6,  10, "MELODY  BASS  HARMONY",COLOR_YELLOW);
+  draw_text(10, 12, "AM - F - C - G",       COLOR_WHITE);
+  draw_text(20,  8, "FIRE TOGGLES PLAYBACK",COLOR_LIGHT_GRAY);
+  draw_text(22, 14, "JOY PORT 2",           COLOR_DARK_GRAY);
+
+  music_init();
+  music_play();
+
+  for (;;) {
+    uint8_t pad;
+    uint8_t beat;
+    wait_vblank();
+
+    if (playing) {
+      music_update();
+    }
+
+    /* Beat = upper bits of the tick — changes every ~8 frames. */
+    beat = (uint8_t)(music_tick() >> 3);
+    if (beat != prev_beat) {
+      prev_beat = beat;
+      border_phase = (uint8_t)(border_phase + 1);
+      POKE(VIC_BORDER, (uint8_t)(border_phase & 0x0F));
+
+      /* VU bars: row 14, 16 cells wide, length tied to phase. */
+      {
+        uint8_t bar_len = (uint8_t)(border_phase & 0x0F);
+        for (i = 0; i < 16; i++) {
+          uint16_t off = (uint16_t)14 * 40 + 12 + i;
+          if (i < bar_len) {
+            SCREEN[off] = 0xA0;            /* solid block */
+            COLORS[off] = (uint8_t)((i >> 1) + 2);
+          } else {
+            SCREEN[off] = 0x20;            /* space */
+          }
+        }
+      }
+    }
+
+    pad = (uint8_t)(~PEEK(CIA1_PRA) & 0x1F);
+    if ((pad & JOY_FIRE) && !(prev_pad & JOY_FIRE)) {
+      playing = (uint8_t)(!playing);
+      if (playing) {
+        music_play();
+      } else {
+        music_stop();
+      }
+    }
+    prev_pad = pad;
+  }
+}