sci2-ts 0.0.0-stage → 0.2.1

package/packages/sci/src/motion/pathfinding.ts

@@ -0,0 +1,147 @@
+/**
+ * Pathfinding over SCI polygons.
+ *
+ * Rooms describe walkable space with polygons of four access types:
+ *   Total     (0): can't enter; if you start inside you may walk out.
+ *   Nearest   (1): can't enter; clicking inside walks to its nearest edge.
+ *   Barred    (2): can't enter at all.
+ *   Contained (3): the walkable area itself: you can't leave it.
+ *
+ * `findPath` snaps unreachable start/end points to the nearest reachable point, builds a
+ * visibility graph over the polygon vertices (two points are connected if the straight
+ * segment between them stays walkable) and runs Dijkstra. Boundaries count as walkable,
+ * so paths can hug walls and corners, like the original.
+ */
+export const PolygonType = { Total: 0, Nearest: 1, Barred: 2, Contained: 3 } as const;
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Polygon {
+  type: number;
+  points: Point[];
+}
+
+const EPS = 1e-9;
+
+const cross = (o: Point, a: Point, b: Point) => (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+
+function onSegment(p: Point, a: Point, b: Point): boolean {
+  if (Math.abs(cross(a, b, p)) > EPS) return false;
+  return p.x >= Math.min(a.x, b.x) - EPS && p.x <= Math.max(a.x, b.x) + EPS && p.y >= Math.min(a.y, b.y) - EPS && p.y <= Math.max(a.y, b.y) + EPS;
+}
+
+function edges(poly: Polygon): [Point, Point][] {
+  return poly.points.map((p, i) => [p, poly.points[(i + 1) % poly.points.length]!]);
+}
+
+export type Containment = "inside" | "outside" | "edge";
+
+export function contains(poly: Polygon, p: Point): Containment {
+  let inside = false;
+  for (const [a, b] of edges(poly)) {
+    if (onSegment(p, a, b)) return "edge";
+    if (a.y > p.y !== b.y > p.y && p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
+  }
+  return inside ? "inside" : "outside";
+}
+
+/** Walkable = inside (or on) every contained polygon and not strictly inside any obstacle. */
+export function walkable(polys: Polygon[], p: Point): boolean {
+  for (const poly of polys) {
+    const c = contains(poly, p);
+    if (poly.type === PolygonType.Contained ? c === "outside" : c === "inside") return false;
+  }
+  return true;
+}
+
+/** True if segments ab and cd cross at a point interior to both. */
+function properlyIntersect(a: Point, b: Point, c: Point, d: Point): boolean {
+  const d1 = cross(c, d, a), d2 = cross(c, d, b), d3 = cross(a, b, c), d4 = cross(a, b, d);
+  return ((d1 > EPS && d2 < -EPS) || (d1 < -EPS && d2 > EPS)) && ((d3 > EPS && d4 < -EPS) || (d3 < -EPS && d4 > EPS));
+}
+
+/** A segment is clear if it crosses no polygon edge and its interior stays walkable. */
+function clear(polys: Polygon[], a: Point, b: Point): boolean {
+  for (const poly of polys) for (const [c, d] of edges(poly)) if (properlyIntersect(a, b, c, d)) return false;
+  // Crossing no edges can still mean running through a polygon's interior (e.g. a diagonal
+  // between two of its vertices), so sample along the segment.
+  const steps = Math.max(2, Math.ceil(Math.hypot(b.x - a.x, b.y - a.y) / 4));
+  for (let i = 1; i < steps; i++) {
+    const t = i / steps;
+    if (!walkable(polys, { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t })) return false;
+  }
+  return true;
+}
+
+function nearestOnSegment(p: Point, a: Point, b: Point): Point {
+  const dx = b.x - a.x, dy = b.y - a.y;
+  const len2 = dx * dx + dy * dy;
+  const t = len2 ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / len2)) : 0;
+  return { x: a.x + t * dx, y: a.y + t * dy };
+}
+
+/** Nearest walkable point to `p`, found on polygon edges (rounded to whole pixels). */
+export function nearestWalkable(polys: Polygon[], p: Point): Point {
+  if (walkable(polys, p)) return p;
+  let best: Point | undefined;
+  let bestDist = Infinity;
+  for (const poly of polys) {
+    for (const [a, b] of edges(poly)) {
+      const q = nearestOnSegment(p, a, b);
+      // Try the point and its integer neighbours; SCI coordinates are whole pixels.
+      for (const cand of [{ x: Math.round(q.x), y: Math.round(q.y) }, { x: Math.floor(q.x), y: Math.floor(q.y) }, { x: Math.ceil(q.x), y: Math.ceil(q.y) }, q]) {
+        const d = Math.hypot(cand.x - p.x, cand.y - p.y);
+        if (d < bestDist && walkable(polys, cand)) {
+          best = cand;
+          bestDist = d;
+        }
+      }
+    }
+  }
+  return best ?? p;
+}
+
+/**
+ * Shortest walkable path from `start` to `end`, including both endpoints. If the end is
+ * unreachable it's moved to the nearest reachable point; if the start is inside an
+ * obstacle (e.g. pushed into one), the path first steps out of it.
+ */
+export function findPath(start: Point, end: Point, polys: Polygon[]): Point[] {
+  // Obstacles that contain the start are ignored, so an actor stuck in one can walk out.
+  const active = polys.filter((p) => p.type === PolygonType.Contained || contains(p, start) !== "inside");
+  const from = nearestWalkable(active, start);
+  const to = nearestWalkable(active, end);
+  const prefix = from.x !== start.x || from.y !== start.y ? [start] : [];
+
+  if (clear(active, from, to)) return [...prefix, from, to];
+
+  const nodes: Point[] = [from, to];
+  for (const poly of active) for (const p of poly.points) if (walkable(active, p)) nodes.push(p);
+
+  // Dijkstra over the visibility graph (edges evaluated lazily; rooms have few vertices).
+  const dist = new Array<number>(nodes.length).fill(Infinity);
+  const prev = new Array<number>(nodes.length).fill(-1);
+  const done = new Array<boolean>(nodes.length).fill(false);
+  dist[0] = 0;
+  for (;;) {
+    let u = -1;
+    for (let i = 0; i < nodes.length; i++) if (!done[i] && dist[i]! < Infinity && (u === -1 || dist[i]! < dist[u]!)) u = i;
+    if (u === -1 || u === 1) break;
+    done[u] = true;
+    for (let v = 0; v < nodes.length; v++) {
+      if (done[v]) continue;
+      const w = Math.hypot(nodes[v]!.x - nodes[u]!.x, nodes[v]!.y - nodes[u]!.y);
+      if (dist[u]! + w < dist[v]! && clear(active, nodes[u]!, nodes[v]!)) {
+        dist[v] = dist[u]! + w;
+        prev[v] = u;
+      }
+    }
+  }
+  if (prev[1] === -1) return [...prefix, from]; // unreachable: stay put
+  const path: Point[] = [];
+  for (let i = 1; i !== -1; i = prev[i]!) path.unshift(nodes[i]!);
+  return [...prefix, ...path];
+}

package/packages/sci/src/resource/archive.d.ts

@@ -0,0 +1,16 @@
+import { type ResourceId } from "./types.ts";
+export interface ResourceData extends ResourceId {
+    data: Uint8Array;
+}
+/**
+ * RESOURCE.MAP and RESOURCE.000 for a set of resources: the files an interpreter opens a game
+ * by. Resources are stored uncompressed (method 0), in type then number order.
+ *
+ *   volume entry: u8 type, u16 number, u32 packed size, u32 unpacked size, u16 method, data
+ *   map: { u8 type, u16 table offset } per type, then 0xFF with the end offset;
+ *        per type, { u16 number, u32 volume offset } per resource (see parseResourceMap)
+ */
+export declare function writeResourceArchive(resources: readonly ResourceData[]): {
+    map: Uint8Array;
+    volume: Uint8Array;
+};

package/packages/sci/src/resource/archive.js

@@ -0,0 +1,51 @@
+import { resourceKey } from "./types.js";
+/**
+ * RESOURCE.MAP and RESOURCE.000 for a set of resources: the files an interpreter opens a game
+ * by. Resources are stored uncompressed (method 0), in type then number order.
+ *
+ *   volume entry: u8 type, u16 number, u32 packed size, u32 unpacked size, u16 method, data
+ *   map: { u8 type, u16 table offset } per type, then 0xFF with the end offset;
+ *        per type, { u16 number, u32 volume offset } per resource (see parseResourceMap)
+ */
+export function writeResourceArchive(resources) {
+    const sorted = [...resources].sort((a, b) => a.type - b.type || a.number - b.number);
+    for (let i = 1; i < sorted.length; i++) {
+        if (sorted[i].type === sorted[i - 1].type && sorted[i].number === sorted[i - 1].number) {
+            throw new Error(`resource ${resourceKey(sorted[i])} is there twice`);
+        }
+    }
+    const volume = new Uint8Array(sorted.reduce((n, r) => n + 13 + r.data.length, 0));
+    const vv = new DataView(volume.buffer);
+    const offsets = [];
+    let at = 0;
+    for (const r of sorted) {
+        offsets.push(at);
+        volume[at] = r.type;
+        vv.setUint16(at + 1, r.number, true);
+        vv.setUint32(at + 3, r.data.length, true);
+        vv.setUint32(at + 7, r.data.length, true);
+        vv.setUint16(at + 11, 0, true);
+        volume.set(r.data, at + 13);
+        at += 13 + r.data.length;
+    }
+    const types = [...new Set(sorted.map((r) => r.type))];
+    const map = new Uint8Array((types.length + 1) * 3 + sorted.length * 6);
+    if (map.length > 0xffff)
+        throw new Error(`too many resources for one map (${sorted.length})`);
+    const mv = new DataView(map.buffer);
+    let table = (types.length + 1) * 3;
+    types.forEach((type, i) => {
+        map[i * 3] = type;
+        mv.setUint16(i * 3 + 1, table, true);
+        sorted.forEach((r, k) => {
+            if (r.type !== type)
+                return;
+            mv.setUint16(table, r.number, true);
+            mv.setUint32(table + 2, offsets[k], true);
+            table += 6;
+        });
+    });
+    map[types.length * 3] = 0xff;
+    mv.setUint16(types.length * 3 + 1, table, true);
+    return { map, volume };
+}

package/packages/sci/src/resource/archive.ts

@@ -0,0 +1,56 @@
+import { resourceKey, type ResourceId } from "./types.ts";
+
+export interface ResourceData extends ResourceId {
+  data: Uint8Array;
+}
+
+/**
+ * RESOURCE.MAP and RESOURCE.000 for a set of resources: the files an interpreter opens a game
+ * by. Resources are stored uncompressed (method 0), in type then number order.
+ *
+ *   volume entry: u8 type, u16 number, u32 packed size, u32 unpacked size, u16 method, data
+ *   map: { u8 type, u16 table offset } per type, then 0xFF with the end offset;
+ *        per type, { u16 number, u32 volume offset } per resource (see parseResourceMap)
+ */
+export function writeResourceArchive(resources: readonly ResourceData[]): { map: Uint8Array; volume: Uint8Array } {
+  const sorted = [...resources].sort((a, b) => a.type - b.type || a.number - b.number);
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i]!.type === sorted[i - 1]!.type && sorted[i]!.number === sorted[i - 1]!.number) {
+      throw new Error(`resource ${resourceKey(sorted[i]!)} is there twice`);
+    }
+  }
+
+  const volume = new Uint8Array(sorted.reduce((n, r) => n + 13 + r.data.length, 0));
+  const vv = new DataView(volume.buffer);
+  const offsets: number[] = [];
+  let at = 0;
+  for (const r of sorted) {
+    offsets.push(at);
+    volume[at] = r.type;
+    vv.setUint16(at + 1, r.number, true);
+    vv.setUint32(at + 3, r.data.length, true);
+    vv.setUint32(at + 7, r.data.length, true);
+    vv.setUint16(at + 11, 0, true);
+    volume.set(r.data, at + 13);
+    at += 13 + r.data.length;
+  }
+
+  const types = [...new Set(sorted.map((r) => r.type))];
+  const map = new Uint8Array((types.length + 1) * 3 + sorted.length * 6);
+  if (map.length > 0xffff) throw new Error(`too many resources for one map (${sorted.length})`);
+  const mv = new DataView(map.buffer);
+  let table = (types.length + 1) * 3;
+  types.forEach((type, i) => {
+    map[i * 3] = type;
+    mv.setUint16(i * 3 + 1, table, true);
+    sorted.forEach((r, k) => {
+      if (r.type !== type) return;
+      mv.setUint16(table, r.number, true);
+      mv.setUint32(table + 2, offsets[k]!, true);
+      table += 6;
+    });
+  });
+  map[types.length * 3] = 0xff;
+  mv.setUint16(types.length * 3 + 1, table, true);
+  return { map, volume };
+}

package/packages/sci/src/resource/lzs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * STACpack / LZS decompression (compression method 32 in SCI2 volumes).
+ *
+ * Bitstream is read MSB-first. Tokens:
+ *   0 bbbbbbbb              literal byte
+ *   1 1 ooooooo  len        back-reference, 7-bit offset (offset 0 = end marker)
+ *   1 0 ooooooooooo len     back-reference, 11-bit offset
+ *
+ * Length codes: 00=2 01=3 10=4 | 1100=5 1101=6 1110=7 | 1111 then nibbles
+ * added to 8 until a nibble other than 0xF.
+ */
+export declare function decompressLzs(src: Uint8Array, unpackedSize: number): Uint8Array;

package/packages/sci/src/resource/lzs.js

@@ -0,0 +1,64 @@
+/**
+ * STACpack / LZS decompression (compression method 32 in SCI2 volumes).
+ *
+ * Bitstream is read MSB-first. Tokens:
+ *   0 bbbbbbbb              literal byte
+ *   1 1 ooooooo  len        back-reference, 7-bit offset (offset 0 = end marker)
+ *   1 0 ooooooooooo len     back-reference, 11-bit offset
+ *
+ * Length codes: 00=2 01=3 10=4 | 1100=5 1101=6 1110=7 | 1111 then nibbles
+ * added to 8 until a nibble other than 0xF.
+ */
+export function decompressLzs(src, unpackedSize) {
+    const out = new Uint8Array(unpackedSize);
+    let written = 0;
+    let bytePos = 0;
+    let bitBuf = 0;
+    let bitCount = 0;
+    const bits = (n) => {
+        while (bitCount < n) {
+            bitBuf = (bitBuf << 8) | (src[bytePos++] ?? 0);
+            bitCount += 8;
+        }
+        bitCount -= n;
+        return (bitBuf >>> bitCount) & ((1 << n) - 1);
+    };
+    const length = () => {
+        switch (bits(2)) {
+            case 0: return 2;
+            case 1: return 3;
+            case 2: return 4;
+        }
+        switch (bits(2)) {
+            case 0: return 5;
+            case 1: return 6;
+            case 2: return 7;
+        }
+        let len = 8;
+        let nibble;
+        do {
+            nibble = bits(4);
+            len += nibble;
+        } while (nibble === 0xf);
+        return len;
+    };
+    while (written < unpackedSize) {
+        if (bits(1) === 0) {
+            out[written++] = bits(8);
+            continue;
+        }
+        const offset = bits(1) ? bits(7) : bits(11);
+        if (offset === 0)
+            break;
+        let from = written - offset;
+        if (from < 0)
+            throw new Error(`LZS: back-reference before start (offset ${offset} at ${written})`);
+        for (let n = length(); n > 0 && written < unpackedSize; n--) {
+            out[written++] = out[from++];
+        }
+    }
+    if (written !== unpackedSize) {
+        throw new Error(`LZS: produced ${written} bytes, expected ${unpackedSize}`);
+    }
+    return out;
+}

package/packages/sci/src/resource/lzs.ts

@@ -0,0 +1,66 @@
+/**
+ * STACpack / LZS decompression (compression method 32 in SCI2 volumes).
+ *
+ * Bitstream is read MSB-first. Tokens:
+ *   0 bbbbbbbb              literal byte
+ *   1 1 ooooooo  len        back-reference, 7-bit offset (offset 0 = end marker)
+ *   1 0 ooooooooooo len     back-reference, 11-bit offset
+ *
+ * Length codes: 00=2 01=3 10=4 | 1100=5 1101=6 1110=7 | 1111 then nibbles
+ * added to 8 until a nibble other than 0xF.
+ */
+export function decompressLzs(src: Uint8Array, unpackedSize: number): Uint8Array {
+  const out = new Uint8Array(unpackedSize);
+  let written = 0;
+  let bytePos = 0;
+  let bitBuf = 0;
+  let bitCount = 0;
+
+  const bits = (n: number): number => {
+    while (bitCount < n) {
+      bitBuf = (bitBuf << 8) | (src[bytePos++] ?? 0);
+      bitCount += 8;
+    }
+    bitCount -= n;
+    return (bitBuf >>> bitCount) & ((1 << n) - 1);
+  };
+
+  const length = (): number => {
+    switch (bits(2)) {
+      case 0: return 2;
+      case 1: return 3;
+      case 2: return 4;
+    }
+    switch (bits(2)) {
+      case 0: return 5;
+      case 1: return 6;
+      case 2: return 7;
+    }
+    let len = 8;
+    let nibble: number;
+    do {
+      nibble = bits(4);
+      len += nibble;
+    } while (nibble === 0xf);
+    return len;
+  };
+
+  while (written < unpackedSize) {
+    if (bits(1) === 0) {
+      out[written++] = bits(8);
+      continue;
+    }
+    const offset = bits(1) ? bits(7) : bits(11);
+    if (offset === 0) break;
+    let from = written - offset;
+    if (from < 0) throw new Error(`LZS: back-reference before start (offset ${offset} at ${written})`);
+    for (let n = length(); n > 0 && written < unpackedSize; n--) {
+      out[written++] = out[from++]!;
+    }
+  }
+
+  if (written !== unpackedSize) {
+    throw new Error(`LZS: produced ${written} bytes, expected ${unpackedSize}`);
+  }
+  return out;
+}

package/packages/sci/src/resource/manager.d.ts

@@ -0,0 +1,45 @@
+import { type ResourceId, type ResourceType } from "./types.ts";
+/** Where game files come from: Node fs in tools, fetch/File API in the browser. */
+export interface FileSource {
+    read(path: string): Promise<Uint8Array | undefined>;
+    /** Byte range read, so large volumes needn't be loaded whole. */
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
+    list(dir: string): Promise<string[]>;
+}
+export interface ResourceInfo extends ResourceId {
+    source: "volume" | "patch" | "memory";
+    /** Volume: header offset. Patch: file path. */
+    location: number | string;
+}
+export interface Resource extends ResourceId {
+    data: Uint8Array;
+}
+export declare class ResourceManager {
+    private readonly files;
+    private readonly index;
+    private volume;
+    private readonly patches;
+    private readonly extras;
+    /** Resources replaced at run time (an editor's latest build), by key. */
+    private readonly memory;
+    private constructor();
+    /** Indexes RESOURCE.MAP, then lets loose patch files (game dir, then PATCHES/) override it. */
+    static open(files: FileSource, patchDirs?: string[]): Promise<ResourceManager>;
+    list(type?: ResourceType): ResourceInfo[];
+    has(id: ResourceId): boolean;
+    /**
+     * Replaces (or adds) a resource with already decoded data, until the page goes away: a
+     * live editor's rebuilt room. Whatever parsed the old one must forget it (replaceResources).
+     */
+    override(id: ResourceId, data: Uint8Array): void;
+    load(id: ResourceId): Promise<Resource>;
+    /**
+     * Reads the whole volume and every patch into memory so `loadSync` works. The VM needs
+     * this: bytecode can load a script or look up a view in the middle of an instruction.
+     */
+    preload(extraFiles?: string[]): Promise<void>;
+    loadSync(id: ResourceId): Resource;
+    /** A whole game file read by `preload` (e.g. RESOURCE.SFX), if present. */
+    file(name: string): Uint8Array | undefined;
+    private info;
+}

package/packages/sci/src/resource/manager.js

@@ -0,0 +1,158 @@
+import { decompressLzs } from "./lzs.js";
+import { parseResourceMap } from "./map.js";
+import { patchExtensions, resourceKey } from "./types.js";
+const VOLUME = "RESOURCE.000";
+const VOLUME_HEADER_SIZE = 13; // type u8, number u16, packed u32, unpacked u32, method u16
+const Compression = { None: 0, Lzs: 32 };
+/** Extra-header sizes for patch size bytes with bit 7 set (per ScummVM). */
+const patchHeaderCodes = { 0: 24, 1: 2, 4: 8 };
+export class ResourceManager {
+    files;
+    index = new Map();
+    volume;
+    patches = new Map();
+    extras = new Map();
+    /** Resources replaced at run time (an editor's latest build), by key. */
+    memory = new Map();
+    constructor(files) {
+        this.files = files;
+    }
+    /** Indexes RESOURCE.MAP, then lets loose patch files (game dir, then PATCHES/) override it. */
+    static async open(files, patchDirs = ["", "PATCHES"]) {
+        const rm = new ResourceManager(files);
+        const map = await files.read("RESOURCE.MAP");
+        if (!map)
+            throw new Error("RESOURCE.MAP not found");
+        for (const e of parseResourceMap(map)) {
+            rm.index.set(resourceKey(e), { type: e.type, number: e.number, source: "volume", location: e.offset });
+        }
+        for (const dir of patchDirs) {
+            for (const name of await files.list(dir)) {
+                const m = /^(\d+)\.([a-z0-9]+)$/i.exec(name);
+                const type = m && patchExtensions[m[2].toLowerCase()];
+                if (type === undefined || type === null)
+                    continue;
+                const id = { type, number: Number(m[1]) };
+                rm.index.set(resourceKey(id), { ...id, source: "patch", location: dir ? `${dir}/${name}` : name });
+            }
+        }
+        return rm;
+    }
+    list(type) {
+        const all = [...this.index.values()];
+        return (type === undefined ? all : all.filter((r) => r.type === type)).sort((a, b) => a.type - b.type || a.number - b.number);
+    }
+    has(id) {
+        return this.index.has(resourceKey(id));
+    }
+    /**
+     * Replaces (or adds) a resource with already decoded data, until the page goes away: a
+     * live editor's rebuilt room. Whatever parsed the old one must forget it (replaceResources).
+     */
+    override(id, data) {
+        const key = resourceKey(id);
+        this.memory.set(key, data);
+        this.index.set(key, { type: id.type, number: id.number, source: "memory", location: key });
+    }
+    async load(id) {
+        const info = this.info(id);
+        let data;
+        if (info.source === "memory") {
+            data = this.memory.get(info.location);
+        }
+        else if (info.source === "patch") {
+            const file = await this.files.read(info.location);
+            if (!file)
+                throw new Error(`Patch file ${info.location} disappeared`);
+            data = decodePatch(info, file);
+        }
+        else if (this.volume) {
+            data = decodeVolumeEntry(info, this.volume, info.location);
+        }
+        else {
+            const offset = info.location;
+            const header = await this.files.readRange(VOLUME, offset, VOLUME_HEADER_SIZE);
+            const packed = new DataView(header.buffer, header.byteOffset).getUint32(3, true);
+            const entry = new Uint8Array(VOLUME_HEADER_SIZE + packed);
+            entry.set(header);
+            entry.set(await this.files.readRange(VOLUME, offset + VOLUME_HEADER_SIZE, packed), VOLUME_HEADER_SIZE);
+            data = decodeVolumeEntry(info, entry, 0);
+        }
+        return { type: info.type, number: info.number, data };
+    }
+    /**
+     * Reads the whole volume and every patch into memory so `loadSync` works. The VM needs
+     * this: bytecode can load a script or look up a view in the middle of an instruction.
+     */
+    async preload(extraFiles = ["RESOURCE.SFX"]) {
+        this.volume ??= await this.files.read(VOLUME);
+        for (const name of extraFiles) {
+            const data = this.extras.has(name) ? undefined : await this.files.read(name);
+            if (data)
+                this.extras.set(name, data);
+        }
+        for (const info of this.index.values()) {
+            if (info.source === "patch" && !this.patches.has(info.location)) {
+                const file = await this.files.read(info.location);
+                if (file)
+                    this.patches.set(info.location, file);
+            }
+        }
+    }
+    loadSync(id) {
+        const info = this.info(id);
+        if (!this.volume)
+            throw new Error("loadSync before preload()");
+        const data = info.source === "memory"
+            ? this.memory.get(info.location)
+            : info.source === "patch"
+                ? decodePatch(info, this.patches.get(info.location))
+                : decodeVolumeEntry(info, this.volume, info.location);
+        return { type: info.type, number: info.number, data };
+    }
+    /** A whole game file read by `preload` (e.g. RESOURCE.SFX), if present. */
+    file(name) {
+        return this.extras.get(name);
+    }
+    info(id) {
+        const info = this.index.get(resourceKey(id));
+        if (!info)
+            throw new Error(`Resource ${resourceKey(id)} not found`);
+        return info;
+    }
+}
+/** Decodes the volume entry at `offset` in `bytes`. */
+function decodeVolumeEntry(info, bytes, offset) {
+    const h = new DataView(bytes.buffer, bytes.byteOffset + offset, VOLUME_HEADER_SIZE);
+    const type = h.getUint8(0) & 0x7f;
+    const number = h.getUint16(1, true);
+    const packed = h.getUint32(3, true);
+    const unpacked = h.getUint32(7, true);
+    const method = h.getUint16(11, true);
+    if (type !== info.type || number !== info.number) {
+        throw new Error(`Volume header mismatch at ${info.location}: got ${type}:${number}, expected ${resourceKey(info)}`);
+    }
+    const body = bytes.subarray(offset + VOLUME_HEADER_SIZE, offset + VOLUME_HEADER_SIZE + packed);
+    switch (method) {
+        case Compression.None: return body;
+        case Compression.Lzs: return decompressLzs(body, unpacked);
+        default: throw new Error(`Unsupported compression method ${method} for ${resourceKey(info)}`);
+    }
+}
+/**
+ * Patch files: u8 type, u8 extra-header size, [extra header], data.
+ * SCI32 view/pic patches set bit 7 of the size byte and store a code instead.
+ */
+function decodePatch(info, file) {
+    const type = file[0] & 0x7f;
+    if (type !== info.type)
+        throw new Error(`Patch ${info.location} has type ${type}, expected ${info.type}`);
+    let extra = file[1];
+    if (extra & 0x80) {
+        const size = patchHeaderCodes[extra & 0x7f];
+        if (size === undefined)
+            throw new Error(`Patch ${info.location}: unknown header code ${extra & 0x7f}`);
+        extra = size;
+    }
+    return file.subarray(2 + extra);
+}