romdev-mcp 0.1.1

package/src/platforms/common/metasprite-adapters.js

@@ -0,0 +1,279 @@
+// Per-platform meta-sprite adapters. Each builds the uniform adapter the
+// generic core (metasprite-core.js) consumes, from a live host (capture) or
+// from saved bytes (re-render). See metasprite-core.js header for the shape.
+//
+// The two platform-specific axes that matter:
+//   - tile bit-depth + byte layout (for encode/decode of tiles.bin)
+//   - multi-cell tile order: Genesis is COLUMN-MAJOR (tile++ goes down a
+//     column); SNES large OBJ + NES 8x16 + SMS-stacked are their own orders;
+//     everything else is single-cell (8x8) so order is trivial.
+
+// ---------- cell-order helpers ----------
+// columnMajor: cell (col,row) → tile offset = col*hTiles + row  (Genesis)
+function colMajorOrder(w, h) { const o = []; for (let c = 0; c < w; c++) for (let r = 0; r < h; r++) o.push(c * h + r); return o; }
+function colMajorPos(w, h) { const p = []; for (let c = 0; c < w; c++) for (let r = 0; r < h; r++) p.push({ col: c, row: r }); return p; }
+// rowMajor: tile offset = row*wTiles + col
+function rowMajorOrder(w, h) { const o = []; for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) o.push(r * w + c); return o; }
+function rowMajorPos(w, h) { const p = []; for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) p.push({ col: c, row: r }); return p; }
+
+// ---------- generic tile encoders (export 8x8 index grids → native bytes) ----------
+function encode2bppPlanar(grids) { // NES: plane0 (8 bytes) then plane1 (8 bytes)
+  const out = new Uint8Array(grids.length * 16);
+  grids.forEach((g, t) => {
+    for (let y = 0; y < 8; y++) {
+      let p0 = 0, p1 = 0;
+      for (let x = 0; x < 8; x++) { const v = g[y][x]; if (v & 1) p0 |= 1 << (7 - x); if (v & 2) p1 |= 1 << (7 - x); }
+      out[t * 16 + y] = p0; out[t * 16 + 8 + y] = p1;
+    }
+  });
+  return out;
+}
+function encode2bppInterleaved(grids) { // GB: per row [lo,hi]
+  const out = new Uint8Array(grids.length * 16);
+  grids.forEach((g, t) => {
+    for (let y = 0; y < 8; y++) {
+      let lo = 0, hi = 0;
+      for (let x = 0; x < 8; x++) { const v = g[y][x]; if (v & 1) lo |= 1 << (7 - x); if (v & 2) hi |= 1 << (7 - x); }
+      out[t * 16 + y * 2] = lo; out[t * 16 + y * 2 + 1] = hi;
+    }
+  });
+  return out;
+}
+function encode4bppGenesis(grids) { // packed: high nibble = left pixel
+  const out = new Uint8Array(grids.length * 32);
+  grids.forEach((g, t) => {
+    for (let y = 0; y < 8; y++) for (let half = 0; half < 4; half++)
+      out[t * 32 + y * 4 + half] = ((g[y][half * 2] & 0xF) << 4) | (g[y][half * 2 + 1] & 0xF);
+  });
+  return out;
+}
+function encode4bppSms(grids) { // interleaved per row [p0,p1,p2,p3]
+  const out = new Uint8Array(grids.length * 32);
+  grids.forEach((g, t) => {
+    for (let y = 0; y < 8; y++) {
+      let p0 = 0, p1 = 0, p2 = 0, p3 = 0;
+      for (let x = 0; x < 8; x++) { const v = g[y][x], b = 7 - x; if (v & 1) p0 |= 1 << b; if (v & 2) p1 |= 1 << b; if (v & 4) p2 |= 1 << b; if (v & 8) p3 |= 1 << b; }
+      out[t * 32 + y * 4] = p0; out[t * 32 + y * 4 + 1] = p1; out[t * 32 + y * 4 + 2] = p2; out[t * 32 + y * 4 + 3] = p3;
+    }
+  });
+  return out;
+}
+function encode4bppSnes(grids) { // planar-pairs: bytes 0-15 planes0&1, 16-31 planes2&3
+  const out = new Uint8Array(grids.length * 32);
+  grids.forEach((g, t) => {
+    for (let y = 0; y < 8; y++) {
+      let p0 = 0, p1 = 0, p2 = 0, p3 = 0;
+      for (let x = 0; x < 8; x++) { const v = g[y][x], b = 7 - x; if (v & 1) p0 |= 1 << b; if (v & 2) p1 |= 1 << b; if (v & 4) p2 |= 1 << b; if (v & 8) p3 |= 1 << b; }
+      out[t * 32 + y * 2] = p0; out[t * 32 + y * 2 + 1] = p1;
+      out[t * 32 + 16 + y * 2] = p2; out[t * 32 + 16 + y * 2 + 1] = p3;
+    }
+  });
+  return out;
+}
+
+// =====================================================================
+//  GENESIS
+// =====================================================================
+export async function genesisAdapter(host) {
+  const { decode4bppTile, decodeGenesisSubpalette } = await import("../genesis/vdp.js");
+  const { decodeGenesisSprites } = await import("../../host/gpgx-state.js");
+  const vram = host.readMemory("video_ram", 0, 0x10000);
+  const cram = host.readMemory("genesis_cram", 0, 128);
+  const regs = host.readMemory("genesis_vdp_regs", 0, 32);
+  const raw = decodeGenesisSprites(vram, regs);
+  return {
+    platform: "genesis", bpp: 4, screenW: 320, screenH: 224, tileColumnMajor: true,
+    sprites: raw.map((s) => ({ slot: s.slot, x: s.x, y: s.y, wTiles: s.size.w / 8, hTiles: s.size.h / 8, tile: s.tile, palette: s.palette, flipH: s.flipH, flipV: s.flipV, priority: s.priority, visible: s.visible })),
+    cellTileOrder: colMajorOrder, cellGridPositions: colMajorPos,
+    getTilePixels: (idx) => decode4bppTile(vram.subarray((idx & 0x7FF) * 32, (idx & 0x7FF) * 32 + 32)),
+    getPaletteRgb: (p) => decodeGenesisSubpalette(cram, p),
+    exportPalette: () => ({ bytes: Uint8Array.from(cram), json: paletteLinesJson(cram, 4, 16, (i) => decodeGenesisSubpalette(cram, i)) }),
+    encodeTiles: encode4bppGenesis,
+  };
+}
+
+// =====================================================================
+//  SNES — large OBJ are row-major in a wTiles×hTiles grid; tile index is
+//  +1 across, +0x10 down (16-wide OBJ name table). We export contiguously.
+// =====================================================================
+export async function snesAdapter(host) {
+  const { decodeOAM, decodeSnesTile, decodeCGRAM, decodePpuRegs, ppuRegsPopulated } =
+    await import("../snes/ppu.js");
+  const vram = host.readMemory("video_ram", 0, 0x10000);
+  const cgram = host.readMemory("snes_cgram", 0, 512);
+  const oam = host.readMemory("snes_oam", 0, 544);
+  const fillram = host.readMemory("snes_fillram", 0, 0x8000);
+  const colors = decodeCGRAM(cgram); // 256 entries
+  // Live OBSEL → correct OBJ size pair so wTiles/hTiles are right (a 16×16
+  // OBJ must capture as 2×2 tiles, not 1×1).
+  const ppu = ppuRegsPopulated(fillram) ? decodePpuRegs(fillram) : null;
+  const raw = decodeOAM(oam, ppu ? {
+    smallSize: ppu.objSize.small, largeSize: ppu.objSize.large,
+    objNameBaseByte: ppu.objNameBaseByte, objGapByte: ppu.objGapByte,
+  } : {});
+  // SNES OBJ palettes are CGRAM 128-255, 16 colors each (8 lines). palette
+  // field is 0-7 → base = 128 + p*16.
+  const palRgb = (p) => { const base = 128 + (p & 7) * 16; return colors.slice(base, base + 16).map((c) => [c.r, c.g, c.b]); };
+  // Large-OBJ tile layout: within a wTiles×hTiles sprite, tile index goes
+  // +1 per column and +0x10 per row (OBJ char table is 16 tiles wide).
+  const orderFn = (w, h) => { const o = []; for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) o.push(r * 0x10 + c); return o; };
+  return {
+    platform: "snes", bpp: 4, screenW: 256, screenH: 224, tileColumnMajor: false,
+    sprites: raw.map((s) => ({ slot: s.slot, x: s.x, y: s.y, wTiles: s.size.w / 8, hTiles: s.size.h / 8, tile: s.tile, palette: s.palette, flipH: s.flipH, flipV: s.flipV, priority: s.priority, visible: s.visible })),
+    cellTileOrder: orderFn, cellGridPositions: rowMajorPos,
+    getTilePixels: (idx) => { const off = ((idx & 0x1FF) * 32) & 0xFFFF; return decodeSnesTile(vram.subarray(off, off + 32), 4); },
+    getPaletteRgb: palRgb,
+    exportPalette: () => ({ bytes: Uint8Array.from(cgram), json: paletteLinesJson(cgram, 8, 16, (i) => palRgb(i), 128) }),
+    encodeTiles: encode4bppSnes,
+  };
+}
+
+// =====================================================================
+//  NES — 8x8 (1 tile) or 8x16 (2 tiles stacked, top then bottom).
+// =====================================================================
+export async function nesAdapter(host) {
+  const { decodeTile } = await import("../nes/ppu.js");
+  const oam = host.readMemory("nes_oam", 0, 256);
+  const chr = host.readMemory("nes_chr", 0, 0x2000); // 8KB pattern space
+  const palBytes = host.readMemory("nes_palette", 0, 32);
+  const ppu = host.readMemory("nes_ppu_regs", 0, 4);
+  const spr8x16 = !!(ppu[0] & 0x20);
+  // NES sprite palettes are entries 16..31 (4 lines of 4). palette field 0-3.
+  const NES_RGB = nesMasterRgb();
+  const palRgb = (p) => { const out = [[0, 0, 0]]; for (let i = 1; i < 4; i++) out.push(NES_RGB[palBytes[16 + p * 4 + i] & 0x3F]); return out; };
+  const sprites = [];
+  for (let i = 0; i < 64; i++) {
+    const y = oam[i * 4], tile = oam[i * 4 + 1], attr = oam[i * 4 + 2], x = oam[i * 4 + 3];
+    sprites.push({
+      slot: i, x, y, wTiles: 1, hTiles: spr8x16 ? 2 : 1,
+      tile: spr8x16 ? (tile & 0xFE) : tile,  // 8x16: bit0 selects pattern table, even tile is top
+      palette: attr & 3, flipH: !!(attr & 0x40), flipV: !!(attr & 0x80), priority: (attr >> 5) & 1,
+      visible: y < 0xEF,
+    });
+  }
+  return {
+    platform: "nes", bpp: 2, screenW: 256, screenH: 240, tileColumnMajor: false,
+    sprites,
+    cellTileOrder: (w, h) => rowMajorOrder(w, h),  // 8x16 → [0,1] = top,bottom
+    cellGridPositions: rowMajorPos,
+    getTilePixels: (idx) => flatToGrid(decodeTile(chr.subarray((idx & 0x1FF) * 16, (idx & 0x1FF) * 16 + 16))),
+    getPaletteRgb: palRgb,
+    exportPalette: () => ({ bytes: Uint8Array.from(palBytes), json: { "sprite0": palRgb(0).map(rgbHex), "sprite1": palRgb(1).map(rgbHex), "sprite2": palRgb(2).map(rgbHex), "sprite3": palRgb(3).map(rgbHex) } }),
+    encodeTiles: encode2bppPlanar,
+  };
+}
+
+// =====================================================================
+//  GB / GBC — 8x8 or 8x16 (top tile = idx&0xFE, bottom = idx|1).
+// =====================================================================
+export async function gbAdapter(host, platform) {
+  const { decodeGbTile } = await import("../gb/ppu.js");
+  const oam = host.readMemory("gb_oam", 0, 0xA0);
+  const vram = host.readMemory("gb_vram", 0, 0x2000);
+  const io = host.readMemory("gb_io", 0, 0x80);
+  const obj8x16 = !!(io[0x40] & 0x04);
+  // DMG OBJ palettes OBP0 ($FF48) / OBP1 ($FF49): 4 shades. CGB has OBJ
+  // palette RAM but we keep it simple: DMG grayscale by palette bits.
+  const DMG = [[224,248,208],[136,192,112],[52,104,86],[8,24,32]];
+  const obp = [io[0x48], io[0x49]];
+  const palRgb = (p) => { const reg = obp[p & 1]; const out = []; for (let i = 0; i < 4; i++) out.push(DMG[(reg >> (i * 2)) & 3]); return out; };
+  const sprites = [];
+  for (let i = 0; i < 40; i++) {
+    const y = oam[i * 4] - 16, x = oam[i * 4 + 1] - 8, t = oam[i * 4 + 2], a = oam[i * 4 + 3];
+    sprites.push({
+      slot: i, x, y, wTiles: 1, hTiles: obj8x16 ? 2 : 1,
+      tile: obj8x16 ? (t & 0xFE) : t,
+      palette: (a >> 4) & 1, flipH: !!(a & 0x20), flipV: !!(a & 0x40), priority: (a >> 7) & 1,
+      visible: oam[i * 4] !== 0 && oam[i * 4] < 160,
+    });
+  }
+  return {
+    platform, bpp: 2, screenW: 160, screenH: 144, tileColumnMajor: false,
+    sprites,
+    cellTileOrder: rowMajorOrder, cellGridPositions: rowMajorPos,
+    getTilePixels: (idx) => flatToGrid(decodeGbTile(vram, (idx & 0xFF) * 16)),
+    getPaletteRgb: palRgb,
+    exportPalette: () => ({ bytes: Uint8Array.from([obp[0], obp[1]]), json: { "obp0": palRgb(0).map(rgbHex), "obp1": palRgb(1).map(rgbHex) } }),
+    encodeTiles: encode2bppInterleaved,
+  };
+}
+
+// =====================================================================
+//  SMS / GG — 8x8 sprites (8x16 stacked when reg1 bit1 set). One sprite
+//  palette line (CRAM entries 16-31). Tile data base from VDP reg 6.
+// =====================================================================
+export async function smsAdapter(host, platform) {
+  const { decodeSmsTile, decodeSmsVdpRegs, decodeSmsCram, decodeGgCram, snapshotPalette } = await import("../sms/vdp.js");
+  const vramRegion = platform === "gg" ? "gg_vram" : "sms_vram";
+  const vram = host.readMemory(vramRegion, 0, 0x4000);
+  const regs = host.readMemory("sms_vdp_regs", 0, 16);
+  const dec = decodeSmsVdpRegs(regs);
+  const { colors } = snapshotPalette(host, platform); // 32 entries
+  const sprPal = colors.slice(16, 32).map((c) => [c.r, c.g, c.b]);
+  const palRgb = () => sprPal;
+  const big = dec.mode2.spriteSize8x16;
+  const base = dec.spriteTileDataBaseDec;
+  const sat = vram.slice(dec.spriteAttrTableBaseDec, dec.spriteAttrTableBaseDec + 256);
+  const sprites = [];
+  for (let i = 0; i < 64; i++) {
+    const y = sat[i];
+    if (y === 0xD0) break;                       // terminator
+    const x = sat[0x80 + i * 2], tile = sat[0x80 + i * 2 + 1];
+    sprites.push({
+      slot: i, x, y: (y + 1) & 0xFF, wTiles: 1, hTiles: big ? 2 : 1,
+      tile: big ? (tile & 0xFE) : tile, palette: 0, flipH: false, flipV: false, priority: 0,
+      visible: true,
+    });
+  }
+  return {
+    platform, bpp: 4, screenW: platform === "gg" ? 160 : 256, screenH: platform === "gg" ? 144 : 192, tileColumnMajor: false,
+    sprites,
+    cellTileOrder: rowMajorOrder, cellGridPositions: rowMajorPos,
+    getTilePixels: (idx) => { const out = decodeSmsTile(vram, base + (idx & 0x1FF) * 32); const g = []; for (let y = 0; y < 8; y++) g.push(Array.from(out.slice(y * 8, y * 8 + 8))); return g; },
+    getPaletteRgb: palRgb,
+    exportPalette: () => { const cram = host.readMemory(platform === "gg" ? "gg_cram" : "sms_cram", 0, platform === "gg" ? 64 : 32); return { bytes: Uint8Array.from(cram), json: { "sprite": sprPal.map(rgbHex) } }; },
+    encodeTiles: encode4bppSms,
+  };
+}
+
+// ---------- shared helpers ----------
+// Some platform tile decoders return a flat Uint8Array(64); the core wants
+// an 8x8 nested array of indices.
+function flatToGrid(flat) { const g = []; for (let y = 0; y < 8; y++) { const row = []; for (let x = 0; x < 8; x++) row.push(flat[y * 8 + x]); g.push(row); } return g; }
+function rgbHex(rgb) { return "#" + [rgb[0], rgb[1], rgb[2]].map((v) => (v & 0xFF).toString(16).padStart(2, "0")).join(""); }
+function paletteLinesJson(cram, lines, perLine, lineRgbFn) {
+  const json = {};
+  for (let i = 0; i < lines; i++) json[String(i)] = lineRgbFn(i).map(rgbHex);
+  return json;
+}
+
+// NES 2C02 master palette (sample — matches sprite-pipeline's NES_MASTER).
+function nesMasterRgb() {
+  // 64-entry approximation; index by the palette byte & 0x3F.
+  const P = [
+    [0x60,0x60,0x60],[0x00,0x20,0x80],[0x00,0x00,0xA0],[0x40,0x00,0x90],[0x80,0x00,0x60],[0xA0,0x00,0x30],[0xA0,0x00,0x00],[0x80,0x20,0x00],
+    [0x60,0x40,0x00],[0x20,0x60,0x00],[0x00,0x80,0x00],[0x00,0x60,0x30],[0x00,0x40,0x60],[0,0,0],[0,0,0],[0,0,0],
+    [0xA0,0xA0,0xA0],[0x00,0x60,0xC0],[0x20,0x40,0xE0],[0x80,0x00,0xF0],[0xC0,0x00,0xC0],[0xE0,0x00,0x60],[0xF0,0x20,0x00],[0xC0,0x60,0x00],
+    [0x80,0x80,0x00],[0x40,0xA0,0x00],[0x00,0xC0,0x00],[0x20,0xA0,0x60],[0x00,0x80,0xA0],[0,0,0],[0,0,0],[0,0,0],
+    [0xF0,0xF0,0xF0],[0x60,0xA0,0xF0],[0x80,0x80,0xF0],[0xC0,0x60,0xF0],[0xF0,0x40,0xF0],[0xF0,0x60,0xA0],[0xF0,0x80,0x60],[0xE0,0xA0,0x40],
+    [0xC0,0xC0,0x20],[0x80,0xE0,0x40],[0x40,0xE0,0x80],[0x40,0xE0,0xC0],[0x00,0xE0,0xE0],[0x60,0x60,0x60],[0,0,0],[0,0,0],
+    [0xF0,0xF0,0xF0],[0xA0,0xD0,0xF0],[0xC0,0xC0,0xF0],[0xE0,0xC0,0xF0],[0xF0,0xC0,0xF0],[0xF0,0xC0,0xE0],[0xF0,0xC0,0xC0],[0xF0,0xD0,0xA0],
+    [0xE0,0xE0,0x80],[0xC0,0xE0,0x80],[0xA0,0xF0,0xA0],[0xA0,0xF0,0xC0],[0xA0,0xF0,0xE0],[0xA0,0xA0,0xA0],[0,0,0],[0,0,0],
+  ];
+  return P;
+}
+
+/** Build the right adapter for a platform from a live host. */
+export async function buildAdapter(host, platform) {
+  switch (platform) {
+    case "genesis": return genesisAdapter(host);
+    case "snes": return snesAdapter(host);
+    case "nes": return nesAdapter(host);
+    case "gb": case "gbc": return gbAdapter(host, platform);
+    case "sms": case "gg": return smsAdapter(host, platform);
+    case "c64":
+      throw new Error("captureMetaSprite[c64]: the C64 has 8 hardware MOBs (24×21px bitmaps, not 8x8 tiles) — they don't fit the tile-based meta-sprite model. Use inspectSprites + the sprite data pointers, and author MOB bitmaps directly.");
+    default:
+      throw new Error(`captureMetaSprite: no meta-sprite adapter for platform '${platform}'. Supported: genesis, snes, nes, gb, gbc, sms, gg.`);
+  }
+}

package/src/platforms/common/metasprite-codegen.js

@@ -0,0 +1,192 @@
+// Platform-aware C codegen for captured meta-sprites. Emits the tile/
+// palette/piece arrays plus a draw helper idiomatic to each platform's
+// sprite hardware. No platform name in the public API — the layout's
+// `platform` field selects the right emitter.
+
+function ident(s) { return (s || "metasprite").replace(/[^A-Za-z0-9_]/g, "_"); }
+
+function tilesU8Array(name, tiles) {
+  const lines = [];
+  for (let i = 0; i < tiles.length; i += 16) {
+    lines.push("  " + Array.from(tiles.slice(i, i + 16), (b) => "0x" + b.toString(16).toUpperCase().padStart(2, "0")).join(", ") + ",");
+  }
+  return `const unsigned char ${name}_tiles[${tiles.length}] = {\n${lines.join("\n")}\n};`;
+}
+
+/**
+ * Emit C for a captured meta-sprite. Dispatches on layout.platform.
+ * @param {object} args { layout, tiles, palette, varName? }
+ * @returns {string}
+ */
+export function emitMetaSpriteCode({ layout, tiles, palette, varName }) {
+  const v = ident(varName || layout.name);
+  switch (layout.platform) {
+    case "genesis": return emitGenesis(v, layout, tiles, palette);
+    case "snes":    return emitSnes(v, layout, tiles, palette);
+    case "nes":     return emitNes(v, layout, tiles, palette);
+    case "gb": case "gbc": return emitGb(v, layout, tiles, palette);
+    case "sms": case "gg": return emitSms(v, layout, tiles, palette, layout.platform);
+    default:        return emitGeneric(v, layout, tiles, palette);
+  }
+}
+
+// ---- Genesis (SGDK) ----
+function emitGenesis(v, layout, tiles, palette) {
+  const u32s = [];
+  for (let i = 0; i < tiles.length; i += 4)
+    u32s.push("0x" + (((tiles[i] << 24) | (tiles[i + 1] << 16) | (tiles[i + 2] << 8) | tiles[i + 3]) >>> 0).toString(16).toUpperCase().padStart(8, "0"));
+  const usedLines = Object.keys(layout.palettes).map(Number).filter((n) => !isNaN(n)).sort();
+  const firstLine = usedLines[0] ?? 0;
+  const palWords = [];
+  for (let i = 0; i < 16; i++) { const off = (firstLine * 16 + i) * 2; palWords.push("0x" + (((palette[off] << 8) | palette[off + 1]) & 0xFFFF).toString(16).toUpperCase().padStart(4, "0")); }
+  const pieces = layout.pieces.map((p) => {
+    const attr = ((p.priority ? 1 : 0) << 15) | ((p.palette & 3) << 13) | ((p.flipV ? 1 : 0) << 12) | ((p.flipH ? 1 : 0) << 11);
+    const size = (((p.wTiles - 1) & 3) << 2) | ((p.hTiles - 1) & 3);
+    return `  { ${p.x}, ${p.y}, 0x${size.toString(16)}, ${p.tileOffset}, 0x${attr.toString(16).toUpperCase().padStart(4, "0")} }, // slot ${p.slot} ${p.wTiles}x${p.hTiles}`;
+  }).join("\n");
+  const wrap = (a, n) => { const o = []; for (let i = 0; i < a.length; i += n) o.push("  " + a.slice(i, i + n).join(", ") + ","); return o.join("\n"); };
+  return `// ${v} — Genesis meta-sprite (romdev). ${layout.tileCount} tiles, ${layout.bounds.w}x${layout.bounds.h}px.
+#ifndef ${v.toUpperCase()}_H
+#define ${v.toUpperCase()}_H
+#include <genesis.h>
+typedef struct { s16 x; s16 y; u8 size; u16 tileOffset; u16 attr; } MetaSpritePiece;
+const u32 ${v}_tiles[${u32s.length}] = {
+${wrap(u32s, 8)}
+};
+const u16 ${v}_palette[16] = {
+${wrap(palWords, 8)}
+};
+const MetaSpritePiece ${v}_pieces[${layout.pieces.length}] = {
+${pieces}
+};
+const u16 ${v}_piece_count = ${layout.pieces.length};
+static u16 ${v}_draw(u16 firstSlot, s16 x, s16 y, u16 baseTile) {
+    u16 slot = firstSlot;
+    for (u16 i = 0; i < ${v}_piece_count; i++) {
+        const MetaSpritePiece *p = &${v}_pieces[i];
+        VDP_setSprite(slot, x + p->x, y + p->y, p->size, p->attr | (baseTile + p->tileOffset), slot + 1);
+        slot++;
+    }
+    if (slot > firstSlot) VDP_setSpriteLink(slot - 1, 0);
+    return slot;
+}
+#endif
+`;
+}
+
+// ---- SNES (PVSnesLib oamSet-style) ----
+function emitSnes(v, layout, tiles, palette) {
+  const pieces = layout.pieces.map((p) => {
+    // PVSnesLib oamSet: size 0=8x8/16x16 small/large per OBSEL — we expose
+    // wPx/hPx and let the user pick the OBSEL pair; flip bits in attr.
+    return `  { ${p.x}, ${p.y}, ${p.wPx}, ${p.hPx}, ${p.tileOffset}, ${p.palette}, ${p.priority ? 1 : 0}, ${p.flipH ? 1 : 0}, ${p.flipV ? 1 : 0} }, // slot ${p.slot}`;
+  }).join("\n");
+  return `// ${v} — SNES meta-sprite (romdev). ${layout.tileCount} 4bpp tiles, ${layout.bounds.w}x${layout.bounds.h}px.
+// Upload ${v}_tiles to OBJ VRAM, ${v}_palette to a CGRAM OBJ line, then draw.
+#ifndef ${v.toUpperCase()}_H
+#define ${v.toUpperCase()}_H
+#include <snes.h>
+typedef struct { short x; short y; unsigned char w; unsigned char h; unsigned short tileOffset; unsigned char palette; unsigned char priority; unsigned char flipH; unsigned char flipV; } MetaSpritePiece;
+${tilesU8Array(v, tiles)}
+const MetaSpritePiece ${v}_pieces[${layout.pieces.length}] = {
+${pieces}
+};
+const unsigned short ${v}_piece_count = ${layout.pieces.length};
+// Draw with PVSnesLib: for each piece, oamSet(oamId, x+px, y+py, prio, flipH, flipV, baseTile+tileOffset, palette);
+// then oamSetEx for size. baseTile = OBJ VRAM tile index where you uploaded ${v}_tiles.
+#endif
+`;
+}
+
+// ---- NES (shadow-OAM bytes) ----
+function emitNes(v, layout, tiles, palette) {
+  // NES draw = write 4 OAM bytes per cell (y, tile, attr, x). We emit pieces
+  // as (x,y,tile,attr) so the user copies them into shadow OAM at their base.
+  const cells = [];
+  for (const p of layout.pieces) {
+    for (let r = 0; r < p.hTiles; r++) for (let c = 0; c < p.wTiles; c++) {
+      const attr = (p.palette & 3) | (p.priority ? 0x20 : 0) | (p.flipH ? 0x40 : 0) | (p.flipV ? 0x80 : 0);
+      cells.push(`  { ${p.x + c * 8}, ${p.y + r * 8}, ${p.tileOffset + r * p.wTiles + c}, 0x${attr.toString(16).padStart(2, "0")} },`);
+    }
+  }
+  return `// ${v} — NES meta-sprite (romdev). ${layout.tileCount} 2bpp CHR tiles.
+// Inject ${v}_chr into CHR (or CHR-RAM); copy ${v}_cells into shadow OAM at runtime.
+#ifndef ${v.toUpperCase()}_H
+#define ${v.toUpperCase()}_H
+typedef struct { signed char dx; signed char dy; unsigned char tile; unsigned char attr; } MetaSpriteCell;
+const unsigned char ${v}_chr[${tiles.length}] = {
+${chunk(tiles)}
+};
+const MetaSpriteCell ${v}_cells[${cells.length}] = {
+${cells.join("\n")}
+};
+const unsigned char ${v}_cell_count = ${cells.length};
+// draw: for each cell i, shadow_oam[base+i*4+0]=y+dy; +1=baseTile+tile; +2=attr; +3=x+dx;
+#endif
+`;
+}
+
+// ---- GB/GBC (shadow-OAM bytes) ----
+function emitGb(v, layout, tiles, palette) {
+  const cells = [];
+  for (const p of layout.pieces) {
+    for (let r = 0; r < p.hTiles; r++) {
+      const attr = ((p.palette & 1) << 4) | (p.flipH ? 0x20 : 0) | (p.flipV ? 0x40 : 0) | (p.priority ? 0x80 : 0);
+      cells.push(`  { ${p.x}, ${p.y + r * 8}, ${p.tileOffset + r}, 0x${attr.toString(16).padStart(2, "0")} },`);
+    }
+  }
+  return `// ${v} — GB/GBC meta-sprite (romdev). ${layout.tileCount} 2bpp tiles.
+// Copy ${v}_tiles to VRAM $8000+; copy ${v}_cells into shadow OAM ($C000-ish) then DMA.
+#ifndef ${v.toUpperCase()}_H
+#define ${v.toUpperCase()}_H
+typedef struct { signed char dx; signed char dy; unsigned char tile; unsigned char attr; } MetaSpriteCell;
+const unsigned char ${v}_tiles[${tiles.length}] = {
+${chunk(tiles)}
+};
+const MetaSpriteCell ${v}_cells[${cells.length}] = {
+${cells.join("\n")}
+};
+const unsigned char ${v}_cell_count = ${cells.length};
+// draw: oam[base+i*4]=y+16+dy; +1=x+8+dx; +2=baseTile+tile; +3=attr;
+#endif
+`;
+}
+
+// ---- SMS/GG (SAT writes) ----
+function emitSms(v, layout, tiles, palette, platform) {
+  const cells = [];
+  for (const p of layout.pieces) {
+    for (let r = 0; r < p.hTiles; r++) cells.push(`  { ${p.x}, ${p.y + r * 8}, ${p.tileOffset + r} },`);
+  }
+  return `// ${v} — ${platform.toUpperCase()} meta-sprite (romdev). ${layout.tileCount} 4bpp tiles.
+// Upload ${v}_tiles to sprite tile data base; write ${v}_cells into the SAT.
+#ifndef ${v.toUpperCase()}_H
+#define ${v.toUpperCase()}_H
+typedef struct { signed char dx; signed char dy; unsigned char tile; } MetaSpriteCell;
+const unsigned char ${v}_tiles[${tiles.length}] = {
+${chunk(tiles)}
+};
+const MetaSpriteCell ${v}_cells[${cells.length}] = {
+${cells.join("\n")}
+};
+const unsigned char ${v}_cell_count = ${cells.length};
+// draw: SAT Y table[base+i]=y+dy; X/tile table[base+i*2]=x+dx, [+1]=baseTile+tile;
+#endif
+`;
+}
+
+function emitGeneric(v, layout, tiles) {
+  return `// ${v} — meta-sprite (romdev), platform ${layout.platform}.
+const unsigned char ${v}_tiles[${tiles.length}] = {
+${chunk(tiles)}
+};
+// pieces: ${JSON.stringify(layout.pieces)}
+`;
+}
+
+function chunk(bytes) {
+  const lines = [];
+  for (let i = 0; i < bytes.length; i += 16)
+    lines.push("  " + Array.from(bytes.slice(i, i + 16), (b) => "0x" + b.toString(16).toUpperCase().padStart(2, "0")).join(", ") + ",");
+  return lines.join("\n");
+}

package/src/platforms/common/metasprite-core.js

@@ -0,0 +1,201 @@
+// Platform-agnostic meta-sprite capture.
+//
+// A meta-sprite is the live composition of a character's hardware sprites
+// (OAM/SAT entries) lifted into a reusable asset: exported tiles + a layout
+// describing each piece's position/size/palette/flips, plus a preview
+// re-rendered FROM the exported data (never a screenshot crop).
+//
+// Each platform supplies an ADAPTER with a uniform interface, so the
+// select / copy-tiles / normalize / render logic below is written once:
+//
+//   adapter = {
+//     platform,                       // "genesis" | "snes" | ...
+//     bpp,                            // 2 | 4 (for tiles)
+//     screenW, screenH,              // visible bounds (for default select)
+//     sprites,                        // [{slot,x,y,wTiles,hTiles,tile,palette,flipH,flipV,priority}]
+//     cellTileOrder(wTiles,hTiles),   // → [tileIndexOffset, ...] in HARDWARE order
+//     getTilePixels(tileIndex),       // → 8x8 array of palette indices (0=transparent)
+//     getPaletteRgb(palette),         // → [[r,g,b], ...] for that sprite's palette line
+//     exportPalette(),                // → { bytes:Uint8Array, json:{line:[hex...]}, lines:[..] }
+//     tileColumnMajor,                // bool — true if cell order increments down columns (Genesis)
+//   }
+
+import { PNG } from "pngjs";
+
+/**
+ * Capture a meta-sprite using a platform adapter.
+ * @param {object} adapter see header
+ * @param {object} opts { rect?, slots?, includePartials?, name? }
+ */
+export function captureFromAdapter(adapter, opts = {}) {
+  const name = opts.name || "metasprite";
+  const includePartials = opts.includePartials !== false;
+  const all = adapter.sprites;
+
+  let selected;
+  if (Array.isArray(opts.slots) && opts.slots.length) {
+    const want = new Set(opts.slots);
+    selected = all.filter((s) => want.has(s.slot));
+  } else if (opts.rect) {
+    const { x, y, w, h } = opts.rect;
+    const rx2 = x + w, ry2 = y + h;
+    selected = all.filter((s) => {
+      const sx2 = s.x + s.wTiles * 8, sy2 = s.y + s.hTiles * 8;
+      const hit = s.x < rx2 && sx2 > x && s.y < ry2 && sy2 > y;
+      if (!hit) return false;
+      if (includePartials) return true;
+      return s.x >= x && s.y >= y && sx2 <= rx2 && sy2 <= ry2;
+    });
+  } else {
+    selected = all.filter((s) => s.visible);
+  }
+  if (selected.length === 0) {
+    throw new Error(
+      `captureMetaSprite[${adapter.platform}]: no sprite entries matched. ` +
+      `Pass slots:[...] (from inspectSprites/groupVisibleSprites) or a rect that overlaps a sprite, ` +
+      `and step to a frame where the character is on screen.`
+    );
+  }
+
+  const originX = Math.min(...selected.map((s) => s.x));
+  const originY = Math.min(...selected.map((s) => s.y));
+  let boundW = 0, boundH = 0;
+
+  // Copy + dedup tiles by their decoded 8x8 pixel grid (platform-agnostic key).
+  const tileByKey = new Map();
+  /** @type {number[][][]} */ const exportTiles = []; // each is an 8x8 index grid
+  const palettesUsed = new Set();
+  const pieces = [];
+
+  const copyTile = (tileIndex) => {
+    const grid = adapter.getTilePixels(tileIndex);
+    let key = "";
+    for (let r = 0; r < 8; r++) for (let c = 0; c < 8; c++) key += grid[r][c].toString(16);
+    let exp = tileByKey.get(key);
+    if (exp === undefined) { exp = exportTiles.length; tileByKey.set(key, exp); exportTiles.push(grid); }
+    return exp;
+  };
+
+  for (const s of selected) {
+    palettesUsed.add(s.palette);
+    const order = adapter.cellTileOrder(s.wTiles, s.hTiles); // tile-index offsets, hardware order
+    let firstExp = -1;
+    for (const off of order) {
+      const exp = copyTile(s.tile + off);
+      if (firstExp === -1) firstExp = exp;
+    }
+    const px = s.x - originX, py = s.y - originY;
+    boundW = Math.max(boundW, px + s.wTiles * 8);
+    boundH = Math.max(boundH, py + s.hTiles * 8);
+    pieces.push({
+      slot: s.slot, x: px, y: py,
+      wTiles: s.wTiles, hTiles: s.hTiles,
+      wPx: s.wTiles * 8, hPx: s.hTiles * 8,
+      sourceTile: s.tile, tileOffset: firstExp,
+      palette: s.palette,
+      priority: !!s.priority, flipH: !!s.flipH, flipV: !!s.flipV,
+    });
+  }
+
+  const pal = adapter.exportPalette();
+  const layout = {
+    platform: adapter.platform,
+    name,
+    bpp: adapter.bpp,
+    tileColumnMajor: !!adapter.tileColumnMajor,
+    origin: { x: originX, y: originY },
+    bounds: { w: boundW, h: boundH },
+    tileCount: exportTiles.length,
+    palettes: pal.json,
+    pieces,
+  };
+
+  // Flatten exported tile pixel-grids into native bytes via the adapter.
+  const tiles = adapter.encodeTiles(exportTiles);
+
+  const previewPng = renderFromExported({ exportTiles, adapter, layout });
+
+  return {
+    layout, tiles, palette: pal.bytes, paletteJson: pal.json, previewPng,
+    note: `${pieces.length} piece(s), ${exportTiles.length} unique tiles, ${boundW}×${boundH}px, ${adapter.bpp}bpp. ` +
+      `Tile order ${adapter.tileColumnMajor ? "column-major (hardware)" : "row-major"} preserved. ` +
+      `Palette line(s) used: ${[...palettesUsed].sort((a,b)=>a-b).join(",")}.`,
+  };
+}
+
+/** Render a meta-sprite to PNG from decoded export tiles + layout. */
+function renderFromExported({ exportTiles, adapter, layout }) {
+  const W = Math.max(8, layout.bounds.w), H = Math.max(8, layout.bounds.h);
+  const png = new PNG({ width: W, height: H });
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const o = (y * W + x) * 4, c = ((x >> 3) + (y >> 3)) & 1 ? 0x60 : 0x40;
+    png.data[o] = c; png.data[o + 1] = c; png.data[o + 2] = c; png.data[o + 3] = 0xFF;
+  }
+  const palCache = {};
+  const palOf = (p) => (palCache[p] ??= adapter.getPaletteRgb(p));
+  for (const piece of layout.pieces) {
+    const rgbPal = palOf(piece.palette);
+    const order = adapter.cellTileOrder(piece.wTiles, piece.hTiles);
+    // Map each hardware cell index to its (col,row) grid position.
+    const cellPos = adapter.cellGridPositions(piece.wTiles, piece.hTiles);
+    for (let i = 0; i < order.length; i++) {
+      const expTile = piece.tileOffset + i;
+      if (expTile >= exportTiles.length) continue;
+      const grid = exportTiles[expTile];
+      let { col, row } = cellPos[i];
+      if (piece.flipH) col = piece.wTiles - 1 - col;
+      if (piece.flipV) row = piece.hTiles - 1 - row;
+      for (let ty = 0; ty < 8; ty++) for (let tx = 0; tx < 8; tx++) {
+        const sx = piece.flipH ? 7 - tx : tx, sy = piece.flipV ? 7 - ty : ty;
+        const ci = grid[sy][sx];
+        if (ci === 0) continue;
+        const [r, g, b] = rgbPal[ci] || [0, 0, 0];
+        const px = piece.x + col * 8 + tx, py = piece.y + row * 8 + ty;
+        if (px < 0 || py < 0 || px >= W || py >= H) continue;
+        const o = (py * W + px) * 4;
+        png.data[o] = r; png.data[o + 1] = g; png.data[o + 2] = b; png.data[o + 3] = 0xFF;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}
+
+/**
+ * Re-render from already-saved files (tiles.bin + palette + layout). The
+ * adapter here is a "decode-only" one built from the layout's bpp + saved
+ * bytes (no live host needed).
+ */
+export function renderSavedMetaSprite({ adapter, layout, exportTiles }) {
+  return renderFromExported({ exportTiles, adapter, layout });
+}
+
+/**
+ * Generic spatial clustering of on-screen sprites into objects.
+ * @param {Array} sprites uniform sprite list (with x,y,wTiles,hTiles,slot)
+ * @param {object} opts { rect?, gap?=8 }
+ */
+export function clusterSprites(sprites, opts = {}) {
+  const gap = opts.gap ?? 8;
+  let list = sprites.filter((s) => s.visible);
+  if (opts.rect) {
+    const { x, y, w, h } = opts.rect, rx2 = x + w, ry2 = y + h;
+    list = list.filter((s) => s.x < rx2 && s.x + s.wTiles * 8 > x && s.y < ry2 && s.y + s.hTiles * 8 > y);
+  }
+  const parent = list.map((_, i) => i);
+  const find = (a) => { while (parent[a] !== a) a = parent[a] = parent[parent[a]]; return a; };
+  const near = (a, b) => {
+    const aw = a.wTiles * 8, ah = a.hTiles * 8, bw = b.wTiles * 8, bh = b.hTiles * 8;
+    return a.x - gap < b.x + bw && a.x + aw + gap > b.x && a.y - gap < b.y + bh && a.y + ah + gap > b.y;
+  };
+  for (let i = 0; i < list.length; i++) for (let j = i + 1; j < list.length; j++)
+    if (near(list[i], list[j])) parent[find(i)] = find(j);
+  const byRoot = new Map();
+  list.forEach((s, i) => { const r = find(i); (byRoot.get(r) || byRoot.set(r, []).get(r)).push(s); });
+  const groups = [...byRoot.values()].map((grp) => {
+    const x = Math.min(...grp.map((s) => s.x)), y = Math.min(...grp.map((s) => s.y));
+    const x2 = Math.max(...grp.map((s) => s.x + s.wTiles * 8)), y2 = Math.max(...grp.map((s) => s.y + s.hTiles * 8));
+    return { slots: grp.map((s) => s.slot).sort((a, b) => a - b), bounds: { x, y, w: x2 - x, h: y2 - y }, spriteCount: grp.length };
+  });
+  groups.sort((a, b) => (b.bounds.w * b.bounds.h) - (a.bounds.w * a.bounds.h));
+  return { groups };
+}