sci2-ts 0.0.0-stage → 0.2.2

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

@@ -0,0 +1,45 @@
+import { type VmSnapshot } from "../savegame.ts";
+import type { KernelFn, Vm } from "../vm.ts";
+export interface SaveInfo {
+    id: number;
+    description: string;
+    version: string;
+    date: number;
+}
+/** Where saves live. Synchronous because kernels are; hosts preload and write through. */
+export interface SaveStore {
+    list(): SaveInfo[];
+    get(id: number): {
+        info: SaveInfo;
+        snapshot: VmSnapshot;
+    } | undefined;
+    put(info: SaveInfo, snapshot: VmSnapshot): void;
+}
+export declare class MemorySaveStore implements SaveStore {
+    readonly saves: Map<number, {
+        info: SaveInfo;
+        snapshot: VmSnapshot;
+    }>;
+    /** Called after every write, e.g. to persist asynchronously. */
+    onWrite?: (info: SaveInfo, snapshot: VmSnapshot) => void;
+    list(): SaveInfo[];
+    get(id: number): {
+        info: SaveInfo;
+        snapshot: VmSnapshot;
+    } | undefined;
+    put(info: SaveInfo, snap: VmSnapshot): void;
+}
+declare class SaveState {
+    store: SaveStore;
+    restarting: number;
+}
+export declare const saves: (vm: Vm) => SaveState;
+/**
+ * Loads a saved game the way SSCI's RestoreGame does: host state (planes, screen items,
+ * palette, sound) is cleared, memory replaced, and the game restarts with `replay` knowing
+ * it's a restore. Hosts that load a save themselves must use this too: stale planes and
+ * items left from before would alias unrelated objects in the restored memory.
+ */
+export declare function restoreGame(vm: Vm, snap: VmSnapshot): void;
+export declare const saveKernels: Record<string, KernelFn>;
+export {};

package/packages/sci/src/vm/kernels/saves.js

@@ -0,0 +1,123 @@
+import { restore, snapshot } from "../savegame.js";
+import { toSigned } from "../value.js";
+import { stringHelpers } from "./arrays.js";
+import { audio } from "./audio.js";
+import { graphics } from "./graphics.js";
+import { paletteEffects } from "./palette.js";
+import { input } from "./system.js";
+export class MemorySaveStore {
+    saves = new Map();
+    /** Called after every write, e.g. to persist asynchronously. */
+    onWrite;
+    list() {
+        return [...this.saves.values()].map((s) => s.info).sort((a, b) => b.date - a.date);
+    }
+    get(id) {
+        return this.saves.get(id);
+    }
+    put(info, snap) {
+        this.saves.set(info.id, { info, snapshot: snap });
+        this.onWrite?.(info, snap);
+    }
+}
+const Restarting = { None: 0, Restart: 1, Restore: 2 };
+/** SSCI's fixed description slot size in GetSaveFiles' output. */
+const DESCRIPTION_SIZE = 36;
+class SaveState {
+    store = new MemorySaveStore();
+    restarting = Restarting.None;
+}
+const stateOf = new WeakMap();
+export const saves = (vm) => {
+    let s = stateOf.get(vm);
+    if (!s)
+        stateOf.set(vm, (s = new SaveState()));
+    return s;
+};
+/**
+ * Loads a saved game the way SSCI's RestoreGame does: host state (planes, screen items,
+ * palette, sound) is cleared, memory replaced, and the game restarts with `replay` knowing
+ * it's a restore. Hosts that load a save themselves must use this too: stale planes and
+ * items left from before would alias unrelated objects in the restored memory.
+ */
+export function restoreGame(vm, snap) {
+    const game = vm.exportAddress(0, 0);
+    resetHostState(vm);
+    restore(vm, snap);
+    saves(vm).restarting = Restarting.Restore;
+    vm.resetExecution();
+    vm.start(game, "replay");
+}
+/** Clears everything that isn't part of the VM's memory before a restart or restore. */
+function resetHostState(vm) {
+    audio(vm).stopEverything();
+    const g = graphics(vm);
+    g.planes.clear();
+    g.items.clear();
+    g.resetPalette();
+    paletteEffects(vm).reset();
+    input(vm).queue.length = 0;
+}
+export const saveKernels = {
+    // SaveGame(gameName, id, description, version)
+    SaveGame: (vm, [, id = 0, description = 0, version = 0]) => {
+        const info = {
+            id,
+            description: stringHelpers.str(vm, description),
+            version: stringHelpers.str(vm, version),
+            date: Date.now(),
+        };
+        saves(vm).store.put(info, snapshot(vm));
+        return 1;
+    },
+    // RestoreGame(gameName, id, version): on success nothing returns; the game restarts in
+    // the saved state via `theGame replay`, as in the original interpreter.
+    RestoreGame: (vm, [, id = 0]) => {
+        const save = saves(vm).store.get(toSigned(id));
+        if (!save)
+            return 0;
+        restoreGame(vm, save.snapshot);
+        return 1;
+    },
+    RestartGame: (vm) => {
+        resetHostState(vm);
+        vm.resetMemory();
+        saves(vm).restarting = Restarting.Restart;
+        vm.start(vm.exportAddress(0, 0), "play");
+        return 0;
+    },
+    // Returns the flag; any argument clears it.
+    GameIsRestarting: (vm, args) => {
+        const s = saves(vm);
+        const flag = s.restarting;
+        if (args.length)
+            s.restarting = Restarting.None;
+        return flag;
+    },
+    // GetSaveFiles(gameName, descriptions, ids): fixed 36-byte description slots and a
+    // 0-terminated id list, newest first.
+    GetSaveFiles: (vm, [, descriptions = 0, ids = 0]) => {
+        const list = saves(vm).store.list();
+        const desc = stringHelpers.resolve(vm, descriptions);
+        const idArray = stringHelpers.resolve(vm, ids);
+        if (desc) {
+            desc.data = new Array(DESCRIPTION_SIZE * list.length + 1).fill(0);
+            list.forEach((s, i) => {
+                const text = s.description.slice(0, DESCRIPTION_SIZE - 1);
+                for (let c = 0; c < text.length; c++)
+                    desc.data[i * DESCRIPTION_SIZE + c] = text.charCodeAt(c) & 0xff;
+            });
+        }
+        if (idArray)
+            idArray.data = [...list.map((s) => s.id & 0xffff), 0];
+        return list.length;
+    },
+    // CheckSaveGame(gameName, id, version): exists and was made by this game version.
+    CheckSaveGame: (vm, [, id = 0, version = 0]) => {
+        const save = saves(vm).store.get(toSigned(id));
+        return save && save.info.version === stringHelpers.str(vm, version) ? 1 : 0;
+    },
+    GetSaveDir: (vm) => stringHelpers.newString(vm, "SAVES"),
+    MakeSaveCatName: (vm, [dst = 0]) => stringHelpers.writeString(vm, dst, "QG4CDSG.CAT"),
+    MakeSaveFileName: (vm, [dst = 0, , id = 0]) => stringHelpers.writeString(vm, dst, `QG4CDSG.${String(toSigned(id)).padStart(3, "0")}`),
+};

package/packages/sci/src/vm/kernels/saves.ts

@@ -0,0 +1,149 @@
+import { restore, snapshot, type VmSnapshot } from "../savegame.ts";
+import type { KernelFn, Vm } from "../vm.ts";
+import { toSigned } from "../value.ts";
+import { stringHelpers } from "./arrays.ts";
+import { audio } from "./audio.ts";
+import { graphics } from "./graphics.ts";
+import { paletteEffects } from "./palette.ts";
+import { input } from "./system.ts";
+
+export interface SaveInfo {
+  id: number;
+  description: string;
+  version: string;
+  date: number;
+}
+
+/** Where saves live. Synchronous because kernels are; hosts preload and write through. */
+export interface SaveStore {
+  list(): SaveInfo[];
+  get(id: number): { info: SaveInfo; snapshot: VmSnapshot } | undefined;
+  put(info: SaveInfo, snapshot: VmSnapshot): void;
+}
+
+export class MemorySaveStore implements SaveStore {
+  readonly saves = new Map<number, { info: SaveInfo; snapshot: VmSnapshot }>();
+  /** Called after every write, e.g. to persist asynchronously. */
+  onWrite?: (info: SaveInfo, snapshot: VmSnapshot) => void;
+
+  list(): SaveInfo[] {
+    return [...this.saves.values()].map((s) => s.info).sort((a, b) => b.date - a.date);
+  }
+
+  get(id: number) {
+    return this.saves.get(id);
+  }
+
+  put(info: SaveInfo, snap: VmSnapshot): void {
+    this.saves.set(info.id, { info, snapshot: snap });
+    this.onWrite?.(info, snap);
+  }
+}
+
+const Restarting = { None: 0, Restart: 1, Restore: 2 } as const;
+/** SSCI's fixed description slot size in GetSaveFiles' output. */
+const DESCRIPTION_SIZE = 36;
+
+class SaveState {
+  store: SaveStore = new MemorySaveStore();
+  restarting: number = Restarting.None;
+}
+
+const stateOf = new WeakMap<Vm, SaveState>();
+export const saves = (vm: Vm): SaveState => {
+  let s = stateOf.get(vm);
+  if (!s) stateOf.set(vm, (s = new SaveState()));
+  return s;
+};
+
+/**
+ * Loads a saved game the way SSCI's RestoreGame does: host state (planes, screen items,
+ * palette, sound) is cleared, memory replaced, and the game restarts with `replay` knowing
+ * it's a restore. Hosts that load a save themselves must use this too: stale planes and
+ * items left from before would alias unrelated objects in the restored memory.
+ */
+export function restoreGame(vm: Vm, snap: VmSnapshot): void {
+  const game = vm.exportAddress(0, 0);
+  resetHostState(vm);
+  restore(vm, snap);
+  saves(vm).restarting = Restarting.Restore;
+  vm.resetExecution();
+  vm.start(game, "replay");
+}
+
+/** Clears everything that isn't part of the VM's memory before a restart or restore. */
+function resetHostState(vm: Vm) {
+  audio(vm).stopEverything();
+  const g = graphics(vm);
+  g.planes.clear();
+  g.items.clear();
+  g.resetPalette();
+  paletteEffects(vm).reset();
+  input(vm).queue.length = 0;
+}
+
+export const saveKernels: Record<string, KernelFn> = {
+  // SaveGame(gameName, id, description, version)
+  SaveGame: (vm, [, id = 0, description = 0, version = 0]) => {
+    const info: SaveInfo = {
+      id,
+      description: stringHelpers.str(vm, description),
+      version: stringHelpers.str(vm, version),
+      date: Date.now(),
+    };
+    saves(vm).store.put(info, snapshot(vm));
+    return 1;
+  },
+
+  // RestoreGame(gameName, id, version): on success nothing returns; the game restarts in
+  // the saved state via `theGame replay`, as in the original interpreter.
+  RestoreGame: (vm, [, id = 0]) => {
+    const save = saves(vm).store.get(toSigned(id));
+    if (!save) return 0;
+    restoreGame(vm, save.snapshot);
+    return 1;
+  },
+
+  RestartGame: (vm) => {
+    resetHostState(vm);
+    vm.resetMemory();
+    saves(vm).restarting = Restarting.Restart;
+    vm.start(vm.exportAddress(0, 0), "play");
+    return 0;
+  },
+
+  // Returns the flag; any argument clears it.
+  GameIsRestarting: (vm, args) => {
+    const s = saves(vm);
+    const flag = s.restarting;
+    if (args.length) s.restarting = Restarting.None;
+    return flag;
+  },
+
+  // GetSaveFiles(gameName, descriptions, ids): fixed 36-byte description slots and a
+  // 0-terminated id list, newest first.
+  GetSaveFiles: (vm, [, descriptions = 0, ids = 0]) => {
+    const list = saves(vm).store.list();
+    const desc = stringHelpers.resolve(vm, descriptions);
+    const idArray = stringHelpers.resolve(vm, ids);
+    if (desc) {
+      desc.data = new Array(DESCRIPTION_SIZE * list.length + 1).fill(0);
+      list.forEach((s, i) => {
+        const text = s.description.slice(0, DESCRIPTION_SIZE - 1);
+        for (let c = 0; c < text.length; c++) desc.data[i * DESCRIPTION_SIZE + c] = text.charCodeAt(c) & 0xff;
+      });
+    }
+    if (idArray) idArray.data = [...list.map((s) => s.id & 0xffff), 0];
+    return list.length;
+  },
+
+  // CheckSaveGame(gameName, id, version): exists and was made by this game version.
+  CheckSaveGame: (vm, [, id = 0, version = 0]) => {
+    const save = saves(vm).store.get(toSigned(id));
+    return save && save.info.version === stringHelpers.str(vm, version) ? 1 : 0;
+  },
+
+  GetSaveDir: (vm) => stringHelpers.newString(vm, "SAVES"),
+  MakeSaveCatName: (vm, [dst = 0]) => stringHelpers.writeString(vm, dst, "QG4CDSG.CAT"),
+  MakeSaveFileName: (vm, [dst = 0, , id = 0]) => stringHelpers.writeString(vm, dst, `QG4CDSG.${String(toSigned(id)).padStart(3, "0")}`),
+};

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

@@ -0,0 +1,62 @@
+import type { KernelFn, Vm } from "../vm.ts";
+import { type Value } from "../value.ts";
+/** SCI key codes for non-character keys: PC BIOS scan codes in the high byte. */
+export declare const SciKey: {
+    readonly Home: 18176;
+    readonly Up: 18432;
+    readonly PageUp: 18688;
+    readonly Left: 19200;
+    readonly Center: 19456;
+    readonly Right: 19712;
+    readonly End: 20224;
+    readonly Down: 20480;
+    readonly PageDown: 20736;
+    readonly Insert: 20992;
+    readonly Delete: 21248;
+    readonly ShiftTab: 3840;
+    readonly F1: 15104;
+    readonly F2: 15360;
+    readonly F3: 15616;
+    readonly F4: 15872;
+    readonly F5: 16128;
+    readonly F6: 16384;
+    readonly F7: 16640;
+    readonly F8: 16896;
+    readonly F9: 17152;
+    readonly F10: 17408;
+};
+/** SCI event types (SCI32). */
+export declare const EventType: {
+    readonly Null: 0;
+    readonly MouseDown: 1;
+    readonly MouseUp: 2;
+    readonly KeyDown: 4;
+    readonly KeyUp: 8;
+    readonly Direction: 16;
+    readonly Quit: 1024;
+};
+export interface SciEvent {
+    type: number;
+    message: number;
+    modifiers: number;
+    x: number;
+    y: number;
+}
+/** Input from the host (browser or test harness). */
+export declare class Input {
+    readonly queue: SciEvent[];
+    x: number;
+    y: number;
+    modifiers: number;
+    push(e: Omit<SciEvent, "x" | "y" | "modifiers"> & Partial<SciEvent>): void;
+}
+export declare const input: (vm: Vm) => Input;
+/** Events, sound (stubbed for now), files and host information. */
+export declare const systemKernels: Record<string, KernelFn>;
+export type { Value };
+/**
+ * Files the game may find with FileIO "exists" (lower-case names). A game may load Sierra's
+ * debug room (script 18: Alt-T teleport, Alt-G flags, Alt-I items...) when "18.scr" exists, as it
+ * did on the developers' machines.
+ */
+export declare const hostFiles: (vm: Vm) => Set<string>;

package/packages/sci/src/vm/kernels/system.js

@@ -0,0 +1,110 @@
+import { stringHelpers } from "./arrays.js";
+import { fromInt, toSigned } from "../value.js";
+/** SCI key codes for non-character keys: PC BIOS scan codes in the high byte. */
+export const SciKey = {
+    Home: 0x4700, Up: 0x4800, PageUp: 0x4900, Left: 0x4b00, Center: 0x4c00, Right: 0x4d00,
+    End: 0x4f00, Down: 0x5000, PageDown: 0x5100, Insert: 0x5200, Delete: 0x5300, ShiftTab: 0x0f00,
+    F1: 0x3b00, F2: 0x3c00, F3: 0x3d00, F4: 0x3e00, F5: 0x3f00, F6: 0x4000, F7: 0x4100, F8: 0x4200, F9: 0x4300, F10: 0x4400,
+};
+/** Keypad/arrow keys → SCI directions (1 = up, clockwise to 8 = up-left; 0 = stop). */
+const KEY_TO_DIRECTION = new Map([
+    [SciKey.Up, 1], [SciKey.PageUp, 2], [SciKey.Right, 3], [SciKey.PageDown, 4],
+    [SciKey.Down, 5], [SciKey.End, 6], [SciKey.Left, 7], [SciKey.Home, 8], [SciKey.Center, 0],
+]);
+/** SCI event types (SCI32). */
+// Direction = 0x10 in SCI2 (scripts test `type & $10`); SCI0 used 0x40.
+export const EventType = { Null: 0, MouseDown: 1, MouseUp: 2, KeyDown: 4, KeyUp: 8, Direction: 0x10, Quit: 0x400 };
+/** Input from the host (browser or test harness). */
+export class Input {
+    queue = [];
+    x = 160;
+    y = 100;
+    modifiers = 0;
+    push(e) {
+        this.queue.push({ x: this.x, y: this.y, modifiers: this.modifiers, ...e });
+    }
+}
+const inputOf = new WeakMap();
+export const input = (vm) => {
+    let i = inputOf.get(vm);
+    if (!i) {
+        const created = new Input();
+        inputOf.set(vm, (i = created));
+        vm.moveMouse ??= (x, y) => {
+            created.x = x;
+            created.y = y;
+        };
+    }
+    return i;
+};
+function shiftEvent(vm, event, plane, sign) {
+    if (!vm.memory.object(event) || !vm.memory.object(plane))
+        return 0;
+    const get = (o, n) => toSigned(vm.getProp(o, n) ?? 0);
+    vm.setProp(event, "x", fromInt(get(event, "x") + sign * get(plane, "inLeft")));
+    vm.setProp(event, "y", fromInt(get(event, "y") + sign * get(plane, "inTop")));
+    return 0;
+}
+/** Events, sound (stubbed for now), files and host information. */
+export const systemKernels = {
+    GetEvent: (vm, [mask = 0, event = 0]) => {
+        const inp = input(vm);
+        const index = inp.queue.findIndex((e) => (e.type & mask) !== 0);
+        const e = index >= 0 ? inp.queue.splice(index, 1)[0] : { type: EventType.Null, message: 0, modifiers: inp.modifiers, x: inp.x, y: inp.y };
+        vm.setProp(event, "type", e.type);
+        vm.setProp(event, "message", e.message);
+        vm.setProp(event, "modifiers", e.modifiers);
+        vm.setProp(event, "x", fromInt(e.x));
+        vm.setProp(event, "y", fromInt(e.y));
+        return e.type === EventType.Null ? 0 : 1;
+    },
+    // Convert an event's x/y between screen and plane-local coordinates.
+    GlobalToLocal: (vm, [event = 0, plane = 0]) => shiftEvent(vm, event, plane, -1),
+    LocalToGlobal: (vm, [event = 0, plane = 0]) => shiftEvent(vm, event, plane, 1),
+    // Turns an arrow/keypad key event into a direction event; 0 if it isn't one.
+    MapKeyToDir: (vm, [event = 0]) => {
+        if (vm.getProp(event, "type") !== EventType.KeyDown)
+            return undefined; // leave acc
+        const dir = KEY_TO_DIRECTION.get(vm.getProp(event, "message") ?? 0);
+        if (dir === undefined)
+            return 0;
+        vm.setProp(event, "type", EventType.Direction);
+        vm.setProp(event, "message", dir);
+        return 1;
+    },
+    VibrateMouse: () => 0,
+    SetQuitStr: () => 0,
+    GetCWD: (vm) => stringHelpers.newString(vm, "C:\\GAME"),
+    ValidPath: () => 1,
+    CheckFreeSpace: () => 1,
+    CheckCDisc: () => 1,
+    GetSaveCDisc: () => 1,
+    DeviceInfo: () => 0,
+    MemoryInfo: () => 0x7fff,
+    ResourceTrack: () => 0,
+    PreloadResource: () => 0,
+    Dummy: () => 0,
+    // No filesystem yet: opens fail (-1), which the scripts handle as "no config/saves".
+    FileIO: (vm, [op = 0, name = 0]) => {
+        switch (op) {
+            case 0: return 0xffff; // open
+            case 10: { // exists: only what the host says is there
+                const file = stringHelpers.str(vm, name).split(/[\\/]/).pop().toLowerCase();
+                return hostFiles(vm).has(file) ? 1 : 0;
+            }
+            default: return 0;
+        }
+    },
+};
+const hostFileSets = new WeakMap();
+/**
+ * Files the game may find with FileIO "exists" (lower-case names). A game may load Sierra's
+ * debug room (script 18: Alt-T teleport, Alt-G flags, Alt-I items...) when "18.scr" exists, as it
+ * did on the developers' machines.
+ */
+export const hostFiles = (vm) => {
+    let set = hostFileSets.get(vm);
+    if (!set)
+        hostFileSets.set(vm, (set = new Set()));
+    return set;
+};

package/packages/sci/src/vm/kernels/system.ts

@@ -0,0 +1,128 @@
+import type { KernelFn, Vm } from "../vm.ts";
+import { stringHelpers } from "./arrays.ts";
+import { fromInt, toSigned, type Value } from "../value.ts";
+
+/** SCI key codes for non-character keys: PC BIOS scan codes in the high byte. */
+export const SciKey = {
+  Home: 0x4700, Up: 0x4800, PageUp: 0x4900, Left: 0x4b00, Center: 0x4c00, Right: 0x4d00,
+  End: 0x4f00, Down: 0x5000, PageDown: 0x5100, Insert: 0x5200, Delete: 0x5300, ShiftTab: 0x0f00,
+  F1: 0x3b00, F2: 0x3c00, F3: 0x3d00, F4: 0x3e00, F5: 0x3f00, F6: 0x4000, F7: 0x4100, F8: 0x4200, F9: 0x4300, F10: 0x4400,
+} as const;
+
+/** Keypad/arrow keys → SCI directions (1 = up, clockwise to 8 = up-left; 0 = stop). */
+const KEY_TO_DIRECTION = new Map<number, number>([
+  [SciKey.Up, 1], [SciKey.PageUp, 2], [SciKey.Right, 3], [SciKey.PageDown, 4],
+  [SciKey.Down, 5], [SciKey.End, 6], [SciKey.Left, 7], [SciKey.Home, 8], [SciKey.Center, 0],
+]);
+
+/** SCI event types (SCI32). */
+// Direction = 0x10 in SCI2 (scripts test `type & $10`); SCI0 used 0x40.
+export const EventType = { Null: 0, MouseDown: 1, MouseUp: 2, KeyDown: 4, KeyUp: 8, Direction: 0x10, Quit: 0x400 } as const;
+
+export interface SciEvent {
+  type: number;
+  message: number;
+  modifiers: number;
+  x: number;
+  y: number;
+}
+
+/** Input from the host (browser or test harness). */
+export class Input {
+  readonly queue: SciEvent[] = [];
+  x = 160;
+  y = 100;
+  modifiers = 0;
+
+  push(e: Omit<SciEvent, "x" | "y" | "modifiers"> & Partial<SciEvent>): void {
+    this.queue.push({ x: this.x, y: this.y, modifiers: this.modifiers, ...e });
+  }
+}
+
+const inputOf = new WeakMap<Vm, Input>();
+export const input = (vm: Vm): Input => {
+  let i = inputOf.get(vm);
+  if (!i) {
+    const created = new Input();
+    inputOf.set(vm, (i = created));
+    vm.moveMouse ??= (x, y) => {
+      created.x = x;
+      created.y = y;
+    };
+  }
+  return i;
+};
+
+function shiftEvent(vm: Vm, event: Value, plane: Value, sign: number): Value {
+  if (!vm.memory.object(event) || !vm.memory.object(plane)) return 0;
+  const get = (o: Value, n: string) => toSigned(vm.getProp(o, n) ?? 0);
+  vm.setProp(event, "x", fromInt(get(event, "x") + sign * get(plane, "inLeft")));
+  vm.setProp(event, "y", fromInt(get(event, "y") + sign * get(plane, "inTop")));
+  return 0;
+}
+
+/** Events, sound (stubbed for now), files and host information. */
+export const systemKernels: Record<string, KernelFn> = {
+  GetEvent: (vm, [mask = 0, event = 0]) => {
+    const inp = input(vm);
+    const index = inp.queue.findIndex((e) => (e.type & mask) !== 0);
+    const e = index >= 0 ? inp.queue.splice(index, 1)[0]! : { type: EventType.Null, message: 0, modifiers: inp.modifiers, x: inp.x, y: inp.y };
+    vm.setProp(event, "type", e.type);
+    vm.setProp(event, "message", e.message);
+    vm.setProp(event, "modifiers", e.modifiers);
+    vm.setProp(event, "x", fromInt(e.x));
+    vm.setProp(event, "y", fromInt(e.y));
+    return e.type === EventType.Null ? 0 : 1;
+  },
+  // Convert an event's x/y between screen and plane-local coordinates.
+  GlobalToLocal: (vm, [event = 0, plane = 0]) => shiftEvent(vm, event, plane, -1),
+  LocalToGlobal: (vm, [event = 0, plane = 0]) => shiftEvent(vm, event, plane, 1),
+  // Turns an arrow/keypad key event into a direction event; 0 if it isn't one.
+  MapKeyToDir: (vm, [event = 0]) => {
+    if (vm.getProp(event, "type") !== EventType.KeyDown) return undefined; // leave acc
+    const dir = KEY_TO_DIRECTION.get(vm.getProp(event, "message") ?? 0);
+    if (dir === undefined) return 0;
+    vm.setProp(event, "type", EventType.Direction);
+    vm.setProp(event, "message", dir);
+    return 1;
+  },
+  VibrateMouse: () => 0,
+
+  SetQuitStr: () => 0,
+  GetCWD: (vm) => stringHelpers.newString(vm, "C:\\GAME"),
+  ValidPath: () => 1,
+  CheckFreeSpace: () => 1,
+  CheckCDisc: () => 1,
+  GetSaveCDisc: () => 1,
+  DeviceInfo: () => 0,
+  MemoryInfo: () => 0x7fff,
+  ResourceTrack: () => 0,
+  PreloadResource: () => 0,
+  Dummy: () => 0,
+
+  // No filesystem yet: opens fail (-1), which the scripts handle as "no config/saves".
+  FileIO: (vm, [op = 0, name = 0]) => {
+    switch (op) {
+      case 0: return 0xffff; // open
+      case 10: { // exists: only what the host says is there
+        const file = stringHelpers.str(vm, name).split(/[\\/]/).pop()!.toLowerCase();
+        return hostFiles(vm).has(file) ? 1 : 0;
+      }
+      default: return 0;
+    }
+  },
+};
+
+export type { Value };
+
+const hostFileSets = new WeakMap<Vm, Set<string>>();
+/**
+ * Files the game may find with FileIO "exists" (lower-case names). A game may load Sierra's
+ * debug room (script 18: Alt-T teleport, Alt-G flags, Alt-I items...) when "18.scr" exists, as it
+ * did on the developers' machines.
+ */
+export const hostFiles = (vm: Vm): Set<string> => {
+  let set = hostFileSets.get(vm);
+  if (!set) hostFileSets.set(vm, (set = new Set()));
+  return set;
+};

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

@@ -0,0 +1,13 @@
+import type { KernelFn, Vm } from "../vm.ts";
+/** For replaceResources: forget parsed message files. */
+export declare const forgetMessages: (vm: Vm) => void;
+/**
+ * Sierra text escapes: `\xx` (two hex digits) is a character code, e.g. `\1d`/`\1e` are the
+ * arrow glyphs on dialog scroll buttons.
+ */
+export declare const unescapeText: (s: string) => string;
+/**
+ * SCI32 text: scripts measure text (TextSize), render it into an off-screen bitmap
+ * (CreateTextBitmap) and show that bitmap as a screen item via the object's `bitmap`.
+ */
+export declare const textKernels: Record<string, KernelFn>;