sci2-ts 0.0.0-stage → 0.2.2

package/tools/asm.ts

@@ -0,0 +1,55 @@
+/**
+ * SCI2 assembly.
+ *   pnpm asm dump <script> [file.sca]     write a script as assembly text
+ *   pnpm asm build <file.sca> [outDir]    assemble into <n>.SCR + <n>.HEP patch files
+ *   pnpm asm roundtrip [script...]        disassemble + reassemble, compare bytes (all by default)
+ *
+ * Mods (diffs against these dumps) are built with `pnpm mod`, see tools/mod.ts.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { ResourceManager, ResourceType, ScriptWorld, assemble, toAssembly } from "../packages/sci/src/index.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"));
+const world = await ScriptWorld.open(rm);
+await world.loadAllClasses();
+const ctx = world.asmContext();
+
+const firstDiff = (a: Uint8Array, b: Uint8Array) => {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) if (a[i] !== b[i]) return i;
+  return -1;
+};
+
+if (command === "dump") {
+  const text = toAssembly(await world.script(Number(args[0])), ctx);
+  if (args[1]) writeFileSync(args[1], text);
+  else process.stdout.write(text);
+} else if (command === "build") {
+  build(readFileSync(args[0]!, "utf8"), args[1] ?? "out/mods");
+} else if (command === "roundtrip") {
+  const numbers = args.length ? args.map(Number) : rm.list(ResourceType.Script).map((r) => r.number).filter((n) => rm.has({ type: ResourceType.Heap, number: n }));
+  let ok = 0;
+  const failures: string[] = [];
+  for (const n of numbers) {
+    const s = await world.script(n);
+    try {
+      const out = assemble(toAssembly(s, ctx), ctx);
+      const dc = firstDiff(s.code, out.code), dh = firstDiff(s.heap, out.heap);
+      if (dc < 0 && dh < 0) ok++;
+      else failures.push(`${n}: ${dc >= 0 ? `code differs at $${dc.toString(16)} (${s.code.length} vs ${out.code.length} bytes)` : ""} ${dh >= 0 ? `heap differs at $${dh.toString(16)} (${s.heap.length} vs ${out.heap.length} bytes)` : ""}`);
+    } catch (e) {
+      failures.push(`${n}: ${(e as Error).message}`);
+    }
+  }
+  console.log(`${ok}/${numbers.length} scripts round-trip byte-exact`);
+  if (failures.length) console.log(failures.slice(0, 20).join("\n"));
+  process.exitCode = failures.length ? 1 : 0;
+}
+
+function build(text: string, dir: string) {
+  const out = assemble(text, ctx);
+  writePatch(dir, ResourceType.Script, out.number, out.code);
+  writePatch(dir, ResourceType.Heap, out.number, out.heap);
+}

package/tools/cli.d.ts

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

package/tools/cli.js

@@ -0,0 +1,99 @@
+/**
+ * sci-ts: the command for making games with sci-ts. Run it in a game's folder, or give it one.
+ *
+ *   sci-ts new <dir>                    a new game: a room in YAML and Yarn, the game, placeholder art
+ *   sci-ts build [dir] [--out <dir>]    RESOURCE.MAP, RESOURCE.000 (and .SFX) in <dir>/out/game
+ *   sci-ts play [dir] [--port <n>]      build it, then serve the player for it
+ *   sci-ts edit [dir] [--port <n>]      build it, then serve the live editor for its rooms
+ *   sci-ts site [dir] [--out <dir>]     a static site: the game's README and docs, and the game
+ *                                       in the player (in <dir>/out/site)
+ *   sci-ts art check|build <art.json> [out]   check or build editor-made art (tools/art.ts)
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { writeResourceArchive } from "../packages/sci/src/index.js";
+import { GameBuildError, buildGame } from "./game/build.js";
+import { newGame } from "./game/new.js";
+import { buildSite } from "./site/build.js";
+const VIEWER = resolve(import.meta.dirname, "../apps/viewer");
+const usage = `usage: sci-ts new <dir>
+       sci-ts build|play|edit|site [dir] [--out <dir>] [--port <n>]
+       sci-ts art check|build <art.json> [out]`;
+const [command, ...rest] = process.argv.slice(2);
+const option = (name) => {
+    const i = rest.indexOf(`--${name}`);
+    return i >= 0 ? rest.splice(i, 2)[1] : undefined;
+};
+const out = option("out"), port = option("port");
+const dir = resolve(rest[0] ?? ".");
+const shown = (p) => relative(process.cwd(), p) || ".";
+/** Builds the game in `dir` into `to`; prints warnings and a summary. */
+async function build(to) {
+    const game = await buildGame(dir);
+    const { map, volume } = writeResourceArchive(game.resources);
+    mkdirSync(to, { recursive: true });
+    writeFileSync(join(to, "RESOURCE.MAP"), map);
+    writeFileSync(join(to, "RESOURCE.000"), volume);
+    for (const [name, data] of Object.entries(game.files))
+        writeFileSync(join(to, name), data);
+    for (const w of game.warnings)
+        console.warn(`warning: ${w}`);
+    console.log(`${shown(to)}: ${game.resources.length} resources, ${game.classes.size} classes`);
+}
+/** Serves the viewer app for the game in `dir`, built into `to`; `page` is what to open. */
+async function serve(to, page) {
+    process.env.SCI_GAME = to;
+    process.env.SCI_GAME_SOURCE = dir;
+    const { createServer } = await import("vite");
+    const server = await createServer({ root: VIEWER, configFile: join(VIEWER, "vite.config.ts"), server: { port: port ? Number(port) : 5173 } });
+    await server.listen();
+    const url = server.resolvedUrls?.local[0] ?? "http://localhost:5173/";
+    console.log(`${basename(dir)}: ${url}${page}`);
+}
+try {
+    if (["build", "play", "edit", "site"].includes(command ?? "") && !existsSync(join(dir, "scripts"))) {
+        throw new GameBuildError(`${shown(dir)}: no game here (no scripts/ folder); sci-ts new <dir> starts one`);
+    }
+    switch (command) {
+        case "new": {
+            if (!rest[0])
+                throw new GameBuildError(usage);
+            const target = newGame(rest[0]);
+            console.log(`${shown(target)}: a room (rooms/1.room.yaml, 1.yarn), the game (scripts/0.sc) and placeholder art (resources.ts)`);
+            console.log(shown(target) === "." ? "  sci-ts play" : `  cd ${shown(target)} && sci-ts play`);
+            break;
+        }
+        case "build":
+            await build(resolve(out ?? join(dir, "out/game")));
+            break;
+        case "play":
+        case "edit": {
+            const to = join(dir, "out/game");
+            await build(to);
+            await serve(to, command === "play" ? "play.html" : `editor.html?mod=${basename(dir)}`);
+            break;
+        }
+        case "site": {
+            const to = resolve(out ?? join(dir, "out/site"));
+            const site = await buildSite(dir, to, { docs: dir, name: basename(dir) });
+            console.log(`${shown(to)}: ${site.pages} pages, the game in play/play.html${site.soundFont ? "" : " (no SoundFont: music is silent)"}`);
+            break;
+        }
+        case "art": {
+            // The art tool keeps its own command line; run it with this process's loader (tsx).
+            const art = spawn(process.execPath, [...process.execArgv, join(import.meta.dirname, "art.ts"), ...rest], { stdio: "inherit" });
+            art.on("exit", (code) => process.exit(code ?? 1));
+            break;
+        }
+        default:
+            console.error(usage);
+            process.exit(2);
+    }
+}
+catch (e) {
+    if (!(e instanceof GameBuildError))
+        throw e;
+    console.error(e.message);
+    process.exit(1);
+}

package/tools/cli.ts

@@ -0,0 +1,100 @@
+/**
+ * sci-ts: the command for making games with sci-ts. Run it in a game's folder, or give it one.
+ *
+ *   sci-ts new <dir>                    a new game: a room in YAML and Yarn, the game, placeholder art
+ *   sci-ts build [dir] [--out <dir>]    RESOURCE.MAP, RESOURCE.000 (and .SFX) in <dir>/out/game
+ *   sci-ts play [dir] [--port <n>]      build it, then serve the player for it
+ *   sci-ts edit [dir] [--port <n>]      build it, then serve the live editor for its rooms
+ *   sci-ts site [dir] [--out <dir>]     a static site: the game's README and docs, and the game
+ *                                       in the player (in <dir>/out/site)
+ *   sci-ts art check|build <art.json> [out]   check or build editor-made art (tools/art.ts)
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { writeResourceArchive } from "../packages/sci/src/index.ts";
+import { GameBuildError, buildGame } from "./game/build.ts";
+import { newGame } from "./game/new.ts";
+import { buildSite } from "./site/build.ts";
+
+const VIEWER = resolve(import.meta.dirname, "../apps/viewer");
+const usage = `usage: sci-ts new <dir>
+       sci-ts build|play|edit|site [dir] [--out <dir>] [--port <n>]
+       sci-ts art check|build <art.json> [out]`;
+
+const [command, ...rest] = process.argv.slice(2);
+const option = (name: string) => {
+  const i = rest.indexOf(`--${name}`);
+  return i >= 0 ? rest.splice(i, 2)[1] : undefined;
+};
+const out = option("out"), port = option("port");
+const dir = resolve(rest[0] ?? ".");
+const shown = (p: string) => relative(process.cwd(), p) || ".";
+
+/** Builds the game in `dir` into `to`; prints warnings and a summary. */
+async function build(to: string) {
+  const game = await buildGame(dir);
+  const { map, volume } = writeResourceArchive(game.resources);
+  mkdirSync(to, { recursive: true });
+  writeFileSync(join(to, "RESOURCE.MAP"), map);
+  writeFileSync(join(to, "RESOURCE.000"), volume);
+  for (const [name, data] of Object.entries(game.files)) writeFileSync(join(to, name), data);
+  for (const w of game.warnings) console.warn(`warning: ${w}`);
+  console.log(`${shown(to)}: ${game.resources.length} resources, ${game.classes.size} classes`);
+}
+
+/** Serves the viewer app for the game in `dir`, built into `to`; `page` is what to open. */
+async function serve(to: string, page: string) {
+  process.env.SCI_GAME = to;
+  process.env.SCI_GAME_SOURCE = dir;
+  const { createServer } = await import("vite");
+  const server = await createServer({ root: VIEWER, configFile: join(VIEWER, "vite.config.ts"), server: { port: port ? Number(port) : 5173 } });
+  await server.listen();
+  const url = server.resolvedUrls?.local[0] ?? "http://localhost:5173/";
+  console.log(`${basename(dir)}: ${url}${page}`);
+}
+
+try {
+  if (["build", "play", "edit", "site"].includes(command ?? "") && !existsSync(join(dir, "scripts"))) {
+    throw new GameBuildError(`${shown(dir)}: no game here (no scripts/ folder); sci-ts new <dir> starts one`);
+  }
+  switch (command) {
+    case "new": {
+      if (!rest[0]) throw new GameBuildError(usage);
+      const target = newGame(rest[0]);
+      console.log(`${shown(target)}: a room (rooms/1.room.yaml, 1.yarn), the game (scripts/0.sc) and placeholder art (resources.ts)`);
+      console.log(shown(target) === "." ? "  sci-ts play" : `  cd ${shown(target)} && sci-ts play`);
+      break;
+    }
+    case "build":
+      await build(resolve(out ?? join(dir, "out/game")));
+      break;
+    case "play":
+    case "edit": {
+      const to = join(dir, "out/game");
+      await build(to);
+      await serve(to, command === "play" ? "play.html" : `editor.html?mod=${basename(dir)}`);
+      break;
+    }
+    case "site": {
+      const to = resolve(out ?? join(dir, "out/site"));
+      const site = await buildSite(dir, to, { docs: dir, name: basename(dir) });
+      console.log(`${shown(to)}: ${site.pages} pages, the game in play/play.html${site.soundFont ? "" : " (no SoundFont: music is silent)"}`);
+      break;
+    }
+    case "art": {
+      // The art tool keeps its own command line; run it with this process's loader (tsx).
+      const art = spawn(process.execPath, [...process.execArgv, join(import.meta.dirname, "art.ts"), ...rest], { stdio: "inherit" });
+      art.on("exit", (code) => process.exit(code ?? 1));
+      break;
+    }
+    default:
+      console.error(usage);
+      process.exit(2);
+  }
+} catch (e) {
+  if (!(e instanceof GameBuildError)) throw e;
+  console.error(e.message);
+  process.exit(1);
+}
+

package/tools/editor-server.d.ts

@@ -0,0 +1,29 @@
+export declare function listMods(): {
+    name: string;
+    kind: "mod" | "game";
+    rooms: number[];
+}[];
+export declare function readFiles(name: string): Record<string, string>;
+export interface BuildResult {
+    ok: boolean;
+    /** Everything the mod builds, base64: the page swaps it into the running game. */
+    resources?: {
+        type: number;
+        number: number;
+        data: string;
+    }[];
+    /** The compiled .sca / .msg text, for reading. */
+    generated?: Record<string, string>;
+    /** flags.yaml after the build (new variables get numbers). */
+    flags?: string;
+    /** What changed can't be swapped into a running game (its selectors): reload the page. */
+    reload?: boolean;
+    ms?: number;
+    error?: {
+        message: string;
+        file?: string;
+        line?: number;
+    };
+}
+/** Writes `files` (only room files) into the mod, then builds it. One build at a time. */
+export declare function save(mod: string, files: Record<string, string>): Promise<BuildResult>;

package/tools/editor-server.js

@@ -0,0 +1,162 @@
+/**
+ * The live editor's server side (apps/viewer/editor.html, through the dev server's
+ * /__editor routes): lists what can be edited, reads its room files, and on save writes them
+ * and builds, returning the built resources for the page to swap into the running game.
+ *
+ * What's edited depends on what the dev server serves. A game of ours (SCI_GAME=
+ * out/games/<name>): its YAML rooms, rebuilt with `pnpm game build`; the page gets the
+ * resources that changed. Sierra's game: mods, built like `pnpm mod build`, with the game's
+ * files and class tables kept loaded between builds.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { ResourceManager, ResourceType, ScriptWorld, writeResourceArchive } from "../packages/sci/src/index.js";
+import { buildGame } from "./game/build.js";
+import { buildMod } from "./mod-build.js";
+import { nodeFiles } from "./node-files.js";
+import { writePatch } from "./patches.js";
+const ROOT = resolve(import.meta.dirname, "..");
+const MODS = join(ROOT, "mods");
+const GAMES = join(ROOT, "games");
+/** The files the editor shows and may write: rooms as data; for our games, scripts and messages too. */
+const EDITABLE = /^(\d+\.room\.yaml|\d+\.yarn|flags\.yaml)$/;
+const GAME_EDITABLE = /^(\d+\.room\.yaml|\d+\.yarn|flags\.yaml|\d+\.sc|\d+\.msg)$/;
+/**
+ * The game of ours the dev server serves, if it is one: SCI_GAME_SOURCE names its folder
+ * (`sci-ts edit`), or SCI_GAME is out/games/<name> for a game in games/.
+ */
+const served = (() => {
+    const source = process.env.SCI_GAME_SOURCE;
+    if (source && existsSync(join(source, "scripts")))
+        return { name: basename(resolve(source)), dir: resolve(source), out: resolve(process.env.SCI_GAME ?? join(source, "out/game")) };
+    const name = /(?:^|\/)out\/games\/([\w-]+)\/?$/.exec(process.env.SCI_GAME ?? "")?.[1];
+    return name && existsSync(join(GAMES, name)) ? { name, dir: join(GAMES, name), out: join(ROOT, "out/games", name) } : undefined;
+})();
+const servedGame = served?.name;
+/** Where an editable thing's files are: a mod's folder, or a game's rooms/ (flags.yaml beside it). */
+function filesDir(name) {
+    if (served && name === served.name)
+        return { dir: served.dir, game: true };
+    return { dir: modDir(name), game: false };
+}
+const fileIn = (where, file) => join(where.dir, !where.game || file === "flags.yaml" ? "" : file.endsWith(".sc") ? "scripts" : file.endsWith(".msg") ? "messages" : "rooms", file);
+let game;
+const openGame = () => (game ??= (async () => {
+    const rm = await ResourceManager.open(nodeFiles(join(ROOT, "original")));
+    const world = await ScriptWorld.open(rm);
+    await world.loadAllClasses();
+    return { rm, world, ctx: world.asmContext() };
+})());
+const modDir = (mod) => {
+    if (!/^[\w-]+$/.test(mod) || !existsSync(join(MODS, mod)))
+        throw new Error(`no mod called "${mod}"`);
+    return join(MODS, mod);
+};
+const roomsIn = (dir) => existsSync(dir) ? readdirSync(dir).flatMap((f) => /^(\d+)\.room\.yaml$/.exec(f)?.[1] ?? []).map(Number).sort((a, b) => a - b) : [];
+export function listMods() {
+    if (servedGame) {
+        // Rooms as data, and scripts (besides 0, the game) that may be rooms.
+        const scripts = existsSync(join(served.dir, "scripts"))
+            ? readdirSync(join(served.dir, "scripts")).flatMap((f) => /^(\d+)\.sc$/.exec(f)?.[1] ?? []).map(Number).filter((n) => n !== 0)
+            : [];
+        const rooms = [...new Set([...roomsIn(join(served.dir, "rooms")), ...scripts])].sort((a, b) => a - b);
+        return [{ name: servedGame, kind: "game", rooms }];
+    }
+    return readdirSync(MODS)
+        .filter((d) => statSync(join(MODS, d)).isDirectory())
+        .map((name) => ({ name, kind: "mod", rooms: roomsIn(join(MODS, name)) }));
+}
+export function readFiles(name) {
+    const where = filesDir(name);
+    const list = (sub) => (existsSync(join(where.dir, sub)) ? readdirSync(join(where.dir, sub)) : []);
+    const names = where.game
+        ? [...list("rooms"), ...list("scripts"), ...list("messages"), ...(existsSync(join(where.dir, "flags.yaml")) ? ["flags.yaml"] : [])]
+        : readdirSync(where.dir);
+    const editable = where.game ? GAME_EDITABLE : EDITABLE;
+    return Object.fromEntries(names.filter((f) => editable.test(f)).map((f) => [f, readFileSync(fileIn(where, f), "utf8")]));
+}
+let queue = Promise.resolve();
+/** Writes `files` (only room files) into the mod, then builds it. One build at a time. */
+export function save(mod, files) {
+    const run = async () => {
+        const started = Date.now();
+        try {
+            const where = filesDir(mod);
+            for (const [name, text] of Object.entries(files)) {
+                if (!(where.game ? GAME_EDITABLE : EDITABLE).test(name))
+                    throw new Error(`the editor doesn't write ${name}`);
+                const path = fileIn(where, name);
+                if (!existsSync(path) || readFileSync(path, "utf8") !== text)
+                    writeFileSync(path, text);
+            }
+            if (where.game)
+                return { ...(await buildServedGame()), ms: Date.now() - started };
+            const dir = where.dir;
+            const { rm, world, ctx } = await openGame();
+            const generated = {};
+            const built = await buildMod(dir, rm, world, ctx, (file, text) => (generated[file] = text));
+            const out = join(ROOT, "out/mods", mod);
+            for (const r of built)
+                writePatch(out, r.type, r.number, r.data);
+            const flagsFile = join(dir, "flags.yaml");
+            return {
+                ok: true,
+                resources: built.map((r) => ({ type: r.type, number: r.number, data: Buffer.from(r.data).toString("base64") })),
+                generated,
+                flags: existsSync(flagsFile) ? readFileSync(flagsFile, "utf8") : undefined,
+                ms: Date.now() - started,
+            };
+        }
+        catch (e) {
+            const message = e.message;
+            // Compiler errors start with file:line.
+            const at = /^(?:.*\/)?([^/:\s]+):(\d+):/.exec(message);
+            // Paths in messages are relative to the dev server's folder (apps/viewer): from the repository's instead.
+            const shown = message.replaceAll(ROOT + "/", "").replace(/^(\.\.\/)+/, "");
+            return { ok: false, error: { message: shown, file: at?.[1], line: at ? Number(at[2]) : undefined }, ms: Date.now() - started };
+        }
+    };
+    const result = queue.then(run, run);
+    queue = result;
+    return result;
+}
+/**
+ * Rebuilds the game being served into its out folder, and returns what changed since the files
+ * there (which the page is running).
+ */
+async function buildServedGame() {
+    const game = await buildGame(served.dir);
+    const out = served.out;
+    const changed = [];
+    if (existsSync(join(out, "RESOURCE.MAP"))) {
+        const before = await ResourceManager.open(nodeFiles(out), []);
+        for (const r of game.resources) {
+            const old = before.has(r) ? (await before.load(r)).data : undefined;
+            if (!old || Buffer.compare(Buffer.from(old), Buffer.from(r.data)) !== 0)
+                changed.push(r);
+        }
+    }
+    else
+        changed.push(...game.resources);
+    const { map, volume } = writeResourceArchive(game.resources);
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "RESOURCE.MAP"), map);
+    writeFileSync(join(out, "RESOURCE.000"), volume);
+    for (const [file, data] of Object.entries(game.files))
+        writeFileSync(join(out, file), data);
+    // The running VM read its selector and class tables when it started.
+    const reload = changed.some((r) => r.type === ResourceType.Vocab);
+    const generated = {};
+    for (const [n, text] of game.generated)
+        generated[`${n}.sca`] = text;
+    for (const [n, text] of game.roomMessages)
+        generated[`${n}.msg`] = text;
+    const flagsFile = join(served.dir, "flags.yaml");
+    return {
+        ok: true,
+        resources: changed.map((r) => ({ type: r.type, number: r.number, data: Buffer.from(r.data).toString("base64") })),
+        generated,
+        flags: existsSync(flagsFile) ? readFileSync(flagsFile, "utf8") : undefined,
+        reload: reload || undefined,
+    };
+}

package/tools/editor-server.ts

@@ -0,0 +1,176 @@
+/**
+ * The live editor's server side (apps/viewer/editor.html, through the dev server's
+ * /__editor routes): lists what can be edited, reads its room files, and on save writes them
+ * and builds, returning the built resources for the page to swap into the running game.
+ *
+ * What's edited depends on what the dev server serves. A game of ours (SCI_GAME=
+ * out/games/<name>): its YAML rooms, rebuilt with `pnpm game build`; the page gets the
+ * resources that changed. Sierra's game: mods, built like `pnpm mod build`, with the game's
+ * files and class tables kept loaded between builds.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { ResourceManager, ResourceType, ScriptWorld, writeResourceArchive, type AsmContext } from "../packages/sci/src/index.ts";
+import { buildGame } from "./game/build.ts";
+import { buildMod, type BuiltResource } from "./mod-build.ts";
+import { nodeFiles } from "./node-files.ts";
+import { writePatch } from "./patches.ts";
+
+const ROOT = resolve(import.meta.dirname, "..");
+const MODS = join(ROOT, "mods");
+const GAMES = join(ROOT, "games");
+/** The files the editor shows and may write: rooms as data; for our games, scripts and messages too. */
+const EDITABLE = /^(\d+\.room\.yaml|\d+\.yarn|flags\.yaml)$/;
+const GAME_EDITABLE = /^(\d+\.room\.yaml|\d+\.yarn|flags\.yaml|\d+\.sc|\d+\.msg)$/;
+
+/**
+ * The game of ours the dev server serves, if it is one: SCI_GAME_SOURCE names its folder
+ * (`sci-ts edit`), or SCI_GAME is out/games/<name> for a game in games/.
+ */
+const served = (() => {
+  const source = process.env.SCI_GAME_SOURCE;
+  if (source && existsSync(join(source, "scripts"))) return { name: basename(resolve(source)), dir: resolve(source), out: resolve(process.env.SCI_GAME ?? join(source, "out/game")) };
+  const name = /(?:^|\/)out\/games\/([\w-]+)\/?$/.exec(process.env.SCI_GAME ?? "")?.[1];
+  return name && existsSync(join(GAMES, name)) ? { name, dir: join(GAMES, name), out: join(ROOT, "out/games", name) } : undefined;
+})();
+const servedGame = served?.name;
+
+/** Where an editable thing's files are: a mod's folder, or a game's rooms/ (flags.yaml beside it). */
+function filesDir(name: string): { dir: string; game: boolean } {
+  if (served && name === served.name) return { dir: served.dir, game: true };
+  return { dir: modDir(name), game: false };
+}
+const fileIn = (where: { dir: string; game: boolean }, file: string) =>
+  join(where.dir, !where.game || file === "flags.yaml" ? "" : file.endsWith(".sc") ? "scripts" : file.endsWith(".msg") ? "messages" : "rooms", file);
+
+let game: Promise<{ rm: ResourceManager; world: ScriptWorld; ctx: AsmContext }> | undefined;
+const openGame = () =>
+  (game ??= (async () => {
+    const rm = await ResourceManager.open(nodeFiles(join(ROOT, "original")));
+    const world = await ScriptWorld.open(rm);
+    await world.loadAllClasses();
+    return { rm, world, ctx: world.asmContext() };
+  })());
+
+const modDir = (mod: string) => {
+  if (!/^[\w-]+$/.test(mod) || !existsSync(join(MODS, mod))) throw new Error(`no mod called "${mod}"`);
+  return join(MODS, mod);
+};
+
+const roomsIn = (dir: string) =>
+  existsSync(dir) ? readdirSync(dir).flatMap((f) => /^(\d+)\.room\.yaml$/.exec(f)?.[1] ?? []).map(Number).sort((a, b) => a - b) : [];
+
+export function listMods(): { name: string; kind: "mod" | "game"; rooms: number[] }[] {
+  if (servedGame) {
+    // Rooms as data, and scripts (besides 0, the game) that may be rooms.
+    const scripts = existsSync(join(served!.dir, "scripts"))
+      ? readdirSync(join(served!.dir, "scripts")).flatMap((f) => /^(\d+)\.sc$/.exec(f)?.[1] ?? []).map(Number).filter((n) => n !== 0)
+      : [];
+    const rooms = [...new Set([...roomsIn(join(served!.dir, "rooms")), ...scripts])].sort((a, b) => a - b);
+    return [{ name: servedGame, kind: "game", rooms }];
+  }
+  return readdirSync(MODS)
+    .filter((d) => statSync(join(MODS, d)).isDirectory())
+    .map((name) => ({ name, kind: "mod" as const, rooms: roomsIn(join(MODS, name)) }));
+}
+
+export function readFiles(name: string): Record<string, string> {
+  const where = filesDir(name);
+  const list = (sub: string) => (existsSync(join(where.dir, sub)) ? readdirSync(join(where.dir, sub)) : []);
+  const names = where.game
+    ? [...list("rooms"), ...list("scripts"), ...list("messages"), ...(existsSync(join(where.dir, "flags.yaml")) ? ["flags.yaml"] : [])]
+    : readdirSync(where.dir);
+  const editable = where.game ? GAME_EDITABLE : EDITABLE;
+  return Object.fromEntries(names.filter((f) => editable.test(f)).map((f) => [f, readFileSync(fileIn(where, f), "utf8")]));
+}
+
+export interface BuildResult {
+  ok: boolean;
+  /** Everything the mod builds, base64: the page swaps it into the running game. */
+  resources?: { type: number; number: number; data: string }[];
+  /** The compiled .sca / .msg text, for reading. */
+  generated?: Record<string, string>;
+  /** flags.yaml after the build (new variables get numbers). */
+  flags?: string;
+  /** What changed can't be swapped into a running game (its selectors): reload the page. */
+  reload?: boolean;
+  ms?: number;
+  error?: { message: string; file?: string; line?: number };
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+/** Writes `files` (only room files) into the mod, then builds it. One build at a time. */
+export function save(mod: string, files: Record<string, string>): Promise<BuildResult> {
+  const run = async (): Promise<BuildResult> => {
+    const started = Date.now();
+    try {
+      const where = filesDir(mod);
+      for (const [name, text] of Object.entries(files)) {
+        if (!(where.game ? GAME_EDITABLE : EDITABLE).test(name)) throw new Error(`the editor doesn't write ${name}`);
+        const path = fileIn(where, name);
+        if (!existsSync(path) || readFileSync(path, "utf8") !== text) writeFileSync(path, text);
+      }
+      if (where.game) return { ...(await buildServedGame()), ms: Date.now() - started };
+      const dir = where.dir;
+      const { rm, world, ctx } = await openGame();
+      const generated: Record<string, string> = {};
+      const built: BuiltResource[] = await buildMod(dir, rm, world, ctx, (file, text) => (generated[file] = text));
+      const out = join(ROOT, "out/mods", mod);
+      for (const r of built) writePatch(out, r.type, r.number, r.data);
+      const flagsFile = join(dir, "flags.yaml");
+      return {
+        ok: true,
+        resources: built.map((r) => ({ type: r.type, number: r.number, data: Buffer.from(r.data).toString("base64") })),
+        generated,
+        flags: existsSync(flagsFile) ? readFileSync(flagsFile, "utf8") : undefined,
+        ms: Date.now() - started,
+      };
+    } catch (e) {
+      const message = (e as Error).message;
+      // Compiler errors start with file:line.
+      const at = /^(?:.*\/)?([^/:\s]+):(\d+):/.exec(message);
+      // Paths in messages are relative to the dev server's folder (apps/viewer): from the repository's instead.
+      const shown = message.replaceAll(ROOT + "/", "").replace(/^(\.\.\/)+/, "");
+      return { ok: false, error: { message: shown, file: at?.[1], line: at ? Number(at[2]) : undefined }, ms: Date.now() - started };
+    }
+  };
+  const result = queue.then(run, run);
+  queue = result;
+  return result;
+}
+
+/**
+ * Rebuilds the game being served into its out folder, and returns what changed since the files
+ * there (which the page is running).
+ */
+async function buildServedGame(): Promise<BuildResult> {
+  const game = await buildGame(served!.dir);
+  const out = served!.out;
+  const changed: typeof game.resources = [];
+  if (existsSync(join(out, "RESOURCE.MAP"))) {
+    const before = await ResourceManager.open(nodeFiles(out), []);
+    for (const r of game.resources) {
+      const old = before.has(r) ? (await before.load(r)).data : undefined;
+      if (!old || Buffer.compare(Buffer.from(old), Buffer.from(r.data)) !== 0) changed.push(r);
+    }
+  } else changed.push(...game.resources);
+  const { map, volume } = writeResourceArchive(game.resources);
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, "RESOURCE.MAP"), map);
+  writeFileSync(join(out, "RESOURCE.000"), volume);
+  for (const [file, data] of Object.entries(game.files)) writeFileSync(join(out, file), data);
+  // The running VM read its selector and class tables when it started.
+  const reload = changed.some((r) => r.type === ResourceType.Vocab);
+  const generated: Record<string, string> = {};
+  for (const [n, text] of game.generated) generated[`${n}.sca`] = text;
+  for (const [n, text] of game.roomMessages) generated[`${n}.msg`] = text;
+  const flagsFile = join(served!.dir, "flags.yaml");
+  return {
+    ok: true,
+    resources: changed.map((r) => ({ type: r.type, number: r.number, data: Buffer.from(r.data).toString("base64") })),
+    generated,
+    flags: existsSync(flagsFile) ? readFileSync(flagsFile, "utf8") : undefined,
+    reload: reload || undefined,
+  };
+}

package/tools/explore.d.ts

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