sci2-ts 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,184 @@
+import { decompressLzs } from "./lzs.ts";
+import { parseResourceMap } from "./map.ts";
+import { patchExtensions, resourceKey, 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;
+}
+
+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 } as const;
+
+/** Extra-header sizes for patch size bytes with bit 7 set (per ScummVM). */
+const patchHeaderCodes: Record<number, number> = { 0: 24, 1: 2, 4: 8 };
+
+export class ResourceManager {
+  private readonly index = new Map<string, ResourceInfo>();
+  private volume: Uint8Array | undefined;
+  private readonly patches = new Map<string, Uint8Array>();
+  private readonly extras = new Map<string, Uint8Array>();
+  /** Resources replaced at run time (an editor's latest build), by key. */
+  private readonly memory = new Map<string, Uint8Array>();
+
+  private constructor(private readonly files: FileSource) {}
+
+  /** Indexes RESOURCE.MAP, then lets loose patch files (game dir, then PATCHES/) override it. */
+  static async open(files: FileSource, patchDirs = ["", "PATCHES"]): Promise<ResourceManager> {
+    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?: ResourceType): ResourceInfo[] {
+    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: ResourceId): boolean {
+    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: ResourceId, data: Uint8Array): void {
+    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: ResourceId): Promise<Resource> {
+    const info = this.info(id);
+    let data: Uint8Array;
+    if (info.source === "memory") {
+      data = this.memory.get(info.location as string)!;
+    } else if (info.source === "patch") {
+      const file = await this.files.read(info.location as string);
+      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 as number);
+    } else {
+      const offset = info.location as number;
+      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: string[] = ["RESOURCE.SFX"]): Promise<void> {
+    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 as string)) {
+        const file = await this.files.read(info.location as string);
+        if (file) this.patches.set(info.location as string, file);
+      }
+    }
+  }
+
+  loadSync(id: ResourceId): Resource {
+    const info = this.info(id);
+    if (!this.volume) throw new Error("loadSync before preload()");
+    const data =
+      info.source === "memory"
+        ? this.memory.get(info.location as string)!
+        : info.source === "patch"
+          ? decodePatch(info, this.patches.get(info.location as string)!)
+          : decodeVolumeEntry(info, this.volume, info.location as number);
+    return { type: info.type, number: info.number, data };
+  }
+
+  /** A whole game file read by `preload` (e.g. RESOURCE.SFX), if present. */
+  file(name: string): Uint8Array | undefined {
+    return this.extras.get(name);
+  }
+
+  private info(id: ResourceId): ResourceInfo {
+    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: ResourceInfo, bytes: Uint8Array, offset: number): Uint8Array {
+  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: ResourceInfo, file: Uint8Array): Uint8Array {
+  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);
+}

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

@@ -0,0 +1,18 @@
+import type { ResourceType } from "./types.ts";
+export interface MapEntry {
+    type: ResourceType;
+    number: number;
+    /** Byte offset of the resource header inside the volume (RESOURCE.000). */
+    offset: number;
+}
+/**
+ * Parses an SCI2 RESOURCE.MAP.
+ *
+ * Layout:
+ *   header: repeated { type: u8, tableOffset: u16 } terminated by type 0xFF
+ *           (the terminator's offset is the end of the last table)
+ *   tables: per type, repeated { number: u16, volumeOffset: u32 } (6 bytes)
+ *
+ * SCI1.1 used 5-byte entries (u24 offset, shifted).
+ */
+export declare function parseResourceMap(data: Uint8Array): MapEntry[];

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

@@ -0,0 +1,34 @@
+/**
+ * Parses an SCI2 RESOURCE.MAP.
+ *
+ * Layout:
+ *   header: repeated { type: u8, tableOffset: u16 } terminated by type 0xFF
+ *           (the terminator's offset is the end of the last table)
+ *   tables: per type, repeated { number: u16, volumeOffset: u32 } (6 bytes)
+ *
+ * SCI1.1 used 5-byte entries (u24 offset, shifted).
+ */
+export function parseResourceMap(data) {
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const tables = [];
+    for (let pos = 0;; pos += 3) {
+        const type = view.getUint8(pos);
+        const offset = view.getUint16(pos + 1, true);
+        tables.push({ type, offset });
+        if (type === 0xff)
+            break;
+    }
+    const entries = [];
+    for (let i = 0; i < tables.length - 1; i++) {
+        const { type, offset: start } = tables[i];
+        const end = tables[i + 1].offset;
+        for (let pos = start; pos < end; pos += 6) {
+            entries.push({
+                type: type,
+                number: view.getUint16(pos, true),
+                offset: view.getUint32(pos + 2, true),
+            });
+        }
+    }
+    return entries;
+}

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

@@ -0,0 +1,44 @@
+import type { ResourceType } from "./types.ts";
+
+export interface MapEntry {
+  type: ResourceType;
+  number: number;
+  /** Byte offset of the resource header inside the volume (RESOURCE.000). */
+  offset: number;
+}
+
+/**
+ * Parses an SCI2 RESOURCE.MAP.
+ *
+ * Layout:
+ *   header: repeated { type: u8, tableOffset: u16 } terminated by type 0xFF
+ *           (the terminator's offset is the end of the last table)
+ *   tables: per type, repeated { number: u16, volumeOffset: u32 } (6 bytes)
+ *
+ * SCI1.1 used 5-byte entries (u24 offset, shifted).
+ */
+export function parseResourceMap(data: Uint8Array): MapEntry[] {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const tables: { type: number; offset: number }[] = [];
+
+  for (let pos = 0; ; pos += 3) {
+    const type = view.getUint8(pos);
+    const offset = view.getUint16(pos + 1, true);
+    tables.push({ type, offset });
+    if (type === 0xff) break;
+  }
+
+  const entries: MapEntry[] = [];
+  for (let i = 0; i < tables.length - 1; i++) {
+    const { type, offset: start } = tables[i]!;
+    const end = tables[i + 1]!.offset;
+    for (let pos = start; pos < end; pos += 6) {
+      entries.push({
+        type: type as ResourceType,
+        number: view.getUint16(pos, true),
+        offset: view.getUint32(pos + 2, true),
+      });
+    }
+  }
+  return entries;
+}

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

@@ -0,0 +1,37 @@
+/** Resource type ids as stored in RESOURCE.MAP and volume headers (SCI1.1 / SCI2 numbering). */
+export declare const ResourceType: {
+    readonly View: 0;
+    readonly Pic: 1;
+    readonly Script: 2;
+    readonly Text: 3;
+    readonly Sound: 4;
+    readonly Memory: 5;
+    readonly Vocab: 6;
+    readonly Font: 7;
+    readonly Cursor: 8;
+    readonly Patch: 9;
+    readonly Bitmap: 10;
+    readonly Palette: 11;
+    readonly CdAudio: 12;
+    readonly Audio: 13;
+    readonly Sync: 14;
+    readonly Message: 15;
+    readonly Map: 16;
+    readonly Heap: 17;
+    readonly Audio36: 18;
+    readonly Sync36: 19;
+    readonly Translation: 20;
+    readonly Robot: 21;
+    readonly Vmd: 22;
+    readonly Chunk: 23;
+    readonly Animation: 24;
+};
+export type ResourceType = (typeof ResourceType)[keyof typeof ResourceType];
+export declare const resourceTypeName: Record<number, string>;
+/** Loose files in the game dir or PATCHES/ override volume resources: `<number>.<ext>`. */
+export declare const patchExtensions: Record<string, ResourceType>;
+export interface ResourceId {
+    type: ResourceType;
+    number: number;
+}
+export declare const resourceKey: ({ type, number }: ResourceId) => string;

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

@@ -0,0 +1,45 @@
+/** Resource type ids as stored in RESOURCE.MAP and volume headers (SCI1.1 / SCI2 numbering). */
+export const ResourceType = {
+    View: 0x00,
+    Pic: 0x01,
+    Script: 0x02,
+    Text: 0x03,
+    Sound: 0x04,
+    Memory: 0x05,
+    Vocab: 0x06,
+    Font: 0x07,
+    Cursor: 0x08,
+    Patch: 0x09,
+    Bitmap: 0x0a,
+    Palette: 0x0b,
+    CdAudio: 0x0c,
+    Audio: 0x0d,
+    Sync: 0x0e,
+    Message: 0x0f,
+    Map: 0x10,
+    Heap: 0x11,
+    Audio36: 0x12,
+    Sync36: 0x13,
+    Translation: 0x14,
+    Robot: 0x15,
+    Vmd: 0x16,
+    Chunk: 0x17,
+    Animation: 0x18,
+};
+export const resourceTypeName = Object.fromEntries(Object.entries(ResourceType).map(([name, id]) => [id, name.toLowerCase()]));
+/** Loose files in the game dir or PATCHES/ override volume resources: `<number>.<ext>`. */
+export const patchExtensions = {
+    v56: ResourceType.View,
+    p56: ResourceType.Pic,
+    scr: ResourceType.Script,
+    hep: ResourceType.Heap,
+    snd: ResourceType.Sound,
+    voc: ResourceType.Vocab,
+    fon: ResourceType.Font,
+    cur: ResourceType.Cursor,
+    pat: ResourceType.Patch,
+    pal: ResourceType.Palette,
+    msg: ResourceType.Message,
+    map: ResourceType.Map,
+};
+export const resourceKey = ({ type, number }) => `${type}:${number}`;

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

@@ -0,0 +1,57 @@
+/** Resource type ids as stored in RESOURCE.MAP and volume headers (SCI1.1 / SCI2 numbering). */
+export const ResourceType = {
+  View: 0x00,
+  Pic: 0x01,
+  Script: 0x02,
+  Text: 0x03,
+  Sound: 0x04,
+  Memory: 0x05,
+  Vocab: 0x06,
+  Font: 0x07,
+  Cursor: 0x08,
+  Patch: 0x09,
+  Bitmap: 0x0a,
+  Palette: 0x0b,
+  CdAudio: 0x0c,
+  Audio: 0x0d,
+  Sync: 0x0e,
+  Message: 0x0f,
+  Map: 0x10,
+  Heap: 0x11,
+  Audio36: 0x12,
+  Sync36: 0x13,
+  Translation: 0x14,
+  Robot: 0x15,
+  Vmd: 0x16,
+  Chunk: 0x17,
+  Animation: 0x18,
+} as const;
+
+export type ResourceType = (typeof ResourceType)[keyof typeof ResourceType];
+
+export const resourceTypeName: Record<number, string> = Object.fromEntries(
+  Object.entries(ResourceType).map(([name, id]) => [id, name.toLowerCase()]),
+);
+
+/** Loose files in the game dir or PATCHES/ override volume resources: `<number>.<ext>`. */
+export const patchExtensions: Record<string, ResourceType> = {
+  v56: ResourceType.View,
+  p56: ResourceType.Pic,
+  scr: ResourceType.Script,
+  hep: ResourceType.Heap,
+  snd: ResourceType.Sound,
+  voc: ResourceType.Vocab,
+  fon: ResourceType.Font,
+  cur: ResourceType.Cursor,
+  pat: ResourceType.Patch,
+  pal: ResourceType.Palette,
+  msg: ResourceType.Message,
+  map: ResourceType.Map,
+};
+
+export interface ResourceId {
+  type: ResourceType;
+  number: number;
+}
+
+export const resourceKey = ({ type, number }: ResourceId): string => `${type}:${number}`;

package/packages/sci/src/script/assembly.d.ts

@@ -0,0 +1,67 @@
+import { type DisasmContext } from "./disasm.ts";
+import { type Script } from "./script.ts";
+/**
+ * SCI2 assembly: a text form of a script + heap pair that assembles back to the same
+ * bytes, and that you can write by hand.
+ *
+ *   script 710
+ *   locals 0 0 5                       ; initial values (@label for heap addresses)
+ *   exports
+ *     rm710                            ; an object, a code label, or 0 (unused)
+ *   instance rm710 of Room             ; or: class Name of Super species 166
+ *     classScript 0                    ; header slots that aren't computed
+ *     info 0
+ *     name @s_0b2c
+ *     picture 710                      ; properties by name (or #slot)
+ *     method init rm710::init
+ *     layout -objID- ... name x y      ; optional: the full property layout, so the class
+ *                                      ; needn't be known when assembling (compiled code)
+ *   strings
+ *     s_0b2c "rm710"
+ *   code
+ *   rm710::init:                       ; code owned by rm710 (self)
+ *     lsg 201
+ *     bnt .L015c                       ; minimal form unless .b / .w says otherwise
+ *     pushi #init                      ; #selector, @heap label, class Name, callk Name
+ *     pToa register                    ; properties of self by name
+ *   proc_0abc:
+ *     owner sExit                      ; procedures say whose properties they use
+ *
+ * Layout rules, measured on all 285 scripts of an SCI2 game (and required to hold for byte-exact
+ * round trips):
+ *   script  header (reloc offset, 0, 0, export count) | exports | per object in heap order:
+ *           class propDict, then methDict | code (no gaps) | code relocation table
+ *   heap    header (reloc offset, local count) | locals | objects | 0 | strings | heap relocs
+ *   Code relocations are object exports and every lofsa/lofss operand (always 16-bit);
+ *   heap relocations are object slots holding heap addresses (names, string properties).
+ *
+ * Operand forms: the compiler didn't always pick the smallest encoding (forward jumps and
+ * selector pushes are split), so round trips mark the exceptions with `.w` / `.b`. By
+ * default the assembler picks the smallest form, except send/self (almost always 16-bit
+ * in the original scripts) and lofsa/lofss (relocated, so always 16-bit).
+ */
+export interface AsmContext extends DisasmContext {
+    /** Class name → class number, for `of Name`, `class Name` and `super Name`. */
+    classSpecies(name: string): number | undefined;
+    /** Property selectors of a class by number (for instances of classes in other scripts). */
+    classPropSelectors(species: number): readonly number[] | undefined;
+    /** A class's default property values, all slots (instances start from these). */
+    classDefaults(species: number): readonly number[] | undefined;
+    /**
+     * A selector the context doesn't know yet: a game built from nothing numbers its selectors
+     * as its scripts use them. Without it, unknown selectors are errors.
+     */
+    newSelector?(name: string): number;
+}
+export declare class AsmError extends Error {
+    readonly line?: number | undefined;
+    constructor(message: string, line?: number | undefined);
+}
+export declare function toAssembly(script: Script, ctx: AsmContext): string;
+export declare function assemble(text: string, ctx: AsmContext): {
+    number: number;
+    code: Uint8Array;
+    heap: Uint8Array;
+};
+/** Reads the heap string at an address (for tools that show assembled output). */
+export declare const heapString: (heap: Uint8Array, offset: number) => string;