sci2-ts 0.0.0-stage → 0.2.1

package/tools/mod-build.js

@@ -0,0 +1,173 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { compileRoom } from "../packages/content/src/index.js";
+import { picFromPngs } from "./pic-build.js";
+import { loadTarget } from "./mod-target.js";
+import { viewFromManifest } from "./view-build.js";
+import { ResourceType, analyzeGame, assemble, messagesFromText, messagesToText, parseMessages, toAssembly, writeMessages, writePic, writeView, } from "../packages/sci/src/index.js";
+/** Message file text with each record annotated: verb name, and the room objects using the noun. */
+export async function dumpMessages(rm, world, n) {
+    const file = parseMessages((await rm.load({ type: ResourceType.Message, number: n })).data);
+    const index = await analyzeGame(rm, { world });
+    const nounOwners = new Map();
+    for (const o of index.scripts.find((s) => s.number === n)?.objects ?? []) {
+        const noun = o.props.find((p) => p.name === "noun")?.value;
+        if (noun)
+            nounOwners.set(noun, [...(nounOwners.get(noun) ?? []), o.name]);
+    }
+    return messagesToText(n, file, (r) => [index.verbs[r.verb], nounOwners.get(r.noun)?.join("/")].filter(Boolean).join(" · ") || undefined);
+}
+/**
+ * Builds a mod directory: <n>.sca / <n>.msg are whole new files (a new room);
+ * <n>.sca.diff / <n>.msg.diff change the game's own, applied to fresh dumps with `patch`;
+ * <n>.png (+ <n>.layer-<priority>.png) is a room picture; *.view.json is a view;
+ * <n>.room.yaml (+ <n>.yarn) is a room described as data, compiled to <n>.sca and <n>.msg
+ * (@sci-ts/content). `generated` receives that compiled text, for reading. Their Yarn
+ * variables are flags numbered in the mod's flags.yaml (see modFlags). Rooms are compiled for
+ * the game named in the mod's mod.yaml (see tools/mod-target.ts).
+ */
+export async function buildMod(modDir, rm, world, ctx, generated) {
+    const work = mkdtempSync(join(tmpdir(), "sci-mod-"));
+    const all = readdirSync(modDir);
+    const files = all.filter((f) => /^\d+\.(sca|msg)(\.diff)?$/.test(f));
+    const pictures = all.filter((f) => /^\d+\.png$/.test(f));
+    const views = all.filter((f) => /\.view\.json$/.test(f));
+    const rooms = all.filter((f) => /^\d+\.room\.yaml$/.test(f));
+    if (!files.length && !pictures.length && !views.length && !rooms.length) {
+        throw new Error(`No <n>.room.yaml, <n>.sca, <n>.msg, .diff, <n>.png or .view.json files in ${modDir}`);
+    }
+    // <n>.room.yaml + <n>.yarn: compiled to the same text a hand-written room would be.
+    const target = rooms.length ? await loadTarget(modDir) : undefined;
+    const flags = target && modFlags(modDir, target);
+    const sources = new Map();
+    // Diffs to apply per generated file: the mod's own, plus the target's support patches.
+    const diffs = new Map();
+    for (const f of files.filter((x) => x.endsWith(".diff")))
+        diffs.set(f.slice(0, -5), [join(modDir, f)]);
+    for (const file of rooms) {
+        const n = file.split(".")[0];
+        for (const kind of ["sca", "msg"]) {
+            if (files.includes(`${n}.${kind}`))
+                throw new Error(`${modDir}: both ${file} and ${n}.${kind} define room ${n}`);
+        }
+        const yarnFile = `${n}.yarn`;
+        const room = compileRoom(readFileSync(join(modDir, file), "utf8"), all.includes(yarnFile) ? readFileSync(join(modDir, yarnFile), "utf8") : undefined, target.content, { yaml: join(modDir, file), yarn: join(modDir, yarnFile) }, { flag: flags.number });
+        sources.set(`${n}.sca`, room.sca).set(`${n}.msg`, room.msg);
+        if (room.roomTalkers) {
+            // Characters: the target's patches that let the game ask the current room for talkers.
+            for (const [patched, diff] of Object.entries(target.roomTalkerPatches ?? {})) {
+                const list = diffs.get(patched) ?? [];
+                if (!list.includes(diff))
+                    diffs.set(patched, [diff, ...list]);
+            }
+        }
+        generated?.(`${n}.sca`, room.sca);
+        generated?.(`${n}.msg`, room.msg);
+        files.push(`${n}.sca`, `${n}.msg`);
+    }
+    flags?.save();
+    const out = [];
+    // <n>.png (+ <n>.layer-<priority>.png): a room picture.
+    for (const file of pictures) {
+        const n = Number(file.split(".")[0]);
+        out.push({ type: ResourceType.Pic, number: n, data: writePic(await picFromPngs(modDir, n, rm)) });
+    }
+    // *.view.json: a view (sprite/animation) from PNGs. Built after pictures, which it may use.
+    for (const file of views) {
+        const { number, view } = await viewFromManifest(join(modDir, file), rmWith(rm, out));
+        out.push({ type: ResourceType.View, number, data: writeView(view) });
+    }
+    const targets = [...files.filter((f) => !f.endsWith(".diff")), ...[...diffs.keys()].map((f) => `${f}.diff`)];
+    for (const file of new Set(targets)) {
+        const [n, kind] = file.split(".");
+        let text;
+        if (file.endsWith(".diff")) {
+            const source = join(work, `${n}.${kind}`);
+            writeFileSync(source, kind === "sca" ? toAssembly(await world.script(Number(n)), ctx) : await dumpMessages(rm, world, Number(n)));
+            for (const diff of diffs.get(`${n}.${kind}`))
+                execFileSync("patch", ["--quiet", "--forward", source, diff], { stdio: "inherit" });
+            text = readFileSync(source, "utf8");
+        }
+        else
+            text = sources.get(file) ?? readFileSync(join(modDir, file), "utf8");
+        if (kind === "sca") {
+            const built = assemble(text, ctx);
+            out.push({ type: ResourceType.Script, number: built.number, data: built.code }, { type: ResourceType.Heap, number: built.number, data: built.heap });
+        }
+        else {
+            const { number, file: messages } = messagesFromText(text);
+            out.push({ type: ResourceType.Message, number, data: writeMessages(messages) });
+        }
+    }
+    return out;
+}
+/**
+ * A mod's flags.yaml: Yarn variable -> flag number. Saved games store flags by number, so
+ * a name keeps its number once given: new names get the next free one (the build adds them
+ * to the file; commit it with the mod). `$game<n>` is the game's own flag n.
+ */
+export function modFlags(modDir, target) {
+    const file = join(modDir, "flags.yaml");
+    const { first, last } = target.content.flags;
+    const numbers = new Map();
+    if (existsSync(file)) {
+        readFileSync(file, "utf8").split("\n").forEach((raw, i) => {
+            const line = raw.replace(/#.*/, "").trim();
+            if (!line)
+                return;
+            const m = /^([A-Za-z_]\w*)\s*:\s*(\d+)$/.exec(line);
+            if (!m)
+                throw new Error(`${file}:${i + 1}: expected name: number`);
+            const n = Number(m[2]);
+            if (n < first || n > last)
+                throw new Error(`${file}:${i + 1}: ${n} is outside the flags mods may use (${first}-${last})`);
+            if ([...numbers.values()].includes(n))
+                throw new Error(`${file}:${i + 1}: flag ${n} is used twice`);
+            numbers.set(m[1], n);
+        });
+    }
+    let added = false;
+    return {
+        number(name) {
+            const game = /^game(\d+)$/.exec(name);
+            if (game) {
+                const n = Number(game[1]);
+                if (n > last)
+                    throw new Error(`the game's flags go up to ${last}`);
+                return n;
+            }
+            let n = numbers.get(name);
+            if (n === undefined) {
+                const used = new Set(numbers.values());
+                for (n = first; used.has(n); n++)
+                    ;
+                if (n > last)
+                    throw new Error(`no free flags left (${first}-${last})`);
+                numbers.set(name, n);
+                added = true;
+            }
+            return n;
+        },
+        save() {
+            if (!added)
+                return;
+            const lines = [...numbers].sort((a, b) => a[1] - b[1]).map(([name, n]) => `${name}: ${n}`);
+            writeFileSync(file, [
+                "# Flags for the Yarn variables ($name) in these rooms, kept by the build: new names get the",
+                "# next free number. Saved games store flags by number, so don't renumber once people play.",
+                ...lines, "",
+            ].join("\n"));
+        },
+    };
+}
+/** The game's resources plus what the mod has built so far (a view may use the mod's picture). */
+function rmWith(rm, built) {
+    return {
+        async load(id) {
+            const b = built.find((r) => r.type === id.type && r.number === id.number);
+            return b ? { ...id, data: b.data } : rm.load(id);
+        },
+    };
+}

package/tools/mod-build.ts

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { compileRoom } from "../packages/content/src/index.ts";
+import { picFromPngs } from "./pic-build.ts";
+import { loadTarget, type ModTarget } from "./mod-target.ts";
+import { viewFromManifest } from "./view-build.ts";
+import {
+  ResourceType, analyzeGame, assemble, messagesFromText, messagesToText, parseMessages, toAssembly, writeMessages, writePic, writeView,
+  type AsmContext, type ResourceManager, type ScriptWorld,
+} from "../packages/sci/src/index.ts";
+
+export interface BuiltResource {
+  type: ResourceType;
+  number: number;
+  data: Uint8Array;
+}
+
+/** Message file text with each record annotated: verb name, and the room objects using the noun. */
+export async function dumpMessages(rm: ResourceManager, world: ScriptWorld, n: number): Promise<string> {
+  const file = parseMessages((await rm.load({ type: ResourceType.Message, number: n })).data);
+  const index = await analyzeGame(rm, { world });
+  const nounOwners = new Map<number, string[]>();
+  for (const o of index.scripts.find((s) => s.number === n)?.objects ?? []) {
+    const noun = o.props.find((p) => p.name === "noun")?.value;
+    if (noun) nounOwners.set(noun, [...(nounOwners.get(noun) ?? []), o.name]);
+  }
+  return messagesToText(n, file, (r) => [index.verbs[r.verb], nounOwners.get(r.noun)?.join("/")].filter(Boolean).join(" · ") || undefined);
+}
+
+/**
+ * Builds a mod directory: <n>.sca / <n>.msg are whole new files (a new room);
+ * <n>.sca.diff / <n>.msg.diff change the game's own, applied to fresh dumps with `patch`;
+ * <n>.png (+ <n>.layer-<priority>.png) is a room picture; *.view.json is a view;
+ * <n>.room.yaml (+ <n>.yarn) is a room described as data, compiled to <n>.sca and <n>.msg
+ * (@sci-ts/content). `generated` receives that compiled text, for reading. Their Yarn
+ * variables are flags numbered in the mod's flags.yaml (see modFlags). Rooms are compiled for
+ * the game named in the mod's mod.yaml (see tools/mod-target.ts).
+ */
+export async function buildMod(
+  modDir: string, rm: ResourceManager, world: ScriptWorld, ctx: AsmContext,
+  generated?: (file: string, text: string) => void,
+): Promise<BuiltResource[]> {
+  const work = mkdtempSync(join(tmpdir(), "sci-mod-"));
+  const all = readdirSync(modDir);
+  const files = all.filter((f) => /^\d+\.(sca|msg)(\.diff)?$/.test(f));
+  const pictures = all.filter((f) => /^\d+\.png$/.test(f));
+  const views = all.filter((f) => /\.view\.json$/.test(f));
+  const rooms = all.filter((f) => /^\d+\.room\.yaml$/.test(f));
+  if (!files.length && !pictures.length && !views.length && !rooms.length) {
+    throw new Error(`No <n>.room.yaml, <n>.sca, <n>.msg, .diff, <n>.png or .view.json files in ${modDir}`);
+  }
+  // <n>.room.yaml + <n>.yarn: compiled to the same text a hand-written room would be.
+  const target: ModTarget | undefined = rooms.length ? await loadTarget(modDir) : undefined;
+  const flags = target && modFlags(modDir, target);
+  const sources = new Map<string, string>();
+  // Diffs to apply per generated file: the mod's own, plus the target's support patches.
+  const diffs = new Map<string, string[]>();
+  for (const f of files.filter((x) => x.endsWith(".diff"))) diffs.set(f.slice(0, -5), [join(modDir, f)]);
+  for (const file of rooms) {
+    const n = file.split(".")[0]!;
+    for (const kind of ["sca", "msg"]) {
+      if (files.includes(`${n}.${kind}`)) throw new Error(`${modDir}: both ${file} and ${n}.${kind} define room ${n}`);
+    }
+    const yarnFile = `${n}.yarn`;
+    const room = compileRoom(
+      readFileSync(join(modDir, file), "utf8"),
+      all.includes(yarnFile) ? readFileSync(join(modDir, yarnFile), "utf8") : undefined,
+      target!.content,
+      { yaml: join(modDir, file), yarn: join(modDir, yarnFile) },
+      { flag: flags!.number },
+    );
+    sources.set(`${n}.sca`, room.sca).set(`${n}.msg`, room.msg);
+    if (room.roomTalkers) {
+      // Characters: the target's patches that let the game ask the current room for talkers.
+      for (const [patched, diff] of Object.entries(target!.roomTalkerPatches ?? {})) {
+        const list = diffs.get(patched) ?? [];
+        if (!list.includes(diff)) diffs.set(patched, [diff, ...list]);
+      }
+    }
+    generated?.(`${n}.sca`, room.sca);
+    generated?.(`${n}.msg`, room.msg);
+    files.push(`${n}.sca`, `${n}.msg`);
+  }
+  flags?.save();
+  const out: BuiltResource[] = [];
+  // <n>.png (+ <n>.layer-<priority>.png): a room picture.
+  for (const file of pictures) {
+    const n = Number(file.split(".")[0]);
+    out.push({ type: ResourceType.Pic, number: n, data: writePic(await picFromPngs(modDir, n, rm)) });
+  }
+  // *.view.json: a view (sprite/animation) from PNGs. Built after pictures, which it may use.
+  for (const file of views) {
+    const { number, view } = await viewFromManifest(join(modDir, file), rmWith(rm, out));
+    out.push({ type: ResourceType.View, number, data: writeView(view) });
+  }
+  const targets = [...files.filter((f) => !f.endsWith(".diff")), ...[...diffs.keys()].map((f) => `${f}.diff`)];
+  for (const file of new Set(targets)) {
+    const [n, kind] = file.split(".") as [string, "sca" | "msg"];
+    let text: string;
+    if (file.endsWith(".diff")) {
+      const source = join(work, `${n}.${kind}`);
+      writeFileSync(source, kind === "sca" ? toAssembly(await world.script(Number(n)), ctx) : await dumpMessages(rm, world, Number(n)));
+      for (const diff of diffs.get(`${n}.${kind}`)!) execFileSync("patch", ["--quiet", "--forward", source, diff], { stdio: "inherit" });
+      text = readFileSync(source, "utf8");
+    } else text = sources.get(file) ?? readFileSync(join(modDir, file), "utf8");
+    if (kind === "sca") {
+      const built = assemble(text, ctx);
+      out.push({ type: ResourceType.Script, number: built.number, data: built.code }, { type: ResourceType.Heap, number: built.number, data: built.heap });
+    } else {
+      const { number, file: messages } = messagesFromText(text);
+      out.push({ type: ResourceType.Message, number, data: writeMessages(messages) });
+    }
+  }
+  return out;
+}
+
+/**
+ * A mod's flags.yaml: Yarn variable -> flag number. Saved games store flags by number, so
+ * a name keeps its number once given: new names get the next free one (the build adds them
+ * to the file; commit it with the mod). `$game<n>` is the game's own flag n.
+ */
+export function modFlags(modDir: string, target: ModTarget): { number: (name: string) => number; save: () => void } {
+  const file = join(modDir, "flags.yaml");
+  const { first, last } = target.content.flags;
+  const numbers = new Map<string, number>();
+  if (existsSync(file)) {
+    readFileSync(file, "utf8").split("\n").forEach((raw, i) => {
+      const line = raw.replace(/#.*/, "").trim();
+      if (!line) return;
+      const m = /^([A-Za-z_]\w*)\s*:\s*(\d+)$/.exec(line);
+      if (!m) throw new Error(`${file}:${i + 1}: expected name: number`);
+      const n = Number(m[2]);
+      if (n < first || n > last) throw new Error(`${file}:${i + 1}: ${n} is outside the flags mods may use (${first}-${last})`);
+      if ([...numbers.values()].includes(n)) throw new Error(`${file}:${i + 1}: flag ${n} is used twice`);
+      numbers.set(m[1]!, n);
+    });
+  }
+  let added = false;
+  return {
+    number(name) {
+      const game = /^game(\d+)$/.exec(name);
+      if (game) {
+        const n = Number(game[1]);
+        if (n > last) throw new Error(`the game's flags go up to ${last}`);
+        return n;
+      }
+      let n = numbers.get(name);
+      if (n === undefined) {
+        const used = new Set(numbers.values());
+        for (n = first; used.has(n); n++);
+        if (n > last) throw new Error(`no free flags left (${first}-${last})`);
+        numbers.set(name, n);
+        added = true;
+      }
+      return n;
+    },
+    save() {
+      if (!added) return;
+      const lines = [...numbers].sort((a, b) => a[1] - b[1]).map(([name, n]) => `${name}: ${n}`);
+      writeFileSync(file, [
+        "# Flags for the Yarn variables ($name) in these rooms, kept by the build: new names get the",
+        "# next free number. Saved games store flags by number, so don't renumber once people play.",
+        ...lines, "",
+      ].join("\n"));
+    },
+  };
+}
+
+/** The game's resources plus what the mod has built so far (a view may use the mod's picture). */
+function rmWith(rm: ResourceManager, built: BuiltResource[]): ResourceManager {
+  return {
+    async load(id: { type: ResourceType; number: number }) {
+      const b = built.find((r) => r.type === id.type && r.number === id.number);
+      return b ? { ...id, data: b.data } : rm.load(id);
+    },
+  } as unknown as ResourceManager;
+}

package/tools/mod-target.d.ts

@@ -0,0 +1,16 @@
+import type { Target } from "../packages/content/src/index.ts";
+/**
+ * A game that mods can add rooms to: how the content compiler should write for it, plus
+ * patches to the game's own scripts that new rooms may need.
+ */
+export interface ModTarget {
+    content: Target;
+    /**
+     * Applied when a room brings its own characters: generated file (e.g. "0.sca") -> diff
+     * that teaches the game to ask the current room for talkers numbered from
+     * `content.firstRoomTalker`.
+     */
+    roomTalkerPatches?: Record<string, string>;
+}
+/** The target named in a mod's mod.yaml (`target: <name>`): tools/targets/<name>.ts. */
+export declare function loadTarget(modDir: string): Promise<ModTarget>;

package/tools/mod-target.js

@@ -0,0 +1,26 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+const TARGETS = join(import.meta.dirname, "targets");
+/** The target named in a mod's mod.yaml (`target: <name>`): tools/targets/<name>.ts. */
+export async function loadTarget(modDir) {
+    const file = join(modDir, "mod.yaml");
+    const known = existsSync(TARGETS) ? readdirSync(TARGETS).filter((f) => f.endsWith(".ts")).map((f) => f.slice(0, -3)) : [];
+    const listing = known.length ? `available: ${known.join(", ")}` : "none in tools/targets";
+    if (!existsSync(file))
+        throw new Error(`${modDir}: rooms need a mod.yaml naming the game (target: <name>; ${listing})`);
+    const name = /^target:\s*([\w-]+)\s*$/m.exec(readFileSync(file, "utf8"))?.[1];
+    if (!name)
+        throw new Error(`${file}: expected a line "target: <name>" (${listing})`);
+    if (!known.includes(name))
+        throw new Error(`${file}: unknown target "${name}" (${listing})`);
+    const mod = (await import(__rewriteRelativeImportExtension(join(TARGETS, `${name}.ts`))));
+    return mod.default;
+}

package/tools/mod-target.ts

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Target } from "../packages/content/src/index.ts";
+
+/**
+ * A game that mods can add rooms to: how the content compiler should write for it, plus
+ * patches to the game's own scripts that new rooms may need.
+ */
+export interface ModTarget {
+  content: Target;
+  /**
+   * Applied when a room brings its own characters: generated file (e.g. "0.sca") -> diff
+   * that teaches the game to ask the current room for talkers numbered from
+   * `content.firstRoomTalker`.
+   */
+  roomTalkerPatches?: Record<string, string>;
+}
+
+const TARGETS = join(import.meta.dirname, "targets");
+
+/** The target named in a mod's mod.yaml (`target: <name>`): tools/targets/<name>.ts. */
+export async function loadTarget(modDir: string): Promise<ModTarget> {
+  const file = join(modDir, "mod.yaml");
+  const known = existsSync(TARGETS) ? readdirSync(TARGETS).filter((f) => f.endsWith(".ts")).map((f) => f.slice(0, -3)) : [];
+  const listing = known.length ? `available: ${known.join(", ")}` : "none in tools/targets";
+  if (!existsSync(file)) throw new Error(`${modDir}: rooms need a mod.yaml naming the game (target: <name>; ${listing})`);
+  const name = /^target:\s*([\w-]+)\s*$/m.exec(readFileSync(file, "utf8"))?.[1];
+  if (!name) throw new Error(`${file}: expected a line "target: <name>" (${listing})`);
+  if (!known.includes(name)) throw new Error(`${file}: unknown target "${name}" (${listing})`);
+  const mod = (await import(join(TARGETS, `${name}.ts`))) as { default: ModTarget };
+  return mod.default;
+}

package/tools/mod.d.ts

@@ -0,0 +1 @@
+export {};

package/tools/mod.js

@@ -0,0 +1,47 @@
+/**
+ * Mods: directories of new files and diffs against generated text.
+ *   pnpm mod build <modDir> [outDir]   build <n>.sca / <n>.msg (new files) and apply <n>.sca.diff /
+ *                                      <n>.msg.diff (changes) to fresh dumps; patch files go to
+ *                                      out/mods/<name> by default
+ *                                      (<n>.room.yaml + <n>.yarn rooms are compiled first; the
+ *                                      generated .sca/.msg land in <outDir>/generated to read)
+ *   pnpm mod dump <n> <dir>            write <n>.sca and <n>.msg to start editing
+ *
+ * The repo holds only our own files and diffs, never Sierra's scripts or text. Tools load
+ * built mods with SCI_MODS=out/mods/<name>[,...] and the browser pages with ?mods=<name>,
+ * the way the game loads Sierra's own patch files.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ResourceManager, ResourceType, ScriptWorld, toAssembly } from "../packages/sci/src/index.js";
+import { buildMod, dumpMessages } from "./mod-build.js";
+import { nodeFiles } from "./node-files.js";
+import { writePatch } from "./patches.js";
+const [command, ...args] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+const world = await ScriptWorld.open(rm);
+await world.loadAllClasses();
+const ctx = world.asmContext();
+if (command === "dump") {
+    const [n, dir = "."] = [Number(args[0]), args[1]];
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${n}.sca`), toAssembly(await world.script(n), ctx));
+    const hasMessages = rm.has({ type: ResourceType.Message, number: n });
+    if (hasMessages)
+        writeFileSync(join(dir, `${n}.msg`), await dumpMessages(rm, world, n));
+    console.log(`wrote ${n}.sca${hasMessages ? ` and ${n}.msg` : ""} to ${dir}`);
+}
+else if (command === "build") {
+    const modDir = args[0].replace(/\/$/, "");
+    const outDir = args[1] ?? join("out/mods", basename(modDir));
+    const generated = join(outDir, "generated");
+    const built = await buildMod(modDir, rm, world, ctx, (file, text) => {
+        mkdirSync(generated, { recursive: true });
+        writeFileSync(join(generated, file), text);
+    });
+    for (const r of built)
+        writePatch(outDir, r.type, r.number, r.data);
+}
+else {
+    console.log("usage: pnpm mod build <modDir> [outDir] | pnpm mod dump <n> <dir>");
+}

package/tools/mod.ts

@@ -0,0 +1,45 @@
+/**
+ * Mods: directories of new files and diffs against generated text.
+ *   pnpm mod build <modDir> [outDir]   build <n>.sca / <n>.msg (new files) and apply <n>.sca.diff /
+ *                                      <n>.msg.diff (changes) to fresh dumps; patch files go to
+ *                                      out/mods/<name> by default
+ *                                      (<n>.room.yaml + <n>.yarn rooms are compiled first; the
+ *                                      generated .sca/.msg land in <outDir>/generated to read)
+ *   pnpm mod dump <n> <dir>            write <n>.sca and <n>.msg to start editing
+ *
+ * The repo holds only our own files and diffs, never Sierra's scripts or text. Tools load
+ * built mods with SCI_MODS=out/mods/<name>[,...] and the browser pages with ?mods=<name>,
+ * the way the game loads Sierra's own patch files.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ResourceManager, ResourceType, ScriptWorld, toAssembly } from "../packages/sci/src/index.ts";
+import { buildMod, dumpMessages } from "./mod-build.ts";
+import { nodeFiles } from "./node-files.ts";
+import { writePatch } from "./patches.ts";
+
+const [command, ...args] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+const world = await ScriptWorld.open(rm);
+await world.loadAllClasses();
+const ctx = world.asmContext();
+
+if (command === "dump") {
+  const [n, dir = "."] = [Number(args[0]), args[1]];
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${n}.sca`), toAssembly(await world.script(n), ctx));
+  const hasMessages = rm.has({ type: ResourceType.Message, number: n });
+  if (hasMessages) writeFileSync(join(dir, `${n}.msg`), await dumpMessages(rm, world, n));
+  console.log(`wrote ${n}.sca${hasMessages ? ` and ${n}.msg` : ""} to ${dir}`);
+} else if (command === "build") {
+  const modDir = args[0]!.replace(/\/$/, "");
+  const outDir = args[1] ?? join("out/mods", basename(modDir));
+  const generated = join(outDir, "generated");
+  const built = await buildMod(modDir, rm, world, ctx, (file, text) => {
+    mkdirSync(generated, { recursive: true });
+    writeFileSync(join(generated, file), text);
+  });
+  for (const r of built) writePatch(outDir, r.type, r.number, r.data);
+} else {
+  console.log("usage: pnpm mod build <modDir> [outDir] | pnpm mod dump <n> <dir>");
+}

package/tools/msg.d.ts

@@ -0,0 +1 @@
+export {};

package/tools/msg.js

@@ -0,0 +1,40 @@
+/**
+ * Message resources as text.
+ *   pnpm msg dump <n> [file.msg]     write a message file as text (verbs and nouns annotated)
+ *   pnpm msg build <file.msg> [dir]  build a <n>.MSG patch file (default out/mods)
+ *   pnpm msg roundtrip               parse + write every message file, compare bytes
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { ResourceManager, ResourceType, ScriptWorld, messagesFromText, messagesToText, parseMessages, writeMessages } from "../packages/sci/src/index.js";
+import { dumpMessages } from "./mod-build.js";
+import { nodeFiles } from "./node-files.js";
+import { writePatch } from "./patches.js";
+const [command = "roundtrip", ...args] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+if (command === "dump") {
+    const text = await dumpMessages(rm, await ScriptWorld.open(rm), Number(args[0]));
+    if (args[1])
+        writeFileSync(args[1], text);
+    else
+        process.stdout.write(text);
+}
+else if (command === "build") {
+    const { number, file } = messagesFromText(readFileSync(args[0], "utf8"));
+    writePatch(args[1] ?? "out/mods", ResourceType.Message, number, writeMessages(file));
+}
+else {
+    let ok = 0;
+    const bad = [];
+    const list = rm.list(ResourceType.Message);
+    for (const info of list) {
+        const data = (await rm.load(info)).data;
+        const direct = writeMessages(parseMessages(data));
+        const viaText = writeMessages(messagesFromText(messagesToText(info.number, parseMessages(data))).file);
+        if (Buffer.compare(Buffer.from(data), Buffer.from(direct)) === 0 && Buffer.compare(Buffer.from(data), Buffer.from(viaText)) === 0)
+            ok++;
+        else
+            bad.push(info.number);
+    }
+    console.log(`${ok}/${list.length} message files round-trip byte-exact (binary and via text)${bad.length ? `; differ: ${bad.join(" ")}` : ""}`);
+    process.exitCode = bad.length ? 1 : 0;
+}

package/tools/msg.ts

@@ -0,0 +1,36 @@
+/**
+ * Message resources as text.
+ *   pnpm msg dump <n> [file.msg]     write a message file as text (verbs and nouns annotated)
+ *   pnpm msg build <file.msg> [dir]  build a <n>.MSG patch file (default out/mods)
+ *   pnpm msg roundtrip               parse + write every message file, compare bytes
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { ResourceManager, ResourceType, ScriptWorld, messagesFromText, messagesToText, parseMessages, writeMessages } from "../packages/sci/src/index.ts";
+import { dumpMessages } from "./mod-build.ts";
+import { nodeFiles } from "./node-files.ts";
+import { writePatch } from "./patches.ts";
+
+const [command = "roundtrip", ...args] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+
+if (command === "dump") {
+  const text = await dumpMessages(rm, await ScriptWorld.open(rm), Number(args[0]));
+  if (args[1]) writeFileSync(args[1], text);
+  else process.stdout.write(text);
+} else if (command === "build") {
+  const { number, file } = messagesFromText(readFileSync(args[0]!, "utf8"));
+  writePatch(args[1] ?? "out/mods", ResourceType.Message, number, writeMessages(file));
+} else {
+  let ok = 0;
+  const bad: number[] = [];
+  const list = rm.list(ResourceType.Message);
+  for (const info of list) {
+    const data = (await rm.load(info)).data;
+    const direct = writeMessages(parseMessages(data));
+    const viaText = writeMessages(messagesFromText(messagesToText(info.number, parseMessages(data))).file);
+    if (Buffer.compare(Buffer.from(data), Buffer.from(direct)) === 0 && Buffer.compare(Buffer.from(data), Buffer.from(viaText)) === 0) ok++;
+    else bad.push(info.number);
+  }
+  console.log(`${ok}/${list.length} message files round-trip byte-exact (binary and via text)${bad.length ? `; differ: ${bad.join(" ")}` : ""}`);
+  process.exitCode = bad.length ? 1 : 0;
+}

package/tools/node-files.d.ts

@@ -0,0 +1,3 @@
+import type { FileSource } from "../packages/sci/src/index.ts";
+/** FileSource over a local game directory. */
+export declare function nodeFiles(root: string): FileSource;

package/tools/node-files.js

@@ -0,0 +1,34 @@
+import { open, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/** FileSource over a local game directory. */
+export function nodeFiles(root) {
+    return {
+        async read(path) {
+            try {
+                return new Uint8Array(await readFile(join(root, path)));
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async readRange(path, offset, length) {
+            const fh = await open(join(root, path));
+            try {
+                const buf = new Uint8Array(length);
+                await fh.read(buf, 0, length, offset);
+                return buf;
+            }
+            finally {
+                await fh.close();
+            }
+        },
+        async list(dir) {
+            try {
+                return await readdir(join(root, dir));
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}