sci2-ts 0.0.0-stage → 0.2.1

package/packages/sci/src/gfx/pic-file.ts

@@ -0,0 +1,155 @@
+import type { Palette } from "./palette.ts";
+import type { PicCel } from "./pic.ts";
+
+/**
+ * A pic resource with everything needed to write it back byte for byte. Measured on all 59
+ * pics of an SCI2 game (every one has this exact layout; all cels are uncompressed):
+ *
+ *   +0  u16 header size (14)  +2 u8 cel count  +3 u8 0  +4 u16 cel header size (42)
+ *   +6  u32 palette offset    +10 u16/u16 resolution (320,200, or 0,0 meaning the default)
+ *   cel headers, 42 bytes each:
+ *     +0 u16 width  +2 u16 height  +4 i16 displaceX  +6 i16 displaceY  +8 u8 skip colour
+ *     +9 u8 compression (0 = raw)  +10 u16 0  +12 u32 pixel bytes (w*h)
+ *     +16 u32 `unknown16` (2768 in most pics, 6 in a few; the engine ignores it)
+ *     +20 u32 0  +24 u32 pixel offset  +28 u32 0  +32 u32 0
+ *     +36 i16 priority  +38 i16 x  +40 i16 y
+ *   00 03 u32 palette size | hunk palette
+ *   00 04 u32 pixel bytes  | each cel's pixels, in cel order
+ */
+export interface PicFile {
+  resolution: [number, number];
+  cels: (PicCel & { unknown16: number })[];
+  palette: HunkPaletteFile;
+}
+
+/**
+ * A hunk palette with its exact header bytes. Pics use one entry: `first` and
+ * `count` colours, each with its own "used" flag (4 bytes per colour) unless `shared`.
+ */
+export interface HunkPaletteFile {
+  /** The 13-byte hunk header (byte 0 = 14, byte 10 = entry count = 1). */
+  header: Uint8Array;
+  /** The first 10 bytes of the entry header (editor data; varies, never read). */
+  entryPrefix: Uint8Array;
+  first: number;
+  used: number[];
+  rgb: [number, number, number][];
+  /** Shared "used" flag: every colour is 3 bytes and takes `defaultUsed`. */
+  shared: boolean;
+  defaultUsed: number;
+}
+
+const PIC_HEADER = 14;
+const CEL_HEADER = 42;
+
+export function parseHunkPaletteFile(data: Uint8Array, offset: number): HunkPaletteFile {
+  const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  if (data[offset + 10] !== 1) throw new Error(`Hunk palette with ${data[offset + 10]} entries: only 1 is supported`);
+  const entry = offset + 13 + 2;
+  const first = data[entry + 10]!;
+  const count = v.getUint16(entry + 14, true);
+  const defaultUsed = data[entry + 16]!;
+  const shared = data[entry + 17]! !== 0;
+  const used: number[] = [], rgb: [number, number, number][] = [];
+  let p = entry + 22;
+  for (let i = 0; i < count; i++) {
+    used.push(shared ? defaultUsed : data[p++]!);
+    rgb.push([data[p]!, data[p + 1]!, data[p + 2]!]);
+    p += 3;
+  }
+  return { header: data.slice(offset, offset + 13), entryPrefix: data.slice(entry, entry + 10), first, used, rgb, shared, defaultUsed };
+}
+
+export function writeHunkPalette(p: HunkPaletteFile): Uint8Array {
+  const colors = p.rgb.length * (p.shared ? 3 : 4);
+  const out = new Uint8Array(13 + 2 + 22 + colors);
+  const v = new DataView(out.buffer);
+  out.set(p.header, 0);
+  out[10] = 1;
+  v.setUint16(13, 22 + colors, true);
+  const entry = 15;
+  out.set(p.entryPrefix, entry);
+  out[entry + 10] = p.first;
+  v.setUint16(entry + 14, p.rgb.length, true);
+  out[entry + 16] = p.defaultUsed;
+  out[entry + 17] = p.shared ? 1 : 0;
+  let o = entry + 22;
+  p.rgb.forEach((c, i) => {
+    if (!p.shared) out[o++] = p.used[i]!;
+    out.set(c, o);
+    o += 3;
+  });
+  return out;
+}
+
+export function parsePicFile(data: Uint8Array): PicFile {
+  const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const count = data[2]!;
+  const cels = Array.from({ length: count }, (_, i) => {
+    const h = PIC_HEADER + CEL_HEADER * i;
+    if (data[h + 9] !== 0) throw new Error(`Compressed pic cels aren't supported (cel ${i})`);
+    const width = v.getUint16(h, true), height = v.getUint16(h + 2, true);
+    const at = v.getUint32(h + 24, true);
+    return {
+      width, height,
+      displaceX: v.getInt16(h + 4, true), displaceY: v.getInt16(h + 6, true),
+      skipColor: data[h + 8]!,
+      pixels: data.slice(at, at + width * height),
+      unknown16: v.getUint32(h + 16, true),
+      priority: v.getInt16(h + 36, true), x: v.getInt16(h + 38, true), y: v.getInt16(h + 40, true),
+    };
+  });
+  return { resolution: [v.getUint16(10, true), v.getUint16(12, true)], cels, palette: parseHunkPaletteFile(data, v.getUint32(6, true)) };
+}
+
+export function writePic(pic: PicFile): Uint8Array {
+  const palette = writeHunkPalette(pic.palette);
+  const headers = PIC_HEADER + CEL_HEADER * pic.cels.length;
+  const paletteAt = headers + 6;
+  const pixelsAt = paletteAt + palette.length + 6;
+  const pixelBytes = pic.cels.reduce((n, c) => n + c.width * c.height, 0);
+  const out = new Uint8Array(pixelsAt + pixelBytes);
+  const v = new DataView(out.buffer);
+  v.setUint16(0, PIC_HEADER, true);
+  out[2] = pic.cels.length;
+  v.setUint16(4, CEL_HEADER, true);
+  v.setUint32(6, paletteAt, true);
+  v.setUint16(10, pic.resolution[0], true);
+  v.setUint16(12, pic.resolution[1], true);
+  let at = pixelsAt;
+  pic.cels.forEach((c, i) => {
+    const h = PIC_HEADER + CEL_HEADER * i;
+    if (c.pixels.length !== c.width * c.height) throw new Error(`cel ${i}: ${c.pixels.length} pixels for ${c.width}x${c.height}`);
+    v.setUint16(h, c.width, true);
+    v.setUint16(h + 2, c.height, true);
+    v.setInt16(h + 4, c.displaceX, true);
+    v.setInt16(h + 6, c.displaceY, true);
+    out[h + 8] = c.skipColor;
+    v.setUint32(h + 12, c.width * c.height, true);
+    v.setUint32(h + 16, c.unknown16, true);
+    v.setUint32(h + 24, at, true);
+    v.setInt16(h + 36, c.priority, true);
+    v.setInt16(h + 38, c.x, true);
+    v.setInt16(h + 40, c.y, true);
+    out.set(c.pixels, at);
+    at += c.pixels.length;
+  });
+  out.set([0, 3], headers);
+  v.setUint32(headers + 2, palette.length, true);
+  out.set(palette, paletteAt);
+  out.set([0, 4], paletteAt + palette.length);
+  v.setUint32(paletteAt + palette.length + 2, pixelBytes, true);
+  return out;
+}
+
+/** The palette a pic installs, as the engine sees it. */
+export function hunkToPalette(p: HunkPaletteFile): Palette {
+  const pal: Palette = { rgb: new Uint8Array(768), used: new Uint8Array(256) };
+  p.rgb.forEach((c, i) => {
+    const idx = p.first + i;
+    if (idx > 255) return;
+    pal.used[idx] = p.used[i]!;
+    pal.rgb.set(c, idx * 3);
+  });
+  return pal;
+}

package/packages/sci/src/gfx/pic.d.ts

@@ -0,0 +1,27 @@
+import { type Cel } from "./cel.ts";
+import { type Palette } from "./palette.ts";
+export interface PicCel extends Cel {
+    /** Draw order against other pic layers and actors. */
+    priority: number;
+    x: number;
+    y: number;
+}
+/** A pic: a room background made of one or more positioned cel layers. */
+export interface Pic {
+    width: number;
+    height: number;
+    cels: PicCel[];
+    palette: Palette | undefined;
+}
+/**
+ * SCI32 pic layout:
+ *
+ *   +0  u16 header size (first cel header starts here)
+ *   +2  u8  cel count
+ *   +4  u16 cel header size
+ *   +6  u32 embedded palette offset
+ *   +10 u16/u16 resolution: (w, h) if the second is non-zero, else a code (0 = 320x200, 1 = 640x480, 2 = 640x400)
+ *
+ * Cel headers are the common layout plus +36 i16 priority, +38 i16 x, +40 i16 y.
+ */
+export declare function parsePic(data: Uint8Array): Pic;

package/packages/sci/src/gfx/pic.js

@@ -0,0 +1,34 @@
+import { decodeCel } from "./cel.js";
+import { parseHunkPalette } from "./palette.js";
+/**
+ * SCI32 pic layout:
+ *
+ *   +0  u16 header size (first cel header starts here)
+ *   +2  u8  cel count
+ *   +4  u16 cel header size
+ *   +6  u32 embedded palette offset
+ *   +10 u16/u16 resolution: (w, h) if the second is non-zero, else a code (0 = 320x200, 1 = 640x480, 2 = 640x400)
+ *
+ * Cel headers are the common layout plus +36 i16 priority, +38 i16 x, +40 i16 y.
+ */
+export function parsePic(data) {
+    const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const headerSize = v.getUint16(0, true);
+    const celCount = data[2];
+    const celHeaderSize = v.getUint16(4, true);
+    const paletteOffset = v.getUint32(6, true);
+    const res1 = v.getUint16(10, true);
+    const res2 = v.getUint16(12, true);
+    const presets = [[320, 200], [640, 480], [640, 400]];
+    const [width, height] = res2 ? [res1, res2] : (presets[res1] ?? [320, 200]);
+    const cels = Array.from({ length: celCount }, (_, i) => {
+        const h = headerSize + celHeaderSize * i;
+        return {
+            ...decodeCel(data, h),
+            priority: v.getInt16(h + 36, true),
+            x: v.getInt16(h + 38, true),
+            y: v.getInt16(h + 40, true),
+        };
+    });
+    return { width, height, cels, palette: paletteOffset ? parseHunkPalette(data, paletteOffset) : undefined };
+}

package/packages/sci/src/gfx/pic.ts

@@ -0,0 +1,53 @@
+import { decodeCel, type Cel } from "./cel.ts";
+import { parseHunkPalette, type Palette } from "./palette.ts";
+
+export interface PicCel extends Cel {
+  /** Draw order against other pic layers and actors. */
+  priority: number;
+  x: number;
+  y: number;
+}
+
+/** A pic: a room background made of one or more positioned cel layers. */
+export interface Pic {
+  width: number;
+  height: number;
+  cels: PicCel[];
+  palette: Palette | undefined;
+}
+
+/**
+ * SCI32 pic layout:
+ *
+ *   +0  u16 header size (first cel header starts here)
+ *   +2  u8  cel count
+ *   +4  u16 cel header size
+ *   +6  u32 embedded palette offset
+ *   +10 u16/u16 resolution: (w, h) if the second is non-zero, else a code (0 = 320x200, 1 = 640x480, 2 = 640x400)
+ *
+ * Cel headers are the common layout plus +36 i16 priority, +38 i16 x, +40 i16 y.
+ */
+export function parsePic(data: Uint8Array): Pic {
+  const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const headerSize = v.getUint16(0, true);
+  const celCount = data[2]!;
+  const celHeaderSize = v.getUint16(4, true);
+  const paletteOffset = v.getUint32(6, true);
+
+  const res1 = v.getUint16(10, true);
+  const res2 = v.getUint16(12, true);
+  const presets: [number, number][] = [[320, 200], [640, 480], [640, 400]];
+  const [width, height] = res2 ? [res1, res2] : (presets[res1] ?? [320, 200]);
+
+  const cels = Array.from({ length: celCount }, (_, i): PicCel => {
+    const h = headerSize + celHeaderSize * i;
+    return {
+      ...decodeCel(data, h),
+      priority: v.getInt16(h + 36, true),
+      x: v.getInt16(h + 38, true),
+      y: v.getInt16(h + 40, true),
+    };
+  });
+
+  return { width, height, cels, palette: paletteOffset ? parseHunkPalette(data, paletteOffset) : undefined };
+}

package/packages/sci/src/gfx/quantize.d.ts

@@ -0,0 +1,42 @@
+import type { Palette } from "./palette.ts";
+import type { PicFile } from "./pic-file.ts";
+/**
+ * Turning RGBA art into a room picture, within an SCI2 game's palette layout (measured on all 59
+ * of its pics, the base palette 999 and the hero's views):
+ *
+ *   0-111    shared character colours: identical in every room and in the hero's views
+ *   112-235  124 colours each room chooses for itself
+ *   236-255  fixed interface/system colours (253, 254 are the shadow/light remaps, 255 is
+ *            white and the pic cels' transparent colour)
+ *
+ * A new picture keeps 0-111 and 236-252 exactly as the base palette has them (it may use
+ * them in its art), picks its 124 own colours by k-means around those fixed ones, and never
+ * uses 253-255.
+ */
+export interface PicLayer {
+    width: number;
+    height: number;
+    /** RGBA; alpha < 128 is transparent (only meaningful for foreground layers). */
+    rgba: Uint8Array;
+    /** Draw order against actors: -1000 for the background; else actors with y below it are behind. */
+    priority: number;
+    x?: number;
+    y?: number;
+}
+export interface QuantizeOptions {
+    /** Floyd–Steinberg error diffusion: smoother gradients for painted art. Default true. */
+    dither?: boolean;
+    /** Lloyd iterations for the room's own colours. Default 8. */
+    iterations?: number;
+}
+export declare function buildRoomPic(layers: PicLayer[], base: Palette, options?: QuantizeOptions): PicFile;
+/** The colours a view may use: shared character colours (+ fixed ones), or a room's too. */
+export declare const SHARED_COLORS: number[];
+export declare const ROOM_COLORS: number[];
+export declare const SHADOW_COLOR = 254;
+/**
+ * Maps RGBA art onto existing palette entries (no new colours): for sprites that must live
+ * with a room's or the shared palette. Alpha below 64 is transparent (`skip`), 64-191 is a
+ * shadow (the remap colour 254, which darkens what's behind), 192+ is opaque.
+ */
+export declare function mapToPalette(rgba: Uint8Array, width: number, height: number, palette: Palette, indices: number[], skip: number, dither?: boolean): Uint8Array;

package/packages/sci/src/gfx/quantize.js

@@ -0,0 +1,199 @@
+const FREE_FIRST = 112, FREE_LAST = 235;
+const FIXED = [...Array.from({ length: 112 }, (_, i) => i), ...Array.from({ length: 17 }, (_, i) => 236 + i)]; // 0-111, 236-252
+const SKIP = 255;
+/** "Redmean": a cheap perceptual RGB distance. */
+function distance(r1, g1, b1, r2, g2, b2) {
+    const rm = (r1 + r2) / 2, dr = r1 - r2, dg = g1 - g2, db = b1 - b2;
+    return (2 + rm / 256) * dr * dr + 4 * dg * dg + (2 + (255 - rm) / 256) * db * db;
+}
+/** Deterministic pseudo-random numbers, so the same art always builds the same picture. */
+function random(seed) {
+    let s = seed >>> 0;
+    return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 0x100000000);
+}
+export function buildRoomPic(layers, base, options = {}) {
+    const { dither = true, iterations = 8 } = options;
+    if (!layers.length)
+        throw new Error("A picture needs at least a background layer");
+    // Training pixels: every opaque pixel of every layer (sampled if there are many).
+    const all = [];
+    for (const l of layers)
+        for (let i = 0; i < l.width * l.height; i++)
+            if (l.rgba[i * 4 + 3] >= 128)
+                all.push([l.rgba[i * 4], l.rgba[i * 4 + 1], l.rgba[i * 4 + 2]]);
+    const rand = random(all.length);
+    const sample = all.length > 30_000 ? Array.from({ length: 30_000 }, () => all[Math.floor(rand() * all.length)]) : all;
+    const fixed = FIXED.map((i) => [base.rgb[i * 3], base.rgb[i * 3 + 1], base.rgb[i * 3 + 2]]);
+    const nearest = (centers, r, g, b) => {
+        let best = 0, bestD = Infinity;
+        for (let c = 0; c < centers.length; c++) {
+            const k = centers[c];
+            const d = distance(r, g, b, k[0], k[1], k[2]);
+            if (d < bestD)
+                (bestD = d), (best = c);
+        }
+        return { index: best, d: bestD };
+    };
+    // k-means++ seeding of the free colours, around the fixed ones.
+    const free = [];
+    const dist = sample.map((p) => nearest(fixed, ...p).d);
+    const count = FREE_LAST - FREE_FIRST + 1;
+    while (free.length < count) {
+        const total = dist.reduce((a, b) => a + b, 0);
+        if (total === 0) {
+            free.push([0, 0, 0]); // the fixed colours already cover the art exactly
+            continue;
+        }
+        let t = rand() * total, pick = 0;
+        for (; pick < dist.length - 1 && (t -= dist[pick]) > 0; pick++)
+            ;
+        const c = sample[pick];
+        free.push([...c]);
+        for (let i = 0; i < sample.length; i++)
+            dist[i] = Math.min(dist[i], distance(...sample[i], ...c));
+    }
+    // Lloyd iterations: only the free colours move.
+    for (let it = 0; it < iterations; it++) {
+        const sums = free.map(() => [0, 0, 0, 0]);
+        const centers = [...fixed, ...free];
+        for (const p of sample) {
+            const { index } = nearest(centers, ...p);
+            if (index < fixed.length)
+                continue;
+            const s = sums[index - fixed.length];
+            s[0] += p[0];
+            s[1] += p[1];
+            s[2] += p[2];
+            s[3]++;
+        }
+        sums.forEach((s, i) => {
+            if (s[3])
+                free[i] = [Math.round(s[0] / s[3]), Math.round(s[1] / s[3]), Math.round(s[2] / s[3])];
+        });
+    }
+    const centers = [...fixed, ...free];
+    const indexOf = [...FIXED, ...Array.from({ length: count }, (_, i) => FREE_FIRST + i)];
+    const map = (layer) => {
+        const { width: w, height: h, rgba } = layer;
+        const out = new Uint8Array(w * h).fill(SKIP);
+        const err = new Float32Array(w * h * 3);
+        for (let y = 0; y < h; y++) {
+            for (let x = 0; x < w; x++) {
+                const i = y * w + x;
+                if (rgba[i * 4 + 3] < 128)
+                    continue;
+                const r = clamp(rgba[i * 4] + err[i * 3]), g = clamp(rgba[i * 4 + 1] + err[i * 3 + 1]), b = clamp(rgba[i * 4 + 2] + err[i * 3 + 2]);
+                const { index } = nearest(centers, r, g, b);
+                out[i] = indexOf[index];
+                if (!dither)
+                    continue;
+                const c = centers[index];
+                const e = [r - c[0], g - c[1], b - c[2]];
+                const spread = (dx, dy, f) => {
+                    const xx = x + dx, yy = y + dy;
+                    if (xx < 0 || xx >= w || yy >= h)
+                        return;
+                    const j = yy * w + xx;
+                    if (rgba[j * 4 + 3] < 128)
+                        return;
+                    for (let k = 0; k < 3; k++)
+                        err[j * 3 + k] += e[k] * f;
+                };
+                spread(1, 0, 7 / 16);
+                spread(-1, 1, 3 / 16);
+                spread(0, 1, 5 / 16);
+                spread(1, 1, 1 / 16);
+            }
+        }
+        return out;
+    };
+    const cels = layers.map((l) => {
+        let pixels = map(l);
+        let [x, y, w, h] = [l.x ?? 0, l.y ?? 0, l.width, l.height];
+        if (l.priority > -1000) {
+            // Foreground pieces: crop to what's opaque.
+            let x0 = w, y0 = h, x1 = -1, y1 = -1;
+            for (let yy = 0; yy < h; yy++)
+                for (let xx = 0; xx < w; xx++)
+                    if (pixels[yy * w + xx] !== SKIP)
+                        (x0 = Math.min(x0, xx)), (x1 = Math.max(x1, xx)), (y0 = Math.min(y0, yy)), (y1 = Math.max(y1, yy));
+            if (x1 < 0)
+                throw new Error(`Layer at priority ${l.priority} is fully transparent`);
+            const cw = x1 - x0 + 1, ch = y1 - y0 + 1;
+            const cropped = new Uint8Array(cw * ch);
+            for (let yy = 0; yy < ch; yy++)
+                cropped.set(pixels.subarray((y0 + yy) * w + x0, (y0 + yy) * w + x0 + cw), yy * cw);
+            [pixels, x, y, w, h] = [cropped, x + x0, y + y0, cw, ch];
+        }
+        return { width: w, height: h, displaceX: 0, displaceY: 0, skipColor: SKIP, pixels, unknown16: 2768, priority: l.priority, x, y };
+    });
+    const rgb = [];
+    for (let i = 0; i < 255; i++) {
+        const k = i >= FREE_FIRST && i <= FREE_LAST ? free[i - FREE_FIRST] : [base.rgb[i * 3], base.rgb[i * 3 + 1], base.rgb[i * 3 + 2]];
+        rgb.push(k);
+    }
+    const palette = {
+        header: Uint8Array.from([14, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0]),
+        entryPrefix: Uint8Array.from([0, 255, 255, 255, 255, 255, 255, 255, 0, 0]),
+        first: 0,
+        used: rgb.map(() => 1),
+        rgb,
+        shared: false,
+        defaultUsed: 1,
+    };
+    return { resolution: [320, 200], cels, palette };
+}
+const clamp = (v) => (v < 0 ? 0 : v > 255 ? 255 : v);
+/** The colours a view may use: shared character colours (+ fixed ones), or a room's too. */
+export const SHARED_COLORS = FIXED;
+export const ROOM_COLORS = [...FIXED, ...Array.from({ length: FREE_LAST - FREE_FIRST + 1 }, (_, i) => FREE_FIRST + i)];
+export const SHADOW_COLOR = 254;
+/**
+ * Maps RGBA art onto existing palette entries (no new colours): for sprites that must live
+ * with a room's or the shared palette. Alpha below 64 is transparent (`skip`), 64-191 is a
+ * shadow (the remap colour 254, which darkens what's behind), 192+ is opaque.
+ */
+export function mapToPalette(rgba, width, height, palette, indices, skip, dither = false) {
+    const centers = indices.map((i) => [palette.rgb[i * 3], palette.rgb[i * 3 + 1], palette.rgb[i * 3 + 2]]);
+    const out = new Uint8Array(width * height).fill(skip);
+    const err = new Float32Array(width * height * 3);
+    const cache = new Map();
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = y * width + x;
+            const a = rgba[i * 4 + 3];
+            if (a < 64)
+                continue;
+            if (a < 192) {
+                out[i] = SHADOW_COLOR;
+                continue;
+            }
+            const r = clamp(rgba[i * 4] + err[i * 3]), g = clamp(rgba[i * 4 + 1] + err[i * 3 + 1]), b = clamp(rgba[i * 4 + 2] + err[i * 3 + 2]);
+            const key = (Math.round(r) << 16) | (Math.round(g) << 8) | Math.round(b);
+            let best = cache.get(key);
+            if (best === undefined) {
+                let bestD = Infinity;
+                best = 0;
+                centers.forEach((c, k) => {
+                    const d = distance(r, g, b, c[0], c[1], c[2]);
+                    if (d < bestD)
+                        (bestD = d), (best = k);
+                });
+                cache.set(key, best);
+            }
+            out[i] = indices[best];
+            if (!dither)
+                continue;
+            const c = centers[best];
+            const e = [r - c[0], g - c[1], b - c[2]];
+            for (const [dx, dy, f] of [[1, 0, 7 / 16], [-1, 1, 3 / 16], [0, 1, 5 / 16], [1, 1, 1 / 16]]) {
+                const xx = x + dx, yy = y + dy;
+                if (xx < 0 || xx >= width || yy >= height)
+                    continue;
+                for (let k = 0; k < 3; k++)
+                    err[(yy * width + xx) * 3 + k] += e[k] * f;
+            }
+        }
+    }
+    return out;
+}