romdevtools 0.13.0

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

@@ -0,0 +1,103 @@
+// MSX screen-2 (GRAPHIC II) image-to-tilemap converter.
+//
+// screen-2 is the MSX1 workhorse "bitmap-ish" mode: the 256×192 screen is 32×24
+// cells, each cell a unique 8×8 tile (the name table usually just counts
+// 0,1,2,... per third of the screen). Each tile is:
+//   - PATTERN: 8 bytes, 1bpp (bit 7 = leftmost pixel; 1 = foreground)
+//   - COLOR:   8 bytes, one per row: high nibble = fg color (0-15), low = bg.
+// The 16 colors are the fixed TMS9918 palette. Each ROW of a tile is limited to
+// 2 colors — that's the classic MSX constraint this converter honors.
+//
+// A full 256×192 screen-2 picture is 768 unique tiles (3 banks of 256). This
+// converter emits the name table (768 bytes: 0..255 ×3), the pattern table
+// (768×8 = 6144 B) and the color table (6144 B), all DMA-ready.
+
+import { PNG } from "pngjs";
+import { TMS9918_PALETTE } from "./vdp.js";
+
+/** Nearest TMS9918 palette index for an RGB triple. */
+function nearestTms(r, g, b) {
+  let best = 0, bestD = Infinity;
+  for (let c = 0; c < 16; c++) {
+    const [pr, pg, pb] = TMS9918_PALETTE[c];
+    const dd = (pr - r) ** 2 + (pg - g) ** 2 + (pb - b) ** 2;
+    if (dd < bestD) { bestD = dd; best = c; }
+  }
+  return best;
+}
+
+/**
+ * @param {{ pngBytes: Uint8Array|Buffer }} args  PNG must be 256×192.
+ * @returns {{ tiles: Uint8Array, color: Uint8Array, nametable: Uint8Array,
+ *   uniqueTiles: number, tilesAcross: number, tilesDown: number }}
+ */
+export function msxImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  const { width: W, height: H } = png;
+  if (W !== 256 || H !== 192) {
+    throw new Error(`MSX screen-2 image must be 256×192, got ${W}×${H}.`);
+  }
+  // Index every pixel to the fixed 16-color palette.
+  const idx = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    idx[i] = nearestTms(png.data[k], png.data[k + 1], png.data[k + 2]);
+  }
+
+  const tilesAcross = 32, tilesDown = 24;
+  const total = tilesAcross * tilesDown; // 768
+  const pattern = new Uint8Array(total * 8);
+  const color = new Uint8Array(total * 8);
+  const nametable = new Uint8Array(total);
+
+  let t = 0;
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      // Per-row: pick the row's 2 most-frequent colors (fg = 2nd, bg = 1st).
+      for (let row = 0; row < 8; row++) {
+        const counts = new Map();
+        for (let x = 0; x < 8; x++) {
+          const v = idx[(ty * 8 + row) * W + (tx * 8 + x)];
+          counts.set(v, (counts.get(v) || 0) + 1);
+        }
+        const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]).map((e) => e[0]);
+        const bg = sorted[0] ?? 0;
+        const fg = sorted.find((c) => c !== bg) ?? bg;
+        let bits = 0;
+        for (let x = 0; x < 8; x++) {
+          const v = idx[(ty * 8 + row) * W + (tx * 8 + x)];
+          const isFg = v === fg || (v !== bg && Math.abs(v - fg) < Math.abs(v - bg));
+          if (isFg) bits |= 1 << (7 - x);
+        }
+        pattern[t * 8 + row] = bits;
+        color[t * 8 + row] = ((fg & 0x0f) << 4) | (bg & 0x0f);
+      }
+      // screen-2 name table: tiles are addressed 0..255 within each screen third.
+      nametable[t] = t & 0xff;
+      t++;
+    }
+  }
+
+  return {
+    tiles: pattern,            // the pattern-generator table (1bpp)
+    color,                     // the color table (per-row fg/bg)
+    nametable,                 // 768 bytes: 0..255 × 3 thirds
+    uniqueTiles: total,
+    tilesAcross,
+    tilesDown,
+  };
+}
+
+/** Render the fixed TMS9918 palette as a swatch PNG (for the tool preview). */
+export function msxPalettePng() {
+  const cols = 16, sw = 12;
+  const png = new PNG({ width: cols * sw, height: sw });
+  for (let i = 0; i < 16; i++) {
+    const [r, g, b] = TMS9918_PALETTE[i];
+    for (let y = 0; y < sw; y++) for (let x = 0; x < sw; x++) {
+      const o = (y * cols * sw + i * sw + x) * 4;
+      png.data[o] = r; png.data[o + 1] = g; png.data[o + 2] = b; png.data[o + 3] = 255;
+    }
+  }
+  return PNG.sync.write(png);
+}

package/src/platforms/msx/lib/c/hello_msx.c

@@ -0,0 +1,51 @@
+/*
+ * hello_msx.c — MSX / MSX2 starter (SDCC z80, C89).
+ *
+ * Boots to a guaranteed-VISIBLE screen by calling the MSX BIOS:
+ *   INITXT ($006C) — set the 40-column text screen (mode 0) and clear it.
+ *   CHPUT  ($00A2) — print the char in register A at the cursor.
+ * C-BIOS (the open MSX BIOS romdev bundles) provides these. No proprietary ROM.
+ *
+ * Build with the cartridge crt0 (msx_crt0.s), which emits the "AB" ROM header
+ * at $4000 and points INIT at this code:
+ *   build({output:'rom'})({ platform:"msx",
+ *     sources: { "main.c": <this>, "msx_crt0.s": <the crt0> },
+ *     crt0: ".module empty\n" })           // empty stock crt0
+ *
+ * IMPORTANT — a cartridge INIT routine must NOT return: C-BIOS CALLs INIT to
+ * hand the machine to the cart, and if INIT `ret`s the BIOS thinks no bootable
+ * cart is present ("No cartridge found"). So main() ends in an infinite loop —
+ * the cart keeps control. Don't add a `return` to main.
+ *
+ * TIMING — C-BIOS shows its logo for ~2-3 seconds (≈150 frames) BEFORE it CALLs
+ * the cart INIT. When testing, step at least 240 frames before expecting output.
+ */
+void main(void) {
+    /* INITXT (set + clear the text screen) then walk a string through CHPUT.
+     * The message bytes sit inside this same asm block (jumped over) so the
+     * label and the print loop share scope and we don't depend on SDCC's
+     * stack-frame calling convention. $0D/$0A = CR/LF between the two lines. */
+    __asm
+        call  0x006C            ; INITXT — 40-col text mode, screen enabled
+
+        ld    hl, #msg$
+print_loop$:
+        ld    a, (hl)
+        or    a, a
+        jr    Z, print_done$
+        call  0x00A2            ; CHPUT — print char in A
+        inc   hl
+        jr    print_loop$
+msg$:
+        .ascii  "HELLO MSX"
+        .db     0x0D, 0x0A
+        .ascii  "ROMDEV TIER-1"
+        .db     0
+print_done$:
+    __endasm;
+
+    /* A cartridge INIT must never return — keep control forever.
+     * A real game would read input + update game state in this loop. */
+    for (;;) {
+    }
+}

package/src/platforms/msx/lib/c/msx_crt0.s

@@ -0,0 +1,74 @@
+;; MSX / MSX2 cartridge crt0 for SDCC (z80 port).
+;;
+;; An MSX ROM cartridge maps at $4000-$BFFF. The first 16 bytes are the ROM
+;; header the BIOS scans on boot:
+;;   $4000: "AB"  (0x41 0x42)  — the cartridge magic
+;;   $4002: INIT  pointer       — the BIOS CALLs this (with a valid stack) to
+;;                                start the cartridge program
+;;   $4004: STATEMENT  ptr      — BASIC CALL handler (0 = none)
+;;   $4006: DEVICE     ptr      — expansion-device handler (0 = none)
+;;   $4008: TEXT       ptr      — BASIC program text (0 = none)
+;;   $400A..$400F: reserved (0)
+;;
+;; Replaces SDCC's stock z80 crt0 (which is a CP/M-style $0000 runtime that
+;; talks to a host via rst $08 — wrong for a cartridge). This one emits the
+;; header, runs the SDCC global-initializer pass, calls main(), then RETs back
+;; to the BIOS (the BIOS gave us the stack, so we don't touch SP).
+;;
+;; Build it as the FIRST object so its _HEADER area lands at $4000. romdev links
+;; _CODE at $4010; this header occupies $4000-$400F. Pass via:
+;;   build({output:'rom'})({ platform:"msx", sources:{ "main.c":..., "msx_crt0.s":<this> },
+;;                 crt0: ".module empty\n" })   // empty stock crt0
+;;
+;; C-BIOS shows its logo for ~2-3s, THEN CALLs INIT — step >= 240 frames before
+;; expecting the cart's output on screen.
+
+        .module msx_crt0
+        .globl  _main
+        .globl  l__INITIALIZER
+        .globl  s__INITIALIZER
+        .globl  s__INITIALIZED
+
+;; ─── Cartridge ROM header at $4000 ────────────────────────────────
+        .area   _HEADER (ABS)
+        .org    0x4000
+        .db     0x41, 0x42          ; "AB" — cartridge magic
+        .dw     init                ; INIT  — BIOS calls this to start us
+        .dw     0x0000              ; STATEMENT (none)
+        .dw     0x0000              ; DEVICE (none)
+        .dw     0x0000              ; TEXT (none)
+        .dw     0x0000              ; reserved
+        .dw     0x0000              ; reserved
+        .dw     0x0000              ; reserved
+
+;; ─── crt0 body ────────────────────────────────────────────────────
+;; Standard SDCC area order so the linker fills _GSINIT with the global
+;; initializer fragments sdcc emits, then _GSFINAL.
+        .area   _HOME
+        .area   _CODE
+        .area   _GSINIT
+        .area   _GSFINAL
+
+        .area   _DATA
+        .area   _INITIALIZED
+        .area   _BSEG
+        .area   _BSS
+        .area   _HEAP
+
+        .area   _CODE
+
+;; INIT entry — the BIOS CALLs here with interrupts on and a valid stack.
+init:
+        ;; Copy initialized-data image from ROM to RAM (SDCC global inits).
+        ld      bc, #l__INITIALIZER
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_done
+        ld      de, #s__INITIALIZED
+        ld      hl, #s__INITIALIZER
+        ldir
+gsinit_done:
+        call    _main
+        ;; Return to the BIOS (it set up the stack and CALLed INIT). A cart that
+        ;; never returns just loops in main(); returning hands control back.
+        ret

package/src/platforms/msx/lib/c/msx_hw.h

@@ -0,0 +1,92 @@
+/* MSX / MSX2 hardware helper library for SDCC (z80, C89).
+ *
+ * Everything here drives the VDP and PSG through DIRECT Z80 I/O PORTS — no
+ * fragile IX-offset inline asm. Under SDCC's default `--sdcccall 1` the first
+ * function argument arrives in registers (NOT on the stack), so the old
+ * `ld c,4(ix)` style wrappers read garbage. The direct-port approach below is
+ * verified on the bluemsx core (msx_wrtvdp(7,0x55) -> msx_vdp_regs[7]==0x55).
+ *
+ * SDCC `__sfr __at <port>` binds a name to a Z80 I/O port: reading the variable
+ * emits `in a,(port)`, writing emits `out (port),a`. That gives us VDP/PSG
+ * access in plain C.
+ *
+ * Add msx_vdp.c to your build alongside main.c and msx_crt0.s:
+ *   buildForPlatform({ platform:"msx",
+ *     sources: { "main.c":..., "msx_vdp.c":..., "msx_crt0.s":... },
+ *     includes:{ "msx_hw.h":... },
+ *     crt0: ".module empty\n", sourceName:"main.c" })
+ */
+#ifndef MSX_HW_H
+#define MSX_HW_H
+
+#include <stdint.h>
+
+/* ─── VDP I/O ports (V9938 on MSX2; TMS9918 on MSX1) ────────────────────── */
+__sfr __at 0x98 VDPDATA;   /* VRAM data read/write (address auto-increments) */
+__sfr __at 0x99 VDPCTRL;   /* address-set (lo then hi) + register write       */
+__sfr __at 0x9A VDPPAL;    /* V9938 palette write (MSX2 only)                 */
+__sfr __at 0x9B VDPREG;    /* V9938 indirect register write (MSX2 only)       */
+
+/* ─── PSG (AY-3-8910), reached through the PPI on ports 0xA0..0xA2 ──────── */
+__sfr __at 0xA0 PSGADDR;   /* select PSG register 0-15                        */
+__sfr __at 0xA1 PSGWRITE;  /* write the selected PSG register                 */
+__sfr __at 0xA2 PSGREAD;   /* read the selected PSG register                  */
+
+/* ─── VDP address-set high-byte flags (for raw VDPCTRL sequencing) ─────────
+ * Set address: VDPCTRL = lo; VDPCTRL = (hi & 0x3F) | <flag>;
+ *   - VRAM write  -> OR with 0x40, then stream bytes out via VDPDATA
+ *   - VRAM read   -> OR with 0x00, then read bytes in  via VDPDATA
+ *   - register    -> VDPCTRL = value; VDPCTRL = 0x80 | reg;  (see msx_wrtvdp)  */
+#define VDP_VRAM_READ  0x00
+#define VDP_VRAM_WRITE 0x40
+#define VDP_REG_WRITE  0x80
+
+/* ─── screen 2 (GRAPHIC II) VRAM layout, the default this lib sets up ──────
+ * 256x192, 32x24 cells, three colour-banked thirds. These match the V9938
+ * register values written by msx_set_screen2() (R2=0x06,R3=0xFF,R4=0x03,
+ * R5=0x36,R6=0x07,R10=0x00,R11=0x00). */
+#define VRAM_PATTERN  0x0000  /* pattern generator  (R4=0x03 -> 0x03<<11)      */
+#define VRAM_NAME     0x1800  /* name table         (R2=0x06 -> 0x06<<10)      */
+#define VRAM_SPRPAT   0x3800  /* sprite patterns    (R6=0x07 -> 0x07<<11)      */
+#define VRAM_SPRATTR  0x1B00  /* sprite attributes  (R5=0x36 -> 0x36<<7)       */
+#define VRAM_COLOR    0x2000  /* colour table       (R3=0xFF,R10=0x00 -> 0x2000)*/
+
+/* ─── joystick directions returned by msx_read_joystick (0=center, CW) ───── */
+#define STICK_CENTER 0
+#define STICK_UP     1
+#define STICK_UR     2
+#define STICK_RIGHT  3
+#define STICK_DR     4
+#define STICK_DOWN   5
+#define STICK_DL     6
+#define STICK_LEFT   7
+#define STICK_UL     8
+
+/* ─── sprite-list terminator: a sprite Y of 0xD0 (208) ends the OAM scan ─── */
+#define SPRITE_END_Y 0xD0
+
+/* ─── BIOS entry addresses we still use (called via function-pointer cast) ── */
+#define BIOS_INITXT 0x006C  /* set 40-col text screen (mode 0) + clear        */
+#define BIOS_INIGRP 0x0072  /* set screen-2 (GRAPHIC II) + clear              */
+
+/* ─── BIOS calls via the SDCC function-pointer-cast trick ──────────────────
+ * Clean under sdcccall(1): A in / A out, no stack-frame juggling. GTSTCK/GTTRIG
+ * live at fixed ROM addresses on every MSX. */
+static uint8_t gtstck(uint8_t s) { return ((uint8_t (*)(uint8_t))0x00D5)(s); }
+static uint8_t gttrig(uint8_t t) { return ((uint8_t (*)(uint8_t))0x00D8)(t); }
+
+/* ─── helper prototypes (implemented in msx_vdp.c, all via direct ports) ─── */
+void    msx_set_screen2(void);
+void    msx_wrtvdp(uint8_t reg, uint8_t value);
+void    msx_vram_write(uint16_t addr, const uint8_t *src, uint16_t len);
+void    msx_fill_vram(uint16_t addr, uint16_t len, uint8_t byte);
+void    msx_set_palette_entry(uint8_t idx, uint16_t grb);
+void    msx_set_sprite(uint8_t plane, uint8_t x, uint8_t y,
+                       uint8_t pattern, uint8_t color);
+void    msx_clear_sprites(void);
+void    msx_vblank_wait(void);
+uint8_t msx_read_joystick(uint8_t stick);
+void    msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol);
+void    msx_psg_off(uint8_t chan);
+
+#endif /* MSX_HW_H */

package/src/platforms/msx/lib/c/msx_vdp.c

@@ -0,0 +1,150 @@
+/* MSX VDP + PSG + input helpers (SDCC z80, C89) — DIRECT-PORT implementation.
+ *
+ * The previous version drove the BIOS through `ld c,4(ix)` inline asm. That is
+ * broken under SDCC's default `--sdcccall 1`: the first argument is passed in a
+ * register, so 4(ix) reads a stale stack slot — msx_wrtvdp(7,0x55) wrote 0xF5
+ * instead of 0x55. Everything here goes straight to the Z80 I/O ports declared
+ * in msx_hw.h, so the C arguments are used exactly as written. Verified on the
+ * bluemsx core.
+ *
+ * VDP register write (the canonical sequence, no BIOS needed):
+ *   VDPCTRL = value;              ; data byte first
+ *   VDPCTRL = 0x80 | reg;         ; then the register selector
+ * VRAM address set:
+ *   VDPCTRL = addr & 0xFF;        ; low byte
+ *   VDPCTRL = ((addr>>8)&0x3F) | flag;  flag = 0x40 write / 0x00 read
+ * then stream/read bytes through VDPDATA (auto-increments).
+ */
+#include "msx_hw.h"
+
+/* Set the VDP autoincrement write pointer to a VRAM address. */
+static void vram_set_write(uint16_t addr) {
+    VDPCTRL = (uint8_t)(addr & 0xFF);
+    VDPCTRL = (uint8_t)(((addr >> 8) & 0x3F) | VDP_VRAM_WRITE);
+}
+
+/* Write one VDP register (R0..R23 on the V9938). */
+void msx_wrtvdp(uint8_t reg, uint8_t value) {
+    VDPCTRL = value;
+    VDPCTRL = (uint8_t)(0x80 | reg);
+}
+
+/* Initialise screen 2 (GRAPHIC II): 256x192, pattern/colour/name/sprite tables
+ * laid out per msx_hw.h's VRAM_* defines. We let the BIOS INIGRP set the base
+ * registers + clear VRAM (it also wires the interrupt + slot state correctly),
+ * which avoids hand-poking every register. INIGRP needs no arguments, so the
+ * bare `call` is safe under any calling convention. */
+void msx_set_screen2(void) {
+    __asm
+        call #0x0072            ; INIGRP — screen 2, clear VRAM, display on
+    __endasm;
+}
+
+/* Copy len bytes from RAM into VRAM starting at addr (auto-increment). */
+void msx_vram_write(uint16_t addr, const uint8_t *src, uint16_t len) {
+    vram_set_write(addr);
+    while (len--) {
+        VDPDATA = *src++;
+    }
+}
+
+/* Fill len VRAM bytes from addr with a constant byte. */
+void msx_fill_vram(uint16_t addr, uint16_t len, uint8_t byte) {
+    vram_set_write(addr);
+    while (len--) {
+        VDPDATA = byte;
+    }
+}
+
+/* Set one V9938 palette entry (MSX2). `grb` packs 3-bit components as
+ * 0x0GRB-ish: bits 8..10 = green, bits 4..6 = red, bits 0..2 = blue. The V9938
+ * protocol: point R16 (colour pointer) at the index, then write two bytes to
+ * port 0x9A — first (red<<4)|blue, then green. */
+void msx_set_palette_entry(uint8_t idx, uint16_t grb) {
+    uint8_t r = (uint8_t)((grb >> 4) & 0x07);
+    uint8_t g = (uint8_t)((grb >> 8) & 0x07);
+    uint8_t b = (uint8_t)(grb & 0x07);
+    msx_wrtvdp(16, (uint8_t)(idx & 0x0F)); /* R16 = palette index */
+    VDPPAL = (uint8_t)((r << 4) | b);      /* byte 0: RRRR_0BBB */
+    VDPPAL = (uint8_t)(g);                 /* byte 1: 0000_0GGG */
+}
+
+/* Write one sprite into the screen-2 sprite-attribute table.
+ * Each OAM entry is 4 bytes: Y, X, pattern, colour(+ EC/tag bits). */
+void msx_set_sprite(uint8_t plane, uint8_t x, uint8_t y,
+                    uint8_t pattern, uint8_t color) {
+    uint16_t addr = (uint16_t)(VRAM_SPRATTR + ((uint16_t)plane << 2));
+    vram_set_write(addr);
+    VDPDATA = y;
+    VDPDATA = x;
+    VDPDATA = pattern;
+    VDPDATA = color;
+}
+
+/* Hide every sprite by terminating the OAM scan at plane 0 (Y=0xD0). */
+void msx_clear_sprites(void) {
+    uint8_t i;
+    vram_set_write(VRAM_SPRATTR);
+    for (i = 0; i < 32; i++) {
+        VDPDATA = SPRITE_END_Y; /* Y = 208 terminates / parks the sprite */
+        VDPDATA = 0;
+        VDPDATA = 0;
+        VDPDATA = 0;
+    }
+}
+
+/* Spin until the BIOS frame counter (JIFFY, $FC9E low byte) advances — i.e.
+ * until the next VBlank interrupt has been serviced. Reading a fixed RAM
+ * address is convention-independent, so plain asm is fine here. */
+void msx_vblank_wait(void) {
+    __asm
+        ld   hl, #0xFC9E       ; JIFFY low byte (incremented each VBlank ISR)
+        ld   a, (hl)
+000001$:
+        cp   a, (hl)
+        jr   z, 000001$
+    __endasm;
+}
+
+/* Read a joystick (0 = keyboard cursor, 1/2 = ports). Returns 0=center,
+ * 1-8 = direction clockwise from up. Uses the BIOS GTSTCK via the clean
+ * function-pointer cast (A in / A out). */
+uint8_t msx_read_joystick(uint8_t stick) {
+    return gtstck(stick);
+}
+
+/* Play a square-tone on PSG channel 0/1/2 at the given 12-bit period and
+ * volume 0-15. Clears the matching tone-disable bit in the mixer (reg 7, the
+ * mixer is active-LOW: a clear bit enables that channel's tone). */
+void msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol) {
+    uint8_t mixer;
+    uint8_t fine = (uint8_t)(period & 0xFF);
+    uint8_t coarse = (uint8_t)((period >> 8) & 0x0F);
+
+    /* tone period: regs 0/1 (A), 2/3 (B), 4/5 (C) */
+    PSGADDR = (uint8_t)(chan << 1);       PSGWRITE = fine;
+    PSGADDR = (uint8_t)((chan << 1) + 1); PSGWRITE = coarse;
+
+    /* volume: regs 8/9/10 */
+    PSGADDR = (uint8_t)(8 + chan);        PSGWRITE = (uint8_t)(vol & 0x0F);
+
+    /* mixer (reg 7): clear this channel's tone bit (bits 0-2), keep noise off
+     * (bits 3-5 set) and the two I/O-direction bits (6,7) set for output. */
+    PSGADDR = 7;
+    mixer = PSGREAD;
+    mixer |= 0x38;                         /* noise off for all 3 channels   */
+    mixer &= (uint8_t)~(1 << chan);        /* tone ON for this channel       */
+    PSGADDR = 7;
+    PSGWRITE = mixer;
+}
+
+/* Silence a PSG channel: zero its volume and re-disable its tone bit. */
+void msx_psg_off(uint8_t chan) {
+    uint8_t mixer;
+    PSGADDR = (uint8_t)(8 + chan); PSGWRITE = 0;  /* volume 0 */
+    PSGADDR = 7;
+    mixer = PSGREAD;
+    mixer |= (uint8_t)(1 << chan);                /* tone OFF for this channel */
+    PSGADDR = 7;
+    PSGWRITE = mixer;
+}

package/src/platforms/msx/tiles.js

@@ -0,0 +1,99 @@
+// MSX TMS9918 / V9938 tile codec.
+//
+// MSX1 "screen 2" (GRAPHIC II) is the workhorse BG mode for homebrew. Each 8×8
+// tile is two parallel 8-byte tables in VRAM:
+//   - PATTERN table: 8 bytes, 1 bit per pixel (bit 7 = leftmost). 1 = foreground.
+//   - COLOR table:   8 bytes, one per row; high nibble = foreground color index
+//                    (0-15), low nibble = background color index. So each ROW of
+//                    a tile can use a different fg/bg pair (the classic MSX
+//                    "2 colors per 8-pixel line" constraint).
+// The 16 colors are the fixed TMS9918 palette (see vdp.js TMS9918_PALETTE).
+//
+// This codec targets screen 2. MSX2 bitmap modes (screen 4+, 4bpp) are a
+// different, larger format; this module covers the common homebrew case and
+// `encodeMsxScreen2Tile` is explicit about the per-row 2-color limit.
+
+/**
+ * Encode one 8×8 tile to MSX screen-2 pattern + color bytes. Each row may use at
+ * most 2 distinct colors (a foreground and a background); if a row has more, the
+ * two most-common are kept and the rest snap to the nearer of those two by index.
+ * @param {Uint8Array|number[]} indices 64 palette indices (0-15), row-major
+ * @returns {{ pattern: Uint8Array, color: Uint8Array }} 8 bytes each
+ */
+export function encodeMsxScreen2Tile(indices) {
+  const pattern = new Uint8Array(8);
+  const color = new Uint8Array(8);
+  for (let row = 0; row < 8; row++) {
+    // Pick the row's two colors: most-frequent = background, next = foreground.
+    const counts = new Map();
+    for (let x = 0; x < 8; x++) {
+      const v = indices[row * 8 + x] & 0x0f;
+      counts.set(v, (counts.get(v) || 0) + 1);
+    }
+    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]).map((e) => e[0]);
+    const bg = sorted[0] ?? 0;
+    const fg = sorted.find((c) => c !== bg) ?? bg;
+    let bits = 0;
+    for (let x = 0; x < 8; x++) {
+      const v = indices[row * 8 + x] & 0x0f;
+      // Foreground bit set when the pixel is closer to fg than bg.
+      const isFg = v === fg || (v !== bg && Math.abs(v - fg) < Math.abs(v - bg));
+      if (isFg) bits |= 1 << (7 - x); // MSB-first
+    }
+    pattern[row] = bits;
+    color[row] = ((fg & 0x0f) << 4) | (bg & 0x0f);
+  }
+  return { pattern, color };
+}
+
+/**
+ * Decode an MSX screen-2 tile (8 pattern + 8 color bytes) back to 64 indices.
+ * @param {Uint8Array} pattern 8 bytes
+ * @param {Uint8Array} color 8 bytes
+ * @returns {Uint8Array} 64 palette indices (0-15)
+ */
+export function decodeMsxScreen2Tile(pattern, color) {
+  const out = new Uint8Array(64);
+  for (let row = 0; row < 8; row++) {
+    const bits = pattern[row];
+    const fg = (color[row] >> 4) & 0x0f;
+    const bg = color[row] & 0x0f;
+    for (let x = 0; x < 8; x++) {
+      out[row * 8 + x] = (bits >> (7 - x)) & 1 ? fg : bg;
+    }
+  }
+  return out;
+}
+
+/**
+ * Encode a full image to MSX screen-2 pattern + color streams. Image dims must
+ * be multiples of 8. Returns the two tables (pattern then color) so the caller
+ * can DMA each to its VRAM base.
+ * @param {Uint8Array} indexed width*height palette indices (0-15)
+ * @param {number} width
+ * @param {number} height
+ * @returns {{ pattern: Uint8Array, color: Uint8Array }}
+ */
+export function encodeMsxScreen2Tiles(indexed, width, height) {
+  const cols = width >> 3;
+  const rows = height >> 3;
+  const n = cols * rows;
+  const pattern = new Uint8Array(n * 8);
+  const color = new Uint8Array(n * 8);
+  const tile = new Uint8Array(64);
+  let o = 0;
+  for (let ty = 0; ty < rows; ty++) {
+    for (let tx = 0; tx < cols; tx++) {
+      for (let y = 0; y < 8; y++) {
+        for (let x = 0; x < 8; x++) {
+          tile[y * 8 + x] = indexed[(ty * 8 + y) * width + (tx * 8 + x)];
+        }
+      }
+      const enc = encodeMsxScreen2Tile(tile);
+      pattern.set(enc.pattern, o * 8);
+      color.set(enc.color, o * 8);
+      o++;
+    }
+  }
+  return { pattern, color };
+}