sci2-ts 0.0.0-stage → 0.2.2

package/tools/adlib-render.d.ts

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

package/tools/adlib-render.js

@@ -0,0 +1,49 @@
+/**
+ * Renders a song through the AdLib path (sequencer → Sierra AdLib driver → OPL2 emulator)
+ * to a WAV file, for listening and for checking the emulator headlessly.
+ *   pnpm tsx tools/adlib-render.ts <sound number> [seconds] [--gm-track]
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { AdLibDriver, OPL_RATE, Opl2, ResourceManager, ResourceType, SongPlayer, SoundDevice, parseAdLibBank, parseSound } from "../packages/sci/src/index.js";
+import { nodeFiles } from "./node-files.js";
+const [number = "130", seconds = "30"] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+const bank = parseAdLibBank((await rm.load({ type: ResourceType.Patch, number: 3 })).data);
+const song = parseSound((await rm.load({ type: ResourceType.Sound, number: Number(number) })).data, SoundDevice.AdLib);
+if (!song)
+    throw new Error(`sound ${number} has no AdLib track`);
+const chip = new Opl2();
+const driver = new AdLibDriver(chip, bank);
+const player = new SongPlayer(song, driver, false, 127, 0);
+const ticks = Number(seconds) * 60;
+const out = new Float32Array(Math.ceil((ticks * OPL_RATE) / 60));
+let written = 0;
+for (let t = 0; t < ticks && !player.finished; t++) {
+    player.update(t);
+    const end = Math.round(((t + 1) * OPL_RATE) / 60);
+    chip.generate(out, written, end - written);
+    written = end;
+}
+let peak = 0, sum = 0;
+for (let i = 0; i < written; i++)
+    (peak = Math.max(peak, Math.abs(out[i]))), (sum += out[i] * out[i]);
+console.log({ sound: Number(number), seconds: +(written / OPL_RATE).toFixed(1), peak: +peak.toFixed(3), rms: +Math.sqrt(sum / written).toFixed(4), finished: player.finished });
+const wav = Buffer.alloc(44 + written * 2);
+wav.write("RIFF", 0);
+wav.writeUInt32LE(36 + written * 2, 4);
+wav.write("WAVE", 8);
+wav.write("fmt ", 12);
+wav.writeUInt32LE(16, 16);
+wav.writeUInt16LE(1, 20);
+wav.writeUInt16LE(1, 22);
+wav.writeUInt32LE(OPL_RATE, 24);
+wav.writeUInt32LE(OPL_RATE * 2, 28);
+wav.writeUInt16LE(2, 32);
+wav.writeUInt16LE(16, 34);
+wav.write("data", 36);
+wav.writeUInt32LE(written * 2, 40);
+for (let i = 0; i < written; i++)
+    wav.writeInt16LE(Math.round(out[i] * 32767), 44 + i * 2);
+mkdirSync("out/audio", { recursive: true });
+writeFileSync(`out/audio/adlib-${number}.wav`, wav);
+console.log(`wrote out/audio/adlib-${number}.wav`);

package/tools/adlib-render.ts

@@ -0,0 +1,42 @@
+/**
+ * Renders a song through the AdLib path (sequencer → Sierra AdLib driver → OPL2 emulator)
+ * to a WAV file, for listening and for checking the emulator headlessly.
+ *   pnpm tsx tools/adlib-render.ts <sound number> [seconds] [--gm-track]
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { AdLibDriver, OPL_RATE, Opl2, ResourceManager, ResourceType, SongPlayer, SoundDevice, parseAdLibBank, parseSound } from "../packages/sci/src/index.ts";
+import { nodeFiles } from "./node-files.ts";
+
+const [number = "130", seconds = "30"] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+const bank = parseAdLibBank((await rm.load({ type: ResourceType.Patch, number: 3 })).data);
+const song = parseSound((await rm.load({ type: ResourceType.Sound, number: Number(number) })).data, SoundDevice.AdLib);
+if (!song) throw new Error(`sound ${number} has no AdLib track`);
+
+const chip = new Opl2();
+const driver = new AdLibDriver(chip, bank);
+const player = new SongPlayer(song, driver, false, 127, 0);
+
+const ticks = Number(seconds) * 60;
+const out = new Float32Array(Math.ceil((ticks * OPL_RATE) / 60));
+let written = 0;
+for (let t = 0; t < ticks && !player.finished; t++) {
+  player.update(t);
+  const end = Math.round(((t + 1) * OPL_RATE) / 60);
+  chip.generate(out, written, end - written);
+  written = end;
+}
+
+let peak = 0, sum = 0;
+for (let i = 0; i < written; i++) (peak = Math.max(peak, Math.abs(out[i]!))), (sum += out[i]! * out[i]!);
+console.log({ sound: Number(number), seconds: +(written / OPL_RATE).toFixed(1), peak: +peak.toFixed(3), rms: +Math.sqrt(sum / written).toFixed(4), finished: player.finished });
+
+const wav = Buffer.alloc(44 + written * 2);
+wav.write("RIFF", 0); wav.writeUInt32LE(36 + written * 2, 4); wav.write("WAVE", 8);
+wav.write("fmt ", 12); wav.writeUInt32LE(16, 16); wav.writeUInt16LE(1, 20); wav.writeUInt16LE(1, 22);
+wav.writeUInt32LE(OPL_RATE, 24); wav.writeUInt32LE(OPL_RATE * 2, 28); wav.writeUInt16LE(2, 32); wav.writeUInt16LE(16, 34);
+wav.write("data", 36); wav.writeUInt32LE(written * 2, 40);
+for (let i = 0; i < written; i++) wav.writeInt16LE(Math.round(out[i]! * 32767), 44 + i * 2);
+mkdirSync("out/audio", { recursive: true });
+writeFileSync(`out/audio/adlib-${number}.wav`, wav);
+console.log(`wrote out/audio/adlib-${number}.wav`);

package/tools/analyze.d.ts

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

package/tools/analyze.js

@@ -0,0 +1,25 @@
+/**
+ * Static game index (rooms, exits, classes, objects) as JSON.
+ *   pnpm tsx tools/analyze.ts [--summary]
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { ResourceManager, analyzeGame } from "../packages/sci/src/index.js";
+import { nodeFiles } from "./node-files.js";
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+const t = performance.now();
+const index = await analyzeGame(rm);
+const ms = Math.round(performance.now() - t);
+mkdirSync("out", { recursive: true });
+writeFileSync("out/game-index.json", JSON.stringify(index));
+const byKind = {};
+for (const e of index.exits)
+    byKind[e.kind] = (byKind[e.kind] ?? 0) + 1;
+console.log(JSON.stringify({
+    ms,
+    rooms: index.rooms.length,
+    classes: index.classes.length,
+    objects: index.scripts.reduce((n, s) => n + s.objects.length, 0),
+    exits: byKind,
+    isolatedRooms: index.rooms.filter((r) => !index.exits.some((e) => e.from === r.number || e.to === r.number)).map((r) => r.number),
+    unresolved: index.unresolved.length,
+}, null, 1));

package/tools/analyze.ts

@@ -0,0 +1,25 @@
+/**
+ * Static game index (rooms, exits, classes, objects) as JSON.
+ *   pnpm tsx tools/analyze.ts [--summary]
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { ResourceManager, analyzeGame } from "../packages/sci/src/index.ts";
+import { nodeFiles } from "./node-files.ts";
+
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+const t = performance.now();
+const index = await analyzeGame(rm);
+const ms = Math.round(performance.now() - t);
+mkdirSync("out", { recursive: true });
+writeFileSync("out/game-index.json", JSON.stringify(index));
+const byKind: Record<string, number> = {};
+for (const e of index.exits) byKind[e.kind] = (byKind[e.kind] ?? 0) + 1;
+console.log(JSON.stringify({
+  ms,
+  rooms: index.rooms.length,
+  classes: index.classes.length,
+  objects: index.scripts.reduce((n, s) => n + s.objects.length, 0),
+  exits: byKind,
+  isolatedRooms: index.rooms.filter((r) => !index.exits.some((e) => e.from === r.number || e.to === r.number)).map((r) => r.number),
+  unresolved: index.unresolved.length,
+}, null, 1));

package/tools/art/build.d.ts

@@ -0,0 +1,34 @@
+import { type ResourceData } from "../../packages/sci/src/index.ts";
+/** Editor-neutral, exact-colour art for standalone games. See docs/art-workflow.md. */
+export interface ArtManifest {
+    version: 1;
+    palette: string;
+    /** Optional project art budget, including black and white but excluding transparency. */
+    maxColours?: number;
+    pictures: {
+        number: number;
+        layers: {
+            png: string;
+            priority: number;
+        }[];
+    }[];
+    views: {
+        number: number;
+        loops: ({
+            cels: {
+                png: string;
+                anchor: [number, number];
+            }[];
+        } | {
+            link: number;
+            mirror: boolean;
+        })[];
+    }[];
+}
+export declare class ArtError extends Error {
+}
+export declare function buildArt(file: string): {
+    resources: ResourceData[];
+    colours: string[];
+    images: number;
+};

package/tools/art/build.js

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { ResourceType, writeHunkPalette, writePic, writeView } from "../../packages/sci/src/index.js";
+import { basePalette } from "../game/defaults.js";
+import { decodePng } from "../png.js";
+export class ArtError extends Error {
+}
+export function buildArt(file) {
+    const fail = (where, message) => { throw new ArtError(`${file}: ${where}: ${message}`); };
+    const json = (path) => {
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (e) {
+            return fail(path, e.message);
+        }
+    };
+    const object = (value, where, keys) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return fail(where, "expected an object");
+        for (const key of Object.keys(value))
+            if (!keys.includes(key))
+                fail(`${where}.${key}`, "unknown key");
+        return value;
+    };
+    const list = (value, where, min, max) => {
+        if (!Array.isArray(value) || value.length < min || value.length > max)
+            return fail(where, `expected ${min}..${max} entries`);
+        return value;
+    };
+    const int = (value, where, min, max) => {
+        if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max)
+            return fail(where, `expected an integer in ${min}..${max}`);
+        return value;
+    };
+    const path = (value, where) => {
+        if (typeof value !== "string" || !value.length)
+            return fail(where, "expected a file path");
+        return resolve(dirname(file), value);
+    };
+    const m = object(json(file), "manifest", ["version", "palette", "maxColours", "pictures", "views"]);
+    if (m.version !== 1)
+        fail("version", "expected 1");
+    const maxColours = m.maxColours === undefined ? 254 : int(m.maxColours, "maxColours", 2, 254);
+    const paletteInput = json(path(m.palette, "palette"));
+    if (Array.isArray(paletteInput) && paletteInput.length > maxColours)
+        fail("palette", `${paletteInput.length} colours exceeds the project budget of ${maxColours}`);
+    const colours = list(paletteInput, "palette", 2, 254).map((c, i) => {
+        if (typeof c !== "string" || !/^#[0-9a-f]{6}$/i.test(c))
+            return fail(`palette[${i}]`, "expected #RRGGBB");
+        return c.toLowerCase();
+    });
+    if (colours[0] !== "#000000" || colours.at(-1) !== "#ffffff")
+        fail("palette", "first colour must be black, last white (interface colours)");
+    if (new Set(colours).size !== colours.length)
+        fail("palette", "duplicate colours");
+    // Preserve the library's black=0, white=255 and transparent=254 conventions.
+    // Entries 1..252 are ours; 253 is reserved. No room quantization or alpha remaps.
+    const palette = basePalette();
+    const indices = new Map();
+    colours.forEach((c, i) => {
+        const index = i === colours.length - 1 ? 255 : i;
+        palette.rgb[index] = [1, 3, 5].map((at) => parseInt(c.slice(at, at + 2), 16));
+        indices.set(c, index);
+    });
+    let images = 0;
+    const image = (value, where, opaque) => {
+        const filename = path(value, where);
+        let img;
+        try {
+            img = decodePng(readFileSync(filename));
+        }
+        catch (e) {
+            return fail(where, `${filename}: ${e.message}`);
+        }
+        int(img.width, `${where}.width`, 1, 320);
+        int(img.height, `${where}.height`, 1, 200);
+        const pixels = new Uint8Array(img.width * img.height);
+        for (let i = 0; i < pixels.length; i++) {
+            const [r, g, b, a] = img.data.subarray(i * 4, i * 4 + 4);
+            const at = `${where} (${i % img.width},${Math.floor(i / img.width)})`;
+            if (a !== 0 && a !== 255)
+                fail(at, `alpha ${a}; export without antialiasing or partial opacity`);
+            if (a === 0) {
+                if (opaque)
+                    fail(at, "background must be opaque");
+                pixels[i] = 254;
+            }
+            else {
+                const hex = `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+                const index = indices.get(hex);
+                if (index === undefined)
+                    fail(at, `${hex} is outside the project palette`);
+                pixels[i] = index;
+            }
+        }
+        images++;
+        return { width: img.width, height: img.height, pixels, skipColor: 254 };
+    };
+    const resources = [{ type: ResourceType.Palette, number: 999, data: writeHunkPalette(palette) }];
+    const numbers = new Set();
+    const number = (value, type, where) => {
+        const n = int(value, where, 0, 65535);
+        if (numbers.has(`${type}:${n}`))
+            fail(where, `duplicate ${type} ${n}`);
+        numbers.add(`${type}:${n}`);
+        return n;
+    };
+    list(m.pictures, "pictures", 0, 65536).forEach((value, i) => {
+        const where = `pictures[${i}]`;
+        const pic = object(value, where, ["number", "layers"]);
+        const n = number(pic.number, "picture", `${where}.number`);
+        const priorities = new Set();
+        const cels = list(pic.layers, `${where}.layers`, 1, 255).map((value, j) => {
+            const at = `${where}.layers[${j}]`;
+            const layer = object(value, at, ["png", "priority"]);
+            const priority = int(layer.priority, `${at}.priority`, -32768, 32767);
+            if (j === 0 ? priority !== -1000 : priority < 0 || priority > 199)
+                fail(at, "background priority is -1000; foreground priorities are 0..199");
+            if (priorities.has(priority))
+                fail(at, "duplicate layer priority; combine these layers in the editor");
+            priorities.add(priority);
+            const img = image(layer.png, `${at}.png`, j === 0);
+            if (img.width !== 320 || img.height !== 200)
+                fail(at, "picture layers must be 320x200");
+            return { ...img, displaceX: 0, displaceY: 0, priority, x: 0, y: 0, unknown16: 0 };
+        });
+        resources.push({ type: ResourceType.Pic, number: n, data: writePic({ resolution: [320, 200], cels, palette }) });
+    });
+    list(m.views, "views", 0, 65536).forEach((value, i) => {
+        const where = `views[${i}]`;
+        const view = object(value, where, ["number", "loops"]);
+        const n = number(view.number, "view", `${where}.number`);
+        const loops = [];
+        let total = 0;
+        list(view.loops, `${where}.loops`, 1, 128).forEach((value, j) => {
+            const at = `${where}.loops[${j}]`;
+            const loop = object(value, at, ["cels", "link", "mirror"]);
+            if ("link" in loop) {
+                if ("cels" in loop)
+                    fail(at, "linked loops cannot also have cels");
+                const link = int(loop.link, `${at}.link`, 0, j - 1);
+                if (loops[link].link !== -1)
+                    fail(at, "link must refer to an earlier loop with its own cels");
+                if (typeof loop.mirror !== "boolean")
+                    fail(at, "mirror must be a boolean");
+                loops.push({ link, mirror: loop.mirror, cels: [] });
+                return;
+            }
+            if ("mirror" in loop)
+                fail(at, "mirror requires link");
+            let size = "";
+            const cels = list(loop.cels, `${at}.cels`, 1, 255).map((value, k) => {
+                const pos = `${at}.cels[${k}]`;
+                const cel = object(value, pos, ["png", "anchor"]);
+                const img = image(cel.png, `${pos}.png`, false);
+                const dimensions = `${img.width}x${img.height}`;
+                if (size && size !== dimensions)
+                    fail(pos, "keep the same canvas size throughout a loop (disable trimming)");
+                size = dimensions;
+                const anchor = list(cel.anchor, `${pos}.anchor`, 2, 2);
+                const x = int(anchor[0], `${pos}.anchor[0]`, 0, img.width - 1);
+                const y = int(anchor[1], `${pos}.anchor[1]`, 0, img.height - 1);
+                total++;
+                return { ...img, displaceX: (img.width >> 1) - x, displaceY: img.height - 1 - y };
+            });
+            loops.push({ link: -1, mirror: false, cels });
+        });
+        if (total > 255)
+            fail(where, "a view supports at most 255 stored cels");
+        resources.push({ type: ResourceType.View, number: n, data: writeView({ flags: 1, loops, palette }) });
+    });
+    resources.sort((a, b) => a.type - b.type || a.number - b.number);
+    return { resources, colours, images };
+}

package/tools/art/build.ts

@@ -0,0 +1,153 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { ResourceType, writeHunkPalette, writePic, writeView, type ResourceData, type ViewLoop } from "../../packages/sci/src/index.ts";
+import { basePalette } from "../game/defaults.ts";
+import { decodePng } from "../png.ts";
+
+/** Editor-neutral, exact-colour art for standalone games. See docs/art-workflow.md. */
+export interface ArtManifest {
+  version: 1;
+  palette: string;
+  /** Optional project art budget, including black and white but excluding transparency. */
+  maxColours?: number;
+  pictures: { number: number; layers: { png: string; priority: number }[] }[];
+  views: { number: number; loops: ({ cels: { png: string; anchor: [number, number] }[] } | { link: number; mirror: boolean })[] }[];
+}
+
+export class ArtError extends Error {}
+
+export function buildArt(file: string): { resources: ResourceData[]; colours: string[]; images: number } {
+  const fail = (where: string, message: string): never => { throw new ArtError(`${file}: ${where}: ${message}`); };
+  const json = (path: string): unknown => {
+    try { return JSON.parse(readFileSync(path, "utf8")); }
+    catch (e) { return fail(path, (e as Error).message); }
+  };
+  const object = (value: unknown, where: string, keys: string[]): Record<string, unknown> => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return fail(where, "expected an object");
+    for (const key of Object.keys(value)) if (!keys.includes(key)) fail(`${where}.${key}`, "unknown key");
+    return value as Record<string, unknown>;
+  };
+  const list = (value: unknown, where: string, min: number, max: number): unknown[] => {
+    if (!Array.isArray(value) || value.length < min || value.length > max) return fail(where, `expected ${min}..${max} entries`);
+    return value;
+  };
+  const int = (value: unknown, where: string, min: number, max: number): number => {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) return fail(where, `expected an integer in ${min}..${max}`);
+    return value;
+  };
+  const path = (value: unknown, where: string): string => {
+    if (typeof value !== "string" || !value.length) return fail(where, "expected a file path");
+    return resolve(dirname(file), value);
+  };
+  const m = object(json(file), "manifest", ["version", "palette", "maxColours", "pictures", "views"]);
+  if (m.version !== 1) fail("version", "expected 1");
+  const maxColours = m.maxColours === undefined ? 254 : int(m.maxColours, "maxColours", 2, 254);
+  const paletteInput = json(path(m.palette, "palette"));
+  if (Array.isArray(paletteInput) && paletteInput.length > maxColours) fail("palette", `${paletteInput.length} colours exceeds the project budget of ${maxColours}`);
+  const colours = list(paletteInput, "palette", 2, 254).map((c, i) => {
+    if (typeof c !== "string" || !/^#[0-9a-f]{6}$/i.test(c)) return fail(`palette[${i}]`, "expected #RRGGBB");
+    return c.toLowerCase();
+  });
+  if (colours[0] !== "#000000" || colours.at(-1) !== "#ffffff") fail("palette", "first colour must be black, last white (interface colours)");
+  if (new Set(colours).size !== colours.length) fail("palette", "duplicate colours");
+  // Preserve the library's black=0, white=255 and transparent=254 conventions.
+  // Entries 1..252 are ours; 253 is reserved. No room quantization or alpha remaps.
+  const palette = basePalette();
+  const indices = new Map<string, number>();
+  colours.forEach((c, i) => {
+    const index = i === colours.length - 1 ? 255 : i;
+    palette.rgb[index] = [1, 3, 5].map((at) => parseInt(c.slice(at, at + 2), 16)) as [number, number, number];
+    indices.set(c, index);
+  });
+  let images = 0;
+  const image = (value: unknown, where: string, opaque: boolean) => {
+    const filename = path(value, where);
+    let img: ReturnType<typeof decodePng>;
+    try { img = decodePng(readFileSync(filename)); }
+    catch (e) { return fail(where, `${filename}: ${(e as Error).message}`); }
+    int(img.width, `${where}.width`, 1, 320);
+    int(img.height, `${where}.height`, 1, 200);
+    const pixels = new Uint8Array(img.width * img.height);
+    for (let i = 0; i < pixels.length; i++) {
+      const [r, g, b, a] = img.data.subarray(i * 4, i * 4 + 4);
+      const at = `${where} (${i % img.width},${Math.floor(i / img.width)})`;
+      if (a !== 0 && a !== 255) fail(at, `alpha ${a}; export without antialiasing or partial opacity`);
+      if (a === 0) {
+        if (opaque) fail(at, "background must be opaque");
+        pixels[i] = 254;
+      } else {
+        const hex = `#${[r, g, b].map((c) => c!.toString(16).padStart(2, "0")).join("")}`;
+        const index = indices.get(hex);
+        if (index === undefined) fail(at, `${hex} is outside the project palette`);
+        pixels[i] = index!;
+      }
+    }
+    images++;
+    return { width: img.width, height: img.height, pixels, skipColor: 254 };
+  };
+  const resources: ResourceData[] = [{ type: ResourceType.Palette, number: 999, data: writeHunkPalette(palette) }];
+  const numbers = new Set<string>();
+  const number = (value: unknown, type: string, where: string) => {
+    const n = int(value, where, 0, 65535);
+    if (numbers.has(`${type}:${n}`)) fail(where, `duplicate ${type} ${n}`);
+    numbers.add(`${type}:${n}`);
+    return n;
+  };
+  list(m.pictures, "pictures", 0, 65536).forEach((value, i) => {
+    const where = `pictures[${i}]`;
+    const pic = object(value, where, ["number", "layers"]);
+    const n = number(pic.number, "picture", `${where}.number`);
+    const priorities = new Set<number>();
+    const cels = list(pic.layers, `${where}.layers`, 1, 255).map((value, j) => {
+      const at = `${where}.layers[${j}]`;
+      const layer = object(value, at, ["png", "priority"]);
+      const priority = int(layer.priority, `${at}.priority`, -32768, 32767);
+      if (j === 0 ? priority !== -1000 : priority < 0 || priority > 199) fail(at, "background priority is -1000; foreground priorities are 0..199");
+      if (priorities.has(priority)) fail(at, "duplicate layer priority; combine these layers in the editor");
+      priorities.add(priority);
+      const img = image(layer.png, `${at}.png`, j === 0);
+      if (img.width !== 320 || img.height !== 200) fail(at, "picture layers must be 320x200");
+      return { ...img, displaceX: 0, displaceY: 0, priority, x: 0, y: 0, unknown16: 0 };
+    });
+    resources.push({ type: ResourceType.Pic, number: n, data: writePic({ resolution: [320, 200], cels, palette }) });
+  });
+  list(m.views, "views", 0, 65536).forEach((value, i) => {
+    const where = `views[${i}]`;
+    const view = object(value, where, ["number", "loops"]);
+    const n = number(view.number, "view", `${where}.number`);
+    const loops: ViewLoop[] = [];
+    let total = 0;
+    list(view.loops, `${where}.loops`, 1, 128).forEach((value, j) => {
+      const at = `${where}.loops[${j}]`;
+      const loop = object(value, at, ["cels", "link", "mirror"]);
+      if ("link" in loop) {
+        if ("cels" in loop) fail(at, "linked loops cannot also have cels");
+        const link = int(loop.link, `${at}.link`, 0, j - 1);
+        if (loops[link]!.link !== -1) fail(at, "link must refer to an earlier loop with its own cels");
+        if (typeof loop.mirror !== "boolean") fail(at, "mirror must be a boolean");
+        loops.push({ link, mirror: loop.mirror as boolean, cels: [] });
+        return;
+      }
+      if ("mirror" in loop) fail(at, "mirror requires link");
+      let size = "";
+      const cels = list(loop.cels, `${at}.cels`, 1, 255).map((value, k) => {
+        const pos = `${at}.cels[${k}]`;
+        const cel = object(value, pos, ["png", "anchor"]);
+        const img = image(cel.png, `${pos}.png`, false);
+        const dimensions = `${img.width}x${img.height}`;
+        if (size && size !== dimensions) fail(pos, "keep the same canvas size throughout a loop (disable trimming)");
+        size = dimensions;
+        const anchor = list(cel.anchor, `${pos}.anchor`, 2, 2);
+        const x = int(anchor[0], `${pos}.anchor[0]`, 0, img.width - 1);
+        const y = int(anchor[1], `${pos}.anchor[1]`, 0, img.height - 1);
+        total++;
+        return { ...img, displaceX: (img.width >> 1) - x, displaceY: img.height - 1 - y };
+      });
+      loops.push({ link: -1, mirror: false, cels });
+    });
+    if (total > 255) fail(where, "a view supports at most 255 stored cels");
+    resources.push({ type: ResourceType.View, number: n, data: writeView({ flags: 1, loops, palette }) });
+  });
+  resources.sort((a, b) => a.type - b.type || a.number - b.number);
+  return { resources, colours, images };
+}

package/tools/art.d.ts

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

package/tools/art.js

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { writeResourceArchive } from "../packages/sci/src/index.js";
+import { ArtError, buildArt } from "./art/build.js";
+const [command, manifest, outArg] = process.argv.slice(2);
+if (!manifest || (command !== "check" && command !== "build")) {
+    console.error("usage: pnpm art <check|build> games/<name>/art/art.json [out dir]");
+    process.exit(2);
+}
+try {
+    const art = buildArt(manifest);
+    if (command === "build") {
+        const out = outArg ?? join("out/art", basename(dirname(dirname(manifest))));
+        const { map, volume } = writeResourceArchive(art.resources);
+        mkdirSync(out, { recursive: true });
+        writeFileSync(join(out, "RESOURCE.MAP"), map);
+        writeFileSync(join(out, "RESOURCE.000"), volume);
+        const gpl = ["GIMP Palette", "Name: SCI project palette", "Columns: 8", "#"];
+        for (const hex of art.colours)
+            gpl.push(`${[1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16)).join(" ")} ${hex}`);
+        writeFileSync(join(out, "palette.gpl"), `${gpl.join("\n")}\n`);
+        console.log(`${out}: art-only archive (no game scripts), palette.gpl`);
+    }
+    console.log(`${manifest}: ${art.images} PNGs checked, ${art.colours.length} colours, ${art.resources.length} resources`);
+}
+catch (e) {
+    if (!(e instanceof ArtError))
+        throw e;
+    console.error(e.message);
+    process.exit(1);
+}

package/tools/art.ts

@@ -0,0 +1,29 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { writeResourceArchive } from "../packages/sci/src/index.ts";
+import { ArtError, buildArt } from "./art/build.ts";
+
+const [command, manifest, outArg] = process.argv.slice(2);
+if (!manifest || (command !== "check" && command !== "build")) {
+  console.error("usage: pnpm art <check|build> games/<name>/art/art.json [out dir]");
+  process.exit(2);
+}
+try {
+  const art = buildArt(manifest);
+  if (command === "build") {
+    const out = outArg ?? join("out/art", basename(dirname(dirname(manifest))));
+    const { map, volume } = writeResourceArchive(art.resources);
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "RESOURCE.MAP"), map);
+    writeFileSync(join(out, "RESOURCE.000"), volume);
+    const gpl = ["GIMP Palette", "Name: SCI project palette", "Columns: 8", "#"];
+    for (const hex of art.colours) gpl.push(`${[1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16)).join(" ")} ${hex}`);
+    writeFileSync(join(out, "palette.gpl"), `${gpl.join("\n")}\n`);
+    console.log(`${out}: art-only archive (no game scripts), palette.gpl`);
+  }
+  console.log(`${manifest}: ${art.images} PNGs checked, ${art.colours.length} colours, ${art.resources.length} resources`);
+} catch (e) {
+  if (!(e instanceof ArtError)) throw e;
+  console.error(e.message);
+  process.exit(1);
+}

package/tools/asm.d.ts

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

package/tools/asm.js

@@ -0,0 +1,61 @@
+/**
+ * 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.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"));
+const world = await ScriptWorld.open(rm);
+await world.loadAllClasses();
+const ctx = world.asmContext();
+const firstDiff = (a, b) => {
+    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 = [];
+    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.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, dir) {
+    const out = assemble(text, ctx);
+    writePatch(dir, ResourceType.Script, out.number, out.code);
+    writePatch(dir, ResourceType.Heap, out.number, out.heap);
+}