sci2-ts 0.0.0-stage → 0.2.2

package/apps/viewer/src/play.ts

@@ -0,0 +1,177 @@
+import { activeMods, availableMods, openGame, rememberMods } from "./files.ts";
+import { GameSession } from "./session.ts";
+import { ResourceType, gameGlobal, heroInPlay, requestRoom, saves, savesToJson, type MemorySaveStore } from "../../../packages/sci/src/index.ts";
+import { APP_ID } from "./app.ts";
+import { gameProfile } from "./game-profile.ts";
+
+const canvas = document.getElementById("screen") as HTMLCanvasElement;
+const status = document.getElementById("status")!;
+const errorBox = document.getElementById("error")!;
+const musicButton = document.getElementById("music") as HTMLButtonElement;
+
+// Mods (?mods=a,b or the last choice) load as patch directories over the game.
+const { rm, mods } = await openGame();
+// `?mute` keeps audio off (e.g. automated testing in a background tab).
+const params = new URLSearchParams(location.search);
+// `?debug` turns on Sierra's own debug room (Alt-T teleport, Alt-G flags, Alt-I items...).
+const session = await GameSession.create({ canvas, rm, mods, muted: params.has("mute"), debug: params.has("debug") });
+await setUpModPicker();
+// For poking at the running game from the browser console (and automated checks).
+(window as unknown as { sci: unknown }).sci = { session };
+
+// Saved games as a JSON file, to replay them headlessly (tools/explore.ts loadsaves:<file>).
+document.getElementById("export-saves")!.addEventListener("click", () => {
+  const store = saves(session.vm).store as MemorySaveStore;
+  const a = document.createElement("a");
+  a.href = URL.createObjectURL(new Blob([savesToJson([...store.saves.values()])], { type: "application/json" }));
+  a.download = `${APP_ID}-saves${mods.length ? `-${mods.join("+")}` : ""}.json`;
+  a.click();
+  URL.revokeObjectURL(a.href);
+});
+const startRoom = /^#room\/(\d+)$/.exec(location.hash) ? Number(location.hash.slice(6)) : undefined;
+/** What room navigation is doing, shown on the status line. */
+let roomStatus: string | undefined;
+setUpRoomNavigation();
+
+/**
+ * Rooms in the address bar: `#room/250` goes there. Opened that way, the game doesn't make
+ * you sit through the intro: it loads your newest saved game (your hero, your progress), or
+ * with none (or `?fresh`), fast-forwards through character creation to a new Wizard called
+ * Hero. Then it jumps. Editing the hash jumps again, and Back returns to the last jump; the
+ * hash follows the game's own room changes without adding history entries.
+ */
+function setUpRoomNavigation() {
+  /** The room asked for, kept until the game gets there (or gives up). */
+  let wanted: { room: number; since: number } | undefined;
+  let shown = 0;
+  const readHash = () => {
+    const m = /^#room\/(\d+)$/.exec(location.hash);
+    if (!m) return;
+    const room = Number(m[1]);
+    if (room === shown && !wanted) return; // the hash we wrote ourselves
+    if (!rm.has({ type: ResourceType.Script, number: room })) {
+      roomStatus = `There's no room ${room}`;
+      return;
+    }
+    wanted = { room, since: performance.now() };
+  };
+  readHash();
+  // Editing the address bar fires hashchange (and popstate, in some browsers and for Back).
+  addEventListener("hashchange", readHash);
+  addEventListener("popstate", readHash);
+
+  session.onDraw.push(() => {
+    const vm = session.vm;
+    // The 20 s allowance only counts while a hero is in play (making one takes a while).
+    if (session.fastForwarding || !heroInPlay(vm)) {
+      if (wanted) wanted.since = performance.now();
+      if (session.fastForwarding) return;
+    }
+    const room = gameGlobal(vm, "curRoomNum") ?? 0;
+    if (wanted) {
+      if (room === wanted.room) {
+        roomStatus = undefined;
+        wanted = undefined;
+      } else if (!heroInPlay(vm)) {
+        roomStatus = `Room ${wanted.room}: waiting for a hero (create one, or restore a save)`;
+      } else if (performance.now() - wanted.since > 20_000) {
+        roomStatus = `Couldn't get to room ${wanted.room} (the game didn't leave room ${room})`;
+        wanted = undefined;
+      } else {
+        // Ask again every frame: while a message or a scripted scene holds the game, its
+        // main loop isn't checking, and a room may reset the request when it starts.
+        requestRoom(vm, wanted.room);
+        roomStatus = performance.now() - wanted.since > 1500
+          ? `Going to room ${wanted.room}… (close any message on screen)`
+          : `Going to room ${wanted.room}…`;
+      }
+    }
+    if (room && room !== shown && heroInPlay(vm)) {
+      shown = room;
+      if (location.hash !== `#room/${room}`) history.replaceState(null, "", `#room/${room}`);
+    }
+  });
+}
+
+/** How a `#room/N` visit gets a hero: the newest save, or a quick new one. */
+const quickStart = gameProfile(session.vm)?.quickStart(session.vm);
+
+function startGame() {
+  const store = saves(session.vm).store;
+  const info = params.has("fresh") ? undefined : store.list()[0];
+  const newest = info && store.get(info.id);
+  if (startRoom === undefined) return session.start();
+  if (newest) {
+    status.textContent = `Loading "${newest.info.description}" to go to room ${startRoom}…`;
+    session.start();
+    // Restore once the game is up (it needs its first frame to exist), like the game's own Restore.
+    let done = false;
+    session.onDraw.push(() => {
+      if (done) return;
+      done = true;
+      session.restore(newest.snapshot);
+    });
+    return;
+  }
+  if (!quickStart) {
+    status.textContent = `Play until your character can walk around, then it goes to room ${startRoom}`;
+    return session.start();
+  }
+  status.textContent = `Creating a hero to go to room ${startRoom}…`;
+  session.start({ fastForward: quickStart });
+}
+
+/** Checkboxes for the built mods; applying reloads the page with the new set. */
+async function setUpModPicker() {
+  const list = document.getElementById("mod-list")!;
+  const apply = document.getElementById("mods-apply") as HTMLButtonElement;
+  const summary = document.querySelector("#mods summary")!;
+  const built = await availableMods();
+  const on = new Set(activeMods());
+  summary.textContent = on.size ? `Mods: ${[...on].join(", ")}` : "Mods";
+  if (!built.length) {
+    list.innerHTML = '<span class="none">No mods built. Try <code>pnpm mod build mods/altar-hello</code>.</span>';
+    apply.hidden = true;
+    return;
+  }
+  for (const name of built) {
+    const box = Object.assign(document.createElement("input"), { type: "checkbox", checked: on.has(name), value: name });
+    const label = document.createElement("label");
+    label.append(box, ` ${name}`);
+    list.append(label);
+  }
+  apply.addEventListener("click", () => {
+    const chosen = [...list.querySelectorAll<HTMLInputElement>("input:checked")].map((b) => b.value);
+    rememberMods(chosen);
+    const url = new URL(location.href);
+    url.searchParams.set("mods", chosen.join(","));
+    location.href = url.toString();
+  });
+}
+
+const showMusicMode = () =>
+  (musicButton.textContent = session.musicMode === "adlib" ? "Music: AdLib (OPL2 FM, 1994 Sound Blaster)" : "Music: General MIDI (SoundFont)");
+musicButton.addEventListener("click", () => {
+  if (session.hasAdLib) session.setMusicMode(session.musicMode === "adlib" ? "gm" : "adlib");
+  showMusicMode();
+});
+showMusicMode();
+
+let lastStatus = 0;
+session.onDraw.push(() => {
+  if (session.error) {
+    errorBox.hidden = false;
+    errorBox.textContent = `${session.error.message}\n${session.error.backtrace.map((l) => `  at ${l}`).join("\n")}`;
+    return;
+  }
+  const now = performance.now();
+  if (session.fastForwarding) {
+    if (now - lastStatus > 250) (status.textContent = `Creating a hero… (${Math.min(100, Math.round((session.frames / (quickStart?.until ?? 1)) * 100))}%)`), (lastStatus = now);
+    return;
+  }
+  if (now - lastStatus < 1000) return;
+  lastStatus = now;
+  status.textContent = !session.vm.running ? "Game exited." : roomStatus ?? `${session.fps} fps · ${session.vm.instructions.toLocaleString()} instructions${mods.length ? ` · mods: ${mods.join(", ")}` : ""}${params.has("debug") ? " · debug: Alt-T teleport" : ""}${session.musicMode === "gm" && !session.music.ready ? " · SoundFont loading" : ""}`;
+});
+status.textContent = "Running";
+startGame();

package/apps/viewer/src/saves.d.ts

@@ -0,0 +1,10 @@
+import { MemorySaveStore } from "../../../packages/sci/src/index.ts";
+/**
+ * Saved games in IndexedDB (per browser, survive reloads). Kernels need synchronous access,
+ * so everything is loaded into a MemorySaveStore at startup and writes go through to disk.
+ *
+ * A save is a snapshot of the running scripts, so it only fits the scripts it was made with:
+ * each set of mods gets its own saves (`namespace`, e.g. "altar-hello"). The unmodded game
+ * keeps plain numeric keys, as before namespaces existed.
+ */
+export declare function browserSaveStore(namespace?: string): Promise<MemorySaveStore>;

package/apps/viewer/src/saves.js

@@ -0,0 +1,50 @@
+import { APP_ID } from "./app.js";
+import { MemorySaveStore } from "../../../packages/sci/src/index.js";
+const DB = APP_ID;
+const STORE = "saves";
+function open() {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(DB, 1);
+        req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+/**
+ * Saved games in IndexedDB (per browser, survive reloads). Kernels need synchronous access,
+ * so everything is loaded into a MemorySaveStore at startup and writes go through to disk.
+ *
+ * A save is a snapshot of the running scripts, so it only fits the scripts it was made with:
+ * each set of mods gets its own saves (`namespace`, e.g. "altar-hello"). The unmodded game
+ * keeps plain numeric keys, as before namespaces existed.
+ */
+export async function browserSaveStore(namespace = "") {
+    const store = new MemorySaveStore();
+    const key = (id) => (namespace ? `${namespace}:${id}` : id);
+    const mine = (k) => (namespace ? typeof k === "string" && k.startsWith(`${namespace}:`) : typeof k === "number");
+    let db;
+    try {
+        db = await open();
+        await new Promise((resolve, reject) => {
+            const req = db.transaction(STORE).objectStore(STORE).openCursor();
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (!cursor)
+                    return resolve();
+                if (mine(cursor.key)) {
+                    const save = cursor.value;
+                    store.saves.set(save.info.id, save);
+                }
+                cursor.continue();
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    catch (e) {
+        console.warn("Saved games unavailable (IndexedDB blocked?); saves will last until reload.", e);
+    }
+    store.onWrite = (info, snapshot) => {
+        db?.transaction(STORE, "readwrite").objectStore(STORE).put({ info, snapshot }, key(info.id));
+    };
+    return store;
+}

package/apps/viewer/src/saves.ts

@@ -0,0 +1,51 @@
+import { APP_ID } from "./app.ts";
+import { MemorySaveStore, type SaveInfo, type VmSnapshot } from "../../../packages/sci/src/index.ts";
+
+const DB = APP_ID;
+const STORE = "saves";
+
+function open(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+/**
+ * Saved games in IndexedDB (per browser, survive reloads). Kernels need synchronous access,
+ * so everything is loaded into a MemorySaveStore at startup and writes go through to disk.
+ *
+ * A save is a snapshot of the running scripts, so it only fits the scripts it was made with:
+ * each set of mods gets its own saves (`namespace`, e.g. "altar-hello"). The unmodded game
+ * keeps plain numeric keys, as before namespaces existed.
+ */
+export async function browserSaveStore(namespace = ""): Promise<MemorySaveStore> {
+  const store = new MemorySaveStore();
+  const key = (id: number): IDBValidKey => (namespace ? `${namespace}:${id}` : id);
+  const mine = (k: IDBValidKey) => (namespace ? typeof k === "string" && k.startsWith(`${namespace}:`) : typeof k === "number");
+  let db: IDBDatabase | undefined;
+  try {
+    db = await open();
+    await new Promise<void>((resolve, reject) => {
+      const req = db!.transaction(STORE).objectStore(STORE).openCursor();
+      req.onsuccess = () => {
+        const cursor = req.result;
+        if (!cursor) return resolve();
+        if (mine(cursor.key)) {
+          const save = cursor.value as { info: SaveInfo; snapshot: VmSnapshot };
+          store.saves.set(save.info.id, save);
+        }
+        cursor.continue();
+      };
+      req.onerror = () => reject(req.error);
+    });
+  } catch (e) {
+    console.warn("Saved games unavailable (IndexedDB blocked?); saves will last until reload.", e);
+  }
+  store.onWrite = (info, snapshot) => {
+    db?.transaction(STORE, "readwrite").objectStore(STORE).put({ info, snapshot }, key(info.id));
+  };
+  return store;
+}

package/apps/viewer/src/session.d.ts

@@ -0,0 +1,91 @@
+import { ResourceManager, Vm, type VmSnapshot } from "../../../packages/sci/src/index.ts";
+import { WebAudioOutput } from "./audio.ts";
+import { SoundFontMidi } from "./music.ts";
+export type MusicMode = "gm" | "adlib";
+export interface SessionOptions {
+    canvas: HTMLCanvasElement;
+    /** Reuse an open resource manager (it gets preloaded). */
+    rm?: ResourceManager;
+    /** Active mods: saves are kept apart per set of mods. */
+    mods?: string[];
+    /** Keep saves under this name instead (the editor's, apart from playing). */
+    saveNamespace?: string;
+    /**
+     * Sierra's debug room, which the game loads when a file "18.scr" exists (their machines had one).
+     * Alt-T teleports, Alt-G sets flags, Alt-I gives items, Alt-H sets the hour... (Alt-? lists).
+     */
+    debug?: boolean;
+    /** Start with audio suspended; `setMuted(false)` turns it on. */
+    muted?: boolean;
+    /**
+     * Keep running when the page isn't painted (a hidden tab or pane), where
+     * requestAnimationFrame stops: a timer takes over. For automated testing.
+     */
+    runHidden?: boolean;
+    /**
+     * Called for canvas mouse-downs before the game sees them; return true to swallow the
+     * click (the explorer's inspect mode). Coordinates are game screen pixels.
+     */
+    interceptClick?: (x: number, y: number, e: MouseEvent) => boolean;
+}
+/**
+ * One running game in a canvas: VM, audio, input and the frame loop. The player page and
+ * the explorer's live view both run the game through this.
+ */
+export declare class GameSession {
+    readonly rm: ResourceManager;
+    readonly vm: Vm;
+    readonly canvas: HTMLCanvasElement;
+    readonly sound: WebAudioOutput;
+    readonly music: SoundFontMidi;
+    /** Only for games with an AdLib instrument bank (patch 3). */
+    private readonly adlib;
+    private readonly options;
+    paused: boolean;
+    /** Game frames run so far. */
+    frames: number;
+    fps: number;
+    error: {
+        message: string;
+        backtrace: string[];
+    } | undefined;
+    /** After each drawn browser frame. */
+    readonly onDraw: (() => void)[];
+    private latest;
+    private readonly ctx;
+    private readonly image;
+    private musicModeValue;
+    private stepsOwed;
+    private constructor();
+    static create(options: SessionOptions): Promise<GameSession>;
+    get musicMode(): MusicMode;
+    /** Whether the game can play its AdLib tracks (it has an instrument bank). */
+    get hasAdLib(): boolean;
+    setMusicMode(mode: MusicMode): void;
+    muted: boolean;
+    /** Browsers keep audio suspended until a user gesture: unmuted, the next gesture unlocks it. */
+    setMuted(muted: boolean): void;
+    /** True while `start({ fastForward })` is still running ahead. */
+    fastForwarding: boolean;
+    /**
+     * Starts the game and the frame loop. With `fastForward`, the game first runs as fast as
+     * it can on a frame clock (60 frames = 1 second of game time), from the very first frame,
+     * with `script[n]` called before frame n (scripted input) until frame `until`; audio is
+     * silent meanwhile. Then real time takes over, continuing the clock where it was.
+     */
+    start(options?: {
+        fastForward?: {
+            script: Record<number, () => void>;
+            until: number;
+            done?: () => void;
+        };
+    }): void;
+    /** While paused: run `n` game frames on the next tick. */
+    step(n?: number): void;
+    snapshot(): VmSnapshot;
+    /** Like the game's own restore: replace memory, then restart execution with `replay`. */
+    /** Loads a snapshot as the game's own Restore does (see `restoreGame`). */
+    restore(snap: VmSnapshot): void;
+    private draw;
+    private attachInput;
+}

package/apps/viewer/src/session.js

@@ -0,0 +1,301 @@
+import { EventType, ResourceManager, ResourceType, SciKey, SoundDevice, Vm, allKernels, audio, graphics, hostFiles, input, parseAdLibBank, readingTime, restoreGame, saves, snapshot, } from "../../../packages/sci/src/index.js";
+import { AdLibOutput } from "./adlib.js";
+import { WebAudioOutput } from "./audio.js";
+import { BASE, httpFiles } from "./files.js";
+import { SoundFontMidi } from "./music.js";
+import { APP_ID } from "./app.js";
+import { browserSaveStore } from "./saves.js";
+/**
+ * One running game in a canvas: VM, audio, input and the frame loop. The player page and
+ * the explorer's live view both run the game through this.
+ */
+export class GameSession {
+    rm;
+    vm;
+    canvas;
+    sound;
+    music;
+    adlib;
+    options;
+    paused = false;
+    /** Game frames run so far. */
+    frames = 0;
+    fps = 0;
+    error;
+    /** After each drawn browser frame. */
+    onDraw = [];
+    latest;
+    ctx;
+    image;
+    musicModeValue = "gm";
+    stepsOwed = 0;
+    constructor(rm, vm, canvas, sound, music, 
+    /** Only for games with an AdLib instrument bank (patch 3). */
+    adlib, options) {
+        this.rm = rm;
+        this.vm = vm;
+        this.canvas = canvas;
+        this.sound = sound;
+        this.music = music;
+        this.adlib = adlib;
+        this.options = options;
+        this.ctx = canvas.getContext("2d");
+        this.image = this.ctx.createImageData(320, 200);
+    }
+    static async create(options) {
+        const rm = options.rm ?? (await ResourceManager.open(httpFiles));
+        await rm.preload();
+        const vm = new Vm(rm);
+        vm.registerKernels(allKernels);
+        // Saved games persist in this browser (IndexedDB) and appear in the game's Restore screen.
+        saves(vm).store = await browserSaveStore(options.saveNamespace ?? [...(options.mods ?? [])].sort().join("+"));
+        if (options.debug)
+            hostFiles(vm).add("18.scr");
+        const sound = new WebAudioOutput(httpFiles, (name) => rm.file(name));
+        audio(vm).output = sound;
+        // Mods add dialogue without recordings: give those lines time to be read.
+        if (options.mods?.length)
+            audio(vm).missingSpeechTicks = readingTime(vm);
+        // Music: General MIDI through a SoundFont (loads in the background), or the AdLib track
+        // through Sierra's driver and an OPL2 emulator: what most players heard in 1994.
+        const music = new SoundFontMidi(sound.ctx);
+        music.load(`${BASE}soundfonts/GeneralUser-GS.sf2`).catch((e) => console.warn("SoundFont unavailable:", e));
+        const bank = { type: ResourceType.Patch, number: 3 };
+        const adlib = rm.has(bank) ? await AdLibOutput.create(sound.ctx, parseAdLibBank(rm.loadSync(bank).data)) : undefined;
+        const session = new GameSession(rm, vm, options.canvas, sound, music, adlib, options);
+        graphics(vm).onFrame = (f) => (session.latest = f);
+        session.setMusicMode(readMusicMode());
+        session.setMuted(!!options.muted);
+        session.attachInput();
+        for (const type of ["pointerdown", "keydown"])
+            window.addEventListener(type, () => session.muted || sound.unlock());
+        return session;
+    }
+    get musicMode() {
+        return this.musicModeValue;
+    }
+    /** Whether the game can play its AdLib tracks (it has an instrument bank). */
+    get hasAdLib() {
+        return !!this.adlib;
+    }
+    setMusicMode(mode) {
+        if (!this.adlib)
+            mode = "gm";
+        this.musicModeValue = mode;
+        this.adlib?.reset();
+        if (mode === "adlib" && this.adlib)
+            audio(this.vm).setMusicDevice(SoundDevice.AdLib, this.adlib);
+        else
+            audio(this.vm).setMusicDevice(SoundDevice.GeneralMidi, this.music);
+        try {
+            localStorage.setItem(`${APP_ID}.music`, mode);
+        }
+        catch {
+            /* private mode: just don't remember */
+        }
+    }
+    muted = false;
+    /** Browsers keep audio suspended until a user gesture: unmuted, the next gesture unlocks it. */
+    setMuted(muted) {
+        this.muted = muted;
+        if (muted)
+            void this.sound.ctx.suspend();
+        else
+            this.sound.unlock();
+    }
+    /** True while `start({ fastForward })` is still running ahead. */
+    fastForwarding = false;
+    /**
+     * Starts the game and the frame loop. With `fastForward`, the game first runs as fast as
+     * it can on a frame clock (60 frames = 1 second of game time), from the very first frame,
+     * with `script[n]` called before frame n (scripted input) until frame `until`; audio is
+     * silent meanwhile. Then real time takes over, continuing the clock where it was.
+     */
+    start(options = {}) {
+        this.vm.start(this.vm.exportAddress(0, 0), "play");
+        const ff = options.fastForward;
+        const g = graphics(this.vm);
+        if (ff) {
+            this.fastForwarding = true;
+            this.vm.clock = () => (g.frames * 1000) / 60;
+            void this.sound.ctx.suspend();
+        }
+        const finishFastForward = () => {
+            this.fastForwarding = false;
+            const base = (g.frames * 1000) / 60, t0 = performance.now();
+            this.vm.clock = () => base + (performance.now() - t0);
+            if (!this.muted)
+                this.sound.unlock();
+            ff?.done?.();
+        };
+        let prev = performance.now();
+        let lastFps = prev;
+        let counted = 0;
+        // SCI32 games expect ~60 FrameOuts per second. If the browser ticks slower (a hidden tab,
+        // a slow machine), run several game frames per tick to catch up, up to a cap.
+        const FRAME_MS = 1000 / 60;
+        let owed = 0;
+        const tick = (now) => {
+            try {
+                if (this.fastForwarding && ff) {
+                    // As many frames as fit in ~30 ms, then draw so the page stays responsive.
+                    const stop = performance.now() + 30;
+                    while (g.frames < ff.until && this.vm.running && performance.now() < stop) {
+                        ff.script[g.frames]?.();
+                        this.vm.run();
+                        this.frames++;
+                    }
+                    if (g.frames >= ff.until)
+                        finishFastForward();
+                    prev = now;
+                }
+                owed = this.paused || this.fastForwarding ? 0 : Math.min(owed + (now - prev) / FRAME_MS, 30);
+                prev = now;
+                let steps = this.paused ? this.stepsOwed : 0;
+                this.stepsOwed = 0;
+                while ((owed >= 1 || steps > 0) && this.vm.running) {
+                    this.vm.run();
+                    this.frames++;
+                    counted++;
+                    if (steps > 0)
+                        steps--;
+                    else
+                        owed--;
+                }
+                if (this.latest)
+                    this.draw(this.latest);
+                for (const hook of this.onDraw)
+                    hook();
+                if (now - lastFps > 1000) {
+                    this.fps = counted;
+                    counted = 0;
+                    lastFps = now;
+                }
+                if (this.vm.running)
+                    schedule();
+            }
+            catch (e) {
+                this.error = { message: e.message, backtrace: this.vm.backtrace() };
+                console.error(e);
+                for (const hook of this.onDraw)
+                    hook();
+            }
+        };
+        // One tick per animation frame; with runHidden, a timer fires it if frames stop coming.
+        let pending = false;
+        const fire = (now) => {
+            if (!pending)
+                return;
+            pending = false;
+            tick(now);
+        };
+        const schedule = () => {
+            pending = true;
+            requestAnimationFrame(fire);
+            if (this.options.runHidden)
+                setTimeout(() => fire(performance.now()), 50);
+        };
+        schedule();
+    }
+    /** While paused: run `n` game frames on the next tick. */
+    step(n = 1) {
+        this.stepsOwed += n;
+    }
+    snapshot() {
+        return snapshot(this.vm);
+    }
+    /** Like the game's own restore: replace memory, then restart execution with `replay`. */
+    /** Loads a snapshot as the game's own Restore does (see `restoreGame`). */
+    restore(snap) {
+        restoreGame(this.vm, snap);
+    }
+    draw(f) {
+        const { pixels, palette, rgb } = f;
+        const data = this.image.data;
+        for (let i = 0; i < pixels.length; i++) {
+            // Mid-transition frames carry RGB directly; otherwise look colours up in the palette.
+            const src = rgb ?? palette.rgb;
+            const c = rgb ? i * 3 : pixels[i] * 3;
+            data[i * 4] = src[c];
+            data[i * 4 + 1] = src[c + 1];
+            data[i * 4 + 2] = src[c + 2];
+            data[i * 4 + 3] = 255;
+        }
+        this.ctx.putImageData(this.image, 0, 0);
+    }
+    // --- Input: map page coordinates to the 320×200 game screen ---------------------
+    attachInput() {
+        const { canvas } = this;
+        const inp = input(this.vm);
+        const toGame = (e) => {
+            const r = canvas.getBoundingClientRect();
+            return {
+                x: Math.max(0, Math.min(319, Math.floor(((e.clientX - r.left) / r.width) * 320))),
+                y: Math.max(0, Math.min(199, Math.floor(((e.clientY - r.top) / r.height) * 200))),
+            };
+        };
+        // While a fast-forward plays its script, the player's mouse and keys stay out of it: a
+        // queued click reads the mouse position when the game gets to it, so a real mouse move in
+        // between would send the scripted click wherever the pointer is.
+        const track = (e) => {
+            if (!this.fastForwarding)
+                ({ x: inp.x, y: inp.y } = toGame(e));
+        };
+        let swallowed = false;
+        canvas.addEventListener("mousemove", track);
+        canvas.addEventListener("contextmenu", (e) => e.preventDefault());
+        canvas.addEventListener("mousedown", (e) => {
+            if (this.fastForwarding)
+                return;
+            const { x, y } = toGame(e);
+            swallowed = !!this.options.interceptClick?.(x, y, e);
+            if (swallowed)
+                return;
+            track(e);
+            // SCI reports the right button as a click with shift held.
+            inp.push({ type: EventType.MouseDown, message: 0, modifiers: e.button === 2 ? 3 : 0 });
+        });
+        canvas.addEventListener("mouseup", (e) => {
+            if (swallowed || this.fastForwarding)
+                return;
+            track(e);
+            inp.push({ type: EventType.MouseUp, message: 0 });
+        });
+        window.addEventListener("keydown", (e) => {
+            if (e.metaKey || !canvas.isConnected || this.fastForwarding)
+                return; // leave browser shortcuts alone
+            // Typing into the page's own inputs (search boxes, the room editor) isn't for the game.
+            const target = e.target;
+            if (target && (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.tagName === "SELECT" || target.isContentEditable))
+                return;
+            // DOS reports Alt+letter as the key's scan code in the high byte (Alt-T = 0x1400); use
+            // the physical key, since on a Mac Alt changes the character (Alt-T types "†").
+            const scan = e.altKey ? ALT_SCAN_CODES[e.code] : undefined;
+            const code = scan ? scan << 8 : e.key === "Tab" && e.shiftKey ? SciKey.ShiftTab : KEY_CODES[e.key] ?? (e.key.length === 1 ? e.key.charCodeAt(0) : 0);
+            if (!code)
+                return;
+            e.preventDefault();
+            inp.push({ type: EventType.KeyDown, message: code, modifiers: modifiers(e) });
+        });
+    }
+}
+const KEY_CODES = {
+    Enter: 13, Escape: 27, Backspace: 8, Tab: 9, " ": 32,
+    ArrowUp: SciKey.Up, ArrowDown: SciKey.Down, ArrowLeft: SciKey.Left, ArrowRight: SciKey.Right,
+    Home: SciKey.Home, End: SciKey.End, PageUp: SciKey.PageUp, PageDown: SciKey.PageDown,
+    Insert: SciKey.Insert, Delete: SciKey.Delete, Clear: SciKey.Center,
+    F1: SciKey.F1, F2: SciKey.F2, F3: SciKey.F3, F4: SciKey.F4, F5: SciKey.F5,
+    F6: SciKey.F6, F7: SciKey.F7, F8: SciKey.F8, F9: SciKey.F9, F10: SciKey.F10,
+};
+/** PC scan codes for the letter keys (Alt+letter). */
+const ALT_SCAN_CODES = Object.fromEntries([..."QWERTYUIOP"].map((k, i) => [`Key${k}`, 0x10 + i]).concat([..."ASDFGHJKL"].map((k, i) => [`Key${k}`, 0x1e + i]), [..."ZXCVBNM"].map((k, i) => [`Key${k}`, 0x2c + i])));
+/** SCI modifier bits: 3 = shift (both), 4 = ctrl, 8 = alt. */
+const modifiers = (e) => (e.shiftKey ? 3 : 0) | (e.ctrlKey ? 4 : 0) | (e.altKey ? 8 : 0);
+function readMusicMode() {
+    try {
+        return localStorage.getItem(`${APP_ID}.music`) === "adlib" ? "adlib" : "gm";
+    }
+    catch {
+        return "gm";
+    }
+}