sci2-ts 0.0.0-stage → 0.2.1

package/packages/content/src/yarn.ts

@@ -0,0 +1,261 @@
+/**
+ * Yarn Spinner's file format (https://docs.yarnspinner.dev), the part rooms use so far:
+ *
+ *   title: wisp.talk        <- headers, `key: value`, until ---
+ *   ---
+ *   Golden pods hang from the rock.     <- a line; `Speaker: text` names who says it
+ *   <<if $met_wisp>>                    <- conditions on true/false variables:
+ *       They hum when you're near.         not, and, or, ==, !=, (...), true, false
+ *   <<else>>
+ *       They're silent.
+ *   <<endif>>
+ *   <<set $looked to true>>
+ *   -> Who are you?                     <- a choice; its body is indented below it
+ *       Wisp: A memory of this place.
+ *   -> Sing for me <<if $met_wisp>>     <- a choice only offered when its condition holds
+ *       Wisp: Not yet.
+ *   // a comment
+ *   ===
+ *
+ * Other commands (<<walk hero 110 160>>, <<wait 2>>...) are kept as name + arguments for
+ * the compiler to check. Choices inside choices or inside <<if>> are rejected with the
+ * line they're on, until the compiler supports them.
+ */
+export interface YarnNode {
+  title: string;
+  headers: Record<string, string>;
+  body: YarnItem[];
+  /** Where the node starts, for error messages. */
+  line: number;
+}
+
+export type YarnItem = YarnLine | YarnChoice | YarnSet | YarnIf | YarnCommand;
+
+/** Any other <<command arg arg ...>>; the compiler knows which exist (walk, wait, ...). */
+export interface YarnCommand {
+  kind: "command";
+  name: string;
+  args: string[];
+  line: number;
+}
+
+export interface YarnLine {
+  kind: "line";
+  speaker?: string;
+  text: string;
+  line: number;
+}
+
+export interface YarnChoice {
+  kind: "choice";
+  text: string;
+  /** Only offered when this holds. */
+  when?: YarnExpr;
+  body: YarnItem[];
+  line: number;
+}
+
+export interface YarnSet {
+  kind: "set";
+  name: string;
+  value: YarnExpr;
+  line: number;
+}
+
+export interface YarnIf {
+  kind: "if";
+  /** `if` and `elseif` branches in order; a final `else` has no condition. */
+  branches: { when?: YarnExpr; body: YarnItem[] }[];
+  line: number;
+}
+
+/** Boolean expressions over variables (each a flag). */
+export type YarnExpr =
+  | { kind: "var"; name: string }
+  | { kind: "const"; value: boolean }
+  | { kind: "not"; of: YarnExpr }
+  | { kind: "and" | "or"; a: YarnExpr; b: YarnExpr };
+
+export class YarnError extends Error {
+  constructor(readonly file: string, readonly line: number, message: string) {
+    super(`${file}:${line}: ${message}`);
+  }
+}
+
+/** Trailing #tags (Yarn's line ids and metadata) don't belong to the text. */
+const stripTags = (s: string) => s.replace(/(\s+#[^\s#]+)+\s*$/, "");
+const indentOf = (s: string) => /^[ \t]*/.exec(s)![0].replace(/\t/g, "    ").length;
+
+export function parseYarn(source: string, file = "<yarn>"): YarnNode[] {
+  const nodes: YarnNode[] = [];
+  const lines = source.split(/\r?\n/);
+  let i = 0;
+  const fail = (line: number, why: string): never => {
+    throw new YarnError(file, line, why);
+  };
+  while (i < lines.length) {
+    // Headers.
+    const start = i + 1;
+    const headers: Record<string, string> = {};
+    for (; i < lines.length && lines[i]!.trim() !== "---"; i++) {
+      const raw = lines[i]!.trim();
+      if (!raw || raw.startsWith("//")) continue;
+      const m = /^([A-Za-z_][\w.-]*)\s*:\s*(.*)$/.exec(raw);
+      if (!m) fail(i + 1, `expected a header (key: value) or ---, got "${raw}"`);
+      headers[m![1]!] = m![2]!.trim();
+    }
+    if (i >= lines.length) {
+      if (Object.keys(headers).length) fail(start, "node has no body: expected --- after its headers");
+      break;
+    }
+    const title = headers.title;
+    if (!title) fail(start, "node has no title: header");
+    if (nodes.some((n) => n.title === title)) fail(start, `a node called "${title}" already exists`);
+    i++; // ---
+    // The body's lines up to ===, then parsed into a tree.
+    const body: { text: string; indent: number; line: number }[] = [];
+    let closed = false;
+    for (; i < lines.length; i++) {
+      const raw = lines[i]!.trim();
+      if (raw === "===") {
+        closed = true;
+        i++;
+        break;
+      }
+      if (!raw || raw.startsWith("//")) continue;
+      body.push({ text: raw, indent: indentOf(lines[i]!), line: i + 1 });
+    }
+    if (!closed) fail(start, `node "${title}" isn't closed with ===`);
+    const parser = new BodyParser(body, fail);
+    nodes.push({ title: title!, headers, body: parser.block(-1, false, false, []), line: start });
+    if (parser.at < body.length) {
+      const extra = body[parser.at]!;
+      fail(extra.line, `unexpected ${extra.text.split(/\s/)[0]} (no <<if>> is open)`);
+    }
+  }
+  return nodes;
+}
+
+class BodyParser {
+  at = 0;
+  constructor(
+    readonly lines: { text: string; indent: number; line: number }[],
+    readonly fail: (line: number, why: string) => never,
+  ) {}
+
+  /**
+   * Items until a line indented at most `parentIndent` (the end of a choice's body) or, in
+   * an <<if>>, one of `stopAt` (elseif/else/endif).
+   */
+  block(parentIndent: number, inChoice: boolean, inIf: boolean, stopAt: string[]): YarnItem[] {
+    const items: YarnItem[] = [];
+    let choiceIndent: number | undefined;
+    while (this.at < this.lines.length) {
+      const { text, indent, line } = this.lines[this.at]!;
+      if (indent <= parentIndent) break;
+      const command = /^<<\s*(\w+)\s*(.*?)\s*>>$/.exec(text);
+      if (command && stopAt.includes(command[1]!)) break;
+      this.at++;
+      if (text.startsWith("->")) {
+        if (inChoice) this.fail(line, "choices inside choices aren't supported yet");
+        if (inIf) this.fail(line, "choices inside <<if>> aren't supported yet (use -> text <<if $x>>)");
+        if (choiceIndent !== undefined && indent !== choiceIndent) this.fail(line, "choices in a group must line up");
+        choiceIndent = indent;
+        let rest = stripTags(text.slice(2).trim());
+        let when: YarnExpr | undefined;
+        const cond = /^(.*?)\s*<<\s*if\s+(.+?)\s*>>$/.exec(rest);
+        if (cond) {
+          rest = cond[1]!;
+          when = parseExpr(cond[2]!, (why) => this.fail(line, why));
+        }
+        if (!rest) this.fail(line, "a choice needs text after ->");
+        items.push({ kind: "choice", text: rest, when, body: this.block(indent, true, false, []), line });
+        continue;
+      }
+      if (command) {
+        const [, name, args] = command;
+        if (name === "set") {
+          const m = /^\$([A-Za-z_]\w*)\s*(?:to|=)\s*(.+)$/.exec(args!);
+          if (!m) this.fail(line, "expected <<set $name to true>> (or false, or a condition)");
+          items.push({ kind: "set", name: m![1]!, value: parseExpr(m![2]!, (why) => this.fail(line, why)), line });
+        } else if (name === "if") {
+          items.push(this.ifBlock(args!, line, indent, inChoice));
+        } else if (["elseif", "else", "endif"].includes(name!)) {
+          this.fail(line, `<<${name}>> without an <<if>>`);
+        } else {
+          items.push({ kind: "command", name: name!, args: args ? args.split(/[\s,]+/).filter(Boolean) : [], line });
+        }
+        continue;
+      }
+      if (text.startsWith("<<")) this.fail(line, `expected <<command ...>>, got "${text}"`);
+      const clean = stripTags(text);
+      const m = /^([A-Za-z][\w ]*?)\s*:\s+(.+)$/.exec(clean);
+      items.push(m ? { kind: "line", speaker: m[1]!, text: m[2]!, line } : { kind: "line", text: clean, line });
+    }
+    return items;
+  }
+
+  private ifBlock(firstCond: string, line: number, indent: number, inChoice: boolean): YarnIf {
+    const fail = (why: string) => this.fail(line, why);
+    const branches: YarnIf["branches"] = [{ when: parseExpr(firstCond, fail), body: [] }];
+    // An <<if>>'s body is whatever comes before its <<elseif>>/<<else>>/<<endif>>, at any
+    // indentation deeper than the enclosing choice (Yarn doesn't require indenting it).
+    for (;;) {
+      branches[branches.length - 1]!.body = this.block(inChoice ? indent - 1 : -1, inChoice, true, ["elseif", "else", "endif"]);
+      const next = this.lines[this.at];
+      const command = next && /^<<\s*(\w+)\s*(.*?)\s*>>$/.exec(next.text);
+      if (!command) this.fail(line, "<<if>> without <<endif>>");
+      this.at++;
+      if (command![1] === "endif") return { kind: "if", branches, line };
+      if (branches.at(-1)!.when === undefined) this.fail(next!.line, `<<${command![1]}>> after <<else>>`);
+      if (command![1] === "else") branches.push({ body: [] });
+      else branches.push({ when: parseExpr(command![2]!, (why) => this.fail(next!.line, why)), body: [] });
+    }
+  }
+}
+
+/** `$a and not ($b or $c == false)`: Yarn's boolean operators, both spellings. */
+export function parseExpr(source: string, fail: (why: string) => never): YarnExpr {
+  const tokens = source.match(/\$[A-Za-z_]\w*|&&|\|\||==|!=|[()!]|[A-Za-z_]\w*|\S/g) ?? [];
+  let p = 0;
+  const peek = () => tokens[p];
+  const take = () => tokens[p++];
+  const word = (t: string | undefined, ...names: string[]) => t !== undefined && names.includes(t.toLowerCase());
+  const or = (): YarnExpr => {
+    let a = and();
+    while (word(peek(), "or", "||")) (take(), (a = { kind: "or", a, b: and() }));
+    return a;
+  };
+  const and = (): YarnExpr => {
+    let a = compare();
+    while (word(peek(), "and", "&&")) (take(), (a = { kind: "and", a, b: compare() }));
+    return a;
+  };
+  const compare = (): YarnExpr => {
+    const a = unary();
+    if (word(peek(), "==", "!=", "is", "eq", "neq")) {
+      const op = take()!.toLowerCase();
+      const b = unary();
+      // a == b is (a and b) or (not a and not b).
+      const same: YarnExpr = { kind: "or", a: { kind: "and", a, b }, b: { kind: "and", a: { kind: "not", of: a }, b: { kind: "not", of: b } } };
+      return op === "!=" || op === "neq" ? { kind: "not", of: same } : same;
+    }
+    return a;
+  };
+  const unary = (): YarnExpr => {
+    const t = take();
+    if (t === undefined) fail(`incomplete condition "${source}"`);
+    if (word(t, "not", "!")) return { kind: "not", of: unary() };
+    if (t === "(") {
+      const e = or();
+      if (take() !== ")") fail(`missing ) in "${source}"`);
+      return e;
+    }
+    if (word(t, "true", "false")) return { kind: "const", value: t!.toLowerCase() === "true" };
+    if (t!.startsWith("$")) return { kind: "var", name: t!.slice(1) };
+    return fail(`unexpected "${t}" in "${source}" (variables are $name; numbers and text aren't supported yet)`);
+  };
+  const e = or();
+  if (p < tokens.length) fail(`unexpected "${tokens[p]}" in "${source}"`);
+  return e;
+}

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

@@ -0,0 +1,90 @@
+import type { ResourceManager } from "../resource/manager.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;
+}
+export declare function analyzeGame(rm: ResourceManager, options?: AnalyzeOptions): Promise<GameIndex>;

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

@@ -0,0 +1,221 @@
+import { ResourceType } from "../resource/types.js";
+import { disassemble } from "../script/disasm.js";
+import { kernelNames } from "../script/kernel-names.js";
+import { ObjectSlot } from "../script/script.js";
+import { ScriptWorld } from "../script/world.js";
+/** 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, options = {}) {
+    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) => world.selectorNames.indexOf(name);
+    const selName = (n) => 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 = [];
+    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 = [];
+    const classBySpecies = new Map();
+    const classScript = new Map();
+    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) => {
+        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) => 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, name) => {
+        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, name) => propsOf(obj).find((p) => p.name === name)?.value;
+    // Disassemble everything once: the facts drive the rest.
+    const functions = new Map();
+    for (const s of scripts)
+        functions.set(s.number, disassemble(s, ctx));
+    const scriptIdKernel = kernelNames.indexOf("ScriptID");
+    const scriptInfos = [];
+    const rooms = [];
+    for (const s of scripts) {
+        const refs = new Set();
+        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) {
+        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();
+    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) => (roomNumbers.has(script) ? [script] : usedBy.get(script) ?? []);
+    const exits = [];
+    const seen = new Set();
+    const addExit = (from, to, kind, script, where) => {
+        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();
+    // Classes whose methods call `newRoom:` with one of the object's own properties.
+    const propertyExits = [];
+    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 = 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 = {};
+    const rank = (name) => (/^icon[A-Z]/.test(name) ? 0 : /Spell$/.test(name) ? 1 : /^the[A-Z]/.test(name) ? 2 : 3);
+    const pretty = (name) => name.replace(/^icon|^the|Spell$/g, "").replace(/^./, (c) => c.toUpperCase());
+    const best = new Map();
+    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 };
+}