romdevtools 0.13.0

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

@@ -0,0 +1,123 @@
+// PC Engine image-to-tilemap converter (HuC6270 BG, 4bpp).
+//
+// The PCE background is a tilemap ("BAT" = Background Attribute Table) of 16-bit
+// entries in VRAM, each: bits 0-10 = tile index, bits 12-15 = sub-palette (0-15).
+// Tiles are 8×8, 4bpp, in the "planar-pairs" layout (see pce/tiles.js — identical
+// to SNES: 16 B plane 0+1, then 16 B plane 2+3). This converter:
+//   1. quantizes the image to ≤16 colors (one BG sub-palette),
+//   2. cuts 8×8 tiles, dedups them (h/v-flip NOT supported by the PCE BAT, so
+//      dedup is exact-match only),
+//   3. emits the tile bytes + the BAT + a suggested 16-color VCE palette.
+//
+// Image dimensions must be multiples of 8. The default virtual screen is 32×28
+// cells (256×224) but any multiple-of-8 image works; the caller DMAs the BAT to
+// VRAM and sets the VDC MWR for the matching virtual-screen size.
+
+import { PNG } from "pngjs";
+import { encodePceTile } from "./tiles.js";
+
+/** Pack 8-bit RGB → a 9-bit VCE GRB word (0bGGG_RRR_BBB), 3 bits per channel. */
+function rgbToVce(r, g, b) {
+  const r3 = (r * 7 / 255) | 0;
+  const g3 = (g * 7 / 255) | 0;
+  const b3 = (b * 7 / 255) | 0;
+  return (g3 << 6) | (r3 << 3) | b3;
+}
+
+/**
+ * @param {{ pngBytes: Uint8Array|Buffer, baseTile?: number, subPalette?: number }} args
+ * @returns {{ tiles: Uint8Array, nametable: Uint8Array, attr: Uint8Array,
+ *   palette: Uint8Array, uniqueTiles: number, tilesAcross: number, tilesDown: number }}
+ */
+export function pceImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  const { width: W, height: H } = png;
+  if (W % 8 || H % 8) {
+    throw new Error(`PCE image must be a multiple of 8 in both dimensions, got ${W}×${H}.`);
+  }
+  const baseTile = args.baseTile ?? 0;
+  const subPalette = (args.subPalette ?? 0) & 0x0f;
+
+  // 1) Quantize to ≤16 colors (color 0 = backdrop/transparent).
+  const colorIndex = new Map();
+  const pxIdx = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const c = rgbToVce(png.data[k], png.data[k + 1], png.data[k + 2]);
+    let idx = colorIndex.get(c);
+    if (idx === undefined) {
+      idx = colorIndex.size;
+      if (idx >= 16) {
+        throw new Error("PCE BG tiles take ≤16 colors per sub-palette; image quantizes to more. Reduce to 16 colors first (e.g. `magick … -colors 16 -dither FloydSteinberg`).");
+      }
+      colorIndex.set(c, idx);
+    }
+    pxIdx[i] = idx;
+  }
+
+  // 2) Build the VCE palette (16 × u16, little-endian).
+  const palette = new Uint8Array(16 * 2);
+  for (const [grb, idx] of colorIndex) {
+    palette[idx * 2] = grb & 0xff;
+    palette[idx * 2 + 1] = (grb >> 8) & 0x01;
+  }
+
+  // 3) Cut + dedup tiles (exact match; the BAT has no flip bits).
+  const tilesAcross = W >> 3;
+  const tilesDown = H >> 3;
+  const tileMap = new Map();        // tile-hash → index
+  const tileBytes = [];
+  const nametable = new Uint8Array(tilesAcross * tilesDown * 2);
+  const cell = new Uint8Array(64);
+
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      for (let y = 0; y < 8; y++) for (let x = 0; x < 8; x++) {
+        cell[y * 8 + x] = pxIdx[(ty * 8 + y) * W + (tx * 8 + x)];
+      }
+      const enc = encodePceTile(cell);
+      const hash = Array.from(enc).join(",");
+      let idx = tileMap.get(hash);
+      if (idx === undefined) {
+        idx = tileMap.size;
+        tileMap.set(hash, idx);
+        tileBytes.push(enc);
+      }
+      const tileIndex = (baseTile + idx) & 0x07ff;
+      const batEntry = tileIndex | (subPalette << 12);
+      const off = (ty * tilesAcross + tx) * 2;
+      nametable[off] = batEntry & 0xff;
+      nametable[off + 1] = (batEntry >> 8) & 0xff;
+    }
+  }
+
+  const tiles = new Uint8Array(tileBytes.length * 32);
+  tileBytes.forEach((t, i) => tiles.set(t, i * 32));
+
+  return {
+    tiles,
+    nametable,                 // the BAT (16-bit entries, LE)
+    attr: new Uint8Array(0),   // PCE attributes are packed into the BAT entry
+    palette,
+    uniqueTiles: tileBytes.length,
+    tilesAcross,
+    tilesDown,
+  };
+}
+
+/** Render a 16-color VCE palette as a small PNG swatch (for the tool preview). */
+export function pcePalettePng(palette) {
+  const cols = 16, sw = 12;
+  const png = new PNG({ width: cols * sw, height: sw });
+  for (let i = 0; i < 16; i++) {
+    const v = (palette[i * 2] | (palette[i * 2 + 1] << 8)) & 0x1ff;
+    const r = Math.round(((v >> 3) & 7) * 255 / 7);
+    const g = Math.round(((v >> 6) & 7) * 255 / 7);
+    const b = Math.round((v & 7) * 255 / 7);
+    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/pce/lib/c/hello_pce.c

@@ -0,0 +1,37 @@
+/*
+ * hello_pce.c — PC Engine / TurboGrafx-16 starter (cc65, C89).
+ *
+ * Boots to a guaranteed-VISIBLE screen using cc65's conio (text) library, which
+ * initializes the HuC6270 VDC + HuC6260 VCE for you and uploads a font to VRAM.
+ * Build with: build({output:'rom'})({ platform: "pce" })  (language defaults to C).
+ *
+ * FOOTGUN — the empty-BSS crt0 trap (cc65 pce/crt0.s line 84):
+ *   The PCE crt0 clears .bss with `tii __BSS_RUN__, __BSS_RUN__+1, __BSS_SIZE__-1`.
+ *   When your program has NO global/static variables, __BSS_SIZE__ is 0 and the
+ *   `- 1` underflows → ld65 throws a "Range error in module pce/crt0.s" and the
+ *   ROM boots to a BLACK screen (VDC never initializes). ALWAYS keep at least one
+ *   global/static variable so .bss is non-empty. The `_keep_bss` byte below does
+ *   exactly that — don't delete it until you have real globals.
+ */
+#include <conio.h>
+#include <pce.h>
+
+/* Keeps .bss non-empty so the crt0 BSS-clear doesn't underflow (see header).
+ * Sized > 1 byte: a 1-byte .bss uploads only a partial conio font on some
+ * builds; >= 2 bytes is reliably full. Replace with your real game state. */
+static unsigned char _keep_bss[4];
+
+void main(void) {
+    _keep_bss[0] = 0;
+
+    clrscr();                       /* clear the text plane, enable display */
+    gotoxy(8, 12);
+    cputs("HELLO PC ENGINE");
+    gotoxy(8, 14);
+    cputs("ROMDEV TIER-1");
+
+    /* conio left the VDC enabled; just idle so the screen stays up. */
+    for (;;) {
+        waitvsync();
+    }
+}

package/src/platforms/pce/lib/c/pce_hw.h

@@ -0,0 +1,130 @@
+/*
+ * pce_hw.h — PC Engine / TurboGrafx-16 hardware helper library (cc65, C89).
+ *
+ * Raw register addresses + prototypes for the HuC6270 VDC (video), HuC6260 VCE
+ * (color), and HuC6280 PSG (sound). There is NO sprite/tile library on the PCE
+ * with cc65 — you talk to the chips directly. These helpers wrap the most common
+ * register dances so you don't have to remember the index/lo/hi protocol.
+ *
+ * USAGE: pair this header with pce_video.c, pce_input.c, pce_sound.c. Build all
+ * four .c files together (the .h goes in `includes:` / `headers:`, the .c files
+ * in `sources:`). cc65 is C89 — declare locals at the top of a block.
+ *
+ * EMPTY-BSS TRAP: cc65's pce/crt0.s clears .bss with a block copy sized
+ * __BSS_SIZE__-1. With NO globals/statics that underflows → "Range error in
+ * pce/crt0.s" + a black screen. Keep at least one (>=2 byte) global. Including
+ * pce_video.c already provides `_pce_keep[4]` for you, so you're covered.
+ *
+ * The pce.inc names from cc65 are ASM-ONLY. In C you write raw addresses, which
+ * is what every macro below expands to.
+ */
+#ifndef PCE_HW_H
+#define PCE_HW_H
+
+/* cc65 fixed-width-ish types */
+typedef unsigned char  u8;
+typedef unsigned short u16;
+
+/* ---- HuC6270 VDC (Video Display Controller) ------------------------------ */
+/* Write the register index to VDC_CTRL, then the 16-bit value to DATA_LO/HI. */
+#define VDC_CTRL      (*(volatile unsigned char *)0x0200) /* select register index   */
+#define VDC_DATA_LO   (*(volatile unsigned char *)0x0202) /* low byte of reg value   */
+#define VDC_DATA_HI   (*(volatile unsigned char *)0x0203) /* high byte of reg value  */
+#define VDC_STATUS    (*(volatile unsigned char *)0x0200) /* read: VDC status flags  */
+
+/* VDC register indices */
+#define VDC_MAWR   0  /* VRAM write address (auto-increments)        */
+#define VDC_MARR   1  /* VRAM read  address (auto-increments)        */
+#define VDC_VWR    2  /* VRAM write data port (stream words here)    */
+#define VDC_VRR    2  /* VRAM read  data port                        */
+#define VDC_CR     5  /* control: bit7 BG enable, bit6 SPR enable    */
+#define VDC_RCR    6  /* raster compare                              */
+#define VDC_BXR    7  /* background X scroll                         */
+#define VDC_BYR    8  /* background Y scroll                         */
+#define VDC_MWR    9  /* memory-access width / virtual screen size   */
+#define VDC_HSR   10  /* horizontal sync                             */
+#define VDC_HDR   11  /* horizontal display                          */
+#define VDC_VPR   12  /* vertical sync                               */
+#define VDC_VDW   13  /* vertical display width                      */
+#define VDC_VCR   14  /* vertical display end                        */
+#define VDC_DCR   15  /* DMA control                                 */
+#define VDC_SOUR  16  /* DMA source                                  */
+#define VDC_DESR  17  /* DMA destination                             */
+#define VDC_LENR  18  /* DMA length                                  */
+#define VDC_SATB  19  /* SATB DMA source (sprite table -> internal)  */
+
+/* VDC R5 (CR) bits */
+#define VDC_CR_BG_ON      0x80
+#define VDC_CR_SPR_ON     0x40
+#define VDC_CR_VBLANK_IRQ 0x08  /* raise the VBlank IRQ (needed for waitvsync) */
+
+/* ---- HuC6260 VCE (Video Color Encoder) ----------------------------------- */
+/* 512 color entries (256 BG sub-palettes + 256 SPR), each a 9-bit GRB value. */
+#define VCE_CTRL      (*(volatile unsigned char *)0x0400)
+#define VCE_ADDR_LO   (*(volatile unsigned char *)0x0402) /* color index low  */
+#define VCE_ADDR_HI   (*(volatile unsigned char *)0x0403) /* color index high */
+#define VCE_DATA_LO   (*(volatile unsigned char *)0x0404) /* GRB low byte     */
+#define VCE_DATA_HI   (*(volatile unsigned char *)0x0405) /* GRB high byte    */
+
+/* Build a 9-bit GRB color: each of g/r/b is 0..7. Layout %gggrrrbbb. */
+#define PCE_RGB(r, g, b)  ((u16)((((g) & 7) << 6) | (((r) & 7) << 3) | ((b) & 7)))
+
+/* ---- HuC6280 PSG (Programmable Sound Generator) -------------------------- */
+/* 6 wavetable channels. Select a channel, then write its registers. */
+#define PSG_CHAN_SELECT (*(volatile unsigned char *)0x0800) /* 0..5 channel   */
+#define PSG_GLOBAL_PAN  (*(volatile unsigned char *)0x0801) /* main L/R volume*/
+#define PSG_FREQ_LO     (*(volatile unsigned char *)0x0802) /* 12-bit freq low */
+#define PSG_FREQ_HI     (*(volatile unsigned char *)0x0803) /* freq high nibble*/
+#define PSG_CHAN_CTRL   (*(volatile unsigned char *)0x0804) /* 0x80|vol = on   */
+#define PSG_CHAN_PAN    (*(volatile unsigned char *)0x0805) /* per-channel L/R */
+#define PSG_CHAN_DATA   (*(volatile unsigned char *)0x0806) /* 32-byte waveform*/
+#define PSG_NOISE       (*(volatile unsigned char *)0x0807) /* ch4/5 noise     */
+#define PSG_LFO_FREQ    (*(volatile unsigned char *)0x0808)
+#define PSG_LFO_CTRL    (*(volatile unsigned char *)0x0809)
+
+/* PSG_CHAN_CTRL bits */
+#define PSG_CTRL_ON       0x80  /* channel enable                  */
+#define PSG_CTRL_DDA      0x40  /* direct D/A mode (else wavetable) */
+#define PSG_CTRL_VOL_MASK 0x1F  /* 5-bit channel volume            */
+
+/* ---- video helpers (pce_video.c) ----------------------------------------- */
+/* The empty-BSS guard array, defined in pce_video.c. Touch _pce_keep[0]=0 at
+ * the top of main() if you have no other globals (see the trap note above). */
+extern unsigned char _pce_keep[4];
+
+void vdc_set_reg(u8 reg, u16 val);              /* select reg, write 16-bit value */
+void vram_set_write_addr(u16 addr);             /* point MAWR + arm VWR streaming */
+void vram_write(u16 addr, const u16 *data, u16 n); /* upload n words to VRAM[addr] */
+void vce_set_color(u16 idx, u16 grb);           /* set VCE palette entry (0..511) */
+void bg_enable(void);     /* VDC R5: background on + VBlank IRQ (so waitvsync works) */
+void spr_enable(void);    /* VDC R5: sprites on    + VBlank IRQ                      */
+void disp_enable(void);   /* VDC R5: BG + SPR + VBlank IRQ on at once                */
+void vblank_irq_enable(void); /* just the VBlank IRQ bit (waitvsync needs it)        */
+void load_tiles(u16 vram, const u16 *src, u16 n);  /* alias of vram_write (tiles) */
+void set_sprite(u8 slot, u16 x, u16 y, u16 pattern, u8 palette); /* fill shadow SATB */
+void satb_dma(void);                            /* DMA shadow SATB -> VDC (R19)    */
+
+/* The shadow SATB lives in VRAM at this word address; satb_dma() points the VDC
+ * SATB-DMA source (R19) here. Pattern base for tiles is your choice; sprites
+ * default to using the same VRAM you load_tiles() into. */
+#define PCE_SATB_VRAM   0x7F00  /* 64 sprites * 4 words = 0x100 words, fits < 0x8000 */
+
+/* ---- input helpers (pce_input.c) ----------------------------------------- */
+void pce_joy_init(void);   /* install the cc65 standard PCE joystick driver */
+u8   pce_joy_read(void);   /* read pad 1 -> clean bitmask (PCE_JOY_* below)  */
+
+/* Clean, stable joystick bitmask returned by pce_joy_read(). */
+#define PCE_JOY_UP      0x01
+#define PCE_JOY_DOWN    0x02
+#define PCE_JOY_LEFT    0x04
+#define PCE_JOY_RIGHT   0x08
+#define PCE_JOY_I       0x10  /* button I  (east / 'a')   */
+#define PCE_JOY_II      0x20  /* button II (west / 'b')   */
+#define PCE_JOY_SELECT  0x40
+#define PCE_JOY_RUN     0x80  /* Run = start              */
+
+/* ---- sound helpers (pce_sound.c) ----------------------------------------- */
+void psg_tone(u8 chan, u16 freq, u8 vol); /* play a wavetable tone (vol 0..31) */
+void psg_off(u8 chan);                    /* silence + disable a channel        */
+
+#endif /* PCE_HW_H */

package/src/platforms/pce/lib/c/pce_input.c

@@ -0,0 +1,36 @@
+/*
+ * pce_input.c — PC Engine pad input via cc65's joystick driver (C89).
+ *
+ * The PCE pad has a 2-button layout: I (east/'a'), II (west/'b'), Select, Run
+ * (start), plus the d-pad. cc65 ships a standard PCE joystick driver linked in
+ * as joy_static_stddrv; pce_joy_init() installs it and pce_joy_read() returns a
+ * CLEAN, stable bitmask (PCE_JOY_* in pce_hw.h) so your game logic doesn't have
+ * to know cc65's odd raw mask layout (LEFT=0x80, DOWN=0x40, ...).
+ */
+#include <joystick.h>
+#include "pce_hw.h"
+
+/* cc65's prebuilt standard PCE joystick driver (pce-stdjoy). */
+extern const void joy_static_stddrv[];
+
+/* Install the driver. Safe to call once at startup. */
+void pce_joy_init(void) {
+    joy_install(joy_static_stddrv);
+}
+
+/* Read pad 1 and translate cc65's raw masks into our clean PCE_JOY_* bitmask.
+ * cc65 PCE raw masks (from pce.h): UP=0x10 DOWN=0x40 LEFT=0x80 RIGHT=0x20,
+ * BTN_1(I)=0x01 BTN_2(II)=0x02 SELECT=0x04 RUN=0x08. */
+u8 pce_joy_read(void) {
+    u8 raw = joy_read(JOY_1);
+    u8 out = 0;
+    if (JOY_UP(raw))     out |= PCE_JOY_UP;
+    if (JOY_DOWN(raw))   out |= PCE_JOY_DOWN;
+    if (JOY_LEFT(raw))   out |= PCE_JOY_LEFT;
+    if (JOY_RIGHT(raw))  out |= PCE_JOY_RIGHT;
+    if (JOY_BTN_1(raw))  out |= PCE_JOY_I;
+    if (JOY_BTN_2(raw))  out |= PCE_JOY_II;
+    if (JOY_BTN_3(raw))  out |= PCE_JOY_SELECT;
+    if (JOY_BTN_4(raw))  out |= PCE_JOY_RUN;
+    return out;
+}

package/src/platforms/pce/lib/c/pce_sound.c

@@ -0,0 +1,53 @@
+/*
+ * pce_sound.c — HuC6280 PSG helpers (C89).
+ *
+ * The PCE PSG has 6 wavetable channels at $0800-$0809. To make a tone you:
+ *   1. select the channel  (PSG_CHAN_SELECT = chan)
+ *   2. set its 12-bit frequency  (PSG_FREQ_LO / PSG_FREQ_HI)
+ *   3. write a 32-byte waveform into the channel's wave RAM (PSG_CHAN_DATA)
+ *   4. enable the channel with a 5-bit volume  (PSG_CHAN_CTRL = 0x80 | vol)
+ *
+ * psg_tone() does all of that with a built-in triangle wave so a single call
+ * makes audible sound. Higher PCE frequency register value = LOWER pitch (it's
+ * a divider): pitch ~= 3.58MHz / (32 * freq).
+ */
+#include "pce_hw.h"
+
+/* A simple 32-sample triangle wave (0..31), loaded once per channel so the
+ * wavetable isn't empty (an all-zero wave is silent even with volume up). */
+static const u8 _pce_tri[32] = {
+     0,  2,  4,  6,  8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30,
+    31, 29, 27, 25, 23, 21, 19, 17, 15, 13, 11,  9,  7,  5,  3,  1
+};
+
+/* Play a wavetable tone on `chan` (0..5) at 12-bit `freq` (divider; lower =
+ * higher pitch), `vol` 0..31. Resets the wave write pointer before loading. */
+void psg_tone(u8 chan, u16 freq, u8 vol) {
+    u8 i;
+    if (chan > 5) return;
+
+    PSG_CHAN_SELECT = chan;                 /* select this channel's registers */
+    PSG_GLOBAL_PAN  = 0xFF;                 /* main amplitude: full L+R        */
+
+    /* Frequency: 12 bits across LO (8) + HI (low 4 bits). */
+    PSG_FREQ_LO = (u8)(freq & 0xFF);
+    PSG_FREQ_HI = (u8)((freq >> 8) & 0x0F);
+
+    /* Arm wavetable write: control bit7=0, bit6=0 selects waveform-write mode,
+     * which also resets the wave index to 0. Then stream 32 samples. */
+    PSG_CHAN_CTRL = 0x00;
+    for (i = 0; i < 32; ++i) {
+        PSG_CHAN_DATA = _pce_tri[i];
+    }
+
+    PSG_CHAN_PAN  = 0xFF;                    /* per-channel full L+R            */
+    /* Enable: bit7 on, bit6=0 (wavetable, not DDA), low 5 bits = volume. */
+    PSG_CHAN_CTRL = (u8)(PSG_CTRL_ON | (vol & PSG_CTRL_VOL_MASK));
+}
+
+/* Silence and disable a channel. */
+void psg_off(u8 chan) {
+    if (chan > 5) return;
+    PSG_CHAN_SELECT = chan;
+    PSG_CHAN_CTRL   = 0x00;   /* bit7 clear = channel off, volume 0 */
+}

package/src/platforms/pce/lib/c/pce_video.c

@@ -0,0 +1,113 @@
+/*
+ * pce_video.c — HuC6270 VDC + HuC6260 VCE helpers (cc65, C89).
+ *
+ * Talks to the two PCE video chips by hand: VRAM uploads, the VCE 9-bit-GRB
+ * color table, the master display-enable bits, and a 64-entry shadow SATB you
+ * build in RAM and DMA into the VDC. See pce_hw.h for the register map and the
+ * empty-BSS trap note.
+ */
+#include "pce_hw.h"
+
+/* Empty-BSS guard: keeps .bss non-empty so cc65's crt0 block-clear doesn't
+ * underflow (see pce_hw.h). The shadow SATB below also lives in .bss, but we
+ * keep this so the guard survives even if someone trims the SATB. */
+unsigned char _pce_keep[4];
+
+/* Shadow SATB: 64 sprites * 4 words. We build sprite state here in work RAM,
+ * then satb_dma() copies it to VRAM and tells the VDC to load it. */
+static u16 _pce_satb[64 * 4];
+
+/* Select a VDC register index and write its 16-bit value (lo then hi). */
+void vdc_set_reg(u8 reg, u16 val) {
+    VDC_CTRL = reg;
+    VDC_DATA_LO = (u8)(val & 0xFF);
+    VDC_DATA_HI = (u8)(val >> 8);
+}
+
+/* Point the VDC VRAM write pointer (MAWR) at `addr` and select VWR so that
+ * subsequent writes to VDC_DATA_LO/HI stream words into VRAM (auto-increment). */
+void vram_set_write_addr(u16 addr) {
+    vdc_set_reg(VDC_MAWR, addr);
+    VDC_CTRL = VDC_VWR;   /* arm the data port for streaming */
+}
+
+/* Upload n 16-bit words to VRAM starting at word address `addr`. */
+void vram_write(u16 addr, const u16 *data, u16 n) {
+    u16 i;
+    vram_set_write_addr(addr);
+    for (i = 0; i < n; ++i) {
+        VDC_DATA_LO = (u8)(data[i] & 0xFF);
+        VDC_DATA_HI = (u8)(data[i] >> 8);
+    }
+}
+
+/* Tile data is just VRAM words; this alias documents intent at call sites. */
+void load_tiles(u16 vram, const u16 *src, u16 n) {
+    vram_write(vram, src, n);
+}
+
+/* Set VCE palette entry `idx` (0..511) to a 9-bit GRB value. The color index
+ * is 9 bits: low 8 in VCE_ADDR_LO, bit 8 (BG vs SPR half) in VCE_ADDR_HI bit0. */
+void vce_set_color(u16 idx, u16 grb) {
+    VCE_ADDR_LO = (u8)(idx & 0xFF);
+    VCE_ADDR_HI = (u8)((idx >> 8) & 0x01);
+    VCE_DATA_LO = (u8)(grb & 0xFF);
+    VCE_DATA_HI = (u8)((grb >> 8) & 0x01);
+}
+
+/* Read-modify-write VDC R5 (CR) is awkward (it's write-only on real HW), so we
+ * track the enable bits in a static shadow and rewrite the whole register.
+ *
+ * NOTE: every enable also sets the VBlank-IRQ bit. cc65's waitvsync() blocks
+ * until the VBlank IRQ ticks a counter — without this bit, waitvsync() spins
+ * FOREVER and your game loop never runs (the screen stays on the last frame).
+ * If you only need a static screen and never call waitvsync(), the IRQ bit is
+ * harmless; cc65's crt0 already installs the VBlank ISR. */
+static u8 _pce_cr = 0;
+
+void vblank_irq_enable(void) {
+    _pce_cr |= VDC_CR_VBLANK_IRQ;
+    vdc_set_reg(VDC_CR, _pce_cr);
+}
+
+void bg_enable(void) {
+    _pce_cr |= (VDC_CR_BG_ON | VDC_CR_VBLANK_IRQ);
+    vdc_set_reg(VDC_CR, _pce_cr);
+}
+
+void spr_enable(void) {
+    _pce_cr |= (VDC_CR_SPR_ON | VDC_CR_VBLANK_IRQ);
+    vdc_set_reg(VDC_CR, _pce_cr);
+}
+
+void disp_enable(void) {
+    _pce_cr |= (VDC_CR_BG_ON | VDC_CR_SPR_ON | VDC_CR_VBLANK_IRQ);
+    vdc_set_reg(VDC_CR, _pce_cr);
+}
+
+/* Fill one shadow-SATB slot. Hardware quirks handled for you:
+ *   - Y is stored +64, X is stored +32 (VDC's coordinate bias).
+ *   - pattern is the 16x16 cell index; the VDC wants (cell << 1) in bits 1..10.
+ *   - attr low nibble selects the sprite sub-palette (0..15).
+ *   - the SPBG priority bit (0x80) is set so the sprite draws IN FRONT of the
+ *     background. Without it, an opaque BG tile (any non-zero color) hides the
+ *     sprite — the classic "my sprite vanished over a full tilemap" bug. Slot 0
+ *     of the BG sub-palette is transparent, so the sprite still shows over the
+ *     backdrop either way; the bit only matters over solid tiles.
+ * Call satb_dma() after building all slots to push them to the VDC. */
+void set_sprite(u8 slot, u16 x, u16 y, u16 pattern, u8 palette) {
+    u16 *e;
+    if (slot >= 64) return;
+    e = &_pce_satb[slot * 4];
+    e[0] = (u16)(y + 64);                          /* word0: Y (biased)        */
+    e[1] = (u16)(x + 32);                          /* word1: X (biased)        */
+    e[2] = (u16)((pattern & 0x3FF) << 1);          /* word2: pattern (cell<<1) */
+    e[3] = (u16)(0x0080 | (palette & 0x0F));       /* word3: SPBG-front + pal  */
+}
+
+/* Copy the shadow SATB into VRAM at PCE_SATB_VRAM, then tell the VDC to DMA it
+ * into its internal sprite table (R19 = SATB source). */
+void satb_dma(void) {
+    vram_write(PCE_SATB_VRAM, _pce_satb, 64 * 4);
+    vdc_set_reg(VDC_SATB, PCE_SATB_VRAM);
+}

package/src/platforms/pce/tiles.js

@@ -0,0 +1,92 @@
+// PC Engine HuC6270 tile (background + sprite) codec.
+//
+// A PCE 8×8 background tile is 16 VRAM words (32 bytes), 4 bitplanes packed as
+// two word-pairs per row (geargrafx huc6270.cpp:721-733 is canonical):
+//   word at (tile<<4)+row     : low byte = plane 0, high byte = plane 1
+//   word at (tile<<4)+row + 8  : low byte = plane 2, high byte = plane 3
+// Pixel = plane0 | plane1<<1 | plane2<<2 | plane3<<3, MSB-first (leftmost pixel
+// is bit 7). So a tile in raw bytes (little-endian words) is:
+//   [p0_row0, p1_row0, p0_row1, p1_row1, ... p0_row7, p1_row7,   (16 bytes)
+//    p2_row0, p3_row0, p2_row1, p3_row1, ... p2_row7, p3_row7]   (16 bytes)
+//
+// Sprites use the same 4-plane scheme but a 16×16 cell (64 words); the 8×8
+// encoder below is the building block (an agent tiles 16×16 sprites as 4 cells).
+
+/**
+ * Encode an 8×8 indexed tile (64 entries, 0-15) into the 32-byte PCE format.
+ * @param {Uint8Array|number[]} indices length 64, row-major, values 0-15
+ * @returns {Uint8Array} 32 bytes
+ */
+export function encodePceTile(indices) {
+  const out = new Uint8Array(32);
+  for (let row = 0; row < 8; row++) {
+    let p0 = 0, p1 = 0, p2 = 0, p3 = 0;
+    for (let x = 0; x < 8; x++) {
+      const v = indices[row * 8 + x] & 0x0f;
+      const bit = 7 - x; // MSB-first
+      if (v & 0x01) p0 |= 1 << bit;
+      if (v & 0x02) p1 |= 1 << bit;
+      if (v & 0x04) p2 |= 1 << bit;
+      if (v & 0x08) p3 |= 1 << bit;
+    }
+    // word (p0,p1) at byte row*2; word (p2,p3) at byte 16 + row*2 (little-endian).
+    out[row * 2] = p0;
+    out[row * 2 + 1] = p1;
+    out[16 + row * 2] = p2;
+    out[16 + row * 2 + 1] = p3;
+  }
+  return out;
+}
+
+/**
+ * Decode a 32-byte PCE tile back to 64 palette indices (0-15), row-major.
+ * @param {Uint8Array} bytes 32 bytes
+ * @param {number} [offset]
+ * @returns {Uint8Array} length 64
+ */
+export function decodePceTile(bytes, offset = 0) {
+  const out = new Uint8Array(64);
+  for (let row = 0; row < 8; row++) {
+    const p0 = bytes[offset + row * 2];
+    const p1 = bytes[offset + row * 2 + 1];
+    const p2 = bytes[offset + 16 + row * 2];
+    const p3 = bytes[offset + 16 + row * 2 + 1];
+    for (let x = 0; x < 8; x++) {
+      const bit = 7 - x;
+      out[row * 8 + x] =
+        ((p0 >> bit) & 1) |
+        (((p1 >> bit) & 1) << 1) |
+        (((p2 >> bit) & 1) << 2) |
+        (((p3 >> bit) & 1) << 3);
+    }
+  }
+  return out;
+}
+
+/**
+ * Encode a full image's worth of 8×8 tiles. The image must be a multiple of 8
+ * in both dimensions; tiles are emitted left-to-right, top-to-bottom.
+ * @param {Uint8Array} indexed width*height palette indices (0-15)
+ * @param {number} width
+ * @param {number} height
+ * @returns {Uint8Array} (width/8)*(height/8)*32 bytes
+ */
+export function encodePceTiles(indexed, width, height) {
+  const cols = width >> 3;
+  const rows = height >> 3;
+  const out = new Uint8Array(cols * rows * 32);
+  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)];
+        }
+      }
+      out.set(encodePceTile(tile), o);
+      o += 32;
+    }
+  }
+  return out;
+}

package/src/platforms/pce/vce.js

@@ -0,0 +1,59 @@
+// PC Engine HuC6260 VCE (Video Color Encoder) decoders.
+//
+// The VCE holds a 512-entry color table (romdev region `pce_vce_palette`,
+// u16 little-endian): indices 0-255 are the 16 background sub-palettes
+// (16 colors each), 256-511 are the 16 sprite sub-palettes. Each entry is a
+// 9-bit GRB value `0bGGG_RRR_BBB` (geargrafx huc6260.cpp:74-76 is canonical):
+//   green = (v >> 6) & 7,  red = (v >> 3) & 7,  blue = v & 7   — each ×255/7.
+// Color 0 of each 16-entry sub-palette is the transparent/backdrop slot.
+
+/** Scale a 3-bit (0-7) channel to 8-bit (0-255). */
+function expand3(c) {
+  return Math.round((c & 0x07) * 255 / 7);
+}
+
+/**
+ * Decode one 9-bit VCE color word to {r,g,b,hex}.
+ * @param {number} v u16 color-table entry (only low 9 bits used)
+ */
+export function decodeVceColor(v) {
+  const g3 = (v >> 6) & 0x07;
+  const r3 = (v >> 3) & 0x07;
+  const b3 = v & 0x07;
+  const r = expand3(r3);
+  const g = expand3(g3);
+  const b = expand3(b3);
+  const hex =
+    "#" +
+    r.toString(16).padStart(2, "0") +
+    g.toString(16).padStart(2, "0") +
+    b.toString(16).padStart(2, "0");
+  return { r, g, b, hex, r3, g3, b3 };
+}
+
+/**
+ * Decode the VCE color table from raw `pce_vce_palette` bytes.
+ * @param {Uint8Array} bytes 1024 bytes = 512 u16 entries (LE)
+ * @param {"all"|"bg"|"sprite"} [which]
+ * @returns {{ entries: Array<{index:number, set:"bg"|"sprite", subPalette:number, slot:number, r:number, g:number, b:number, hex:string}> }}
+ */
+export function decodeVcePalette(bytes, which = "all") {
+  const u16 = (i) => bytes[i * 2] | (bytes[i * 2 + 1] << 8);
+  const entries = [];
+  const start = which === "sprite" ? 256 : 0;
+  const end = which === "bg" ? 256 : 512;
+  for (let i = start; i < end; i++) {
+    const v = u16(i) & 0x1ff;
+    const set = i < 256 ? "bg" : "sprite";
+    const local = i & 0xff;
+    const c = decodeVceColor(v);
+    entries.push({
+      index: i,
+      set,
+      subPalette: local >> 4,
+      slot: local & 0x0f,
+      ...c,
+    });
+  }
+  return { entries };
+}