sci2-ts 0.2.2 → 0.4.0

package/packages/sci/src/vm/kernels/saves.js

@@ -1,3 +1,4 @@
+import { ResourceType } from "../../resource/types.js";
 import { restore, snapshot } from "../savegame.js";
 import { toSigned } from "../value.js";
 import { stringHelpers } from "./arrays.js";
@@ -26,7 +27,25 @@ const DESCRIPTION_SIZE = 36;
 class SaveState {
     store = new MemorySaveStore();
     restarting = Restarting.None;
+    fingerprint;
 }
+/** A hash (FNV-1a) of every script and heap resource: which scripts a save belongs to. */
+export function scriptsFingerprint(vm) {
+    const s = saves(vm);
+    if (s.fingerprint === undefined) {
+        let h = 0x811c9dc5;
+        const resources = vm.resources.list().filter((r) => r.type === ResourceType.Script || r.type === ResourceType.Heap);
+        resources.sort((a, b) => a.type - b.type || a.number - b.number);
+        for (const r of resources) {
+            for (const b of [r.type, r.number & 0xff, r.number >> 8, ...vm.resources.loadSync(r).data])
+                h = Math.imul(h ^ b, 0x01000193) >>> 0;
+        }
+        s.fingerprint = h.toString(16).padStart(8, "0");
+    }
+    return s.fingerprint;
+}
+/** Whether a save can be restored into the scripts running now. */
+const fits = (vm, info) => info.scripts === undefined || info.scripts === scriptsFingerprint(vm);
 const stateOf = new WeakMap();
 export const saves = (vm) => {
     let s = stateOf.get(vm);
@@ -66,6 +85,7 @@ export const saveKernels = {
             description: stringHelpers.str(vm, description),
             version: stringHelpers.str(vm, version),
             date: Date.now(),
+            scripts: scriptsFingerprint(vm),
         };
         saves(vm).store.put(info, snapshot(vm));
         return 1;
@@ -74,7 +94,7 @@ export const saveKernels = {
     // the saved state via `theGame replay`, as in the original interpreter.
     RestoreGame: (vm, [, id = 0]) => {
         const save = saves(vm).store.get(toSigned(id));
-        if (!save)
+        if (!save || !fits(vm, save.info))
             return 0;
         restoreGame(vm, save.snapshot);
         return 1;
@@ -97,7 +117,8 @@ export const saveKernels = {
     // GetSaveFiles(gameName, descriptions, ids): fixed 36-byte description slots and a
     // 0-terminated id list, newest first.
     GetSaveFiles: (vm, [, descriptions = 0, ids = 0]) => {
-        const list = saves(vm).store.list();
+        // Only saves these scripts can restore.
+        const list = saves(vm).store.list().filter((info) => fits(vm, info));
         const desc = stringHelpers.resolve(vm, descriptions);
         const idArray = stringHelpers.resolve(vm, ids);
         if (desc) {
@@ -115,7 +136,7 @@ export const saveKernels = {
     // CheckSaveGame(gameName, id, version): exists and was made by this game version.
     CheckSaveGame: (vm, [, id = 0, version = 0]) => {
         const save = saves(vm).store.get(toSigned(id));
-        return save && save.info.version === stringHelpers.str(vm, version) ? 1 : 0;
+        return save && fits(vm, save.info) && save.info.version === stringHelpers.str(vm, version) ? 1 : 0;
     },
     GetSaveDir: (vm) => stringHelpers.newString(vm, "SAVES"),
     MakeSaveCatName: (vm, [dst = 0]) => stringHelpers.writeString(vm, dst, "QG4CDSG.CAT"),

package/packages/sci/src/vm/kernels/saves.ts

@@ -1,3 +1,4 @@
+import { ResourceType } from "../../resource/types.ts";
 import { restore, snapshot, type VmSnapshot } from "../savegame.ts";
 import type { KernelFn, Vm } from "../vm.ts";
 import { toSigned } from "../value.ts";
@@ -12,6 +13,11 @@ export interface SaveInfo {
   description: string;
   version: string;
   date: number;
+  /**
+   * The scripts it was made with (scriptsFingerprint). A save is a snapshot of running
+   * scripts, so it only restores into the same ones; saves from before this was kept have none.
+   */
+  scripts?: string;
 }
 
 /** Where saves live. Synchronous because kernels are; hosts preload and write through. */
@@ -47,8 +53,27 @@ const DESCRIPTION_SIZE = 36;
 class SaveState {
   store: SaveStore = new MemorySaveStore();
   restarting: number = Restarting.None;
+  fingerprint: string | undefined;
 }
 
+/** A hash (FNV-1a) of every script and heap resource: which scripts a save belongs to. */
+export function scriptsFingerprint(vm: Vm): string {
+  const s = saves(vm);
+  if (s.fingerprint === undefined) {
+    let h = 0x811c9dc5;
+    const resources = vm.resources.list().filter((r) => r.type === ResourceType.Script || r.type === ResourceType.Heap);
+    resources.sort((a, b) => a.type - b.type || a.number - b.number);
+    for (const r of resources) {
+      for (const b of [r.type, r.number & 0xff, r.number >> 8, ...vm.resources.loadSync(r).data]) h = Math.imul(h ^ b, 0x01000193) >>> 0;
+    }
+    s.fingerprint = h.toString(16).padStart(8, "0");
+  }
+  return s.fingerprint;
+}
+
+/** Whether a save can be restored into the scripts running now. */
+const fits = (vm: Vm, info: SaveInfo) => info.scripts === undefined || info.scripts === scriptsFingerprint(vm);
+
 const stateOf = new WeakMap<Vm, SaveState>();
 export const saves = (vm: Vm): SaveState => {
   let s = stateOf.get(vm);
@@ -90,6 +115,7 @@ export const saveKernels: Record<string, KernelFn> = {
       description: stringHelpers.str(vm, description),
       version: stringHelpers.str(vm, version),
       date: Date.now(),
+      scripts: scriptsFingerprint(vm),
     };
     saves(vm).store.put(info, snapshot(vm));
     return 1;
@@ -99,7 +125,7 @@ export const saveKernels: Record<string, KernelFn> = {
   // the saved state via `theGame replay`, as in the original interpreter.
   RestoreGame: (vm, [, id = 0]) => {
     const save = saves(vm).store.get(toSigned(id));
-    if (!save) return 0;
+    if (!save || !fits(vm, save.info)) return 0;
     restoreGame(vm, save.snapshot);
     return 1;
   },
@@ -123,7 +149,8 @@ export const saveKernels: Record<string, KernelFn> = {
   // GetSaveFiles(gameName, descriptions, ids): fixed 36-byte description slots and a
   // 0-terminated id list, newest first.
   GetSaveFiles: (vm, [, descriptions = 0, ids = 0]) => {
-    const list = saves(vm).store.list();
+    // Only saves these scripts can restore.
+    const list = saves(vm).store.list().filter((info) => fits(vm, info));
     const desc = stringHelpers.resolve(vm, descriptions);
     const idArray = stringHelpers.resolve(vm, ids);
     if (desc) {
@@ -140,7 +167,7 @@ export const saveKernels: Record<string, KernelFn> = {
   // CheckSaveGame(gameName, id, version): exists and was made by this game version.
   CheckSaveGame: (vm, [, id = 0, version = 0]) => {
     const save = saves(vm).store.get(toSigned(id));
-    return save && save.info.version === stringHelpers.str(vm, version) ? 1 : 0;
+    return save && fits(vm, save.info) && save.info.version === stringHelpers.str(vm, version) ? 1 : 0;
   },
 
   GetSaveDir: (vm) => stringHelpers.newString(vm, "SAVES"),

package/packages/sci/src/vm/kernels/text.js

@@ -330,9 +330,34 @@ export const textKernels = {
         g.items.delete(obj);
         return text !== original ? 1 : 0;
     },
-    Bitmap: (vm, [subop = 0, ref = 0]) => {
-        if (subop === 1 && vm.memory.bitmap(ref))
+    // Bitmap(1, bitmap): dispose. Bitmap(3, bitmap, view, loop, cel, x, y): draw a view's cel
+    // into the bitmap with its origin at (x, y), skipping its transparent pixels (SCI2.1's
+    // kBitmapDrawView; the class library frames text boxes with it).
+    Bitmap: (vm, [subop = 0, ref = 0, ...args]) => {
+        const bmp = vm.memory.bitmap(ref);
+        if (subop === 1 && bmp)
             vm.memory.free(segmentOf(ref));
+        if (subop === 3 && bmp) {
+            const [view = 0, loop = 0, celNo = 0, x = 0, y = 0] = args.map(toSigned);
+            const found = graphics(vm).cel(view, loop, celNo);
+            if (!found)
+                return 0;
+            const { cel, mirror } = found;
+            const left = x - ((cel.width >> 1) - cel.displaceX), top = y - (cel.height - 1 - cel.displaceY);
+            for (let cy = 0; cy < cel.height; cy++) {
+                const by = top + cy;
+                if (by < 0 || by >= bmp.height)
+                    continue;
+                for (let cx = 0; cx < cel.width; cx++) {
+                    const bx = left + cx;
+                    if (bx < 0 || bx >= bmp.width)
+                        continue;
+                    const c = cel.pixels[cy * cel.width + (mirror ? cel.width - 1 - cx : cx)];
+                    if (c !== cel.skipColor)
+                        bmp.pixels[by * bmp.width + bx] = c;
+                }
+            }
+        }
         return 0;
     },
 };

package/packages/sci/src/vm/kernels/text.ts

@@ -321,8 +321,29 @@ export const textKernels: Record<string, KernelFn> = {
     return text !== original ? 1 : 0;
   },
 
-  Bitmap: (vm, [subop = 0, ref = 0]) => {
-    if (subop === 1 && vm.memory.bitmap(ref)) vm.memory.free(segmentOf(ref));
+  // Bitmap(1, bitmap): dispose. Bitmap(3, bitmap, view, loop, cel, x, y): draw a view's cel
+  // into the bitmap with its origin at (x, y), skipping its transparent pixels (SCI2.1's
+  // kBitmapDrawView; the class library frames text boxes with it).
+  Bitmap: (vm, [subop = 0, ref = 0, ...args]) => {
+    const bmp = vm.memory.bitmap(ref);
+    if (subop === 1 && bmp) vm.memory.free(segmentOf(ref));
+    if (subop === 3 && bmp) {
+      const [view = 0, loop = 0, celNo = 0, x = 0, y = 0] = args.map(toSigned);
+      const found = graphics(vm).cel(view, loop, celNo);
+      if (!found) return 0;
+      const { cel, mirror } = found;
+      const left = x - ((cel.width >> 1) - cel.displaceX), top = y - (cel.height - 1 - cel.displaceY);
+      for (let cy = 0; cy < cel.height; cy++) {
+        const by = top + cy;
+        if (by < 0 || by >= bmp.height) continue;
+        for (let cx = 0; cx < cel.width; cx++) {
+          const bx = left + cx;
+          if (bx < 0 || bx >= bmp.width) continue;
+          const c = cel.pixels[cy * cel.width + (mirror ? cel.width - 1 - cx : cx)]!;
+          if (c !== cel.skipColor) bmp.pixels[by * bmp.width + bx] = c;
+        }
+      }
+    }
     return 0;
   },
 };

package/tools/art/build.d.ts

@@ -24,6 +24,16 @@ export interface ArtManifest {
             mirror: boolean;
         })[];
     }[];
+    /** Fonts drawn as sheets of glyphs (tools/art/font.ts). */
+    fonts?: {
+        number: number;
+        png: string;
+        cell: [number, number];
+        first?: number;
+        spacing?: number;
+        space?: number;
+        lineHeight?: number;
+    }[];
 }
 export declare class ArtError extends Error {
 }

package/tools/art/build.js

@@ -1,8 +1,9 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { ResourceType, writeHunkPalette, writePic, writeView } from "../../packages/sci/src/index.js";
+import { ResourceType, writeFont, writeHunkPalette, writePic, writeView } from "../../packages/sci/src/index.js";
 import { basePalette } from "../game/defaults.js";
 import { decodePng } from "../png.js";
+import { FontSheetError, fontFromSheet } from "./font.js";
 export class ArtError extends Error {
 }
 export function buildArt(file) {
@@ -38,7 +39,7 @@ export function buildArt(file) {
             return fail(where, "expected a file path");
         return resolve(dirname(file), value);
     };
-    const m = object(json(file), "manifest", ["version", "palette", "maxColours", "pictures", "views"]);
+    const m = object(json(file), "manifest", ["version", "palette", "maxColours", "pictures", "views", "fonts"]);
     if (m.version !== 1)
         fail("version", "expected 1");
     const maxColours = m.maxColours === undefined ? 254 : int(m.maxColours, "maxColours", 2, 254);
@@ -170,6 +171,35 @@ export function buildArt(file) {
             fail(where, "a view supports at most 255 stored cels");
         resources.push({ type: ResourceType.View, number: n, data: writeView({ flags: 1, loops, palette }) });
     });
+    list(m.fonts ?? [], "fonts", 0, 65536).forEach((value, i) => {
+        const where = `fonts[${i}]`;
+        const f = object(value, where, ["number", "png", "cell", "first", "spacing", "space", "lineHeight"]);
+        const n = number(f.number, "font", `${where}.number`);
+        const filename = path(f.png, `${where}.png`);
+        let img;
+        try {
+            img = decodePng(readFileSync(filename));
+        }
+        catch (e) {
+            return fail(`${where}.png`, `${filename}: ${e.message}`);
+        }
+        const cell = list(f.cell, `${where}.cell`, 2, 2);
+        const optional = (key, min, max) => (f[key] === undefined ? undefined : int(f[key], `${where}.${key}`, min, max));
+        try {
+            const font = fontFromSheet(img, {
+                cell: [int(cell[0], `${where}.cell[0]`, 1, 128), int(cell[1], `${where}.cell[1]`, 1, 128)],
+                first: optional("first", 0, 255), spacing: optional("spacing", 0, 16),
+                space: optional("space", 1, 128), lineHeight: optional("lineHeight", 1, 255),
+            });
+            resources.push({ type: ResourceType.Font, number: n, data: writeFont(font) });
+            images++;
+        }
+        catch (e) {
+            if (!(e instanceof FontSheetError))
+                throw e;
+            fail(`${where}.png`, e.message);
+        }
+    });
     resources.sort((a, b) => a.type - b.type || a.number - b.number);
     return { resources, colours, images };
 }

package/tools/art/build.ts

@@ -1,8 +1,9 @@
 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 { ResourceType, writeFont, writeHunkPalette, writePic, writeView, type ResourceData, type ViewLoop } from "../../packages/sci/src/index.ts";
 import { basePalette } from "../game/defaults.ts";
 import { decodePng } from "../png.ts";
+import { FontSheetError, fontFromSheet } from "./font.ts";
 
 /** Editor-neutral, exact-colour art for standalone games. See docs/art-workflow.md. */
 export interface ArtManifest {
@@ -12,6 +13,8 @@ export interface ArtManifest {
   maxColours?: number;
   pictures: { number: number; layers: { png: string; priority: number }[] }[];
   views: { number: number; loops: ({ cels: { png: string; anchor: [number, number] }[] } | { link: number; mirror: boolean })[] }[];
+  /** Fonts drawn as sheets of glyphs (tools/art/font.ts). */
+  fonts?: { number: number; png: string; cell: [number, number]; first?: number; spacing?: number; space?: number; lineHeight?: number }[];
 }
 
 export class ArtError extends Error {}
@@ -39,7 +42,7 @@ export function buildArt(file: string): { resources: ResourceData[]; colours: st
     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"]);
+  const m = object(json(file), "manifest", ["version", "palette", "maxColours", "pictures", "views", "fonts"]);
   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"));
@@ -148,6 +151,29 @@ export function buildArt(file: string): { resources: ResourceData[]; colours: st
     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 }) });
   });
+  list(m.fonts ?? [], "fonts", 0, 65536).forEach((value, i) => {
+    const where = `fonts[${i}]`;
+    const f = object(value, where, ["number", "png", "cell", "first", "spacing", "space", "lineHeight"]);
+    const n = number(f.number, "font", `${where}.number`);
+    const filename = path(f.png, `${where}.png`);
+    let img: ReturnType<typeof decodePng>;
+    try { img = decodePng(readFileSync(filename)); }
+    catch (e) { return fail(`${where}.png`, `${filename}: ${(e as Error).message}`); }
+    const cell = list(f.cell, `${where}.cell`, 2, 2);
+    const optional = (key: string, min: number, max: number) => (f[key] === undefined ? undefined : int(f[key], `${where}.${key}`, min, max));
+    try {
+      const font = fontFromSheet(img, {
+        cell: [int(cell[0], `${where}.cell[0]`, 1, 128), int(cell[1], `${where}.cell[1]`, 1, 128)],
+        first: optional("first", 0, 255), spacing: optional("spacing", 0, 16),
+        space: optional("space", 1, 128), lineHeight: optional("lineHeight", 1, 255),
+      });
+      resources.push({ type: ResourceType.Font, number: n, data: writeFont(font) });
+      images++;
+    } catch (e) {
+      if (!(e instanceof FontSheetError)) throw e;
+      fail(`${where}.png`, e.message);
+    }
+  });
   resources.sort((a, b) => a.type - b.type || a.number - b.number);
   return { resources, colours, images };
 }

package/tools/art/font.d.ts

@@ -0,0 +1,24 @@
+import type { Font } from "../../packages/sci/src/index.ts";
+import type { Rgba } from "../png.ts";
+/**
+ * A font from a sheet of glyphs drawn in a paint program: a grid of same-size cells, one
+ * character per cell, left to right and top to bottom from `first`. A glyph is drawn from
+ * its cell's left edge; any opaque pixel is ink (its colour doesn't matter: text takes its
+ * colour when it's drawn), and its width is up to its rightmost ink. A cell with no ink is
+ * a character the font doesn't have, except the space, which is `space` pixels wide.
+ */
+export interface FontSheet {
+    /** Cell size in pixels: [width, height]. */
+    cell: [number, number];
+    /** The character in the first cell (default 32, the space). */
+    first?: number;
+    /** Pixels between one glyph and the next (default 1). */
+    spacing?: number;
+    /** Width of the space (default half a cell). */
+    space?: number;
+    /** Line height (default the cell height). */
+    lineHeight?: number;
+}
+export declare class FontSheetError extends Error {
+}
+export declare function fontFromSheet(img: Rgba, sheet: FontSheet): Font;

package/tools/art/font.js

@@ -0,0 +1,40 @@
+export class FontSheetError extends Error {
+}
+export function fontFromSheet(img, sheet) {
+    const [cw, ch] = sheet.cell;
+    const first = sheet.first ?? 32, spacing = sheet.spacing ?? 1;
+    const space = sheet.space ?? Math.max(1, cw >> 1), lineHeight = sheet.lineHeight ?? ch;
+    const fail = (message) => { throw new FontSheetError(message); };
+    if (img.width % cw || img.height % ch)
+        fail(`${img.width}x${img.height} is not a whole number of ${cw}x${ch} cells`);
+    const columns = img.width / cw, cells = columns * (img.height / ch);
+    if (first + cells > 256)
+        fail(`${cells} cells from character ${first} go past 255`);
+    if (lineHeight < 1 || lineHeight > 255)
+        fail(`line height ${lineHeight} is outside 1..255`);
+    const glyphs = Array.from({ length: Math.max(128, first + cells) }, () => ({ width: 0, height: 0, pixels: new Uint8Array(0) }));
+    for (let i = 0; i < cells; i++) {
+        const left = (i % columns) * cw, top = Math.floor(i / columns) * ch;
+        const ink = new Uint8Array(cw * ch);
+        let right = -1;
+        for (let y = 0; y < ch; y++) {
+            for (let x = 0; x < cw; x++) {
+                const a = img.data[((top + y) * img.width + left + x) * 4 + 3];
+                if (a !== 0 && a !== 255)
+                    fail(`character ${first + i} (${left + x},${top + y}): alpha ${a}; export without antialiasing`);
+                if (a)
+                    (ink[y * cw + x] = 1), (right = Math.max(right, x));
+            }
+        }
+        const code = first + i;
+        if (right < 0 && code !== 32)
+            continue;
+        const inked = right + 1, width = (code === 32 && right < 0 ? space : inked + spacing);
+        const pixels = new Uint8Array(width * ch);
+        for (let y = 0; y < ch; y++)
+            for (let x = 0; x < inked; x++)
+                pixels[y * width + x] = ink[y * cw + x];
+        glyphs[code] = { width, height: ch, pixels };
+    }
+    return { height: lineHeight, glyphs };
+}

package/tools/art/font.ts

@@ -0,0 +1,56 @@
+import type { Font, Glyph } from "../../packages/sci/src/index.ts";
+import type { Rgba } from "../png.ts";
+
+/**
+ * A font from a sheet of glyphs drawn in a paint program: a grid of same-size cells, one
+ * character per cell, left to right and top to bottom from `first`. A glyph is drawn from
+ * its cell's left edge; any opaque pixel is ink (its colour doesn't matter: text takes its
+ * colour when it's drawn), and its width is up to its rightmost ink. A cell with no ink is
+ * a character the font doesn't have, except the space, which is `space` pixels wide.
+ */
+export interface FontSheet {
+  /** Cell size in pixels: [width, height]. */
+  cell: [number, number];
+  /** The character in the first cell (default 32, the space). */
+  first?: number;
+  /** Pixels between one glyph and the next (default 1). */
+  spacing?: number;
+  /** Width of the space (default half a cell). */
+  space?: number;
+  /** Line height (default the cell height). */
+  lineHeight?: number;
+}
+
+export class FontSheetError extends Error {}
+
+export function fontFromSheet(img: Rgba, sheet: FontSheet): Font {
+  const [cw, ch] = sheet.cell;
+  const first = sheet.first ?? 32, spacing = sheet.spacing ?? 1;
+  const space = sheet.space ?? Math.max(1, cw >> 1), lineHeight = sheet.lineHeight ?? ch;
+  const fail = (message: string): never => { throw new FontSheetError(message); };
+  if (img.width % cw || img.height % ch) fail(`${img.width}x${img.height} is not a whole number of ${cw}x${ch} cells`);
+  const columns = img.width / cw, cells = columns * (img.height / ch);
+  if (first + cells > 256) fail(`${cells} cells from character ${first} go past 255`);
+  if (lineHeight < 1 || lineHeight > 255) fail(`line height ${lineHeight} is outside 1..255`);
+
+  const glyphs: Glyph[] = Array.from({ length: Math.max(128, first + cells) }, () => ({ width: 0, height: 0, pixels: new Uint8Array(0) }));
+  for (let i = 0; i < cells; i++) {
+    const left = (i % columns) * cw, top = Math.floor(i / columns) * ch;
+    const ink = new Uint8Array(cw * ch);
+    let right = -1;
+    for (let y = 0; y < ch; y++) {
+      for (let x = 0; x < cw; x++) {
+        const a = img.data[((top + y) * img.width + left + x) * 4 + 3]!;
+        if (a !== 0 && a !== 255) fail(`character ${first + i} (${left + x},${top + y}): alpha ${a}; export without antialiasing`);
+        if (a) (ink[y * cw + x] = 1), (right = Math.max(right, x));
+      }
+    }
+    const code = first + i;
+    if (right < 0 && code !== 32) continue;
+    const inked = right + 1, width = (code === 32 && right < 0 ? space : inked + spacing);
+    const pixels = new Uint8Array(width * ch);
+    for (let y = 0; y < ch; y++) for (let x = 0; x < inked; x++) pixels[y * width + x] = ink[y * cw + x]!;
+    glyphs[code] = { width, height: ch, pixels };
+  }
+  return { height: lineHeight, glyphs };
+}

package/tools/game/build.d.ts

@@ -9,6 +9,8 @@ import { type ResourceData } from "../../packages/sci/src/index.ts";
  *   games/<name>/rooms/<n>.room.yaml (+ <n>.yarn)  rooms as data (packages/content), compiled
  *                                  for the class library; their Yarn variables are flags
  *                                  numbered in flags.yaml
+ *   games/<name>/items.yaml        optional: the verbs of the things the hero can carry
+ *                                  (`lens: 10`), so rooms' Yarn can answer them (filings.lens)
  *   games/<name>/music/<n>.mid     music: sound n, from a Standard MIDI File (General MIDI)
  *   games/<name>/sounds/<n>.wav    digital effects: sound n plays this instead of music
  *   games/<name>/resources.ts      optional: `export default () => ResourceData[]` for art,
@@ -44,3 +46,5 @@ export declare const LIBRARY_DIR: string;
 export declare function buildGame(dir: string, options?: {
     library?: boolean;
 }): Promise<BuiltGame>;
+/** items.yaml: `name: verb` lines, each item's verb from 10 to 255 (1 to 4 are the player's). */
+export declare function itemVerbs(dir: string): Record<string, number>;

package/tools/game/build.js

@@ -108,7 +108,7 @@ export async function buildGame(dir, options = {}) {
         const roomsDir = join(dir, "rooms");
         if (!existsSync(roomsDir))
             return [];
-        const target = libraryTarget(globals);
+        const target = libraryTarget(globals, itemVerbs(dir));
         const flags = modFlags(dir, { content: target });
         const out = [];
         for (const { file, text } of load(roomsDir, /^\d+\.room\.yaml$/)) {
@@ -257,3 +257,29 @@ export async function buildGame(dir, options = {}) {
         warnings: [...new Set(warnings)],
     };
 }
+/** items.yaml: `name: verb` lines, each item's verb from 10 to 255 (1 to 4 are the player's). */
+export function itemVerbs(dir) {
+    const file = join(dir, "items.yaml");
+    if (!existsSync(file))
+        return {};
+    const where = relative(process.cwd(), file);
+    const verbs = {};
+    readFileSync(file, "utf8").split("\n").forEach((raw, i) => {
+        const line = raw.replace(/#.*/, "").trim();
+        if (!line)
+            return;
+        const at = `${where}:${i + 1}`;
+        const m = /^([A-Za-z]\w*)\s*:\s*(\d+)$/.exec(line);
+        if (!m)
+            throw new GameBuildError(`${at}: expected item: verb`);
+        const [, name, n] = m, verb = Number(n);
+        if (!/^[a-z][A-Za-z0-9]*$/.test(name) || ["look", "talk", "walk", "do", "enter"].includes(name))
+            throw new GameBuildError(`${at}: "${name}" can't name an item (lower camelCase, and not a verb)`);
+        if (verb < 10 || verb > 255)
+            throw new GameBuildError(`${at}: ${name}: the verb is a number from 10 to 255`);
+        if (Object.values(verbs).includes(verb))
+            throw new GameBuildError(`${at}: ${name}: verb ${verb} is used twice`);
+        verbs[name] = verb;
+    });
+    return verbs;
+}

package/tools/game/build.ts

@@ -22,6 +22,8 @@ import { libraryTarget } from "./target.ts";
  *   games/<name>/rooms/<n>.room.yaml (+ <n>.yarn)  rooms as data (packages/content), compiled
  *                                  for the class library; their Yarn variables are flags
  *                                  numbered in flags.yaml
+ *   games/<name>/items.yaml        optional: the verbs of the things the hero can carry
+ *                                  (`lens: 10`), so rooms' Yarn can answer them (filings.lens)
  *   games/<name>/music/<n>.mid     music: sound n, from a Standard MIDI File (General MIDI)
  *   games/<name>/sounds/<n>.wav    digital effects: sound n plays this instead of music
  *   games/<name>/resources.ts      optional: `export default () => ResourceData[]` for art,
@@ -140,7 +142,7 @@ export async function buildGame(dir: string, options: { library?: boolean } = {}
   const compileRooms = (): { file: string; text: string }[] => {
     const roomsDir = join(dir, "rooms");
     if (!existsSync(roomsDir)) return [];
-    const target = libraryTarget(globals);
+    const target = libraryTarget(globals, itemVerbs(dir));
     const flags = modFlags(dir, { content: target });
     const out: { file: string; text: string }[] = [];
     for (const { file, text } of load(roomsDir, /^\d+\.room\.yaml$/)) {
@@ -281,3 +283,24 @@ export async function buildGame(dir: string, options: { library?: boolean } = {}
     warnings: [...new Set(warnings)],
   };
 }
+
+/** items.yaml: `name: verb` lines, each item's verb from 10 to 255 (1 to 4 are the player's). */
+export function itemVerbs(dir: string): Record<string, number> {
+  const file = join(dir, "items.yaml");
+  if (!existsSync(file)) return {};
+  const where = relative(process.cwd(), file);
+  const verbs: Record<string, number> = {};
+  readFileSync(file, "utf8").split("\n").forEach((raw, i) => {
+    const line = raw.replace(/#.*/, "").trim();
+    if (!line) return;
+    const at = `${where}:${i + 1}`;
+    const m = /^([A-Za-z]\w*)\s*:\s*(\d+)$/.exec(line);
+    if (!m) throw new GameBuildError(`${at}: expected item: verb`);
+    const [, name, n] = m, verb = Number(n);
+    if (!/^[a-z][A-Za-z0-9]*$/.test(name!) || ["look", "talk", "walk", "do", "enter"].includes(name!)) throw new GameBuildError(`${at}: "${name}" can't name an item (lower camelCase, and not a verb)`);
+    if (verb < 10 || verb > 255) throw new GameBuildError(`${at}: ${name}: the verb is a number from 10 to 255`);
+    if (Object.values(verbs).includes(verb)) throw new GameBuildError(`${at}: ${name}: verb ${verb} is used twice`);
+    verbs[name!] = verb;
+  });
+  return verbs;
+}

package/tools/game/kit.d.ts

@@ -5,3 +5,4 @@
 export { ResourceType, SoundDevice, writeFont, writeHunkPalette, writePic, writeSound, writeView, type Cel, type Font, type HunkPaletteFile, type MidiEvent, type PicFile, type ResourceData, type SoundSpec, type ViewFile, } from "../../packages/sci/src/index.ts";
 export { BASE_PALETTE, CURSOR_VIEW, Colour, DEFAULT_FONT, basePalette, cube } from "./defaults.ts";
 export { pixelFont } from "./font.ts";
+export { fontFromSheet, type FontSheet } from "../art/font.ts";

package/tools/game/kit.js

@@ -5,3 +5,4 @@
 export { ResourceType, SoundDevice, writeFont, writeHunkPalette, writePic, writeSound, writeView, } from "../../packages/sci/src/index.js";
 export { BASE_PALETTE, CURSOR_VIEW, Colour, DEFAULT_FONT, basePalette, cube } from "./defaults.js";
 export { pixelFont } from "./font.js";
+export { fontFromSheet } from "../art/font.js";

package/tools/game/kit.ts

@@ -8,3 +8,4 @@ export {
 } from "../../packages/sci/src/index.ts";
 export { BASE_PALETTE, CURSOR_VIEW, Colour, DEFAULT_FONT, basePalette, cube } from "./defaults.ts";
 export { pixelFont } from "./font.ts";
+export { fontFromSheet, type FontSheet } from "../art/font.ts";

package/tools/game/target.d.ts

@@ -4,4 +4,4 @@ import type { Target } from "../../packages/content/src/index.ts";
  * (packages/content). Global numbers depend on the game's script 0, so the target is made
  * for each build from the compiled globals' names.
  */
-export declare function libraryTarget(globals: readonly string[]): Target;
+export declare function libraryTarget(globals: readonly string[], items?: Record<string, number>): Target;

package/tools/game/target.js

@@ -3,7 +3,7 @@
  * (packages/content). Global numbers depend on the game's script 0, so the target is made
  * for each build from the compiled globals' names.
  */
-export function libraryTarget(globals) {
+export function libraryTarget(globals, items = {}) {
     const g = (name) => {
         const n = globals.indexOf(name);
         if (n < 0)
@@ -28,12 +28,14 @@ export function libraryTarget(globals) {
         firstRoomTalker: 200,
         voice: { class: "Talker", props: {} },
         // Portraits stand at the top left, the text beside them.
-        portrait: { class: "PortraitTalker", props: {}, at: [36, 70], frameSignal: 0, partSignal: 0 },
+        portrait: { class: "PortraitTalker", props: {}, at: [8, 8], frameSignal: 0, partSignal: 0 },
         teller: { class: "Teller", props: {}, verb: 2 },
         forwardCycle: "Forward",
+        closeUp: "CloseUp",
         // room.enter lines: a verb the player can't use.
         narrationVerb: 0,
-        verbs: { look: 1, talk: 2, walk: 3, do: 4 },
+        // And the game's items (items.yaml): using one is its own verb.
+        verbs: { look: 1, talk: 2, walk: 3, do: 4, ...items },
         messageVersion: 4321,
         // SetFlag, ClearFlag and IsFlag: script 999's exports 0, 1 and 2.
         flags: { script: 999, set: 0, clear: 1, test: 2, first: 0, last: 1023 },

package/tools/game/target.ts

@@ -5,7 +5,7 @@ import type { Target } from "../../packages/content/src/index.ts";
  * (packages/content). Global numbers depend on the game's script 0, so the target is made
  * for each build from the compiled globals' names.
  */
-export function libraryTarget(globals: readonly string[]): Target {
+export function libraryTarget(globals: readonly string[], items: Record<string, number> = {}): Target {
   const g = (name: string) => {
     const n = globals.indexOf(name);
     if (n < 0) throw new Error(`the library's global ${name} isn't there: is script 0 compiled with the library?`);
@@ -29,12 +29,14 @@ export function libraryTarget(globals: readonly string[]): Target {
     firstRoomTalker: 200,
     voice: { class: "Talker", props: {} },
     // Portraits stand at the top left, the text beside them.
-    portrait: { class: "PortraitTalker", props: {}, at: [36, 70], frameSignal: 0, partSignal: 0 },
+    portrait: { class: "PortraitTalker", props: {}, at: [8, 8], frameSignal: 0, partSignal: 0 },
     teller: { class: "Teller", props: {}, verb: 2 },
     forwardCycle: "Forward",
+    closeUp: "CloseUp",
     // room.enter lines: a verb the player can't use.
     narrationVerb: 0,
-    verbs: { look: 1, talk: 2, walk: 3, do: 4 },
+    // And the game's items (items.yaml): using one is its own verb.
+    verbs: { look: 1, talk: 2, walk: 3, do: 4, ...items },
     messageVersion: 4321,
     // SetFlag, ClearFlag and IsFlag: script 999's exports 0, 1 and 2.
     flags: { script: 999, set: 0, clear: 1, test: 2, first: 0, last: 1023 },