sci2-ts 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project. Versions follow [Semantic Versioning](https
 and the entries are generated from commit messages
 ([Conventional Commits](https://www.conventionalcommits.org/)) when a release is made.
 
+## [0.16.0](https://github.com/rlueder/sci-ts/compare/v0.15.1...v0.16.0) (2026-10-02)
+
+### Added
+
+* **lib:** a lens magnifies what's under it, and portraits don't cover faces ([#19](https://github.com/rlueder/sci-ts/issues/19)) ([cc901d2](https://github.com/rlueder/sci-ts/commit/cc901d23716fad1b6466950fb77d7809f00b7f00))
+
 ## [0.15.1](https://github.com/rlueder/sci-ts/compare/v0.15.0...v0.15.1) (2026-10-02)
 
 ### Fixed

package/lib/993.sc

@@ -5,13 +5,15 @@
 
 ;; Something the hero can carry. Its view's loop 0 is its icon in the inventory window and
 ;; loop 1 the cursor while it's being used (the cel's anchor is the hotspot); both anchored
-;; at the top-left corner. Using it on something sends that thing doVerb: with the item's
+;; at the top-left corner. One that magnifies (a lens) has its glass as loop 2, placed like
+;; the cursor: while it's in use, the room shows through the glass `magnify` times larger. Using it on something sends that thing doVerb: with the item's
 ;; own verb, 10 and up, so the room answers with noun and that verb (in Yarn, a node like
 ;; filings.lens: the game names its items' verbs in items.yaml).
 (class InvItem of Obj
   (properties
     view -1
     verb 0
+    magnify 0       ; 0, or how much bigger things look through it
     description 0)  ; what looking at it in the window says
 
   ;; Looked at in the inventory window.

package/lib/995.sc

@@ -65,7 +65,11 @@
     (if (or (!= v cursor) (!= l cursorLoop))
       (= cursor v)
       (= cursorLoop l)
-      (SetCursor v l 0)))
+      (SetCursor v l 0)
+      (if (and (== l 1) theItem (theItem magnify?))
+        (AddMagnify v 2 0 (theItem magnify?))
+       else
+        (DeleteMagnify))))
 
   (method (doit)
     (self showCursor:)

package/lib/996.sc

@@ -233,18 +233,47 @@
       (= mouth ((Prop new:) view: view yourself:))
       (= eyes ((Prop new:) view: view yourself:))))
 
-  ;; This line's side: see above.
-  (method (pickSide &tmp s)
-    (if (== self heroTalker) (return (- 1 otherSide)))
-    (= s (if (and who ego (< (who x?) (ego x?))) 0 else 1))
-    (if (and heroTalker (!= heroTalker self) (heroTalker respondsTo: #otherSide)) (heroTalker otherSide: s))
+  ;; This line's side: see above. A side whose portrait would cover the speaker or the hero
+  ;; (a face under the frame) gives way to the other, if that one covers no one.
+  (method (pickSide face &tmp s)
+    (= s
+      (cond
+        ((== self heroTalker) (- 1 otherSide))
+        ((and who ego (< (who x?) (ego x?))) 0)
+        (else 1)))
+    (if (and face (self covers: face s) (not (self covers: face (- 1 s)))) (= s (- 1 s)))
+    (if (and (!= self heroTalker) heroTalker (heroTalker respondsTo: #otherSide)) (heroTalker otherSide: s))
     (return s))
 
+  ;; Whether the portrait on side s (frame and all) would be over the speaker or the hero.
+  (method (covers face s &tmp pw ph over left right bottom)
+    (= pw (CelWide (face view?) 0 0))
+    (= ph (CelHigh (face view?) 0 0))
+    (= over (if (!= (textStyle portraitFrame?) -1) (/ (- (CelWide (textStyle portraitFrame?) 0 0) pw) 2) else 0))
+    (= left (if s (- SCREEN_WIDTH (+ (textStyle portraitX?) pw over)) else (- (textStyle portraitX?) over)))
+    (= right (+ left pw over over))
+    (= bottom (+ (textStyle portraitY?) ph over))
+    (return
+      (or
+        (self over: (if (== self heroTalker) ego else who) left right bottom)
+        (and (!= self heroTalker) (self over: ego left right bottom)))))
+
+  ;; Whether someone's figure reaches into the screen's top band from left to right, down to bottom.
+  (method (over body left right bottom &tmp w h)
+    (if (or (not body) (not (body respondsTo: #view)) (& (body signal?) SIG_HIDDEN)) (return FALSE))
+    (= w (CelWide (body view?) (body loop?) (body cel?)))
+    (= h (CelHigh (body view?) (body loop?) (body cel?)))
+    (if (& (body scaleSignal?) SCALE_ON)
+      (= w (/ (* w (body scaleX?)) 128))
+      (= h (/ (* h (body scaleY?)) 128)))
+    (return
+      (and (< (- (body x?) (/ w 2)) right) (> (+ (body x?) (/ w 2)) left) (< (- (body y?) h) bottom))))
+
   (method (say txt whoCares &tmp face l pw f fx fy over)
     (self init: makeParts:)
     (= face (if frame frame else bust))
     (if face
-      (= side (self pickSide:))
+      (= side (self pickSide: face))
       (= l (if (and side (>= (NumLoops face) 6)) 3 else 0))
       (= pw (CelWide (face view?) l 0))
       (= f (textStyle portraitFrame?))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sci2-ts",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "An SCI2 adventure game engine in TypeScript, and the tools to make games with it",
   "license": "MIT",
   "type": "module",

package/packages/sci/src/vm/kernels/graphics.d.ts

@@ -56,6 +56,16 @@ export declare class Graphics {
         x: number;
         y: number;
     };
+    /**
+     * The cursor as a magnifying glass (AddMagnify): where this cel is opaque, placed like the
+     * cursor, the screen under the cursor's hotspot shows `zoom` times larger.
+     */
+    magnify: {
+        view: number;
+        loop: number;
+        cel: number;
+        zoom: number;
+    } | undefined;
     /** Palette range affected by fade show styles (SetPalStyleRange). */
     styleRange: {
         from: number;

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

@@ -85,6 +85,11 @@ export class Graphics {
     transitions = new Map();
     /** The mouse cursor: a view cel drawn on top at the mouse position (its origin = hotspot). */
     cursor = { view: -1, loop: 0, cel: 0, visible: true, x: 160, y: 100 };
+    /**
+     * The cursor as a magnifying glass (AddMagnify): where this cel is opaque, placed like the
+     * cursor, the screen under the cursor's hotspot shows `zoom` times larger.
+     */
+    magnify;
     /** Palette range affected by fade show styles (SetPalStyleRange). */
     styleRange = { from: 0, to: 255 };
     lastFrame;
@@ -218,8 +223,28 @@ export class Graphics {
             for (const d of draws)
                 blit(pixels, d, clip, remap);
         }
-        // The cursor goes on top of everything.
+        // The cursor goes on top of everything: first what a magnifier shows through its glass.
         const cur = this.cursor;
+        const mag = this.magnify;
+        const glass = cur.visible && mag ? this.cel(mag.view, mag.loop, mag.cel) : undefined;
+        if (glass && mag) {
+            const scene = pixels.slice();
+            const o = celOrigin(glass.cel, glass.mirror);
+            const { width: w, height: h, skipColor } = glass.cel;
+            for (let gy = 0; gy < h; gy++) {
+                for (let gx = 0; gx < w; gx++) {
+                    if (glass.cel.pixels[gy * w + (glass.mirror ? w - 1 - gx : gx)] === skipColor)
+                        continue;
+                    const x = cur.x - o.x + gx, y = cur.y - o.y + gy;
+                    if (x < 0 || y < 0 || x >= SCREEN_WIDTH || y >= SCREEN_HEIGHT)
+                        continue;
+                    const sx = cur.x + Math.floor((x - cur.x) / mag.zoom), sy = cur.y + Math.floor((y - cur.y) / mag.zoom);
+                    if (sx < 0 || sy < 0 || sx >= SCREEN_WIDTH || sy >= SCREEN_HEIGHT)
+                        continue;
+                    pixels[y * SCREEN_WIDTH + x] = scene[sy * SCREEN_WIDTH + sx];
+                }
+            }
+        }
         if (cur.visible && cur.view >= 0) {
             const found = this.cel(cur.view, cur.loop, cur.cel);
             if (found) {
@@ -467,8 +492,17 @@ export const graphicsKernels = {
     HaveMouse: () => 1,
     ShakeScreen: () => 0,
     SetScroll: () => 0,
-    AddMagnify: () => 0,
-    DeleteMagnify: () => 0,
+    // AddMagnify(view, loop, cel, zoom): sci-ts makes the cursor a magnifying glass, the cel's
+    // opaque pixels its glass (placed like the cursor), showing what's under the hotspot zoom
+    // times larger. DeleteMagnify() stops it.
+    AddMagnify: (vm, [view = 0, loop = 0, cel = 0, zoom = 2]) => {
+        graphics(vm).magnify = { view: toSigned(view), loop, cel, zoom: Math.max(1, toSigned(zoom)) };
+        return 0;
+    },
+    DeleteMagnify: (vm) => {
+        graphics(vm).magnify = undefined;
+        return 0;
+    },
     GetHighItemPri: () => 0,
     SetFontRes: () => 0,
     NULL_: () => NULL,

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

@@ -90,6 +90,11 @@ export class Graphics {
   readonly transitions = new Map<Value, Transition>();
   /** The mouse cursor: a view cel drawn on top at the mouse position (its origin = hotspot). */
   cursor = { view: -1, loop: 0, cel: 0, visible: true, x: 160, y: 100 };
+  /**
+   * The cursor as a magnifying glass (AddMagnify): where this cel is opaque, placed like the
+   * cursor, the screen under the cursor's hotspot shows `zoom` times larger.
+   */
+  magnify: { view: number; loop: number; cel: number; zoom: number } | undefined;
   /** Palette range affected by fade show styles (SetPalStyleRange). */
   styleRange = { from: 0, to: 255 };
   lastFrame: Frame | undefined;
@@ -224,8 +229,25 @@ export class Graphics {
       }
       for (const d of draws) blit(pixels, d, clip, remap);
     }
-    // The cursor goes on top of everything.
+    // The cursor goes on top of everything: first what a magnifier shows through its glass.
     const cur = this.cursor;
+    const mag = this.magnify;
+    const glass = cur.visible && mag ? this.cel(mag.view, mag.loop, mag.cel) : undefined;
+    if (glass && mag) {
+      const scene = pixels.slice();
+      const o = celOrigin(glass.cel, glass.mirror);
+      const { width: w, height: h, skipColor } = glass.cel;
+      for (let gy = 0; gy < h; gy++) {
+        for (let gx = 0; gx < w; gx++) {
+          if (glass.cel.pixels[gy * w + (glass.mirror ? w - 1 - gx : gx)] === skipColor) continue;
+          const x = cur.x - o.x + gx, y = cur.y - o.y + gy;
+          if (x < 0 || y < 0 || x >= SCREEN_WIDTH || y >= SCREEN_HEIGHT) continue;
+          const sx = cur.x + Math.floor((x - cur.x) / mag.zoom), sy = cur.y + Math.floor((y - cur.y) / mag.zoom);
+          if (sx < 0 || sy < 0 || sx >= SCREEN_WIDTH || sy >= SCREEN_HEIGHT) continue;
+          pixels[y * SCREEN_WIDTH + x] = scene[sy * SCREEN_WIDTH + sx]!;
+        }
+      }
+    }
     if (cur.visible && cur.view >= 0) {
       const found = this.cel(cur.view, cur.loop, cur.cel);
       if (found) {
@@ -501,8 +523,17 @@ export const graphicsKernels: Record<string, KernelFn> = {
   HaveMouse: () => 1,
   ShakeScreen: () => 0,
   SetScroll: () => 0,
-  AddMagnify: () => 0,
-  DeleteMagnify: () => 0,
+  // AddMagnify(view, loop, cel, zoom): sci-ts makes the cursor a magnifying glass, the cel's
+  // opaque pixels its glass (placed like the cursor), showing what's under the hotspot zoom
+  // times larger. DeleteMagnify() stops it.
+  AddMagnify: (vm, [view = 0, loop = 0, cel = 0, zoom = 2]) => {
+    graphics(vm).magnify = { view: toSigned(view), loop, cel, zoom: Math.max(1, toSigned(zoom)) };
+    return 0;
+  },
+  DeleteMagnify: (vm) => {
+    graphics(vm).magnify = undefined;
+    return 0;
+  },
   GetHighItemPri: () => 0,
   SetFontRes: () => 0,
   NULL_: () => NULL,

package/tools/game/build.d.ts

@@ -60,12 +60,14 @@ export interface GameItem {
     verb: number;
     view?: number;
     description?: string;
+    /** How much bigger things look through it (a lens): its view's loop 2 is the glass. */
+    magnify?: number;
 }
 /**
  * items.yaml: each thing the hero can carry, by name. `lens: 10` names just its verb (10 to
  * 255; 1 to 4 are the player's), for a game whose scripts make the item; with a view, the
  * build makes it too, in script ITEMS_SCRIPT, and rooms can give it (`<<get lens>>`):
  *
- *   lens: { verb: 10, view: 250, description: "Holmes's lens." }
+ *   lens: { verb: 10, view: 250, description: "Holmes's lens.", magnify: 2 }
  */
 export declare function gameItems(dir: string): Record<string, GameItem>;

package/tools/game/build.js

@@ -340,7 +340,7 @@ export async function buildGame(dir, options = {}) {
  * 255; 1 to 4 are the player's), for a game whose scripts make the item; with a view, the
  * build makes it too, in script ITEMS_SCRIPT, and rooms can give it (`<<get lens>>`):
  *
- *   lens: { verb: 10, view: 250, description: "Holmes's lens." }
+ *   lens: { verb: 10, view: 250, description: "Holmes's lens.", magnify: 2 }
  */
 export function gameItems(dir) {
     const file = join(dir, "items.yaml");
@@ -366,7 +366,7 @@ export function gameItems(dir) {
         const spec = typeof value === "number" ? { verb: value } : value;
         if (!spec || typeof spec !== "object" || Array.isArray(spec))
             return fail(`${name}: expected a verb, or { verb, view, description }`);
-        const { verb, view, description, ...rest } = spec;
+        const { verb, view, description, magnify, ...rest } = spec;
         const unknown = Object.keys(rest)[0];
         if (unknown)
             fail(`${name}: unknown key ${unknown}`);
@@ -380,7 +380,11 @@ export function gameItems(dir) {
             fail(`${name}: description is text without quotes or backslashes`);
         if (description !== undefined && view === undefined)
             fail(`${name}: an item the build makes needs a view`);
-        items[name] = { verb: verb, view: view, description: description };
+        if (magnify !== undefined && (typeof magnify !== "number" || !Number.isInteger(magnify) || magnify < 2 || magnify > 8))
+            fail(`${name}: magnify is how much bigger, 2 to 8`);
+        if (magnify !== undefined && view === undefined)
+            fail(`${name}: an item that magnifies needs a view (its loop 2 is the glass)`);
+        items[name] = { verb: verb, view: view, description: description, ...(magnify === undefined ? {} : { magnify: magnify }) };
     }
     return items;
 }
@@ -394,7 +398,7 @@ function itemsScript(items) {
         `(script ${ITEMS_SCRIPT})`,
         '(include "system.sh")',
         `(public ${made.map(([name], i) => `${name} ${i}`).join(" ")})`,
-        ...made.map(([name, i]) => `(instance ${name} of InvItem (properties view ${i.view} verb ${i.verb}${i.description ? ` description "${i.description}"` : ""}))`),
+        ...made.map(([name, i]) => `(instance ${name} of InvItem (properties view ${i.view} verb ${i.verb}${i.magnify ? ` magnify ${i.magnify}` : ""}${i.description ? ` description "${i.description}"` : ""}))`),
         "",
     ].join("\n");
 }

package/tools/game/build.ts

@@ -370,6 +370,8 @@ export interface GameItem {
   verb: number;
   view?: number;
   description?: string;
+  /** How much bigger things look through it (a lens): its view's loop 2 is the glass. */
+  magnify?: number;
 }
 
 /**
@@ -377,7 +379,7 @@ export interface GameItem {
  * 255; 1 to 4 are the player's), for a game whose scripts make the item; with a view, the
  * build makes it too, in script ITEMS_SCRIPT, and rooms can give it (`<<get lens>>`):
  *
- *   lens: { verb: 10, view: 250, description: "Holmes's lens." }
+ *   lens: { verb: 10, view: 250, description: "Holmes's lens.", magnify: 2 }
  */
 export function gameItems(dir: string): Record<string, GameItem> {
   const file = join(dir, "items.yaml");
@@ -394,7 +396,7 @@ export function gameItems(dir: string): Record<string, GameItem> {
     if (!/^[a-z][A-Za-z0-9]*$/.test(name) || ["look", "talk", "walk", "do", "enter"].includes(name)) fail(`"${name}" can't name an item (lower camelCase, and not a verb)`);
     const spec = typeof value === "number" ? { verb: value } : value;
     if (!spec || typeof spec !== "object" || Array.isArray(spec)) return fail(`${name}: expected a verb, or { verb, view, description }`);
-    const { verb, view, description, ...rest } = spec as Record<string, unknown>;
+    const { verb, view, description, magnify, ...rest } = spec as Record<string, unknown>;
     const unknown = Object.keys(rest)[0];
     if (unknown) fail(`${name}: unknown key ${unknown}`);
     if (typeof verb !== "number" || !Number.isInteger(verb) || verb < 10 || verb > 255) fail(`${name}: the verb is a number from 10 to 255`);
@@ -402,7 +404,9 @@ export function gameItems(dir: string): Record<string, GameItem> {
     if (view !== undefined && (typeof view !== "number" || !Number.isInteger(view) || view < 0 || view > 65535)) fail(`${name}: view is a view number`);
     if (description !== undefined && (typeof description !== "string" || /["\\]/.test(description))) fail(`${name}: description is text without quotes or backslashes`);
     if (description !== undefined && view === undefined) fail(`${name}: an item the build makes needs a view`);
-    items[name] = { verb: verb as number, view: view as number | undefined, description: description as string | undefined };
+    if (magnify !== undefined && (typeof magnify !== "number" || !Number.isInteger(magnify) || magnify < 2 || magnify > 8)) fail(`${name}: magnify is how much bigger, 2 to 8`);
+    if (magnify !== undefined && view === undefined) fail(`${name}: an item that magnifies needs a view (its loop 2 is the glass)`);
+    items[name] = { verb: verb as number, view: view as number | undefined, description: description as string | undefined, ...(magnify === undefined ? {} : { magnify: magnify as number }) };
   }
   return items;
 }
@@ -416,7 +420,7 @@ function itemsScript(items: Record<string, GameItem>): string | undefined {
     `(script ${ITEMS_SCRIPT})`,
     '(include "system.sh")',
     `(public ${made.map(([name], i) => `${name} ${i}`).join(" ")})`,
-    ...made.map(([name, i]) => `(instance ${name} of InvItem (properties view ${i.view} verb ${i.verb}${i.description ? ` description "${i.description}"` : ""}))`),
+    ...made.map(([name, i]) => `(instance ${name} of InvItem (properties view ${i.view} verb ${i.verb}${i.magnify ? ` magnify ${i.magnify}` : ""}${i.description ? ` description "${i.description}"` : ""}))`),
     "",
   ].join("\n");
 }