sci2-ts 0.0.0-stage → 0.2.2

package/packages/sci/src/analysis/game.ts

@@ -0,0 +1,305 @@
+import type { ResourceManager } from "../resource/manager.ts";
+import { ResourceType } from "../resource/types.ts";
+import { disassemble, type DisasmFunction, type ValueFact } from "../script/disasm.ts";
+import { kernelNames } from "../script/kernel-names.ts";
+import { ObjectSlot, type Script, type ScriptObject } from "../script/script.ts";
+import { ScriptWorld } from "../script/world.ts";
+
+/**
+ * A static map of a game, built from its scripts alone: which scripts are rooms, how rooms
+ * connect, the class hierarchy and every object. Nothing runs; facts come from the
+ * disassembler's stack simulation, so anything computed at run time is missed (and marked
+ * as such where we can tell).
+ */
+export interface GameIndex {
+  rooms: RoomInfo[];
+  exits: Exit[];
+  /** Exits whose target isn't a room script (maze codes, cut rooms). */
+  unresolved: Exit[];
+  classes: ClassInfo[];
+  scripts: ScriptInfo[];
+  /**
+   * Verb names, guessed from the objects that send them: icons, inventory items and spells
+   * keep their verb in `message` (iconLook → 1, theCloth → 54).
+   */
+  verbs: Record<number, string>;
+}
+
+export interface RoomInfo {
+  number: number;
+  /** The room object's name, e.g. "rm710". */
+  name: string;
+  className: string;
+  picture: number;
+  noun: number;
+  /** Scripts this room loads (ScriptID and export calls), which may hold more of its logic. */
+  uses: number[];
+}
+
+/**
+ * How we know two rooms connect:
+ *   newRoom    `curRoom newRoom: N` with a constant
+ *   script     a script object calls `newRoom: register`, started with `setScript: s 0 N`
+ *   property   `newRoom:` with one of the object's own properties (exit features)
+ *   direction  the room's north/south/east/west property
+ *   entry      the target room checks `prevRoomNum == N`: it can be entered from N
+ */
+export type ExitKind = "newRoom" | "script" | "property" | "direction" | "entry";
+
+export interface Exit {
+  from: number;
+  to: number;
+  kind: ExitKind;
+  /** The script whose code holds the evidence (may be a helper, not `from` itself). */
+  script: number;
+  /** Method or procedure label, e.g. "sExit::changeState". */
+  where: string;
+}
+
+export interface PropValue {
+  name: string;
+  value: number;
+}
+
+export interface ClassInfo {
+  species: number;
+  name: string;
+  script: number;
+  /** Superclass species, or -1 for a root class. */
+  superclass: number;
+  props: PropValue[];
+  methods: string[];
+}
+
+export interface ObjectInfo {
+  name: string;
+  script: number;
+  /** Heap offset in its script: identifies the object. */
+  offset: number;
+  superclass: number;
+  className: string;
+  props: PropValue[];
+  methods: string[];
+}
+
+export interface ScriptInfo {
+  number: number;
+  isRoom: boolean;
+  objects: ObjectInfo[];
+  /** Other scripts referenced by ScriptID or export calls. */
+  references: number[];
+}
+
+export interface AnalyzeOptions {
+  /** Globals the room logic uses; SCI's system scripts fix these. */
+  curRoomGlobal?: number;
+  prevRoomGlobal?: number;
+  /** Class every room inherits from. */
+  roomClass?: string;
+  /** Reuse a world (and its loaded scripts), e.g. to disassemble on demand afterwards. */
+  world?: ScriptWorld;
+  onProgress?: (done: number, total: number) => void;
+}
+
+/** The objects' header slots aren't interesting to show as properties. */
+const HEADER_SLOTS = ObjectSlot.Name + 1;
+const DIRECTIONS = ["north", "east", "south", "west"];
+
+export async function analyzeGame(rm: ResourceManager, options: AnalyzeOptions = {}): Promise<GameIndex> {
+  const { prevRoomGlobal = 12, roomClass = "Room", onProgress } = options;
+  const world = options.world ?? (await ScriptWorld.open(rm));
+  await world.loadAllClasses();
+  const ctx = world.context();
+  const selector = (name: string) => world.selectorNames.indexOf(name);
+  const selName = (n: number) => world.selectorNames[n] ?? `sel_${n}`;
+
+  const numbers = rm.list(ResourceType.Script).map((r) => r.number).filter((n) => rm.has({ type: ResourceType.Heap, number: n }));
+  const scripts: Script[] = [];
+  for (const [i, n] of numbers.entries()) {
+    scripts.push(await world.script(n));
+    onProgress?.(i + 1, numbers.length);
+  }
+
+  // Classes, with property names from their own dictionaries.
+  const classList: ClassInfo[] = [];
+  const classBySpecies = new Map<number, ScriptObject>();
+  const classScript = new Map<number, number>();
+  for (const s of scripts) {
+    for (const o of s.objects) {
+      if (!o.isClass) continue;
+      classBySpecies.set(o.species, o);
+      classScript.set(o.species, s.number);
+    }
+  }
+  const propsOf = (obj: ScriptObject): PropValue[] => {
+    const names = ctx.propSelectors(obj) ?? [];
+    return obj.properties.slice(HEADER_SLOTS).map((value, i) => ({ name: selName(names[i + HEADER_SLOTS] ?? -1), value }));
+  };
+  const methodsOf = (obj: ScriptObject) => obj.methods.map((m) => selName(m.selector));
+  for (const [species, o] of classBySpecies) {
+    classList.push({
+      species,
+      name: o.name,
+      script: classScript.get(species)!,
+      superclass: o.superclass === 0xffff ? -1 : o.superclass,
+      props: propsOf(o),
+      methods: methodsOf(o),
+    });
+  }
+  classList.sort((a, b) => a.species - b.species);
+
+  const inherits = (species: number, name: string): boolean => {
+    for (let s = species, guard = 0; s !== 0xffff && guard < 64; guard++) {
+      const c = classBySpecies.get(s);
+      if (!c) return false;
+      if (c.name === name) return true;
+      s = c.superclass;
+    }
+    return false;
+  };
+  const prop = (obj: ScriptObject, name: string) => propsOf(obj).find((p) => p.name === name)?.value;
+
+  // Disassemble everything once: the facts drive the rest.
+  const functions = new Map<number, DisasmFunction[]>();
+  for (const s of scripts) functions.set(s.number, disassemble(s, ctx));
+
+  const scriptIdKernel = kernelNames.indexOf("ScriptID");
+  const scriptInfos: ScriptInfo[] = [];
+  const rooms: RoomInfo[] = [];
+  for (const s of scripts) {
+    const refs = new Set<number>();
+    for (const fn of functions.get(s.number)!) {
+      for (const c of fn.facts.calls) {
+        if (c.kind === "export" && c.target !== 0) refs.add(c.target);
+        if (c.kind === "kernel" && c.target === scriptIdKernel && c.args[0]?.const !== undefined) refs.add(c.args[0].const);
+      }
+    }
+    refs.delete(s.number);
+    const room = roomObject(s);
+    scriptInfos.push({
+      number: s.number,
+      isRoom: !!room,
+      references: [...refs].sort((a, b) => a - b),
+      objects: s.objects.filter((o) => !o.isClass).map((o) => ({
+        name: o.name,
+        script: s.number,
+        offset: o.offset,
+        superclass: o.superclass,
+        className: classBySpecies.get(o.superclass)?.name ?? `class ${o.superclass}`,
+        props: propsOf(o),
+        methods: methodsOf(o),
+      })),
+    });
+    if (room) {
+      rooms.push({
+        number: s.number,
+        name: room.name,
+        className: classBySpecies.get(room.superclass)?.name ?? "",
+        picture: prop(room, "picture") ?? -1,
+        noun: prop(room, "noun") ?? 0,
+        uses: [...refs].sort((a, b) => a - b),
+      });
+    }
+  }
+
+  function roomObject(s: Script): ScriptObject | undefined {
+    const e0 = s.exports[0];
+    const obj = e0?.kind === "object" ? s.objects.find((o) => o.offset === e0.offset) : undefined;
+    return obj && !obj.isClass && inherits(obj.superclass, roomClass) ? obj : undefined;
+  }
+
+  const roomNumbers = new Set(rooms.map((r) => r.number));
+  // Helper scripts (like 711 for 710) act on behalf of the rooms that load them.
+  const usedBy = new Map<number, number[]>();
+  for (const r of rooms) for (const u of r.uses) if (!roomNumbers.has(u)) usedBy.set(u, [...(usedBy.get(u) ?? []), r.number]);
+  const ownersOf = (script: number) => (roomNumbers.has(script) ? [script] : usedBy.get(script) ?? []);
+
+  const exits: Exit[] = [];
+  const seen = new Set<string>();
+  const addExit = (from: number, to: number, kind: ExitKind, script: number, where: string) => {
+    if (to <= 0 || to >= 0xffff || from === to) return;
+    const key = `${from}>${to}>${kind}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    exits.push({ from, to, kind, script, where });
+  };
+
+  const newRoom = selector("newRoom");
+  const setScript = selector("setScript");
+  const register = selector("register");
+  // Script objects whose code calls `newRoom: register`: keyed "script:heapOffset".
+  const registerExits = new Map<string, string>();
+  // Classes whose methods call `newRoom:` with one of the object's own properties.
+  const propertyExits: { species: number; propName: string; where: string; script: number }[] = [];
+
+  for (const s of scripts) {
+    for (const fn of functions.get(s.number)!) {
+      for (const send of fn.facts.sends) {
+        if (send.selector !== newRoom) continue;
+        const arg: ValueFact = send.args[0] ?? {};
+        if (arg.const !== undefined) {
+          for (const from of ownersOf(s.number)) addExit(from, arg.const, "newRoom", s.number, fn.label);
+        } else if (arg.prop === register && fn.owner) {
+          registerExits.set(`${s.number}:${fn.owner.offset}`, fn.label);
+        } else if (arg.prop !== undefined && fn.owner) {
+          const propName = selName(arg.prop);
+          if (fn.owner.isClass) propertyExits.push({ species: fn.owner.species, propName, where: fn.label, script: s.number });
+          else {
+            const to = prop(fn.owner, propName);
+            if (to !== undefined) for (const from of ownersOf(s.number)) addExit(from, to, "property", s.number, fn.label);
+          }
+        }
+      }
+    }
+  }
+
+  for (const s of scripts) {
+    for (const fn of functions.get(s.number)!) {
+      for (const send of fn.facts.sends) {
+        // `setScript: sExit 0 N` → sExit runs `newRoom: register` with N.
+        if (send.selector === setScript && send.args[0]?.heap !== undefined && send.args[2]?.const !== undefined) {
+          const where = registerExits.get(`${s.number}:${send.args[0].heap}`);
+          if (where) for (const from of ownersOf(s.number)) addExit(from, send.args[2].const, "script", s.number, where);
+        }
+      }
+      // Rooms that check where the hero came from can be entered from there.
+      if (roomNumbers.has(s.number)) {
+        for (const c of fn.facts.compares) {
+          if (c.global === prevRoomGlobal && c.op === "eq?" && roomNumbers.has(c.value)) addExit(c.value, s.number, "entry", s.number, fn.label);
+        }
+      }
+    }
+    for (const o of s.objects) {
+      for (const pe of propertyExits) {
+        if (o.isClass || !inherits(o.superclass, classBySpecies.get(pe.species)!.name)) continue;
+        const to = prop(o, pe.propName);
+        if (to !== undefined) for (const from of ownersOf(s.number)) addExit(from, to, "property", pe.script, `${o.name} (${pe.where})`);
+      }
+    }
+    const room = roomObject(s);
+    if (room) {
+      for (const d of DIRECTIONS) {
+        const to = prop(room, d);
+        if (to) addExit(s.number, to, "direction", s.number, `${room.name}.${d}`);
+      }
+    }
+  }
+
+  const verbs: Record<number, string> = {};
+  const rank = (name: string) => (/^icon[A-Z]/.test(name) ? 0 : /Spell$/.test(name) ? 1 : /^the[A-Z]/.test(name) ? 2 : 3);
+  const pretty = (name: string) => name.replace(/^icon|^the|Spell$/g, "").replace(/^./, (c) => c.toUpperCase());
+  const best = new Map<number, string>();
+  for (const info of scriptInfos) {
+    for (const o of info.objects) {
+      const verb = o.props.find((p) => p.name === "message")?.value;
+      if (!verb || verb >= 0x8000) continue;
+      const current = best.get(verb);
+      if (current === undefined || rank(o.name) < rank(current)) best.set(verb, o.name);
+    }
+  }
+  for (const [verb, name] of best) verbs[verb] = pretty(name);
+
+  const resolved = exits.filter((e) => roomNumbers.has(e.to));
+  const unresolved = exits.filter((e) => !roomNumbers.has(e.to));
+  return { rooms, exits: resolved, unresolved, classes: classList, scripts: scriptInfos, verbs };
+}

package/packages/sci/src/analysis/runtime.d.ts

@@ -0,0 +1,58 @@
+import type { SciObject } from "../vm/memory.ts";
+import type { Value } from "../vm/value.ts";
+import type { Vm } from "../vm/vm.ts";
+/**
+ * Reading a running game for tools (the explorer's live view): globals, the system
+ * collections, polygons and what's drawn where. Read-only: nothing here sends messages or
+ * changes state.
+ */
+/**
+ * The globals tools need: the hero, the room object and its number, and the room the game
+ * should go to next (the game changes rooms when it's set).
+ */
+export type SystemGlobal = "ego" | "curRoom" | "curRoomNum" | "newRoomNum";
+/** Games built by sci-ts name their globals in this vocab (the selector list format). */
+export declare const GLOBAL_NAMES_VOCAB = 990;
+/** Script 0's variables are the game's globals: one by number, or a system global by name. */
+export declare const gameGlobal: (vm: Vm, g: number | SystemGlobal) => Value | undefined;
+export declare const objectAt: (vm: Vm, v: Value | undefined) => SciObject | undefined;
+/** A property as a signed 16-bit number (object references come back unchanged). */
+export declare const signedProp: (vm: Vm, o: SciObject | Value, name: string) => number;
+/** The first instance with this name, e.g. the system collections cast, features, regions. */
+export declare function namedObject(vm: Vm, name: string): SciObject | undefined;
+/** The objects in a collection's `elements` list (cast, features, obstacles...). */
+export declare function collectionElements(vm: Vm, collection: SciObject | Value | undefined): SciObject[];
+/** Numbers from an array, or an IntArray object's `data`. */
+export declare function readInts(vm: Vm, ref: Value, count: number): number[];
+/** Polygon types: 0 total access, 1 near point, 2 barred, 3 contained. */
+export declare function polygonOf(vm: Vm, poly: SciObject): {
+    type: number;
+    points: [number, number][];
+};
+export declare function isKindOf(vm: Vm, o: SciObject, className: string): boolean;
+/** The room's plane (below the status bar): room objects' coordinates are relative to it. */
+export declare function roomPlane(vm: Vm): {
+    left: number;
+    top: number;
+    address: Value;
+} | undefined;
+export interface DrawnItem {
+    item: SciObject;
+    plane: Value;
+    /** Screen rectangle. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** View screen items in visible planes, frontmost first, where they're drawn on screen. */
+export declare function drawnItems(vm: Vm): DrawnItem[];
+/**
+ * Asks the game to go to `room`, the way it changes rooms itself: `Game::doit` sees
+ * `newRoomNum` (global 13) differ from the current room and calls `newRoom:` (transitions and
+ * all). Call between frames. Rooms may assume story state (flags, items, where you came
+ * from); Sierra's debug keys (Alt-G flags, Alt-I items) can set that up.
+ */
+export declare function requestRoom(vm: Vm, room: number): void;
+/** True once there's a hero in play (after character creation or a restore). */
+export declare function heroInPlay(vm: Vm): boolean;

package/packages/sci/src/analysis/runtime.js

@@ -0,0 +1,133 @@
+import { ResourceType } from "../resource/types.js";
+import { parseSelectorNames } from "../script/vocab.js";
+import { graphics } from "../vm/kernels/graphics.js";
+/** Where Sierra's system scripts keep them. */
+const SIERRA_GLOBALS = { ego: 0, curRoom: 2, curRoomNum: 11, newRoomNum: 13 };
+/** Games built by sci-ts name their globals in this vocab (the selector list format). */
+export const GLOBAL_NAMES_VOCAB = 990;
+const globalNumbers = new WeakMap();
+function globalNumber(vm, name) {
+    let lookup = globalNumbers.get(vm);
+    if (!lookup) {
+        const id = { type: ResourceType.Vocab, number: GLOBAL_NAMES_VOCAB };
+        const names = vm.resources.has(id) ? parseSelectorNames(vm.resources.loadSync(id).data) : undefined;
+        lookup = (n) => (names ? names.indexOf(n) : SIERRA_GLOBALS[n]);
+        globalNumbers.set(vm, lookup);
+    }
+    return lookup(name);
+}
+/** Script 0's variables are the game's globals: one by number, or a system global by name. */
+export const gameGlobal = (vm, g) => {
+    const n = typeof g === "number" ? g : globalNumber(vm, g);
+    return n < 0 ? undefined : vm.loadedScripts.find((s) => s.number === 0)?.locals[n];
+};
+export const objectAt = (vm, v) => (v ? vm.memory.object(v) : undefined);
+/** A property as a signed 16-bit number (object references come back unchanged). */
+export const signedProp = (vm, o, name) => {
+    const v = vm.getProp(o, name) ?? 0;
+    return v >= 0x8000 && v < 0x10000 ? v - 0x10000 : v;
+};
+/** The first instance with this name, e.g. the system collections cast, features, regions. */
+export function namedObject(vm, name) {
+    for (const o of vm.memory.objects.values())
+        if (!o.isClass && o.name === name)
+            return o;
+    return undefined;
+}
+/** The objects in a collection's `elements` list (cast, features, obstacles...). */
+export function collectionElements(vm, collection) {
+    const c = typeof collection === "number" ? objectAt(vm, collection) : collection;
+    const elements = c && vm.getProp(c, "elements");
+    const list = elements ? vm.memory.list(elements) : undefined;
+    const out = [];
+    // Guard against a corrupted (cyclic) list: a tool must never hang the page.
+    for (let n = list?.first, guard = 0; n && guard < 10_000; n = n.next, guard++) {
+        const o = objectAt(vm, n.value);
+        if (o)
+            out.push(o);
+    }
+    return out;
+}
+/** Numbers from an array, or an IntArray object's `data`. */
+export function readInts(vm, ref, count) {
+    if (!ref)
+        return [];
+    const direct = vm.memory.array(ref);
+    const data = direct ? undefined : vm.memory.object(ref) ? vm.getProp(ref, "data") : undefined;
+    const array = direct ?? (data ? vm.memory.array(data) : undefined);
+    return (array?.data ?? []).slice(0, count).map((v) => (v >= 0x8000 ? v - 0x10000 : v));
+}
+/** Polygon types: 0 total access, 1 near point, 2 barred, 3 contained. */
+export function polygonOf(vm, poly) {
+    const size = Math.max(0, Math.min(signedProp(vm, poly, "size"), 1000));
+    const flat = readInts(vm, vm.getProp(poly, "points") ?? 0, size * 2);
+    return {
+        type: signedProp(vm, poly, "type"),
+        points: Array.from({ length: Math.floor(flat.length / 2) }, (_, i) => [flat[i * 2], flat[i * 2 + 1]]),
+    };
+}
+export function isKindOf(vm, o, className) {
+    for (let species = o.isClass ? o.species : o.superclass, guard = 0; species !== 0xffff && guard < 64; guard++) {
+        let c;
+        try {
+            c = vm.classObject(species);
+        }
+        catch {
+            return false;
+        }
+        if (c.name === className)
+            return true;
+        species = c.superclass;
+    }
+    return false;
+}
+/** The room's plane (below the status bar): room objects' coordinates are relative to it. */
+export function roomPlane(vm) {
+    const g = graphics(vm);
+    const room = objectAt(vm, gameGlobal(vm, "curRoom"));
+    let plane = room ? vm.getProp(room, "plane") : undefined;
+    if (!plane || !vm.memory.object(plane)) {
+        plane = [...g.planes].find((p) => vm.memory.object(p) && g.prop(p, "picture") >= 0 && g.prop(p, "picture") < 0x8000);
+    }
+    return plane ? { left: g.prop(plane, "inLeft"), top: g.prop(plane, "inTop"), address: plane } : undefined;
+}
+/** View screen items in visible planes, frontmost first, where they're drawn on screen. */
+export function drawnItems(vm) {
+    const g = graphics(vm);
+    const out = [];
+    for (const item of g.items) {
+        const o = objectAt(vm, item);
+        const plane = o && vm.getProp(item, "plane");
+        if (!o || !plane || !vm.memory.object(plane))
+            continue;
+        const planePriority = g.prop(plane, "priority");
+        if (planePriority === -1)
+            continue;
+        const bitmap = vm.getProp(item, "bitmap");
+        if (bitmap && vm.memory.bitmap(bitmap))
+            continue;
+        const r = g.viewRect(item);
+        if (!r)
+            continue;
+        const priority = g.prop(item, "fixPriority") ? g.prop(item, "priority") : g.prop(item, "y");
+        out.push({ item: o, plane, x: g.prop(plane, "inLeft") + r.x, y: g.prop(plane, "inTop") + r.y, w: r.width, h: r.height, order: planePriority * 100_000 + priority });
+    }
+    return out.sort((a, b) => b.order - a.order);
+}
+/**
+ * Asks the game to go to `room`, the way it changes rooms itself: `Game::doit` sees
+ * `newRoomNum` (global 13) differ from the current room and calls `newRoom:` (transitions and
+ * all). Call between frames. Rooms may assume story state (flags, items, where you came
+ * from); Sierra's debug keys (Alt-G flags, Alt-I items) can set that up.
+ */
+export function requestRoom(vm, room) {
+    const script0 = vm.loadedScripts.find((s) => s.number === 0);
+    if (!script0)
+        throw new Error("The game hasn't started");
+    script0.locals[globalNumber(vm, "newRoomNum")] = room & 0xffff;
+}
+/** True once there's a hero in play (after character creation or a restore). */
+export function heroInPlay(vm) {
+    const ego = objectAt(vm, gameGlobal(vm, "ego"));
+    return !!ego && signedProp(vm, ego, "view") > 0;
+}

package/packages/sci/src/analysis/runtime.ts

@@ -0,0 +1,163 @@
+import { ResourceType } from "../resource/types.ts";
+import { parseSelectorNames } from "../script/vocab.ts";
+import type { SciObject } from "../vm/memory.ts";
+import { graphics } from "../vm/kernels/graphics.ts";
+import type { Value } from "../vm/value.ts";
+import type { Vm } from "../vm/vm.ts";
+
+/**
+ * Reading a running game for tools (the explorer's live view): globals, the system
+ * collections, polygons and what's drawn where. Read-only: nothing here sends messages or
+ * changes state.
+ */
+
+/**
+ * The globals tools need: the hero, the room object and its number, and the room the game
+ * should go to next (the game changes rooms when it's set).
+ */
+export type SystemGlobal = "ego" | "curRoom" | "curRoomNum" | "newRoomNum";
+
+/** Where Sierra's system scripts keep them. */
+const SIERRA_GLOBALS: Record<SystemGlobal, number> = { ego: 0, curRoom: 2, curRoomNum: 11, newRoomNum: 13 };
+
+/** Games built by sci-ts name their globals in this vocab (the selector list format). */
+export const GLOBAL_NAMES_VOCAB = 990;
+
+const globalNumbers = new WeakMap<Vm, (name: SystemGlobal) => number>();
+
+function globalNumber(vm: Vm, name: SystemGlobal): number {
+  let lookup = globalNumbers.get(vm);
+  if (!lookup) {
+    const id = { type: ResourceType.Vocab, number: GLOBAL_NAMES_VOCAB };
+    const names = vm.resources.has(id) ? parseSelectorNames(vm.resources.loadSync(id).data) : undefined;
+    lookup = (n) => (names ? names.indexOf(n) : SIERRA_GLOBALS[n]);
+    globalNumbers.set(vm, lookup);
+  }
+  return lookup(name);
+}
+
+/** Script 0's variables are the game's globals: one by number, or a system global by name. */
+export const gameGlobal = (vm: Vm, g: number | SystemGlobal): Value | undefined => {
+  const n = typeof g === "number" ? g : globalNumber(vm, g);
+  return n < 0 ? undefined : vm.loadedScripts.find((s) => s.number === 0)?.locals[n];
+};
+
+export const objectAt = (vm: Vm, v: Value | undefined): SciObject | undefined => (v ? vm.memory.object(v) : undefined);
+
+/** A property as a signed 16-bit number (object references come back unchanged). */
+export const signedProp = (vm: Vm, o: SciObject | Value, name: string): number => {
+  const v = vm.getProp(o, name) ?? 0;
+  return v >= 0x8000 && v < 0x10000 ? v - 0x10000 : v;
+};
+
+/** The first instance with this name, e.g. the system collections cast, features, regions. */
+export function namedObject(vm: Vm, name: string): SciObject | undefined {
+  for (const o of vm.memory.objects.values()) if (!o.isClass && o.name === name) return o;
+  return undefined;
+}
+
+/** The objects in a collection's `elements` list (cast, features, obstacles...). */
+export function collectionElements(vm: Vm, collection: SciObject | Value | undefined): SciObject[] {
+  const c = typeof collection === "number" ? objectAt(vm, collection) : collection;
+  const elements = c && vm.getProp(c, "elements");
+  const list = elements ? vm.memory.list(elements) : undefined;
+  const out: SciObject[] = [];
+  // Guard against a corrupted (cyclic) list: a tool must never hang the page.
+  for (let n = list?.first, guard = 0; n && guard < 10_000; n = n.next, guard++) {
+    const o = objectAt(vm, n.value);
+    if (o) out.push(o);
+  }
+  return out;
+}
+
+/** Numbers from an array, or an IntArray object's `data`. */
+export function readInts(vm: Vm, ref: Value, count: number): number[] {
+  if (!ref) return [];
+  const direct = vm.memory.array(ref);
+  const data = direct ? undefined : vm.memory.object(ref) ? vm.getProp(ref, "data") : undefined;
+  const array = direct ?? (data ? vm.memory.array(data) : undefined);
+  return (array?.data ?? []).slice(0, count).map((v) => (v >= 0x8000 ? v - 0x10000 : v));
+}
+
+/** Polygon types: 0 total access, 1 near point, 2 barred, 3 contained. */
+export function polygonOf(vm: Vm, poly: SciObject): { type: number; points: [number, number][] } {
+  const size = Math.max(0, Math.min(signedProp(vm, poly, "size"), 1000));
+  const flat = readInts(vm, vm.getProp(poly, "points") ?? 0, size * 2);
+  return {
+    type: signedProp(vm, poly, "type"),
+    points: Array.from({ length: Math.floor(flat.length / 2) }, (_, i) => [flat[i * 2]!, flat[i * 2 + 1]!] as [number, number]),
+  };
+}
+
+export function isKindOf(vm: Vm, o: SciObject, className: string): boolean {
+  for (let species = o.isClass ? o.species : o.superclass, guard = 0; species !== 0xffff && guard < 64; guard++) {
+    let c: SciObject | undefined;
+    try {
+      c = vm.classObject(species);
+    } catch {
+      return false;
+    }
+    if (c.name === className) return true;
+    species = c.superclass;
+  }
+  return false;
+}
+
+/** The room's plane (below the status bar): room objects' coordinates are relative to it. */
+export function roomPlane(vm: Vm): { left: number; top: number; address: Value } | undefined {
+  const g = graphics(vm);
+  const room = objectAt(vm, gameGlobal(vm, "curRoom"));
+  let plane = room ? vm.getProp(room, "plane") : undefined;
+  if (!plane || !vm.memory.object(plane)) {
+    plane = [...g.planes].find((p) => vm.memory.object(p) && g.prop(p, "picture") >= 0 && g.prop(p, "picture") < 0x8000);
+  }
+  return plane ? { left: g.prop(plane, "inLeft"), top: g.prop(plane, "inTop"), address: plane } : undefined;
+}
+
+export interface DrawnItem {
+  item: SciObject;
+  plane: Value;
+  /** Screen rectangle. */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** View screen items in visible planes, frontmost first, where they're drawn on screen. */
+export function drawnItems(vm: Vm): DrawnItem[] {
+  const g = graphics(vm);
+  const out: (DrawnItem & { order: number })[] = [];
+  for (const item of g.items) {
+    const o = objectAt(vm, item);
+    const plane = o && vm.getProp(item, "plane");
+    if (!o || !plane || !vm.memory.object(plane)) continue;
+    const planePriority = g.prop(plane, "priority");
+    if (planePriority === -1) continue;
+    const bitmap = vm.getProp(item, "bitmap");
+    if (bitmap && vm.memory.bitmap(bitmap)) continue;
+    const r = g.viewRect(item);
+    if (!r) continue;
+    const priority = g.prop(item, "fixPriority") ? g.prop(item, "priority") : g.prop(item, "y");
+    out.push({ item: o, plane, x: g.prop(plane, "inLeft") + r.x, y: g.prop(plane, "inTop") + r.y, w: r.width, h: r.height, order: planePriority * 100_000 + priority });
+  }
+  return out.sort((a, b) => b.order - a.order);
+}
+
+/**
+ * Asks the game to go to `room`, the way it changes rooms itself: `Game::doit` sees
+ * `newRoomNum` (global 13) differ from the current room and calls `newRoom:` (transitions and
+ * all). Call between frames. Rooms may assume story state (flags, items, where you came
+ * from); Sierra's debug keys (Alt-G flags, Alt-I items) can set that up.
+ */
+export function requestRoom(vm: Vm, room: number): void {
+  const script0 = vm.loadedScripts.find((s) => s.number === 0);
+  if (!script0) throw new Error("The game hasn't started");
+  script0.locals[globalNumber(vm, "newRoomNum")] = room & 0xffff;
+}
+
+/** True once there's a hero in play (after character creation or a restore). */
+export function heroInPlay(vm: Vm): boolean {
+  const ego = objectAt(vm, gameGlobal(vm, "ego"));
+  return !!ego && signedProp(vm, ego, "view") > 0;
+}