romdevtools 0.13.0

package/examples/lynx/templates/sports.c

@@ -0,0 +1,59 @@
+// ── sports.c — Atari Lynx Pong vs AI ─────────────────────────────────
+//
+// Lynx is a handheld with one controller. Right paddle = AI tracking
+// the ball.
+
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include <stdint.h>
+#include "lynx_sfx.h"
+
+#define PADDLE_H 16
+#define PADDLE_W 3
+#define BALL_SIZE 4
+#define COURT_TOP 4
+#define COURT_BOT 96
+#define PADDLE_X1 6
+#define PADDLE_X2 (160 - 6 - PADDLE_W)
+
+void main(void) {
+  int16_t p1y = 40, p2y = 40, bx = 78, by = 48;
+  int8_t bdx = 2, bdy = 1;
+  uint8_t joy;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+  joy_install(&lynx_stdjoy_joy);
+  sfx_init();
+
+  for (;;) {
+    tgi_clear();
+    tgi_setcolor(COLOR_WHITE);
+    tgi_bar(PADDLE_X1, (unsigned)p1y, PADDLE_X1 + PADDLE_W - 1, (unsigned)(p1y + PADDLE_H - 1));
+    tgi_bar(PADDLE_X2, (unsigned)p2y, PADDLE_X2 + PADDLE_W - 1, (unsigned)(p2y + PADDLE_H - 1));
+    tgi_setcolor(COLOR_YELLOW);
+    tgi_bar((unsigned)bx, (unsigned)by, (unsigned)(bx + BALL_SIZE - 1), (unsigned)(by + BALL_SIZE - 1));
+    tgi_updatedisplay();
+    sfx_update();
+
+    joy = joy_read(JOY_1);
+    if (JOY_UP(joy)   && p1y > COURT_TOP)             p1y -= 2;
+    if (JOY_DOWN(joy) && p1y < COURT_BOT - PADDLE_H)  p1y += 2;
+
+    /* AI */
+    if (p2y + PADDLE_H/2 < by && p2y < COURT_BOT - PADDLE_H) p2y++;
+    else if (p2y + PADDLE_H/2 > by && p2y > COURT_TOP)       p2y--;
+
+    bx += bdx;
+    by += bdy;
+    if (by < COURT_TOP)              { by = COURT_TOP; bdy = -bdy; sfx_tone(2, 90, 2); }
+    if (by + BALL_SIZE > COURT_BOT)  { by = COURT_BOT - BALL_SIZE; bdy = -bdy; sfx_tone(2, 90, 2); }
+    if (bdx < 0 && bx <= PADDLE_X1 + PADDLE_W && bx + BALL_SIZE >= PADDLE_X1
+        && by + BALL_SIZE > p1y && by < p1y + PADDLE_H) { bdx = -bdx; sfx_tone(0, 70, 3); }
+    if (bdx > 0 && bx + BALL_SIZE >= PADDLE_X2 && bx <= PADDLE_X2 + PADDLE_W
+        && by + BALL_SIZE > p2y && by < p2y + PADDLE_H) { bdx = -bdx; sfx_tone(0, 70, 3); }
+    if (bx < -BALL_SIZE) { bx = 78; by = 48; bdx = 2; sfx_noise(20); }
+    if (bx > 160)        { bx = 78; by = 48; bdx = -2; sfx_tone(0, 50, 12); }
+  }
+}

package/examples/msx/catch_game/README.md

@@ -0,0 +1,75 @@
+# MSX — catch_game
+
+A complete, playable MSX cartridge game (SDCC z80, C89). Move the basket at the
+bottom left/right with the joystick (or keyboard cursor keys) to catch the coin
+falling from the top. Catch it: **+1 score** and the coin respawns in a new
+column; miss it (it reaches the floor): it just respawns — a friendly, no-fail
+demo. The score is drawn as on-screen tiles (`SCORE 000`) along the top row.
+
+What it demonstrates, end to end:
+
+- **screen 2 (GRAPHIC II)** setup via `msx_set_screen2()` (BIOS INIGRP).
+- **Tile font** — a 16-glyph mini font (`SCORE` + the 10 digits) uploaded to the
+  pattern generator + color table, then placed via the name table. This is how
+  you draw HUD text without the BIOS text mode.
+- **Two hardware sprites** — basket (plane 0) + coin (plane 1), repositioned
+  every frame with `msx_set_sprite()`.
+- **Input** — `msx_read_joystick()` (BIOS GTSTCK) read on BOTH stick 0 (keyboard
+  cursor) and stick 1 (port), so keys or a pad both work.
+- **AABB collision + scoring**, with a short PSG catch blip (`msx_psg_tone`).
+- **Vblank-synced game loop** — one step per VDP frame.
+
+## Vblank without the BIOS ISR (the load-bearing gotcha)
+
+The shared lib's `msx_vblank_wait()` spins on the BIOS **JIFFY** counter, which
+only advances while the BIOS VBlank **interrupt handler** runs. On a bare
+cartridge under C-BIOS, JIFFY does **not** advance (it stays frozen) — so
+`msx_vblank_wait()` hangs forever and the game loop never runs (you'd see the
+static HUD but no moving sprites). This example instead polls the VDP directly:
+
+```c
+__sfr __at 0x99 VDPSTATUS;          /* port 0x99 read = selected S# register */
+static void vsync(void) {
+    (void)VDPSTATUS;                /* reading S#0 clears the frame flag */
+    while (!(VDPSTATUS & 0x80)) { } /* spin until the next VBlank sets it */
+}
+```
+
+Reading status register S#0 bit 7 (the frame flag) needs **no interrupts** and
+works on any MSX. Use this pattern in any bare-cart MSX game; don't depend on
+JIFFY/`msx_vblank_wait()` unless you've installed your own ISR or confirmed the
+BIOS one is live.
+
+## Build + run
+
+`.c`/`.s` go in `sources`, `.h` in `includes`:
+
+```js
+import { buildForPlatform } from "romdev/src/toolchains/index.js";
+const build = await buildForPlatform({
+  platform: "msx",
+  sources:  { "main.c": SRC, "msx_vdp.c": LIB, "msx_crt0.s": CRT0 },
+  includes: { "msx_hw.h": HDR },
+  crt0: ".module empty\n",
+  sourceName: "main.c",
+});
+```
+
+`_verify.mjs` is the runnable harness used to verify this example: it builds,
+steps past the C-BIOS logo (~300 frames), screenshots, then drives RIGHT and
+LEFT input and confirms the basket sprite's bright-pixel centroid actually moves
+(`shot_before.png` → `shot_after_right.png` → `shot_after_left.png`).
+
+```
+node examples/msx/catch_game/_verify.mjs   # prints VERIFIED_OK
+```
+
+Verified on the bluemsx core: HUD + both sprites render, the basket tracks
+left/right input, and catching coins increments the on-screen score
+(`SCORE 000` → `SCORE 003` while auto-tracking the coin).
+
+## Reusable starter
+
+This is a good base for any **catch / dodge / single-screen arcade** MSX game.
+The tile-font HUD, two-sprite + AABB pattern, dual-stick input read, and the
+interrupt-free `vsync()` are all drop-in reusable.

package/examples/msx/catch_game/_verify.mjs

@@ -0,0 +1,93 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { buildForPlatform } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/toolchains/index.js";
+import { resolveCore } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/cores/registry.js";
+import { LibretroHost } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/host/LibretroHost.js";
+
+const LIBDIR = "/home/monteslu/code/cliemu/romdev/packages/romdev/src/platforms/msx/lib/c";
+const DIR = "/home/monteslu/code/cliemu/romdev/packages/romdev/examples/msx/catch_game";
+
+const SRC  = readFileSync(`${DIR}/main.c`, "utf8");
+const LIB  = readFileSync(`${LIBDIR}/msx_vdp.c`, "utf8");
+const CRT0 = readFileSync(`${LIBDIR}/msx_crt0.s`, "utf8");
+const HDR  = readFileSync(`${LIBDIR}/msx_hw.h`, "utf8");
+
+const PLATFORM = "msx";
+
+console.log("== building ==");
+const build = await buildForPlatform({
+  platform: PLATFORM,
+  sources: { "main.c": SRC, "msx_vdp.c": LIB, "msx_crt0.s": CRT0 },
+  includes: { "msx_hw.h": HDR },
+  crt0: ".module empty\n",
+  sourceName: "main.c",
+});
+
+if (!build.binary) {
+  console.log(build.log || build.stderr || JSON.stringify(build));
+  console.log("BUILD FAILED stage=", build.stage, "exit=", build.exitCode);
+  process.exit(1);
+}
+console.log("build OK, bytes=", build.binary.length);
+
+const c = resolveCore(PLATFORM);
+const h = new LibretroHost();
+await h.loadCore(c.jsPath, c.wasmPath);
+await h.loadMedia({ platform: PLATFORM, bytes: build.binary });
+
+// ---- honest pixel helpers over raw RGBA ----
+function nonBlackFraction(rgba) {
+  let nb = 0;
+  for (let i = 0; i < rgba.length; i += 4) {
+    if (rgba[i] > 16 || rgba[i + 1] > 16 || rgba[i + 2] > 16) nb++;
+  }
+  return nb / (rgba.length / 4);
+}
+// Find the brightest-pixel X centroid in a horizontal band of rows (the basket
+// rides near the bottom; the basket sprite is white). Returns -1 if no bright px.
+function brightCentroidX(frame, y0, y1) {
+  const { width, height, rgba } = frame;
+  let sx = 0, n = 0;
+  for (let y = y0; y < Math.min(y1, height); y++) {
+    for (let x = 0; x < width; x++) {
+      const i = (y * width + x) * 4;
+      // white basket: all channels high
+      if (rgba[i] > 180 && rgba[i + 1] > 180 && rgba[i + 2] > 180) { sx += x; n++; }
+    }
+  }
+  return n ? sx / n : -1;
+}
+
+// boot past the C-BIOS logo + a few game frames
+for (let i = 0; i < 320; i++) h.stepFrames(1);
+
+const sa = h.screenshotRgba();
+writeFileSync(`${DIR}/shot_before.png`, Buffer.from(h.screenshot().pngBase64, "base64"));
+// basket band: BASKET_Y=160 in a 192-tall internal buffer; band 150..180
+const fracA = nonBlackFraction(sa.rgba);
+const basketA = brightCentroidX(sa, Math.floor(sa.height * 0.78), Math.floor(sa.height * 0.95));
+console.log(`before: ${sa.width}x${sa.height} nonBlack=${(fracA*100).toFixed(2)}% basketX=${basketA.toFixed(1)}`);
+
+// Drive RIGHT for many frames
+for (let i = 0; i < 120; i++) { h.setInput({ ports: [{ right: true }] }); h.stepFrames(1); }
+const sb = h.screenshotRgba();
+writeFileSync(`${DIR}/shot_after_right.png`, Buffer.from(h.screenshot().pngBase64, "base64"));
+const basketB = brightCentroidX(sb, Math.floor(sb.height * 0.78), Math.floor(sb.height * 0.95));
+console.log(`after RIGHT: basketX=${basketB.toFixed(1)}`);
+
+// Drive LEFT for many frames
+for (let i = 0; i < 200; i++) { h.setInput({ ports: [{ left: true }] }); h.stepFrames(1); }
+const sc = h.screenshotRgba();
+writeFileSync(`${DIR}/shot_after_left.png`, Buffer.from(h.screenshot().pngBase64, "base64"));
+const basketC = brightCentroidX(sc, Math.floor(sc.height * 0.78), Math.floor(sc.height * 0.95));
+console.log(`after LEFT: basketX=${basketC.toFixed(1)}`);
+
+// ---- verdict ----
+const visible = fracA > 0.005;            // playfield is not black
+const movedRight = basketB > basketA + 5; // basket moved right with input
+const movedLeft  = basketC < basketB - 5; // basket moved back left
+console.log("VISIBLE:", visible, "MOVED_RIGHT:", movedRight, "MOVED_LEFT:", movedLeft);
+if (visible && movedRight && movedLeft) {
+  console.log("VERIFIED_OK");
+} else {
+  console.log("VERIFY_INCOMPLETE");
+}

package/examples/msx/catch_game/main.c

@@ -0,0 +1,249 @@
+/*
+ * catch_game — a tiny COMPLETE MSX game (SDCC z80, C89).
+ *
+ * Move the basket at the bottom of the screen left/right with the joystick (or
+ * the keyboard cursor keys — stick 0) to catch the coin falling from the top.
+ * Catch it: +1 score and the coin respawns at the top in a new column. Miss it
+ * (it reaches the floor): the coin just respawns, no penalty — a friendly demo.
+ * The score is drawn as on-screen tiles ("SCORE 000") along the top row.
+ *
+ * Hardware path (all through the romdev MSX helper lib, no fragile inline asm):
+ *   - msx_set_screen2()      screen 2 (GRAPHIC II), 256x192, display ON
+ *   - msx_vram_write()       upload our tile font + sprite patterns to VRAM
+ *   - msx_set_sprite()       position the basket + coin sprites each frame
+ *   - msx_read_joystick()    BIOS GTSTCK — 0=center, 1-8 = direction clockwise
+ *   - msx_psg_tone/off()     a short blip on a catch
+ *   - msx_vblank_wait()      one game step per VDP frame (~60 Hz NTSC)
+ *
+ * Cartridge rule: INIT must never return, so main() ends in for(;;). C-BIOS
+ * shows its logo ~150 frames before CALLing the cart — step >= 300 before you
+ * expect to see the playfield.
+ *
+ * Build (multi-source — .c/.s in `sources`, .h in `includes`):
+ *   buildForPlatform({ platform:"msx",
+ *     sources:  { "main.c":<this>, "msx_vdp.c":<lib>, "msx_crt0.s":<crt0> },
+ *     includes: { "msx_hw.h":<hdr> },
+ *     crt0:".module empty\n", sourceName:"main.c" })
+ */
+#include "msx_hw.h"
+
+/* ── interrupt-free vblank sync ─────────────────────────────────────────────
+ * The shared lib's msx_vblank_wait() spins on the BIOS JIFFY counter, which
+ * only advances if the BIOS VBlank ISR is running (interrupts enabled). On a
+ * bare cartridge we can't rely on that, so we poll the VDP itself: VDP status
+ * register S#0 bit 7 is the frame (VBlank) flag — it sets at the start of
+ * vertical blanking and the act of READING S#0 clears it. So we read once to
+ * clear, then spin until it sets again = exactly one frame elapsed. This needs
+ * no interrupts and works on any MSX. Port 0x99 returns the selected status
+ * register; S#0 is selected by default after INIGRP. */
+__sfr __at 0x99 VDPSTATUS;   /* reading port 0x99 returns the selected S# */
+
+static void vsync(void) {
+    (void)VDPSTATUS;                 /* clear any pending frame flag */
+    while (!(VDPSTATUS & 0x80)) {    /* wait for the next VBlank */
+    }
+}
+
+/* ── tile font ────────────────────────────────────────────────────────────
+ * Screen 2's pattern generator holds 256 8x8 chars per third of the screen.
+ * We define a tiny font (space, S C O R E, and the 10 digits) and place those
+ * patterns at known tile indices, then replicate the SAME pattern bytes into
+ * all three pattern-generator thirds so a tile renders identically anywhere.
+ *
+ * Each glyph is 8 bytes (one bitmask per row, MSB = leftmost pixel). */
+
+/* tile indices we assign to glyphs in the name table */
+#define T_SPACE 0
+#define T_S     1
+#define T_C     2
+#define T_O     3
+#define T_R     4
+#define T_E     5
+#define T_0     6   /* digits 0..9 are consecutive: T_0 + n */
+
+/* 16 glyph patterns (indices 0..15, the rest of VRAM stays blank) */
+static const uint8_t font[16][8] = {
+    /* 0  SPACE */ {0,0,0,0,0,0,0,0},
+    /* 1  S */ {0x7C,0xC0,0xC0,0x78,0x0C,0x0C,0xF8,0x00},
+    /* 2  C */ {0x7C,0xC6,0xC0,0xC0,0xC0,0xC6,0x7C,0x00},
+    /* 3  O */ {0x7C,0xC6,0xC6,0xC6,0xC6,0xC6,0x7C,0x00},
+    /* 4  R */ {0xFC,0xC6,0xC6,0xFC,0xD8,0xCC,0xC6,0x00},
+    /* 5  E */ {0xFE,0xC0,0xC0,0xF8,0xC0,0xC0,0xFE,0x00},
+    /* 6  0 */ {0x7C,0xCE,0xDE,0xF6,0xE6,0xC6,0x7C,0x00},
+    /* 7  1 */ {0x18,0x38,0x18,0x18,0x18,0x18,0x7E,0x00},
+    /* 8  2 */ {0x7C,0xC6,0x06,0x1C,0x70,0xC0,0xFE,0x00},
+    /* 9  3 */ {0x7C,0xC6,0x06,0x3C,0x06,0xC6,0x7C,0x00},
+    /* 10 4 */ {0x1C,0x3C,0x6C,0xCC,0xFE,0x0C,0x0C,0x00},
+    /* 11 5 */ {0xFE,0xC0,0xFC,0x06,0x06,0xC6,0x7C,0x00},
+    /* 12 6 */ {0x3C,0x60,0xC0,0xFC,0xC6,0xC6,0x7C,0x00},
+    /* 13 7 */ {0xFE,0x06,0x0C,0x18,0x30,0x30,0x30,0x00},
+    /* 14 8 */ {0x7C,0xC6,0xC6,0x7C,0xC6,0xC6,0x7C,0x00},
+    /* 15 9 */ {0x7C,0xC6,0xC6,0x7E,0x06,0x0C,0x78,0x00}
+};
+
+/* ── sprite patterns ───────────────────────────────────────────────────────
+ * Two 8x8 sprite patterns: the basket (plane 0) and the coin (plane 1).
+ * Sprite pattern N lives at sprite-pattern-base + N*8. */
+static const uint8_t spr_basket[8] = {
+    0x00, 0x00, 0x81, 0x81, 0xC3, 0x7E, 0x3C, 0x00  /* an open cup/basket */
+};
+static const uint8_t spr_coin[8] = {
+    0x3C, 0x7E, 0xFF, 0xFF, 0xFF, 0xFF, 0x7E, 0x3C  /* a round coin */
+};
+
+/* sprite colours (TMS9918 fixed palette): 4=blue, 10=yellow, 15=white */
+#define COL_BASKET 15
+#define COL_COIN   10
+
+/* ── game state ──────────────────────────────────────────────────────────── */
+static uint8_t  basket_x;   /* basket sprite X (pixels), 0..248                */
+static uint8_t  coin_x;     /* coin sprite X (pixels)                          */
+static uint8_t  coin_y;     /* coin sprite Y (pixels), grows until caught/floor*/
+static uint16_t score;      /* caught count                                    */
+static uint16_t rng;        /* tiny LFSR-ish pseudo-random for respawn columns */
+
+#define BASKET_Y    160     /* basket rides near the bottom                    */
+#define FLOOR_Y     168     /* below this the coin is "missed"                 */
+#define BASKET_W    8
+#define COIN_W      8
+
+/* upload the 16 glyph patterns into ALL THREE screen-2 pattern thirds, and
+ * paint a solid colour (white on black) over the tile rows we draw text in.
+ * Pattern third K covers tile rows K*8..K*8+7; each third is 0x800 bytes of
+ * pattern and 0x800 of colour. We only use the top third for the score line,
+ * but writing all three keeps any tile we place looking right. */
+static void load_font(void) {
+    uint8_t third;
+    uint16_t patbase, colbase;
+    uint8_t i;
+
+    for (third = 0; third < 3; third++) {
+        patbase = (uint16_t)(VRAM_PATTERN + ((uint16_t)third << 11));
+        colbase = (uint16_t)(VRAM_COLOR   + ((uint16_t)third << 11));
+        for (i = 0; i < 16; i++) {
+            /* pattern bytes for glyph i */
+            msx_vram_write((uint16_t)(patbase + ((uint16_t)i << 3)), font[i], 8);
+            /* colour bytes for glyph i: 0xF0 = white fg (15) on black bg (0) */
+            msx_fill_vram((uint16_t)(colbase + ((uint16_t)i << 3)), 8, 0xF0);
+        }
+    }
+}
+
+/* place one tile (pattern index) at name-table cell (col,row) of the 32x24 grid */
+static void put_tile(uint8_t col, uint8_t row, uint8_t tile) {
+    uint16_t addr = (uint16_t)(VRAM_NAME + (uint16_t)row * 32 + col);
+    msx_vram_write(addr, &tile, 1);
+}
+
+/* draw the static "SCORE" label at the top-left */
+static void draw_label(void) {
+    put_tile(1, 0, T_S);
+    put_tile(2, 0, T_C);
+    put_tile(3, 0, T_O);
+    put_tile(4, 0, T_R);
+    put_tile(5, 0, T_E);
+}
+
+/* draw the 3-digit score after the label */
+static void draw_score(void) {
+    uint16_t s = score;
+    uint8_t hundreds = (uint8_t)((s / 100) % 10);
+    uint8_t tens     = (uint8_t)((s / 10) % 10);
+    uint8_t ones     = (uint8_t)(s % 10);
+    put_tile(7, 0, (uint8_t)(T_0 + hundreds));
+    put_tile(8, 0, (uint8_t)(T_0 + tens));
+    put_tile(9, 0, (uint8_t)(T_0 + ones));
+}
+
+/* cheap pseudo-random 0..255 (xorshift on a 16-bit seed) */
+static uint8_t next_rand(void) {
+    rng ^= (uint16_t)(rng << 7);
+    rng ^= (uint16_t)(rng >> 9);
+    rng ^= (uint16_t)(rng << 8);
+    return (uint8_t)(rng & 0xFF);
+}
+
+/* respawn the coin at the top in a random column (8..240) */
+static void respawn_coin(void) {
+    coin_x = (uint8_t)(8 + (next_rand() % 232));
+    coin_y = 0;
+}
+
+void main(void) {
+    uint8_t stick, dir, frame;
+
+    /* ── set up the screen ── */
+    msx_set_screen2();          /* screen 2, VRAM cleared, display ON */
+    msx_clear_sprites();        /* park all 32 sprite planes off-list */
+    load_font();                /* upload glyph patterns + colours    */
+
+    /* fill the whole 32x24 name table with the SPACE tile so the playfield is
+     * uniformly blank under our score line + sprites */
+    msx_fill_vram(VRAM_NAME, 32 * 24, T_SPACE);
+
+    /* upload the two 8x8 sprite patterns: basket=pattern 0, coin=pattern 1 */
+    msx_vram_write((uint16_t)(VRAM_SPRPAT + 0 * 8), spr_basket, 8);
+    msx_vram_write((uint16_t)(VRAM_SPRPAT + 1 * 8), spr_coin,   8);
+
+    draw_label();
+
+    /* ── init game state ── */
+    basket_x = 120;
+    score = 0;
+    rng = 0xACE1;               /* nonzero LFSR seed */
+    respawn_coin();
+    frame = 0;
+    draw_score();
+
+    /* ── main loop: one step per VDP frame ── */
+    for (;;) {
+        vsync();
+
+        /* read joystick 0 (keyboard cursor) AND joystick 1 (port), so it works
+         * whether the player uses keys or a pad. Any nonzero wins. */
+        dir = msx_read_joystick(0);
+        if (dir == STICK_CENTER) {
+            dir = msx_read_joystick(1);
+        }
+        stick = dir;
+
+        /* left = directions 6,7,8 (DL,LEFT,UL); right = 2,3,4 (UR,RIGHT,DR) */
+        if (stick == STICK_LEFT || stick == STICK_UL || stick == STICK_DL) {
+            if (basket_x >= 3) basket_x -= 3;
+        } else if (stick == STICK_RIGHT || stick == STICK_UR || stick == STICK_DR) {
+            if (basket_x <= 248 - 3) basket_x += 3;
+        }
+
+        /* coin falls 2px/frame */
+        coin_y += 2;
+
+        /* caught? coin overlaps the basket near the basket row */
+        if (coin_y + COIN_W >= BASKET_Y && coin_y <= BASKET_Y + 8) {
+            /* AABB overlap on X */
+            if (coin_x + COIN_W > basket_x && coin_x < basket_x + BASKET_W) {
+                score++;
+                if (score > 999) score = 0;
+                draw_score();
+                /* short catch blip on PSG channel 0 */
+                msx_psg_tone(0, 0x080, 13);
+                frame = 4;       /* hold the blip ~4 frames then silence */
+                respawn_coin();
+            }
+        }
+
+        /* missed (hit the floor)? just respawn — friendly demo, no game-over */
+        if (coin_y >= FLOOR_Y) {
+            respawn_coin();
+        }
+
+        /* silence the catch blip a few frames after it started */
+        if (frame) {
+            frame--;
+            if (frame == 0) msx_psg_off(0);
+        }
+
+        /* push sprite positions for this frame */
+        msx_set_sprite(0, basket_x, BASKET_Y, 0, COL_BASKET);  /* plane 0 basket */
+        msx_set_sprite(1, coin_x,   coin_y,   1, COL_COIN);    /* plane 1 coin   */
+    }
+}

package/examples/msx/music_sfx/README.md

@@ -0,0 +1,38 @@
+# MSX — music_sfx
+
+AY-3-8910 PSG demo with on-screen state.
+
+- **Channel A** plays a looping 8-note melody (~0.2 s/note).
+- **Channel B** plays a soft bass line under it (harmony).
+- **Channel C** fires a descending "blip" SFX on the joystick **trigger** press
+  edge (`gttrig(1)`, bit 7 = pressed).
+
+On screen (sprites — screen 2's font isn't loaded, so sprites are the reliable
+"visible state"):
+
+- A **step sequencer**: eight beat markers, the one for the current melody step
+  lights **yellow**, the rest are gray. They're split across two rows of four so
+  the VDP's 4-sprites-per-scanline limit doesn't drop any.
+- A **big 16x16 ring indicator** turns **red** while the trigger is held (white
+  when idle). Uses the VDP 16x16 sprite-size bit (`R1` bit 1).
+
+Shows `msx_psg_tone(chan, period, vol)` / `msx_psg_off(chan)`, multi-channel PSG
+mixing, and trigger input. AY note period = 1789772 / (16 × freq); period 0 =
+silent.
+
+Build (link the helper lib):
+
+```js
+buildForPlatform({
+  platform: "msx",
+  sources:  { "main.c": …, "msx_vdp.c": …, "msx_crt0.s": … },
+  includes: { "msx_hw.h": … },
+  crt0: ".module empty\n", sourceName: "main.c",
+})
+```
+
+Verified on the bluemsx core: chA cycles 6 distinct note periods, chB 3 bass
+periods, chC stays silent until the trigger is held then sweeps through 17
+descending periods. Screenshots before/after a held trigger confirm the ring
+indicator flips white → red and the sequencer beat lights — see
+`audioDebug({op:'inspect', chip:"ay8910"})` and `memory({op:'read'}, "msx_psg_regs", …)`.