sci2-ts 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.8.1](https://github.com/rlueder/sci-ts/compare/v0.8.0...v0.8.1) (2026-10-02)
+
+### Fixed
+
+* timers past 32767 cycles, waits on missing sounds, methods hidden by properties ([#9](https://github.com/rlueder/sci-ts/issues/9)) ([7ec09d7](https://github.com/rlueder/sci-ts/commit/7ec09d765ab2818cf0171d5e96d9fa1b6744b576))
+
+### Documentation
+
+* AGENTS.md for people and agents working here ([#8](https://github.com/rlueder/sci-ts/issues/8)) ([42bec1f](https://github.com/rlueder/sci-ts/commit/42bec1fafbb2798b26539923608882fef0c5118d))
+
+## [0.8.0](https://github.com/rlueder/sci-ts/compare/v0.7.0...v0.8.0) (2026-10-02)
+
+### Added
+
+* **content:** poses, idles and prop behaviours ([#7](https://github.com/rlueder/sci-ts/issues/7)) ([1413ca3](https://github.com/rlueder/sci-ts/commit/1413ca334a29255d9a67ca136f01607187e7bee6))
+
 ## [0.7.0](https://github.com/rlueder/sci-ts/compare/v0.6.1...v0.7.0) (2026-10-01)
 
 ### Added

package/lib/996.sc

@@ -100,7 +100,8 @@
   (properties
     caller 0
     box 0
-    until 0         ; the game time it goes
+    shownAt 0       ; the game time it went up
+    readFor 0       ; how long it stays (-1: until dismissed)
     font -1         ; -1: the textStyle's
     x -1            ; -1: centred
     y 16
@@ -120,19 +121,21 @@
         yourself:))
     (box init:)
     (= talking self)
-    (= until (self readingTime: (String STRING_LENGTH txt))))
+    (= shownAt gameTime)
+    (= readFor (self readingTime: (String STRING_LENGTH txt))))
 
-  ;; Game time to read a line of n characters: normally two seconds, and more for longer
-  ;; lines; -1 is until the player dismisses it.
+  ;; Cycles to read a line of n characters: normally two seconds, and more for longer lines;
+  ;; -1 is until the player dismisses it.
   (method (readingTime n)
     (switch textSpeed
-      (TEXT_SLOW (return (+ gameTime 180 (* 5 n))))
-      (TEXT_FAST (return (+ gameTime 70 (* 2 n))))
+      (TEXT_SLOW (return (+ 180 (* 5 n))))
+      (TEXT_FAST (return (+ 70 (* 2 n))))
       (TEXT_CLICK (return -1))
-      (else (return (+ gameTime 120 (* 3 n))))))
+      (else (return (+ 120 (* 3 n))))))
 
+  ;; Time is measured as cycles since, which stays right when gameTime wraps past 32767.
   (method (doit)
-    (if (and box (!= until -1) (>= gameTime until)) (self done:)))
+    (if (and box (!= readFor -1) (>= (- gameTime shownAt) readFor)) (self done:)))
 
   ;; A click, Enter, Space or "." while a line is up dismisses it (and nothing else).
   (method (handleEvent event)
@@ -174,7 +177,7 @@
   (properties
     mouth 0 bust 0 eyes 0 frame 0
     priority 150
-    mouthUntil 0)   ; the game time the mouth stops
+    mouthFor 0)     ; cycles the mouth moves for
 
   (method (init theMouth theBust theEyes theFrame)
     (= mouth theMouth)
@@ -198,10 +201,10 @@
     (if mouth
       (mouth setCycle: Forward)
       ;; About as long as it takes to say: half a second, and two cycles a letter.
-      (= mouthUntil (+ gameTime 30 (* 2 (String STRING_LENGTH txt))))))
+      (= mouthFor (+ 30 (* 2 (String STRING_LENGTH txt))))))
 
   (method (doit)
-    (if (and mouth (mouth cycler?) (>= gameTime mouthUntil))
+    (if (and mouth (mouth cycler?) (>= (- gameTime shownAt) mouthFor))
       (mouth setCycle: 0 setCel: 0))
     (super doit:))
 

package/lib/997.sc

@@ -173,18 +173,20 @@
 ;; (shut) and back to 0.
 (class Blink of Cycle
   (properties
-    nextBlink 0)
+    restSince 0
+    restFor 0)
 
   (method (init who)
     (super init: who)
     (self rest:))
 
   (method (rest)
-    (= nextBlink (+ gameTime 90 (Random 0 90))))
+    (= restSince gameTime)
+    (= restFor (+ 90 (Random 0 90))))
 
   (method (doit &tmp c)
     (if (== (client cel?) 0)
-      (if (and (>= gameTime nextBlink) (> (self lastCel:) 0))
+      (if (and (>= (- gameTime restSince) restFor) (> (self lastCel:) 0))
         (= cycleCnt gameTime)
         (client cel: 1))
      else

package/lib/998.sc

@@ -207,9 +207,11 @@
     (if (not (and noun (messager say: noun verb 0 0 0 modNum)))
       (curRoom doVerb: verb))))
 
-;; A Feature drawn with a view: a screen item in the room's plane.
+;; A Feature drawn with a view: a screen item in the room's plane. One that's only there to
+;; look at (rain on a window, a sky) has clickable 0, and clicks go to what's behind it.
 (class View of Feature
   (properties
+    clickable 1
     view -1 loop 0 cel 0
     z 0
     priority 0 fixPriority 0
@@ -230,7 +232,7 @@
     (if (not (& signal SIG_HIDDEN)) (UpdateScreenItem self)))
 
   (method (onMe theX theY)
-    (return (and (not (& signal SIG_HIDDEN)) (IsOnMe theX theY self))))
+    (return (and clickable (not (& signal SIG_HIDDEN)) (IsOnMe theX theY self))))
 
   (method (hide)
     (|= signal SIG_HIDDEN)
@@ -364,13 +366,51 @@
     (if scaler (scaler dispose:) (= scaler 0))
     (super dispose:)))
 
-;; The hero: walks where the player clicks, and goes from room to room.
+;; The hero: walks where the player clicks, and goes from room to room. Standing still
+;; for idleAfter seconds while the player can act, he plays a loop of idleView once (a
+;; puff on the pipe, a glance at a watch), chosen at random, then stands again.
 (class Ego of Actor
-  ;; Back to walking: cycling as he moves, turning as he goes, seen.
+  (properties
+    normalView -1   ; the walking view (the first view he's normalized with)
+    idleView -1     ; -1: no idles
+    idleAfter 8
+    stillSince 0    ; the game time he was last busy
+    idling 0)
+
+  ;; Back to walking: his walking view, cycling as he moves, turning as he goes, seen.
   (method (normalize)
+    (if (== normalView -1) (= normalView view) else (= view normalView))
+    (= idling 0)
     (self setLoop: -1 setCycle: Walk show:)
     (return self))
 
+  (method (doit)
+    (super doit:)
+    (self checkIdle:))
+
+  (method (checkIdle)
+    (cond
+      ((== idleView -1) 0)
+      ;; Busy, or someone else is in charge: no idle, and one under way stops.
+      ((or mover talking dialog (not (user canInput?)) (and (not idling) (!= view normalView)))
+        (if idling (self normalize:))
+        (= stillSince gameTime))
+      (idling 0)
+      ((>= (- gameTime stillSince) (* idleAfter 60))
+        (= idling 1)
+        (= view idleView)
+        (self setLoop: (Random 0 (- (NumLoops self) 1)) setCel: 0 setCycle: End self))))
+
+  ;; An idle has played through.
+  (method (cue)
+    (if idling
+      (self normalize:)
+      (= stillSince gameTime)))
+
+  (method (setMotion)
+    (if idling (self normalize:))
+    (super setMotion: &rest))
+
   (method (roomDisposed)
     (self setMotion: 0)
     (DeleteScreenItem self)

package/package.json

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

package/packages/content/room.schema.json

@@ -222,6 +222,11 @@
           "moves": {
             "type": "boolean",
             "description": "It walks or floats about in cutscenes (<<walk name x y>>): an Actor instead of a Prop"
+          },
+          "script": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Za-z0-9]*$",
+            "description": "A Script class of the game's: an instance of it runs on the prop, e.g. an ambient behaviour"
           }
         }
       }

package/packages/content/src/room.d.ts

@@ -82,6 +82,8 @@ interface PropSpec {
     /** forward: loop the animation forever. */
     cycle?: "forward";
     sightAngle?: number;
+    /** A Script class of the game's: an instance of it runs on the prop (ambient behaviour). */
+    script?: string;
 }
 export interface CompiledRoom {
     number: number;

package/packages/content/src/room.js

@@ -83,7 +83,9 @@ class SpecChecker {
                 names.add(name);
                 const t = this.map(value, path);
                 if (group === "props") {
-                    this.known(t, path, ["view", "at", "loop", "cel", "cycle", "sightAngle", "moves"]);
+                    this.known(t, path, ["view", "at", "loop", "cel", "cycle", "sightAngle", "moves", "script"]);
+                    if (t.script !== undefined && (typeof t.script !== "string" || !/^[A-Z][A-Za-z0-9]*$/.test(t.script)))
+                        this.fail([...path, "script"], "expected a class name, e.g. Scurry");
                     if (t.moves !== undefined && typeof t.moves !== "boolean")
                         this.fail([...path, "moves"], "expected true or false");
                     this.int(t.view, [...path, "view"], 0, 65535);
@@ -522,6 +524,14 @@ class RoomCompiler {
                     return [{ op: "code", code: send(to, [["setCycle", [{ cls: this.target.forwardCycle }]]]) }];
                 return fail("expected once or forever");
             }
+            case "view":
+                arity(2, "hero|<prop> view");
+                return [{ op: "code", code: send(who(args[0], false), [["view", [int(args[1], "view", 0, 65535)]], ["setCel", [0]]]) }];
+            case "normal":
+                arity(1, "hero");
+                if (args[0] !== "hero")
+                    fail("only the hero goes back to normal (walking, turning as he goes)");
+                return [{ op: "code", code: send({ global: g.ego }, [["normalize", []]]) }];
             case "stop":
                 arity(1, "<prop>");
                 return [{ op: "code", code: send(who(args[0], false), [["setCycle", [0]]]) }];
@@ -564,7 +574,7 @@ class RoomCompiler {
                 arity(1, "number");
                 return [{ op: "code", code: send({ global: g.curRoom }, [["newRoom", [int(args[0], "room", 0, 65535)]]]) }];
             default:
-                return fail("unknown command (known: walk, face, wait, hide, show, loop, cel, animate, stop, music, sound, closeup, get, drop, room; and set, if)");
+                return fail("unknown command (known: walk, face, wait, hide, show, view, loop, cel, animate, normal, stop, music, sound, closeup, get, drop, room; and set, if)");
         }
     }
     /** Loop music n, unless it's what's playing already. */
@@ -728,7 +738,12 @@ class RoomCompiler {
         for (const name of [...Object.keys(spec.features ?? {}), ...Object.keys(spec.exits ?? {})])
             c.push(...send({ obj: name }, [["init", []]]));
         for (const [name, p] of Object.entries(spec.props ?? {})) {
-            c.push(...send({ obj: name }, [["init", []], ...(p.cycle === "forward" ? [["setCycle", [{ cls: this.target.forwardCycle }]]] : [])]));
+            c.push(...send({ obj: name }, [
+                ["init", []],
+                ...(p.cycle === "forward" ? [["setCycle", [{ cls: this.target.forwardCycle }]]] : []),
+                // A new instance of the game's Script class, running on the prop.
+                ...(p.script ? [["setScript", [{ code: ["pushi #new", "push0", `class ${p.script}`, "send 4"] }]]] : []),
+            ]));
         }
         const polygons = [
             ...(spec.walkable ? [[3, spec.walkable]] : []),

package/packages/content/src/room.ts

@@ -85,6 +85,8 @@ interface PropSpec {
   /** forward: loop the animation forever. */
   cycle?: "forward";
   sightAngle?: number;
+  /** A Script class of the game's: an instance of it runs on the prop (ambient behaviour). */
+  script?: string;
 }
 
 export interface CompiledRoom {
@@ -186,7 +188,8 @@ class SpecChecker {
         names.add(name);
         const t = this.map(value, path);
         if (group === "props") {
-          this.known(t, path, ["view", "at", "loop", "cel", "cycle", "sightAngle", "moves"]);
+          this.known(t, path, ["view", "at", "loop", "cel", "cycle", "sightAngle", "moves", "script"]);
+          if (t.script !== undefined && (typeof t.script !== "string" || !/^[A-Z][A-Za-z0-9]*$/.test(t.script))) this.fail([...path, "script"], "expected a class name, e.g. Scurry");
           if (t.moves !== undefined && typeof t.moves !== "boolean") this.fail([...path, "moves"], "expected true or false");
           this.int(t.view, [...path, "view"], 0, 65535);
           this.point(t.at, [...path, "at"]);
@@ -622,6 +625,13 @@ class RoomCompiler {
         if (args[1] === "forever") return [{ op: "code", code: send(to, [["setCycle", [{ cls: this.target.forwardCycle }]]]) }];
         return fail("expected once or forever");
       }
+      case "view":
+        arity(2, "hero|<prop> view");
+        return [{ op: "code", code: send(who(args[0], false), [["view", [int(args[1], "view", 0, 65535)]], ["setCel", [0]]]) }];
+      case "normal":
+        arity(1, "hero");
+        if (args[0] !== "hero") fail("only the hero goes back to normal (walking, turning as he goes)");
+        return [{ op: "code", code: send({ global: g.ego }, [["normalize", []]]) }];
       case "stop":
         arity(1, "<prop>");
         return [{ op: "code", code: send(who(args[0], false), [["setCycle", [0]]]) }];
@@ -661,7 +671,7 @@ class RoomCompiler {
         arity(1, "number");
         return [{ op: "code", code: send({ global: g.curRoom }, [["newRoom", [int(args[0], "room", 0, 65535)]]]) }];
       default:
-        return fail("unknown command (known: walk, face, wait, hide, show, loop, cel, animate, stop, music, sound, closeup, get, drop, room; and set, if)");
+        return fail("unknown command (known: walk, face, wait, hide, show, view, loop, cel, animate, normal, stop, music, sound, closeup, get, drop, room; and set, if)");
     }
   }
 
@@ -831,7 +841,12 @@ class RoomCompiler {
     if (spec.music !== undefined) c.push(...this.playMusic(spec.music));
     for (const name of [...Object.keys(spec.features ?? {}), ...Object.keys(spec.exits ?? {})]) c.push(...send({ obj: name }, [["init", []]]));
     for (const [name, p] of Object.entries(spec.props ?? {})) {
-      c.push(...send({ obj: name }, [["init", []], ...(p.cycle === "forward" ? [["setCycle", [{ cls: this.target.forwardCycle }]] as [string, Val[]]] : [])]));
+      c.push(...send({ obj: name }, [
+        ["init", []],
+        ...(p.cycle === "forward" ? [["setCycle", [{ cls: this.target.forwardCycle }]] as [string, Val[]]] : []),
+        // A new instance of the game's Script class, running on the prop.
+        ...(p.script ? [["setScript", [{ code: ["pushi #new", "push0", `class ${p.script}`, "send 4"] }]] as [string, Val[]]] : []),
+      ]));
     }
     const polygons: [number, [number, number][]][] = [
       ...(spec.walkable ? [[3, spec.walkable] as [number, [number, number][]]] : []),

package/packages/sci/src/script/compiler.js

@@ -95,6 +95,27 @@ export function compileScripts(sources, ctx) {
                     defined.add(m.name);
             }
         }
+        // A method named like a property of its object: `x:` sets the property and the method
+        // never runs.
+        const propertiesOf = (name, seen = new Set()) => {
+            if (!name || seen.has(name))
+                return new Set(OBJECT_HEADER);
+            seen.add(name);
+            const c = classes.get(name);
+            if (c)
+                return new Set([...c.obj.props.map((p) => p.name), ...propertiesOf(c.obj.superName, seen)]);
+            return new Set([...OBJECT_HEADER, ...(ctx.externalClass?.(name)?.properties.map((p) => p.name) ?? [])]);
+        };
+        for (const u of units) {
+            for (const o of u.objects) {
+                const props = new Set([...o.props.map((p) => p.name), ...propertiesOf(o.superName)]);
+                for (const m of o.methods) {
+                    if (!props.has(m.name))
+                        continue;
+                    ctx.onWarning({ message: `method ${m.name}: ${o.name} has a property called ${m.name}, so ${m.name}: sets it and this never runs`, file: u.file, line: m.line });
+                }
+            }
+        }
         const reported = new Set();
         for (const s of project.sent) {
             if (defined.has(s.name) || reported.has(s.name))

package/packages/sci/src/script/compiler.ts

@@ -195,6 +195,24 @@ export function compileScripts(sources: readonly CompileSource[], ctx: CompileCo
         for (const m of o.methods) defined.add(m.name);
       }
     }
+    // A method named like a property of its object: `x:` sets the property and the method
+    // never runs.
+    const propertiesOf = (name: string | undefined, seen = new Set<string>()): Set<string> => {
+      if (!name || seen.has(name)) return new Set(OBJECT_HEADER);
+      seen.add(name);
+      const c = classes.get(name);
+      if (c) return new Set([...c.obj.props.map((p) => p.name), ...propertiesOf(c.obj.superName, seen)]);
+      return new Set([...OBJECT_HEADER, ...(ctx.externalClass?.(name)?.properties.map((p) => p.name) ?? [])]);
+    };
+    for (const u of units) {
+      for (const o of u.objects) {
+        const props = new Set([...o.props.map((p) => p.name), ...propertiesOf(o.superName)]);
+        for (const m of o.methods) {
+          if (!props.has(m.name)) continue;
+          ctx.onWarning({ message: `method ${m.name}: ${o.name} has a property called ${m.name}, so ${m.name}: sets it and this never runs`, file: u.file, line: m.line });
+        }
+      }
+    }
     const reported = new Set<string>();
     for (const s of project.sent) {
       if (defined.has(s.name) || reported.has(s.name)) continue;

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

@@ -266,6 +266,10 @@ export const audioKernels = {
                     a.play(soundKey(obj), clip, loop, volume);
                 else
                     a.startSong(obj, number, loop, volume);
+                // Neither an effect nor a song by that number: it has ended already, so the next
+                // update reports it and whoever waits for it carries on.
+                if (!clip && !a.songs.has(obj))
+                    vm.setProp(obj, "signal", NOT_PLAYING);
                 return 0;
             }
             case 9: // stop

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

@@ -274,6 +274,9 @@ export const audioKernels: Record<string, KernelFn> = {
         const clip = a.index.effects.get(number);
         if (clip) a.play(soundKey(obj), clip, loop, volume);
         else a.startSong(obj, number, loop, volume);
+        // Neither an effect nor a song by that number: it has ended already, so the next
+        // update reports it and whoever waits for it carries on.
+        if (!clip && !a.songs.has(obj)) vm.setProp(obj, "signal", NOT_PLAYING);
         return 0;
       }
       case 9: // stop