romdev-mcp 0.1.1

package/src/platforms/c64/image-to-tilemap.js

@@ -0,0 +1,190 @@
+// C64 image → charset/screen/color conversion.
+//
+// The C64 has no "tilemap" in the NES sense, but its standard hi-res
+// character mode is the direct analog: a 40×25 grid of 8×8 cells, each
+// cell a char code into a 2 KB charset (256 chars × 8 bytes, 1bpp). Per
+// cell you get ONE foreground color (from Color RAM, $D800) over a SINGLE
+// shared background color ($D021). So each 8×8 cell is 2-color.
+//
+// This maps onto the generic imageToTilemap contract:
+//   chr        → charset bytes (deduped 8×8 1bpp chars, ≤256 × 8 = ≤2048 B)
+//   nametable  → screen RAM (1000 bytes, char code per cell)
+//   attr       → color RAM (1000 bytes, low nibble = fg color 0..15 per cell)
+//   palette    → 1 byte: the shared background color index
+//
+// Input must be 320×200, already quantized to the 16-color C64 palette
+// (use getPlatformPalettePng({platform:"c64"}) as the ImageMagick -remap
+// target). Each 8×8 cell may use at most 2 of those colors (one is the
+// global background, the other is that cell's foreground) — hi-res char
+// mode's hard constraint. Cells that violate it are reported.
+
+import { PNG } from "pngjs";
+import { C64_PALETTE } from "./vic.js";
+
+const W = 320;
+const H = 200;
+const COLS = 40;
+const ROWS = 25;
+
+/** nearest C64 palette index for an (r,g,b) — exact match preferred. */
+function nearestC64Index(r, g, b) {
+  let best = 0;
+  let bestD = Infinity;
+  for (let i = 0; i < 16; i++) {
+    const [pr, pg, pb] = C64_PALETTE[i];
+    const d = (pr - r) ** 2 + (pg - g) ** 2 + (pb - b) ** 2;
+    if (d < bestD) { bestD = d; best = i; }
+  }
+  return best;
+}
+
+/**
+ * Convert a 320×200 PNG into C64 hi-res character-mode assets.
+ *
+ * @param {{ pngBytes: Buffer|Uint8Array, backdrop?: number }} args
+ *   backdrop: force a specific palette index (0..15) as the shared
+ *   background color. If omitted, the most-common color is chosen.
+ * @returns {{
+ *   chr: Uint8Array, nametable: Uint8Array, attr: Uint8Array,
+ *   palette: Uint8Array, uniqueTilesBeforeMerge: number, uniqueTiles: number,
+ *   imageColors: number, backgroundColor: number, previewPng: Buffer,
+ *   warnings: string[]
+ * }}
+ */
+export function c64ImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  if (png.width !== W || png.height !== H) {
+    throw new Error(`C64 hi-res image must be ${W}×${H}, got ${png.width}×${png.height}`);
+  }
+
+  // Quantize every pixel to a C64 palette index.
+  const pxIdx = new Uint8Array(W * H);
+  const colorHist = new Array(16).fill(0);
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const ci = nearestC64Index(png.data[k], png.data[k + 1], png.data[k + 2]);
+    pxIdx[i] = ci;
+    colorHist[ci]++;
+  }
+
+  // Choose the shared background color: caller override, else most common.
+  let bg = args.backdrop;
+  if (bg == null) {
+    bg = 0;
+    for (let i = 1; i < 16; i++) if (colorHist[i] > colorHist[bg]) bg = i;
+  }
+
+  const warnings = [];
+  const charByKey = new Map();
+  const chars = []; // each: Uint8Array(8)
+  const screen = new Uint8Array(COLS * ROWS);
+  const color = new Uint8Array(COLS * ROWS);
+  let uniqueBefore = 0;
+  let overflowReported = false;
+  let multiColorCells = 0;
+
+  for (let cy = 0; cy < ROWS; cy++) {
+    for (let cx = 0; cx < COLS; cx++) {
+      uniqueBefore++;
+      // Determine this cell's foreground color: the most-common non-bg
+      // color in the cell. Any pixel that's neither bg nor fg is forced
+      // to fg (and counted as a constraint violation).
+      const cellHist = new Array(16).fill(0);
+      for (let y = 0; y < 8; y++) {
+        for (let x = 0; x < 8; x++) {
+          cellHist[pxIdx[(cy * 8 + y) * W + (cx * 8 + x)]]++;
+        }
+      }
+      let fg = -1;
+      for (let i = 0; i < 16; i++) {
+        if (i === bg) continue;
+        if (fg === -1 || cellHist[i] > cellHist[fg]) fg = i;
+      }
+      if (fg === -1) fg = bg; // solid-background cell
+      const distinctNonBg = cellHist.filter((c, i) => c > 0 && i !== bg).length;
+      if (distinctNonBg > 1) multiColorCells++;
+
+      // Encode the 8×8 char: bit set = foreground pixel.
+      const ch = new Uint8Array(8);
+      for (let y = 0; y < 8; y++) {
+        let byte = 0;
+        for (let x = 0; x < 8; x++) {
+          const p = pxIdx[(cy * 8 + y) * W + (cx * 8 + x)];
+          // A pixel is "foreground" if it's not the bg color.
+          if (p !== bg) byte |= 1 << (7 - x);
+        }
+        ch[y] = byte;
+      }
+
+      let key = "";
+      for (const b of ch) key += b.toString(16).padStart(2, "0");
+      let idx = charByKey.get(key);
+      if (idx === undefined) {
+        if (chars.length >= 256) {
+          if (!overflowReported) {
+            warnings.push(
+              `Image needs more than 256 unique chars after dedup — extra cells reuse char 0. ` +
+              `Reduce detail or split across multiple charsets/screens.`
+            );
+            overflowReported = true;
+          }
+          idx = 0;
+        } else {
+          idx = chars.length;
+          charByKey.set(key, idx);
+          chars.push(ch);
+        }
+      }
+      screen[cy * COLS + cx] = idx;
+      color[cy * COLS + cx] = fg & 0x0F;
+    }
+  }
+
+  if (multiColorCells > 0) {
+    warnings.push(
+      `${multiColorCells} of ${COLS * ROWS} cells contain >2 colors (bg + >1 fg). ` +
+      `Hi-res char mode is 2 colors per 8×8 cell — those cells collapsed all non-background ` +
+      `pixels to a single foreground color. For 3-4 colors per cell use multicolor mode ` +
+      `(half horizontal resolution) — not yet implemented; pre-author the image to 2 colors/cell.`
+    );
+  }
+
+  const chrFlat = new Uint8Array(chars.length * 8);
+  for (let i = 0; i < chars.length; i++) chrFlat.set(chars[i], i * 8);
+
+  // Preview: re-render from encoded charset + screen + color.
+  const preview = new PNG({ width: W, height: H });
+  const [bgr, bgg, bgb] = C64_PALETTE[bg];
+  for (let cy = 0; cy < ROWS; cy++) {
+    for (let cx = 0; cx < COLS; cx++) {
+      const charCode = screen[cy * COLS + cx];
+      const fg = color[cy * COLS + cx];
+      const [fr, fgg, fb] = C64_PALETTE[fg];
+      const base = charCode * 8;
+      for (let y = 0; y < 8; y++) {
+        const byte = chrFlat[base + y];
+        for (let x = 0; x < 8; x++) {
+          const on = (byte >> (7 - x)) & 1;
+          const o = ((cy * 8 + y) * W + (cx * 8 + x)) * 4;
+          preview.data[o + 0] = on ? fr : bgr;
+          preview.data[o + 1] = on ? fgg : bgg;
+          preview.data[o + 2] = on ? fb : bgb;
+          preview.data[o + 3] = 0xFF;
+        }
+      }
+    }
+  }
+
+  return {
+    chr: chrFlat,
+    nametable: screen,
+    attr: color,
+    palette: new Uint8Array([bg]),
+    uniqueTilesBeforeMerge: uniqueBefore,
+    uniqueTiles: chars.length,
+    imageColors: colorHist.filter((c) => c > 0).length,
+    backgroundColor: bg,
+    previewPng: PNG.sync.write(preview),
+    warnings,
+  };
+}

package/src/platforms/c64/lib/README.md

@@ -0,0 +1,52 @@
+Commodore 64 starter snippets
+=============================
+
+Hand-vetted boilerplate for cc65-targeted C64 development. cc65 ships C
+as the default language; assembly via ca65 is also supported. The snippets
+here mix C (for the most common workflows) and asm (for where you need
+cycle-level control or are touching VIC-II / SID registers directly).
+
+Files
+-----
+
+- **c64_registers.h** — symbolic names for VIC-II ($D000-$D02E), SID
+  ($D400-$D41C), CIA1/2 ($DC00/$DD00) registers. `#include` from C; ca65
+  imports it as well.
+- **vic_init.s** — boot-time setup: black-out the screen, set border + bg
+  colors, switch char-ROM/RAM banking.
+- **sprite_table.s** — load 8 sprite pixel-data blocks + position + enable
+  + color. The classic "render moving sprites" recipe.
+- **read_joystick.s** — read joystick port 2 (the usual game port) from
+  CIA1 $DC00 into a zp byte. Includes the "fire is bit 4" trap.
+- **sid_play.s** — start a SID voice (waveform + ADSR + gate). Pair with
+  setting frequency from main loop for arpeggios / sound effects.
+- **basic_stub.s** — the canonical 12-byte BASIC stub at $0801 that just
+  does `SYS 2061` (jumps to your machine code at $080D). Lets your program
+  start with `LOAD"NAME",8,1` then `RUN`.
+
+Toolchain
+---------
+
+Build via `buildSource({ platform: "c64", source: <C or asm> })`. cc65
+auto-sniffs C vs asm; for explicit control pass `language: "c"` or `"asm"`.
+
+Foot-guns
+---------
+
+1. **The 6510's I/O port at $00/$01 controls ROM banking.** Writing the
+   wrong value can hide the KERNAL or character ROM. Default is $37
+   (LORAM=1, HIRAM=1, CHAREN=1) which means BASIC + KERNAL + I/O are all
+   visible. Most games don't change this.
+2. **VIC bank select is in CIA2 $DD00 bits 0-1** (inverted). VIC sees
+   one of 4 × 16 KB banks of main RAM. Default = bank 0 ($0000-$3FFF),
+   which puts screen RAM at $0400 and char ROM at $1000 (via mirror).
+3. **Color RAM is 4-bit only.** $D800-$DBE7 stores the foreground color
+   nibble for each text cell — only the low 4 bits are used; high bits
+   read back as garbage.
+4. **The IRQ vector at $FFFE points through $0314/$0315 by default**
+   (KERNAL interrupt thunk). To install your own raster IRQ, write your
+   handler addr to $0314/$0315.
+5. **Sprite pixel data lives in RAM, not VIC.** $D000-$D02E only stores
+   X/Y/color/enable. The actual 64-byte pixel block per sprite is at
+   `screen_ram[$3F8 + sprite_index] × 64` — write that address to point
+   at your sprite data.

package/src/platforms/c64/lib/basic_stub.s

@@ -0,0 +1,25 @@
+; ── BASIC stub: SYS 2061 ────────────────────────────────────────────
+; The standard 12-byte BASIC bootstrap at $0801 that lets a user type
+; `LOAD"NAME",8,1` followed by `RUN`. The stub is a one-line BASIC
+; program tokenized to SYS 2061, where 2061 = $080D = the first byte
+; AFTER the stub. So your machine-code main routine should start at $080D.
+;
+; Bytes:
+;   $0801  $0B $08   ; pointer to next BASIC line ($080B)
+;          $0A $00   ; line number 10
+;          $9E       ; SYS token
+;          "2061"    ; ASCII "2061"
+;          $00       ; end of statement
+;          $00 $00   ; end of BASIC program (null pointer)
+;
+; After this stub, put `.org $080D` (or just continue assembling) and
+; place your real main routine there.
+
+.segment "STARTUP"
+    .word $080B                ; next line pointer
+    .word 10                   ; line number
+    .byte $9E                  ; SYS
+    .byte "2061", $00          ; "2061" + line terminator
+    .word $0000                ; end-of-program
+
+; Your code starts at $080D — define your reset entry there.

package/src/platforms/c64/lib/c/c64_music.c

@@ -0,0 +1,248 @@
+/* c64_music.c — per-frame 3-voice SID music driver.
+ *
+ *  Architecture
+ *  ────────────
+ *  Three voices, each walks an independent (freq, length_frames) table:
+ *
+ *    voice0 = melody   (pulse,  high register)
+ *    voice1 = bass     (pulse,  low  register, longer notes)
+ *    voice2 = harmony  (pulse,  mid  register)
+ *
+ *  On each music_update() (called once per VBlank ≈ 50 Hz PAL / 60 Hz NTSC):
+ *    - decrement the current note's frames-remaining counter for each voice
+ *    - when it hits 0, advance to the next note: write FREQ_LO/HI, retrigger
+ *      GATE (off-on transition keys the envelope) and start the new counter
+ *    - if a voice reaches end-of-table it wraps to 0 → continuous loop
+ *
+ *  ADSR shape (same for all 3 voices for simplicity):
+ *    attack=0  decay=4  sustain=8 release=4
+ *  → punchy front, ~half-volume sustain, short tail. Notes don't bleed
+ *    into each other but sound musical.
+ *
+ *  Frequency values are the standard PAL SID 16-bit dividers from any
+ *  C64 programmer reference. Hz ≈ freq * 0.0596.
+ *
+ *  The song
+ *  ────────
+ *  16-bar loop, 4/4, ~125 BPM. Each "step" is 12 frames = ~0.2s @ 50 Hz.
+ *  Melody plays mostly quarter-steps, bass holds half-steps, harmony
+ *  rides between. C major / A minor flavor — chord progression:
+ *    Am  F   C   G   (the classic four-chord loop)
+ *  repeated 4× per loop with melody variations.
+ *
+ *  A rest is encoded as freq=0 (driver gates off without retriggering).
+ */
+
+#include "c64_music.h"
+#include "c64_registers.h"
+
+#define POKE(addr, val)  (*(volatile uint8_t*)(addr) = (val))
+
+/* ── SID 16-bit frequency dividers for PAL (985248 Hz clock) ────── */
+/* Standard table — match any C64 programmer's guide. Hz ≈ f * 0.0596. */
+#define N_REST  0x0000u
+
+#define N_C3    0x1199u
+#define N_D3    0x13EEu
+#define N_E3    0x1666u
+#define N_F3    0x1798u
+#define N_G3    0x1AE6u
+#define N_A3    0x1E78u
+#define N_B3    0x2253u
+
+#define N_C4    0x2333u
+#define N_D4    0x27DDu
+#define N_E4    0x2CCCu
+#define N_F4    0x2F30u
+#define N_G4    0x35CCu
+#define N_A4    0x3CF1u
+#define N_B4    0x44A7u
+
+#define N_C5    0x4666u
+#define N_D5    0x4FBAu
+#define N_E5    0x5998u
+#define N_F5    0x5E60u
+#define N_G5    0x6B99u
+#define N_A5    0x79E1u
+#define N_B5    0x894Eu
+
+/* Step length: number of frames a "unit" note occupies. */
+#define STEP  10
+
+typedef struct {
+  uint16_t freq;
+  uint8_t  len;   /* frames */
+} Note;
+
+/* ── Voice 0: melody (lead). High register, ~quarter-note pacing. ─
+ * Chord progression spelled out as Am F C G repeated. Each chord
+ * gets 4 melody notes (one bar). 16 bars × 4 notes = 64 notes. */
+static const Note melody[] = {
+  /* Am bar */
+  { N_A4, STEP*2 }, { N_C5, STEP }, { N_E5, STEP }, { N_C5, STEP*2 }, { N_A4, STEP*2 },
+  /* F  bar */
+  { N_F4, STEP*2 }, { N_A4, STEP }, { N_C5, STEP }, { N_A4, STEP*2 }, { N_F4, STEP*2 },
+  /* C  bar */
+  { N_C5, STEP*2 }, { N_E5, STEP }, { N_G5, STEP }, { N_E5, STEP*2 }, { N_C5, STEP*2 },
+  /* G  bar */
+  { N_G4, STEP*2 }, { N_B4, STEP }, { N_D5, STEP }, { N_B4, STEP*2 }, { N_G4, STEP*2 },
+
+  /* — verse 2: same chords, ornamented — */
+  { N_A4, STEP   }, { N_C5, STEP }, { N_E5, STEP*2 }, { N_D5, STEP }, { N_C5, STEP }, { N_E5, STEP*2 },
+  { N_F4, STEP   }, { N_A4, STEP }, { N_C5, STEP*2 }, { N_B4, STEP }, { N_A4, STEP }, { N_C5, STEP*2 },
+  { N_C5, STEP   }, { N_E5, STEP }, { N_G5, STEP*2 }, { N_F5, STEP }, { N_E5, STEP }, { N_G5, STEP*2 },
+  { N_G4, STEP   }, { N_B4, STEP }, { N_D5, STEP*2 }, { N_C5, STEP }, { N_B4, STEP }, { N_D5, STEP*2 },
+
+  /* — verse 3: rising arpeggios — */
+  { N_A3, STEP }, { N_C4, STEP }, { N_E4, STEP }, { N_A4, STEP }, { N_C5, STEP }, { N_E5, STEP }, { N_A5, STEP*2 },
+  { N_F3, STEP }, { N_A3, STEP }, { N_C4, STEP }, { N_F4, STEP }, { N_A4, STEP }, { N_C5, STEP }, { N_F5, STEP*2 },
+  { N_C4, STEP }, { N_E4, STEP }, { N_G4, STEP }, { N_C5, STEP }, { N_E5, STEP }, { N_G5, STEP }, { N_C5, STEP*2 },
+  { N_G3, STEP }, { N_B3, STEP }, { N_D4, STEP }, { N_G4, STEP }, { N_B4, STEP }, { N_D5, STEP }, { N_G5, STEP*2 },
+
+  /* — verse 4: cooldown, longer notes — */
+  { N_A4, STEP*4 }, { N_E5, STEP*4 },
+  { N_F4, STEP*4 }, { N_C5, STEP*4 },
+  { N_C5, STEP*4 }, { N_G5, STEP*4 },
+  { N_G4, STEP*4 }, { N_D5, STEP*4 },
+
+  /* end-mark not needed; we wrap. */
+};
+
+/* ── Voice 1: bass. Low register, half-note pacing. ───────────── */
+static const Note bass[] = {
+  /* Am F C G — one note per bar, sustained */
+  { N_A3, STEP*8 }, { N_F3, STEP*8 }, { N_C3, STEP*8 }, { N_G3, STEP*8 },
+  /* repeat for verse 2 */
+  { N_A3, STEP*8 }, { N_F3, STEP*8 }, { N_C3, STEP*8 }, { N_G3, STEP*8 },
+  /* verse 3 — walking bass */
+  { N_A3, STEP*4 }, { N_E3, STEP*4 },
+  { N_F3, STEP*4 }, { N_C3, STEP*4 },
+  { N_C3, STEP*4 }, { N_G3, STEP*4 },
+  { N_G3, STEP*4 }, { N_D3, STEP*4 },
+  /* verse 4 — pedal */
+  { N_A3, STEP*8 }, { N_F3, STEP*8 }, { N_C3, STEP*8 }, { N_G3, STEP*8 },
+};
+
+/* ── Voice 2: harmony. Mid register, offset rhythm. ─────────── */
+static const Note harmony[] = {
+  /* Am chord tones */
+  { N_C4, STEP*2 }, { N_E4, STEP*2 }, { N_A4, STEP*2 }, { N_E4, STEP*2 },
+  /* F  chord tones */
+  { N_A3, STEP*2 }, { N_C4, STEP*2 }, { N_F4, STEP*2 }, { N_C4, STEP*2 },
+  /* C  chord tones */
+  { N_E4, STEP*2 }, { N_G4, STEP*2 }, { N_C5, STEP*2 }, { N_G4, STEP*2 },
+  /* G  chord tones */
+  { N_D4, STEP*2 }, { N_G4, STEP*2 }, { N_B4, STEP*2 }, { N_G4, STEP*2 },
+
+  /* verse 2 — same with rest accents */
+  { N_C4, STEP }, { N_E4, STEP }, { N_REST, STEP }, { N_A4, STEP*2 }, { N_E4, STEP*2 }, { N_C4, STEP },
+  { N_A3, STEP }, { N_C4, STEP }, { N_REST, STEP }, { N_F4, STEP*2 }, { N_C4, STEP*2 }, { N_A3, STEP },
+  { N_E4, STEP }, { N_G4, STEP }, { N_REST, STEP }, { N_C5, STEP*2 }, { N_G4, STEP*2 }, { N_E4, STEP },
+  { N_D4, STEP }, { N_G4, STEP }, { N_REST, STEP }, { N_B4, STEP*2 }, { N_G4, STEP*2 }, { N_D4, STEP },
+
+  /* verse 3 — long pads */
+  { N_E4, STEP*8 }, { N_F4, STEP*8 }, { N_G4, STEP*8 }, { N_B4, STEP*8 },
+
+  /* verse 4 — drop out partly */
+  { N_REST, STEP*8 }, { N_C4, STEP*8 }, { N_REST, STEP*8 }, { N_D4, STEP*8 },
+};
+
+#define ARR_LEN(a) (sizeof(a) / sizeof((a)[0]))
+
+/* Per-voice state. */
+static uint16_t v_pos[3];      /* index into the voice's note table */
+static uint8_t  v_remaining[3];/* frames left on current note */
+static uint8_t  m_tick;
+
+static uint16_t voice_len(uint8_t v) {
+  switch (v) {
+    case 0: return (uint16_t)ARR_LEN(melody);
+    case 1: return (uint16_t)ARR_LEN(bass);
+    default: return (uint16_t)ARR_LEN(harmony);
+  }
+}
+static const Note *voice_note(uint8_t v, uint16_t i) {
+  switch (v) {
+    case 0: return &melody[i];
+    case 1: return &bass[i];
+    default: return &harmony[i];
+  }
+}
+
+/* Set up the pulse-wave shape on a voice: PW = 50% duty, ADSR shape. */
+static void setup_voice(uint8_t v) {
+  POKE(SID_PW_LO(v), 0x00);
+  POKE(SID_PW_HI(v), 0x08);   /* PW = $0800 = 50% */
+  POKE(SID_AD(v), 0x04);      /* attack=0, decay=4 */
+  POKE(SID_SR(v), 0x84);      /* sustain=8, release=4 */
+  POKE(SID_CTRL(v), 0);       /* gate off until first note */
+}
+
+/* Trigger a note: write freq, gate off→on retrigger so envelope keys. */
+static void trigger(uint8_t v, uint16_t freq) {
+  if (freq == N_REST) {
+    /* Rest: gate off, no retrigger. Release tail plays. */
+    POKE(SID_CTRL(v), SID_PULSE);
+    return;
+  }
+  POKE(SID_FREQ_LO(v), (uint8_t)(freq & 0xFF));
+  POKE(SID_FREQ_HI(v), (uint8_t)(freq >> 8));
+  /* Off then on for clean envelope retrigger. */
+  POKE(SID_CTRL(v), SID_PULSE);
+  POKE(SID_CTRL(v), SID_PULSE | SID_GATE);
+}
+
+void music_init(void) {
+  uint8_t v;
+  POKE(SID_VOL_MODE, 0x0F);   /* master vol = 15, no filter */
+  for (v = 0; v < 3; v++) {
+    setup_voice(v);
+    v_pos[v] = 0;
+    v_remaining[v] = 0;
+  }
+  m_tick = 0;
+}
+
+void music_play(void) {
+  uint8_t v;
+  const Note *n;
+  for (v = 0; v < 3; v++) {
+    v_pos[v] = 0;
+    n = voice_note(v, 0);
+    v_remaining[v] = n->len;
+    trigger(v, n->freq);
+  }
+}
+
+void music_update(void) {
+  uint8_t v;
+  const Note *n;
+  m_tick++;
+  for (v = 0; v < 3; v++) {
+    if (v_remaining[v] > 0) {
+      v_remaining[v]--;
+    }
+    if (v_remaining[v] == 0) {
+      /* Advance, with wrap. */
+      v_pos[v]++;
+      if (v_pos[v] >= voice_len(v)) v_pos[v] = 0;
+      n = voice_note(v, v_pos[v]);
+      v_remaining[v] = n->len;
+      trigger(v, n->freq);
+    }
+  }
+}
+
+void music_stop(void) {
+  uint8_t v;
+  for (v = 0; v < 3; v++) {
+    POKE(SID_CTRL(v), 0);
+    v_remaining[v] = 0;
+    v_pos[v] = 0;
+  }
+  POKE(SID_VOL_MODE, 0);
+}
+
+uint8_t music_tick(void) {
+  return m_tick;
+}

package/src/platforms/c64/lib/c/c64_music.h

@@ -0,0 +1,36 @@
+/* c64_music.h — tiny per-frame SID music driver for C64 scaffolds.
+ *
+ * 3-voice continuous music player on top of the SID. The note table IS
+ * the song — open this file's .c sibling to see and edit the tune.
+ *
+ * NOT a .sid player (those need reSID-class emulation of a 6502 sub-
+ * program). This is a plain frame-tick sequencer: each voice walks a
+ * parallel array of (freq, length_frames) pairs and writes SID registers
+ * on note transitions. Lightweight, source-visible, perfect for a
+ * scaffold "music_demo".
+ *
+ * Wire it up:
+ *   music_init()       — set master vol + ADSR for all 3 voices
+ *   music_play()       — reset song position to 0 (begin playback)
+ *   music_update()     — call once per frame from your main loop
+ *   music_stop()       — clear gates + silence
+ *
+ * The track loops indefinitely; each voice can have its own length so
+ * polyphony stays interesting.
+ */
+
+#ifndef C64_MUSIC_H
+#define C64_MUSIC_H
+
+#include <stdint.h>
+
+void music_init(void);
+void music_play(void);
+void music_update(void);
+void music_stop(void);
+
+/* Returns 0..255 — a frame counter useful for sync (e.g. flash colors
+ * on the beat). Wraps freely. */
+uint8_t music_tick(void);
+
+#endif

package/src/platforms/c64/lib/c/c64_sfx.c

@@ -0,0 +1,94 @@
+/* c64_sfx.c — SID driver for C64 scaffolds.
+ *
+ * Three voices, each with:
+ *   FREQ_LO/HI   16-bit frequency divider
+ *   PW_LO/HI     12-bit pulse width (only relevant for pulse waveform)
+ *   CTRL         bit 0  = GATE (1 = note on, 0 = release)
+ *                bit 4  = triangle wave
+ *                bit 5  = sawtooth
+ *                bit 6  = pulse
+ *                bit 7  = noise
+ *   AD           attack (high nibble) / decay (low nibble), 0..15 each
+ *   SR           sustain (high) / release (low), 0..15 each
+ *
+ * SID_VOL_MODE ($D418):
+ *   bits 0..3  master volume 0..15 (15 = full)
+ *   (filter bits in 4..7 — not used here)
+ *
+ * Per-voice "frames-left" counter drives auto-key-off.
+ */
+
+#include "c64_sfx.h"
+#include "c64_registers.h"
+
+#define POKE(addr, val)  (*(volatile uint8_t*)(addr) = (val))
+
+static uint8_t sfx_remaining[3];
+static uint8_t sfx_ctrl[3];   /* the current waveform+gate bits so we can clear GATE on key-off */
+
+void sfx_init(void) {
+  uint8_t i;
+  /* Master volume = full, no filter. */
+  POKE(SID_VOL_MODE, 0x0F);
+  /* Clear all voice control registers. */
+  for (i = 0; i < 3; i++) {
+    POKE(SID_CTRL(i), 0);
+    POKE(SID_AD(i), 0);
+    POKE(SID_SR(i), 0);
+    sfx_remaining[i] = 0;
+    sfx_ctrl[i] = 0;
+  }
+}
+
+void sfx_tone(uint8_t channel, uint8_t freq_lo, uint8_t freq_hi, uint8_t length_frames) {
+  uint8_t ctrl;
+  if (channel > 2) return;
+  POKE(SID_FREQ_LO(channel), freq_lo);
+  POKE(SID_FREQ_HI(channel), freq_hi);
+  /* Pulse waveform at 50% duty (PW = 0x800). */
+  POKE(SID_PW_LO(channel), 0x00);
+  POKE(SID_PW_HI(channel), 0x08);
+  /* Attack 0, decay 9 — punchy then fades. */
+  POKE(SID_AD(channel), 0x09);
+  /* Sustain 8/15, release 5/15 — note holds then fades. */
+  POKE(SID_SR(channel), 0x85);
+  /* Pulse waveform + GATE on. */
+  ctrl = SID_PULSE | SID_GATE;
+  POKE(SID_CTRL(channel), ctrl);
+  sfx_ctrl[channel] = ctrl;
+  sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* Use voice 2 for noise so voice 0/1 can hold tones underneath. */
+  POKE(SID_FREQ_LO(2), 0x00);
+  POKE(SID_FREQ_HI(2), 0x40);
+  POKE(SID_AD(2), 0x09);
+  POKE(SID_SR(2), 0x84);
+  POKE(SID_CTRL(2), SID_NOISE | SID_GATE);
+  sfx_ctrl[2] = SID_NOISE | SID_GATE;
+  sfx_remaining[2] = length_frames;
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  for (i = 0; i < 3; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        /* Clear GATE — release phase of the ADSR envelope plays. */
+        POKE(SID_CTRL(i), sfx_ctrl[i] & ~SID_GATE);
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  uint8_t i;
+  for (i = 0; i < 3; i++) {
+    POKE(SID_CTRL(i), 0);
+    sfx_remaining[i] = 0;
+    sfx_ctrl[i] = 0;
+  }
+  POKE(SID_VOL_MODE, 0);
+}

package/src/platforms/c64/lib/c/c64_sfx.h

@@ -0,0 +1,37 @@
+/* c64_sfx.h — minimal C64 SID sound-effects wrapper.
+ *
+ * SID = Sound Interface Device. The legendary C64 audio chip, 3 voices,
+ * 4 waveforms (triangle/sawtooth/pulse/noise), per-voice ADSR
+ * envelope, and a programmable filter. Sounds amazing when used well;
+ * this scaffold wrapper uses the basics.
+ *
+ * Same 5-function cross-platform shape:
+ *   sfx_init()
+ *   sfx_tone(channel, freq_lo, freq_hi, length_frames)   — pulse wave
+ *   sfx_noise(length_frames)                              — voice 2 noise
+ *   sfx_update()                                          — call once per frame
+ *   sfx_off()
+ *
+ * channel = 0, 1, or 2 (SID has 3 voices).
+ *
+ * Frequency is a 16-bit divider:
+ *   Hz = (freq * 0.0596) for PAL, or (freq * 0.0596) for NTSC.
+ *   Useful values: 0x1000 ≈ middle range, 0x2000 ≈ higher, 0x0800 ≈ low.
+ *
+ * The SID has REAL ADSR — sfx_tone sets a sensible default (fast attack,
+ * mid release) so the note has shape. sfx_update keys-off (clears GATE)
+ * when the countdown hits 0, letting the release tail play.
+ */
+
+#ifndef C64_SFX_H
+#define C64_SFX_H
+
+#include <stdint.h>
+
+void sfx_init(void);
+void sfx_tone(uint8_t channel, uint8_t freq_lo, uint8_t freq_hi, uint8_t length_frames);
+void sfx_noise(uint8_t length_frames);
+void sfx_update(void);
+void sfx_off(void);
+
+#endif