sci2-ts 0.0.0-stage → 0.2.2

package/packages/sci/src/vm/savegame.d.ts

@@ -0,0 +1,89 @@
+import { type PaletteEffectsState } from "./kernels/palette.ts";
+import type { Palette } from "../gfx/palette.ts";
+import { type ArrayType } from "./memory.ts";
+import type { Vm } from "./vm.ts";
+import { type Value } from "./value.ts";
+/**
+ * A saved game: the VM's memory, not the original interpreter's. Every reference in the game
+ * is a (segment, offset) pair, so restoring means recreating each segment at its original id:
+ * scripts by number (their code comes from the resources), clones by the script object they
+ * were cloned from, and arrays, lists, nodes and bitmaps by value. The call stack isn't
+ * saved: like Sierra's interpreter, restoring restarts execution with `theGame replay`.
+ */
+export interface VmSnapshot {
+    format: 1;
+    segments: (SegmentSnapshot | null)[];
+    freeSegments: number[];
+    scripts: {
+        number: number;
+        segment: number;
+        localsSegment: number;
+        locals: Value[];
+        objects: [offset: number, vars: Value[]][];
+    }[];
+    stack: Value[];
+    graphics: {
+        planes: Value[];
+        items: Value[];
+        palette?: Palette;
+        effects: PaletteEffectsState;
+    };
+    audio: {
+        masterVolume: number;
+        songs: {
+            object: Value;
+            number: number;
+            loop: boolean;
+            volume: number;
+            position: number;
+        }[];
+    };
+}
+type SegmentSnapshot = {
+    kind: "script" | "locals" | "stack";
+} | {
+    kind: "clone";
+    template: Value;
+    vars: Value[];
+} | {
+    kind: "array";
+    type: ArrayType;
+    data: Value[];
+} | {
+    kind: "list";
+    first: number;
+    last: number;
+} | {
+    kind: "node";
+    value: Value;
+    key: Value;
+    prev: number;
+    next: number;
+    list: number;
+} | {
+    kind: "bitmap";
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+    skipColor: number;
+    originX: number;
+    originY: number;
+};
+export declare function snapshot(vm: Vm): VmSnapshot;
+/** Replaces the VM's state with `snap`. The caller then restarts execution (`replay`). */
+export declare function restore(vm: Vm, snap: VmSnapshot): void;
+/** Sanity check used by tests: every object's -super- points at a live class object. */
+export declare function checkObjects(vm: Vm): string[];
+/**
+ * Saved games as JSON text, for moving them between the browser (IndexedDB keeps them as
+ * structured clones) and the Node tools. Typed arrays become `{ $typed, data }`.
+ */
+export declare function savesToJson(list: {
+    info: unknown;
+    snapshot: VmSnapshot;
+}[]): string;
+export declare function savesFromJson<Info>(text: string): {
+    info: Info;
+    snapshot: VmSnapshot;
+}[];
+export {};

package/packages/sci/src/vm/savegame.js

@@ -0,0 +1,161 @@
+import { ObjectSlot } from "../script/script.js";
+import { audio } from "./kernels/audio.js";
+import { graphics } from "./kernels/graphics.js";
+import { paletteEffects } from "./kernels/palette.js";
+import { cloneShape } from "./memory.js";
+import { makeRef, segmentOf } from "./value.js";
+const seg = (v) => (v ? segmentOf(v.address) : -1);
+export function snapshot(vm) {
+    const m = vm.memory;
+    const segments = m.segments.map((s) => {
+        switch (s.kind) {
+            case "script":
+            case "locals":
+            case "stack": return { kind: s.kind };
+            case "clone": return { kind: "clone", template: s.object.template.address, vars: s.object.vars.slice() };
+            case "array": return { kind: "array", type: s.array.type, data: s.array.data.slice() };
+            case "list": return { kind: "list", first: seg(s.list.first), last: seg(s.list.last) };
+            case "node": return { kind: "node", value: s.node.value, key: s.node.key, prev: seg(s.node.prev), next: seg(s.node.next), list: seg(s.node.list) };
+            case "bitmap": return { kind: "bitmap", ...s.bitmap, pixels: s.bitmap.pixels.slice() };
+            default: return null;
+        }
+    });
+    const g = graphics(vm);
+    const a = audio(vm);
+    const now = a.ticks();
+    return {
+        format: 1,
+        segments,
+        freeSegments: [...m.free_],
+        scripts: vm.loadedScripts.map((s) => ({
+            number: s.number,
+            segment: s.segment,
+            localsSegment: s.localsSegment,
+            locals: s.locals.slice(),
+            objects: [...s.objects].map(([offset, obj]) => [offset, obj.vars.slice()]),
+        })),
+        stack: m.stack.slice(),
+        graphics: {
+            planes: [...g.planes],
+            items: [...g.items],
+            palette: g.sourcePalette && { rgb: g.sourcePalette.rgb.slice(), used: g.sourcePalette.used.slice() },
+            effects: paletteEffects(vm).save(),
+        },
+        audio: {
+            masterVolume: a.masterVolume,
+            songs: a.playingSongs().map((p) => ({ object: p.object, number: p.number, loop: p.player.loop, volume: p.player.volume, position: p.player.position(now) })),
+        },
+    };
+}
+/** Replaces the VM's state with `snap`. The caller then restarts execution (`replay`). */
+export function restore(vm, snap) {
+    if (snap.format !== 1)
+        throw new Error(`Unsupported save format ${snap.format}`);
+    audio(vm).stopEverything();
+    vm.resetMemory();
+    const m = vm.memory;
+    if (m.stackSegment !== snap.segments.findIndex((s) => s?.kind === "stack"))
+        throw new Error("Stack segment moved");
+    // Reserve the whole table so nothing we create lands on a saved id by accident.
+    m.allocateAt(snap.segments.length - 1, { kind: "free" });
+    m.setFreeSegments([]);
+    for (const s of vm.restoreScripts(snap.scripts)) {
+        const saved = snap.scripts.find((x) => x.number === s.number);
+        s.locals.splice(0, s.locals.length, ...saved.locals);
+        for (const [offset, vars] of saved.objects) {
+            const obj = s.objects.get(offset);
+            if (obj)
+                obj.vars = vars.slice();
+        }
+    }
+    const nodes = new Map();
+    const lists = new Map();
+    snap.segments.forEach((s, id) => {
+        if (!s)
+            return;
+        const address = makeRef(id, 0);
+        switch (s.kind) {
+            case "clone": {
+                const template = m.object(s.template);
+                if (!template)
+                    throw new Error(`Clone template ${s.template.toString(16)} missing`);
+                const obj = cloneShape(template.template ?? template, s.vars.slice());
+                obj.address = address;
+                m.allocateAt(id, { kind: "clone", object: obj });
+                m.objects.set(address, obj);
+                break;
+            }
+            case "array":
+                m.allocateAt(id, { kind: "array", array: { type: s.type, data: s.data.slice() } });
+                break;
+            case "bitmap":
+                m.allocateAt(id, { kind: "bitmap", bitmap: { width: s.width, height: s.height, pixels: s.pixels.slice(), skipColor: s.skipColor, originX: s.originX, originY: s.originY } });
+                break;
+            case "list": {
+                const list = { address, first: undefined, last: undefined };
+                lists.set(id, list);
+                m.allocateAt(id, { kind: "list", list });
+                break;
+            }
+            case "node": {
+                const node = { address, value: s.value, key: s.key, prev: undefined, next: undefined, list: undefined };
+                nodes.set(id, node);
+                m.allocateAt(id, { kind: "node", node });
+                break;
+            }
+        }
+    });
+    // Link lists and nodes now that they all exist.
+    snap.segments.forEach((s, id) => {
+        if (s?.kind === "list")
+            Object.assign(lists.get(id), { first: nodes.get(s.first), last: nodes.get(s.last) });
+        if (s?.kind === "node")
+            Object.assign(nodes.get(id), { prev: nodes.get(s.prev), next: nodes.get(s.next), list: lists.get(s.list) });
+    });
+    m.setFreeSegments(snap.freeSegments.slice());
+    // Derived identity slots (see Vm.fixObjectIdentity): recompute rather than trust old saves.
+    for (const obj of m.objects.values())
+        vm.fixObjectIdentity(obj);
+    m.stack.splice(0, m.stack.length, ...snap.stack);
+    const g = graphics(vm);
+    g.planes.clear();
+    g.items.clear();
+    for (const p of snap.graphics.planes)
+        g.planes.add(p);
+    for (const i of snap.graphics.items)
+        g.items.add(i);
+    g.resetPalette();
+    g.sourcePalette = snap.graphics.palette && { rgb: snap.graphics.palette.rgb.slice(), used: snap.graphics.palette.used.slice() };
+    paletteEffects(vm).load(snap.graphics.effects, Math.floor((vm.clock() * 60) / 1000));
+    const a = audio(vm);
+    a.masterVolume = snap.audio.masterVolume;
+    a.midi?.setMasterVolume?.(a.masterVolume);
+    for (const song of snap.audio.songs)
+        a.startSong(song.object, song.number, song.loop, song.volume, song.position);
+}
+/** Sanity check used by tests: every object's -super- points at a live class object. */
+export function checkObjects(vm) {
+    const problems = [];
+    for (const obj of vm.memory.objects.values()) {
+        const sup = obj.vars[ObjectSlot.Super];
+        if (sup && !vm.memory.object(sup))
+            problems.push(`${obj.name}: -super- ${sup.toString(16)} is not an object`);
+    }
+    return problems;
+}
+/**
+ * Saved games as JSON text, for moving them between the browser (IndexedDB keeps them as
+ * structured clones) and the Node tools. Typed arrays become `{ $typed, data }`.
+ */
+export function savesToJson(list) {
+    return JSON.stringify(list, (_key, value) => ArrayBuffer.isView(value) && !(value instanceof DataView)
+        ? { $typed: value.constructor.name, data: Array.from(value) }
+        : value);
+}
+const TYPED = { Uint8Array, Uint16Array, Int16Array, Uint32Array, Int32Array, Float32Array, Float64Array };
+export function savesFromJson(text) {
+    return JSON.parse(text, (_key, value) => {
+        const t = value;
+        return t && typeof t === "object" && t.$typed && TYPED[t.$typed] ? new TYPED[t.$typed](t.data) : value;
+    });
+}

package/packages/sci/src/vm/savegame.ts

@@ -0,0 +1,188 @@
+import { ObjectSlot } from "../script/script.ts";
+import { audio } from "./kernels/audio.ts";
+import { graphics } from "./kernels/graphics.ts";
+import { paletteEffects, type PaletteEffectsState } from "./kernels/palette.ts";
+import type { Palette } from "../gfx/palette.ts";
+import { cloneShape, type ArrayType, type ListNode, type SciList, type SciObject } from "./memory.ts";
+import type { Vm } from "./vm.ts";
+import { makeRef, segmentOf, type Value } from "./value.ts";
+
+/**
+ * A saved game: the VM's memory, not the original interpreter's. Every reference in the game
+ * is a (segment, offset) pair, so restoring means recreating each segment at its original id:
+ * scripts by number (their code comes from the resources), clones by the script object they
+ * were cloned from, and arrays, lists, nodes and bitmaps by value. The call stack isn't
+ * saved: like Sierra's interpreter, restoring restarts execution with `theGame replay`.
+ */
+export interface VmSnapshot {
+  format: 1;
+  segments: (SegmentSnapshot | null)[];
+  freeSegments: number[];
+  scripts: { number: number; segment: number; localsSegment: number; locals: Value[]; objects: [offset: number, vars: Value[]][] }[];
+  stack: Value[];
+  graphics: { planes: Value[]; items: Value[]; palette?: Palette; effects: PaletteEffectsState };
+  audio: { masterVolume: number; songs: { object: Value; number: number; loop: boolean; volume: number; position: number }[] };
+}
+
+type SegmentSnapshot =
+  | { kind: "script" | "locals" | "stack" }
+  | { kind: "clone"; template: Value; vars: Value[] }
+  | { kind: "array"; type: ArrayType; data: Value[] }
+  | { kind: "list"; first: number; last: number }
+  | { kind: "node"; value: Value; key: Value; prev: number; next: number; list: number }
+  | { kind: "bitmap"; width: number; height: number; pixels: Uint8Array; skipColor: number; originX: number; originY: number };
+
+const seg = (v: { address: Value } | undefined) => (v ? segmentOf(v.address) : -1);
+
+export function snapshot(vm: Vm): VmSnapshot {
+  const m = vm.memory;
+  const segments = m.segments.map((s): SegmentSnapshot | null => {
+    switch (s.kind) {
+      case "script": case "locals": case "stack": return { kind: s.kind };
+      case "clone": return { kind: "clone", template: s.object.template!.address, vars: s.object.vars.slice() };
+      case "array": return { kind: "array", type: s.array.type, data: s.array.data.slice() };
+      case "list": return { kind: "list", first: seg(s.list.first), last: seg(s.list.last) };
+      case "node": return { kind: "node", value: s.node.value, key: s.node.key, prev: seg(s.node.prev), next: seg(s.node.next), list: seg(s.node.list) };
+      case "bitmap": return { kind: "bitmap", ...s.bitmap, pixels: s.bitmap.pixels.slice() };
+      default: return null;
+    }
+  });
+  const g = graphics(vm);
+  const a = audio(vm);
+  const now = a.ticks();
+  return {
+    format: 1,
+    segments,
+    freeSegments: [...m.free_],
+    scripts: vm.loadedScripts.map((s) => ({
+      number: s.number,
+      segment: s.segment,
+      localsSegment: s.localsSegment,
+      locals: s.locals.slice(),
+      objects: [...s.objects].map(([offset, obj]) => [offset, obj.vars.slice()]),
+    })),
+    stack: m.stack.slice(),
+    graphics: {
+      planes: [...g.planes],
+      items: [...g.items],
+      palette: g.sourcePalette && { rgb: g.sourcePalette.rgb.slice(), used: g.sourcePalette.used.slice() },
+      effects: paletteEffects(vm).save(),
+    },
+    audio: {
+      masterVolume: a.masterVolume,
+      songs: a.playingSongs().map((p) => ({ object: p.object, number: p.number, loop: p.player.loop, volume: p.player.volume, position: p.player.position(now) })),
+    },
+  };
+}
+
+/** Replaces the VM's state with `snap`. The caller then restarts execution (`replay`). */
+export function restore(vm: Vm, snap: VmSnapshot): void {
+  if (snap.format !== 1) throw new Error(`Unsupported save format ${snap.format}`);
+  audio(vm).stopEverything();
+  vm.resetMemory();
+  const m = vm.memory;
+  if (m.stackSegment !== snap.segments.findIndex((s) => s?.kind === "stack")) throw new Error("Stack segment moved");
+
+  // Reserve the whole table so nothing we create lands on a saved id by accident.
+  m.allocateAt(snap.segments.length - 1, { kind: "free" });
+  m.setFreeSegments([]);
+
+  for (const s of vm.restoreScripts(snap.scripts)) {
+    const saved = snap.scripts.find((x) => x.number === s.number)!;
+    s.locals.splice(0, s.locals.length, ...saved.locals);
+    for (const [offset, vars] of saved.objects) {
+      const obj = s.objects.get(offset);
+      if (obj) obj.vars = vars.slice();
+    }
+  }
+
+  const nodes = new Map<number, ListNode>();
+  const lists = new Map<number, SciList>();
+  snap.segments.forEach((s, id) => {
+    if (!s) return;
+    const address = makeRef(id, 0);
+    switch (s.kind) {
+      case "clone": {
+        const template = m.object(s.template);
+        if (!template) throw new Error(`Clone template ${s.template.toString(16)} missing`);
+        const obj: SciObject = cloneShape(template.template ?? template, s.vars.slice());
+        obj.address = address;
+        m.allocateAt(id, { kind: "clone", object: obj });
+        m.objects.set(address, obj);
+        break;
+      }
+      case "array":
+        m.allocateAt(id, { kind: "array", array: { type: s.type, data: s.data.slice() } });
+        break;
+      case "bitmap":
+        m.allocateAt(id, { kind: "bitmap", bitmap: { width: s.width, height: s.height, pixels: s.pixels.slice(), skipColor: s.skipColor, originX: s.originX, originY: s.originY } });
+        break;
+      case "list": {
+        const list: SciList = { address, first: undefined, last: undefined };
+        lists.set(id, list);
+        m.allocateAt(id, { kind: "list", list });
+        break;
+      }
+      case "node": {
+        const node: ListNode = { address, value: s.value, key: s.key, prev: undefined, next: undefined, list: undefined };
+        nodes.set(id, node);
+        m.allocateAt(id, { kind: "node", node });
+        break;
+      }
+    }
+  });
+  // Link lists and nodes now that they all exist.
+  snap.segments.forEach((s, id) => {
+    if (s?.kind === "list") Object.assign(lists.get(id)!, { first: nodes.get(s.first), last: nodes.get(s.last) });
+    if (s?.kind === "node") Object.assign(nodes.get(id)!, { prev: nodes.get(s.prev), next: nodes.get(s.next), list: lists.get(s.list) });
+  });
+  m.setFreeSegments(snap.freeSegments.slice());
+  // Derived identity slots (see Vm.fixObjectIdentity): recompute rather than trust old saves.
+  for (const obj of m.objects.values()) vm.fixObjectIdentity(obj);
+  m.stack.splice(0, m.stack.length, ...snap.stack);
+
+  const g = graphics(vm);
+  g.planes.clear();
+  g.items.clear();
+  for (const p of snap.graphics.planes) g.planes.add(p);
+  for (const i of snap.graphics.items) g.items.add(i);
+  g.resetPalette();
+  g.sourcePalette = snap.graphics.palette && { rgb: snap.graphics.palette.rgb.slice(), used: snap.graphics.palette.used.slice() };
+  paletteEffects(vm).load(snap.graphics.effects, Math.floor((vm.clock() * 60) / 1000));
+
+  const a = audio(vm);
+  a.masterVolume = snap.audio.masterVolume;
+  a.midi?.setMasterVolume?.(a.masterVolume);
+  for (const song of snap.audio.songs) a.startSong(song.object, song.number, song.loop, song.volume, song.position);
+}
+
+/** Sanity check used by tests: every object's -super- points at a live class object. */
+export function checkObjects(vm: Vm): string[] {
+  const problems: string[] = [];
+  for (const obj of vm.memory.objects.values()) {
+    const sup = obj.vars[ObjectSlot.Super]!;
+    if (sup && !vm.memory.object(sup)) problems.push(`${obj.name}: -super- ${sup.toString(16)} is not an object`);
+  }
+  return problems;
+}
+
+/**
+ * Saved games as JSON text, for moving them between the browser (IndexedDB keeps them as
+ * structured clones) and the Node tools. Typed arrays become `{ $typed, data }`.
+ */
+export function savesToJson(list: { info: unknown; snapshot: VmSnapshot }[]): string {
+  return JSON.stringify(list, (_key, value: unknown) =>
+    ArrayBuffer.isView(value) && !(value instanceof DataView)
+      ? { $typed: value.constructor.name, data: Array.from(value as unknown as ArrayLike<number>) }
+      : value,
+  );
+}
+
+const TYPED: Record<string, new (data: number[]) => ArrayBufferView> = { Uint8Array, Uint16Array, Int16Array, Uint32Array, Int32Array, Float32Array, Float64Array };
+
+export function savesFromJson<Info>(text: string): { info: Info; snapshot: VmSnapshot }[] {
+  return JSON.parse(text, (_key, value: unknown) => {
+    const t = value as { $typed?: string; data?: number[] } | null;
+    return t && typeof t === "object" && t.$typed && TYPED[t.$typed] ? new TYPED[t.$typed]!(t.data!) : value;
+  });
+}

package/packages/sci/src/vm/value.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An SCI value ("reg_t"): a (segment, offset) pair packed into one JS number as
+ * `segment * 0x10000 + offset`. Segment 0 holds plain 16-bit integers; every other
+ * segment is something addressable: a script's heap, a clone, an array, a list...
+ *
+ * Numbers are stored unsigned (0..0xFFFF) and read signed where the bytecode wants it.
+ */
+export type Value = number;
+export declare const NULL: Value;
+export declare const makeRef: (segment: number, offset: number) => Value;
+export declare const segmentOf: (v: Value) => number;
+export declare const offsetOf: (v: Value) => number;
+export declare const isNumber: (v: Value) => boolean;
+export declare const toSigned: (v: Value) => number;
+export declare const fromInt: (n: number) => Value;
+export declare const bool: (b: boolean) => Value;
+export declare const formatValue: (v: Value) => string;

package/packages/sci/src/vm/value.js

@@ -0,0 +1,12 @@
+export const NULL = 0;
+export const makeRef = (segment, offset) => segment * 0x10000 + (offset & 0xffff);
+export const segmentOf = (v) => Math.floor(v / 0x10000);
+export const offsetOf = (v) => v & 0xffff;
+export const isNumber = (v) => v < 0x10000;
+export const toSigned = (v) => {
+    const n = v & 0xffff;
+    return n >= 0x8000 ? n - 0x10000 : n;
+};
+export const fromInt = (n) => n & 0xffff;
+export const bool = (b) => (b ? 1 : 0);
+export const formatValue = (v) => isNumber(v) ? String(toSigned(v)) : `${segmentOf(v).toString(16)}:${offsetOf(v).toString(16).padStart(4, "0")}`;

package/packages/sci/src/vm/value.ts

@@ -0,0 +1,25 @@
+/**
+ * An SCI value ("reg_t"): a (segment, offset) pair packed into one JS number as
+ * `segment * 0x10000 + offset`. Segment 0 holds plain 16-bit integers; every other
+ * segment is something addressable: a script's heap, a clone, an array, a list...
+ *
+ * Numbers are stored unsigned (0..0xFFFF) and read signed where the bytecode wants it.
+ */
+export type Value = number;
+
+export const NULL: Value = 0;
+
+export const makeRef = (segment: number, offset: number): Value => segment * 0x10000 + (offset & 0xffff);
+export const segmentOf = (v: Value): number => Math.floor(v / 0x10000);
+export const offsetOf = (v: Value): number => v & 0xffff;
+export const isNumber = (v: Value): boolean => v < 0x10000;
+
+export const toSigned = (v: Value): number => {
+  const n = v & 0xffff;
+  return n >= 0x8000 ? n - 0x10000 : n;
+};
+export const fromInt = (n: number): Value => n & 0xffff;
+export const bool = (b: boolean): Value => (b ? 1 : 0);
+
+export const formatValue = (v: Value): string =>
+  isNumber(v) ? String(toSigned(v)) : `${segmentOf(v).toString(16)}:${offsetOf(v).toString(16).padStart(4, "0")}`;

package/packages/sci/src/vm/vm.d.ts

@@ -0,0 +1,155 @@
+import type { ResourceManager } from "../resource/manager.ts";
+import { Memory, type LoadedScript, type SciObject } from "./memory.ts";
+import { type Value } from "./value.ts";
+/** A message a native (generator) kernel wants sent; the VM resumes it with the result. */
+export interface SendRequest {
+    object: Value;
+    selector: number;
+    args: Value[];
+}
+/** A native kernel's request to end the current frame (it has drawn one) and resume next tick. */
+export interface FrameRequest {
+    frame: true;
+}
+/**
+ * A kernel function receives its arguments (argc = args.length) and returns acc.
+ * Kernels that call back into scripts are generators: they yield SendRequests and run as a
+ * "native frame" on the VM's frame stack, so a FrameOut inside the callback can still pause
+ * the whole VM for the browser.
+ */
+export type KernelFn = (vm: Vm, args: Value[]) => Value | void | Generator<SendRequest | FrameRequest, Value | void, Value>;
+/** SCI2 -info- flag: a drawing property changed since the screen item was last updated. */
+export declare const INFO_VIEW_CHANGED = 8;
+export declare class VmError extends Error {
+}
+/**
+ * The SCI virtual machine: a stack machine with an accumulator, executing bytecode methods
+ * of objects that talk to each other through `send`.
+ *
+ * Execution uses an explicit frame stack rather than JS recursion, so `run()` can stop at
+ * any instruction boundary (e.g. when FrameOut wants the browser to draw) and pick up later.
+ */
+export declare class Vm {
+    readonly resources: ResourceManager;
+    memory: Memory;
+    readonly selectors: string[];
+    readonly selectorIds: Map<string, number>;
+    private readonly classScripts;
+    private readonly classes;
+    private readonly scripts;
+    private readonly kernels;
+    readonly missingKernels: Map<string, number>;
+    acc: Value;
+    prev: Value;
+    private sp;
+    private rest;
+    private frames;
+    /** Set by kernels (FrameOut) to end the current `run()` slice. */
+    yieldRequested: boolean;
+    instructions: number;
+    /** Milliseconds since boot. Browser: real time. Headless runs can drive it per frame. */
+    clock: () => number;
+    /** Host hook: move the mouse (SetCursor warp), e.g. update the input position. */
+    moveMouse?: (x: number, y: number) => void;
+    /** Called once per FrameOut (music sequencing, etc.). */
+    readonly frameHooks: (() => void)[];
+    /** Optional hook for tracing method calls (object, selector name, argument count). */
+    onSend?: (object: SciObject, selector: string, argc: number) => void;
+    /** Optional hook for tracing kernel calls. */
+    onKernelCall?: (name: string, args: Value[], result: Value) => void;
+    constructor(resources: ResourceManager);
+    registerKernels(table: Record<string, KernelFn>): void;
+    loadScript(number: number): LoadedScript;
+    /**
+     * Creates a script's segments, locals and objects from its resources, without linking
+     * instances to their classes (which may load other scripts). Restoring a save instantiates
+     * every script at its saved segment ids first, then resolves them all.
+     */
+    private instantiateScript;
+    private resolveScript;
+    /**
+     * `Obj::isKindOf` compares -propDict- and -classScript- to decide whether two objects share
+     * a class, so (as in the original interpreter) every object's -classScript- is its script
+     * number and an instance's -propDict- is its class's. Left as raw heap values, unrelated
+     * objects can match (e.g. a spell icon claiming to be an inventory item).
+     */
+    fixObjectIdentity(obj: SciObject): void;
+    /**
+     * DisposeScript: as in SSCI the script is unloaded, so its objects start fresh from the
+     * resource the next time it's used. Dialogs rely on that: SRDialog's init offsets its
+     * buttons from where they are, which only works on fresh objects. A script still running
+     * (the dialog disposing its own script) goes once its last frame returns.
+     */
+    disposeScript(number: number): void;
+    private readonly disposed;
+    private unloadDisposed;
+    /** Objects the host keeps outside VM memory (planes, screen items, playing sounds). */
+    readonly hostRoots: (() => Iterable<Value>)[];
+    /**
+     * Whether anything live still needs the script: a reference into it, or a clone or
+     * subclass of one of its classes, reachable from the roots (other scripts' locals and
+     * objects, the stack, acc, running frames, the host). As in ScummVM's GC, only reachable
+     * data counts, so garbage (a list nobody points to any more) doesn't pin it; a disposed
+     * script that's still needed stays loaded (a pending Cue to a room's script, say).
+     */
+    private scriptInUse;
+    private unloadScript;
+    get loadedScripts(): LoadedScript[];
+    /** Throws away all scripts, objects and execution state (restart / before a restore). */
+    resetMemory(): void;
+    /** Drops the call stack: nothing that was running will resume. */
+    resetExecution(): void;
+    /** Recreates scripts at their saved segment ids, then links them (see instantiateScript). */
+    restoreScripts(entries: {
+        number: number;
+        segment: number;
+        localsSegment: number;
+    }[]): LoadedScript[];
+    localsSegment(s: LoadedScript): number;
+    classObject(species: number): SciObject;
+    /** Address of export `index` of `script` (objects: the object; procedures: a code ref). */
+    exportAddress(scriptNumber: number, index: number): Value;
+    object(v: Value): SciObject;
+    selector(name: string): number;
+    /** Reads a property by selector name; undefined if the object doesn't have it. */
+    getProp(obj: Value | SciObject, name: string): Value | undefined;
+    setProp(obj: Value | SciObject, name: string, value: Value): void;
+    /**
+     * Writes a property. SCI2's interpreter also marks the object "changed since drawn"
+     * (bit 0x0008 of -info-) when the property is one that affects drawing (variable slots
+     * 26-44: plane, x, y, z, scale..., priority, inset, view, loop, cel, bitmap), whoever
+     * writes it: script, send or kernel. Updating the screen item clears it. Scripts rely on
+     * it: Actor::doit only runs its scaler and UpdateScreenItem when the bit is set.
+     * (ScummVM: Object::mustSetViewVisible, updateInfoFlagViewVisible.)
+     */
+    writeVar(obj: SciObject, slot: number, value: Value): void;
+    private findMethod;
+    respondsTo(obj: SciObject, selector: number): boolean;
+    private push;
+    /**
+     * Starts a send of `selector` with `args` to `object` as a new top-level frame.
+     * Used to boot the game (`theGame play`); `run()` then drives it.
+     */
+    start(object: Value, selectorName: string, args?: Value[]): void;
+    /**
+     * Synchronously sends a message and runs until it returns: for kernels that call back
+     * into scripts (e.g. ListEachElementDo). Returns the resulting acc.
+     */
+    invoke(object: Value, selector: number, args?: Value[]): Value;
+    get running(): boolean;
+    /** Runs until the game yields (FrameOut), finishes, or `budget` instructions pass. */
+    run(budget?: number): void;
+    /** Dispatches remaining selectors of `caller.send`; returns when a method frame is pushed or the send ends. */
+    private continueSend;
+    private beginSend;
+    private callKernel;
+    private callLocal;
+    /** Resumes a native frame: performs its next send request, or finishes it. */
+    private resumeNative;
+    private varArray;
+    /** Executes until frames drop to `stopDepth`, a yield (top level only), or the budget runs out. */
+    private execute;
+    /** Human-readable call stack, for errors and debugging. */
+    backtrace(): string[];
+    isScriptLoaded(n: number): boolean;
+}