sci2-ts 0.0.0-stage → 0.2.2

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

@@ -0,0 +1,349 @@
+import { AudioIndex, speechKey, type AudioClip, type AudioOutput } from "../../audio/index.ts";
+import { SongPlayer, SoundDevice, parseSound, type MidiOutput, type Song } from "../../audio/midi.ts";
+import { ResourceType } from "../../resource/types.ts";
+import { findMessage, parseMessages, type MessageFile } from "../../text/message.ts";
+import type { KernelFn, Vm } from "../vm.ts";
+import { toSigned, type Value } from "../value.ts";
+
+const NOT_PLAYING = 0xffff;
+const MAX_VOLUME = 127;
+
+interface Channel {
+  clip: AudioClip;
+  /** VM clock (ms) when playback started; undefined while waiting to start. */
+  start: number | undefined;
+  pausedAt: number | undefined;
+  ticks: number;
+  loop: boolean;
+  volume: number;
+}
+
+/**
+ * Digital audio state. Durations are known synchronously from the index, so the scripts'
+ * position polling works off the VM clock; the host's AudioOutput does the actual playback
+ * (fetching and decoding clips asynchronously).
+ */
+export class AudioState {
+  readonly index: AudioIndex;
+  readonly channels = new Map<string, Channel>();
+  output: AudioOutput | undefined;
+  /** MIDI music goes here (a SoundFont synth or the AdLib driver). */
+  midi: MidiOutput | undefined;
+  /** Which track of each sound resource to play: General MIDI or AdLib. */
+  device: number = SoundDevice.GeneralMidi;
+  readonly songs = new Map<Value, SongPlayer>();
+  private readonly songNumbers = new Map<Value, number>();
+  private readonly songCache = new Map<string, Song | null>();
+  masterVolume = 15;
+  /**
+   * Ticks to report when a speech clip doesn't exist (new dialogue in a mod). The game times
+   * a spoken line by its clip, so a missing clip would flash the text for a second; hosts
+   * that load mods set this (see `readingTime`). Unset, missing clips report 0 like SSCI.
+   */
+  missingSpeechTicks?: (module: number, noun: number, verb: number, cond: number, seq: number) => number;
+
+  constructor(private readonly vm: Vm) {
+    this.index = AudioIndex.build(vm.resources);
+    vm.frameHooks.push(() => {
+      const now = this.ticks();
+      for (const player of this.songs.values()) player.update(now);
+    });
+  }
+
+  ticks(): number {
+    return Math.floor((this.vm.clock() * 60) / 1000);
+  }
+
+  song(number: number, device = this.device): Song | undefined {
+    const key = `${number}:${device}`;
+    if (!this.songCache.has(key)) {
+      const id = { type: ResourceType.Sound, number };
+      this.songCache.set(key, this.vm.resources.has(id) ? (parseSound(this.vm.resources.loadSync(id).data, device) ?? null) : null);
+    }
+    return this.songCache.get(key) ?? undefined;
+  }
+
+  startSong(obj: Value, number: number, loop: boolean, volume: number, position = 0): void {
+    const song = this.song(number);
+    if (!song) return;
+    const player = new SongPlayer(song, this.midi, loop, volume, this.ticks());
+    if (position) player.seek(position % Math.max(song.length, 1), this.ticks());
+    this.songs.set(obj, player);
+    this.songNumbers.set(obj, number);
+  }
+
+  playingSongs(): { object: Value; number: number; player: SongPlayer }[] {
+    return [...this.songs].map(([object, player]) => ({ object, number: this.songNumbers.get(object)!, player }));
+  }
+
+  /** Silences all music, effects and speech (restart / restore). */
+  stopEverything(): void {
+    for (const obj of [...this.songs.keys()]) this.stopSong(obj);
+    for (const key of [...this.channels.keys()]) this.stop(key);
+  }
+
+  stopSong(obj: Value): void {
+    this.songs.get(obj)?.stop();
+    this.songs.delete(obj);
+    this.songNumbers.delete(obj);
+  }
+
+  /**
+   * Switches music to another device (track) and output, carrying every playing song over
+   * at its current position.
+   */
+  setMusicDevice(device: number, output: MidiOutput | undefined): void {
+    const now = this.ticks();
+    const playing = [...this.songs].map(([obj, player]) => ({ obj, player, pos: player.position(now) }));
+    for (const { player } of playing) player.stop();
+    this.device = device;
+    this.midi = output;
+    output?.setMasterVolume?.(this.masterVolume);
+    for (const { obj, player, pos } of playing) {
+      const song = this.song(this.songNumbers.get(obj)!);
+      if (!song) {
+        this.songs.delete(obj);
+        continue;
+      }
+      const next = new SongPlayer(song, output, player.loop, player.volume, now);
+      next.seek(song.length ? pos % Math.max(song.length, 1) : 0, now);
+      this.songs.set(obj, next);
+    }
+  }
+
+  play(key: string, clip: AudioClip, loop: boolean, volume: number, autoStart = true): number {
+    this.stop(key);
+    const ticks = AudioIndex.ticks(clip);
+    this.channels.set(key, { clip, start: undefined, pausedAt: undefined, ticks, loop, volume });
+    if (autoStart) this.start(key);
+    return ticks;
+  }
+
+  start(key: string): void {
+    const ch = this.channels.get(key);
+    if (!ch || ch.start !== undefined) return;
+    ch.start = this.vm.clock();
+    this.output?.play(key, ch.clip, { loop: ch.loop, volume: ch.volume / MAX_VOLUME });
+  }
+
+  stop(key: string): void {
+    if (!this.channels.delete(key)) return;
+    this.output?.stop(key);
+  }
+
+  stopAll(prefix = ""): void {
+    for (const key of [...this.channels.keys()]) if (key.startsWith(prefix)) this.stop(key);
+  }
+
+  /** Elapsed ticks, or undefined once the clip has finished (non-looping). */
+  position(key: string): number | undefined {
+    const ch = this.channels.get(key);
+    if (!ch) return undefined;
+    if (ch.start === undefined) return 0;
+    const now = ch.pausedAt ?? this.vm.clock();
+    const elapsed = Math.floor(((now - ch.start) * 60) / 1000);
+    if (!ch.loop && elapsed >= ch.ticks) {
+      this.stop(key);
+      return undefined;
+    }
+    return ch.loop ? elapsed % ch.ticks : elapsed;
+  }
+
+  pause(key: string, paused: boolean): void {
+    const ch = this.channels.get(key);
+    if (!ch || ch.start === undefined) return;
+    if (paused && ch.pausedAt === undefined) {
+      ch.pausedAt = this.vm.clock();
+      this.output?.pause(key);
+    } else if (!paused && ch.pausedAt !== undefined) {
+      ch.start += this.vm.clock() - ch.pausedAt;
+      ch.pausedAt = undefined;
+      this.output?.resume(key);
+    }
+  }
+}
+
+const stateOf = new WeakMap<Vm, AudioState>();
+export const audio = (vm: Vm): AudioState => {
+  let a = stateOf.get(vm);
+  if (!a) {
+    const created = (a = new AudioState(vm));
+    stateOf.set(vm, created);
+    vm.hostRoots.push(() => created.songs.keys());
+  }
+  return a;
+};
+
+/**
+ * DoAudio arguments name a clip either as an audio36 (speech) tuple
+ * `module, noun, verb, cond, seq, [loop], [volume]` or as a plain audio number
+ * `number, [loop], [volume]`.
+ */
+function resolveArgs(a: AudioState, args: Value[]): { key: string; clip?: AudioClip; loop: boolean; volume: number } | undefined {
+  if (args.length >= 5) {
+    const [module = 0, noun = 0, verb = 0, cond = 0, seq = 0, loop, volume] = args;
+    return {
+      key: `aud:${speechKey(module, noun, verb, cond, seq)}`,
+      clip: a.index.speech.get(speechKey(module, noun, verb, cond, seq)),
+      loop: loop !== undefined && toSigned(loop) === -1,
+      volume: volume !== undefined && toSigned(volume) >= 0 ? Math.min(toSigned(volume), MAX_VOLUME) : MAX_VOLUME,
+    };
+  }
+  if (args.length >= 1) {
+    const [number = 0, loop, volume] = args;
+    return {
+      key: `sfx:${number}`,
+      clip: a.index.effects.get(number),
+      loop: loop !== undefined && toSigned(loop) === -1,
+      volume: volume !== undefined && toSigned(volume) >= 0 ? Math.min(toSigned(volume), MAX_VOLUME) : MAX_VOLUME,
+    };
+  }
+  return undefined;
+}
+
+const soundKey = (obj: Value) => `snd:${obj.toString(16)}`;
+const prop = (vm: Vm, obj: Value, name: string) => toSigned(vm.getProp(obj, name) ?? 0);
+
+export const audioKernels: Record<string, KernelFn> = {
+  DoAudio: (vm, [subop = 0, ...args]) => {
+    const a = audio(vm);
+    const target = resolveArgs(a, args);
+    switch (subop) {
+      case 0: return 0; // init
+      case 1: // wait-for-play: prepare without starting, return length
+      case 2: { // play
+        if (!target) return a.channels.size;
+        if (!target.clip) {
+          const [module = 0, noun = 0, verb = 0, cond = 0, seq = 0] = args;
+          return args.length >= 5 && a.missingSpeechTicks ? a.missingSpeechTicks(module, noun, verb, cond, seq) & 0xffff : 0;
+        }
+        return a.play(target.key, target.clip, target.loop, target.volume, subop === 2);
+      }
+      case 3: // stop
+        if (target) a.stop(target.key);
+        else a.stopAll("aud:"), a.stopAll("sfx:");
+        return 0;
+      case 4: case 5: // pause / resume
+        for (const key of target ? [target.key] : [...a.channels.keys()]) a.pause(key, subop === 4);
+        return 0;
+      case 6: { // position in ticks, -1 when not playing
+        const key = target?.key ?? [...a.channels.keys()].find((k) => k.startsWith("aud:"));
+        const pos = key === undefined ? undefined : a.position(key);
+        return pos === undefined ? NOT_PLAYING : pos & 0xffff;
+      }
+      case 8: return 0; // volume
+      case 9: return 1; // capability: audio present
+      case 10: return 16; // bit depth
+      case 12: return 1; // mixing
+      case 13: return 2; // channels
+      default: return 0;
+    }
+  },
+
+  // Sound objects. Numbers with a digital effect in RESOURCE.SFX play as samples;
+  // everything else is MIDI, sequenced here and sent to `midi` (a SoundFont synth).
+  DoSound: (vm, [subop = 0, obj = 0, arg = 0, , , stopAfter = 0]) => {
+    const a = audio(vm);
+    switch (subop) {
+      case 0: // master volume (get, or set to arg)
+        if (obj !== 0 || arg) {
+          a.masterVolume = obj & 0xf;
+          a.midi?.setMasterVolume?.(a.masterVolume);
+        }
+        return a.masterVolume;
+      case 3: return 32; // polyphony
+      case 4: return 1; // digital audio available
+      case 6: // init
+        vm.setProp(obj, "nodePtr", obj);
+        return 0;
+      case 7: // dispose
+        a.stop(soundKey(obj));
+        a.stopSong(obj);
+        vm.setProp(obj, "nodePtr", 0);
+        return 0;
+      case 8: { // play: a digital effect if RESOURCE.SFX has this number, else MIDI
+        const number = prop(vm, obj, "number");
+        const loop = prop(vm, obj, "loop") === -1;
+        const volume = vm.getProp(obj, "vol") === undefined ? MAX_VOLUME : prop(vm, obj, "vol");
+        a.stop(soundKey(obj));
+        a.stopSong(obj);
+        vm.setProp(obj, "signal", 0);
+        // SCI2 Sounds ask for updates (Sound::check -> updateCues, which reports the end and
+        // cues the client) only while `handle` is set; playing sets it, stopping clears it.
+        vm.setProp(obj, "handle", obj);
+        const clip = a.index.effects.get(number);
+        if (clip) a.play(soundKey(obj), clip, loop, volume);
+        else a.startSong(obj, number, loop, volume);
+        return 0;
+      }
+      case 9: // stop
+        a.stop(soundKey(obj));
+        a.stopSong(obj);
+        vm.setProp(obj, "signal", NOT_PLAYING);
+        vm.setProp(obj, "handle", 0);
+        return 0;
+      case 10: { // pause (obj or 0 = all, arg = pause?)
+        for (const key of obj ? [soundKey(obj)] : [...a.channels.keys()].filter((k) => k.startsWith("snd:"))) a.pause(key, arg !== 0);
+        for (const player of obj ? [a.songs.get(obj)] : [...a.songs.values()]) {
+          if (arg !== 0) player?.pause(a.ticks());
+          else player?.resume(a.ticks());
+        }
+        return 0;
+      }
+      case 11: { // fade(obj, targetVolume, ticks, step, stopAfter): fading out → stop
+        if (arg === 0 || stopAfter) {
+          a.stop(soundKey(obj));
+          a.stopSong(obj);
+          vm.setProp(obj, "signal", NOT_PLAYING);
+        } else a.songs.get(obj)?.setVolume(arg);
+        return 0;
+      }
+      case 14: // set volume
+        a.output?.setVolume(soundKey(obj), arg / MAX_VOLUME);
+        a.songs.get(obj)?.setVolume(arg);
+        vm.setProp(obj, "vol", arg);
+        return 0;
+      case 16: { // set loop
+        vm.setProp(obj, "loop", arg);
+        const player = a.songs.get(obj);
+        if (player) player.loop = toSigned(arg) === -1;
+        return 0;
+      }
+      case 17: { // update cues: report song signals/cues and finished sounds to the script
+        if (a.channels.has(soundKey(obj)) && a.position(soundKey(obj)) === undefined) vm.setProp(obj, "signal", NOT_PLAYING);
+        const player = a.songs.get(obj);
+        if (player) {
+          player.update(a.ticks());
+          if (player.signal) {
+            vm.setProp(obj, "signal", player.signal);
+            vm.setProp(obj, "dataInc", player.dataInc);
+            player.signal = 0;
+          }
+          if (player.finished) a.stopSong(obj);
+        }
+        return 0;
+      }
+      default:
+        return 0;
+    }
+  },
+
+  DoSync: () => 0,
+};
+
+/**
+ * A `missingSpeechTicks` that gives a line without a recording as long as it takes to read:
+ * ~15 characters a second, at least two seconds. Reads the text from the message resources.
+ */
+export function readingTime(vm: Vm): (module: number, noun: number, verb: number, cond: number, seq: number) => number {
+  const files = new Map<number, MessageFile | undefined>();
+  return (module, noun, verb, cond, seq) => {
+    if (!files.has(module)) {
+      const id = { type: ResourceType.Message, number: module };
+      files.set(module, vm.resources.has(id) ? parseMessages(vm.resources.loadSync(id).data) : undefined);
+    }
+    const file = files.get(module);
+    const text = file ? findMessage(file, { noun, verb, cond, seq })?.text ?? "" : "";
+    return Math.max(120, text.length * 4);
+  };
+}

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

@@ -0,0 +1,5 @@
+import type { KernelFn } from "../vm.ts";
+/** Script, object and resource management. */
+export declare const coreKernels: Record<string, KernelFn>;
+/** Maths, time and the host platform. */
+export declare const mathKernels: Record<string, KernelFn>;

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

@@ -0,0 +1,87 @@
+import { ResourceType } from "../../resource/types.js";
+import { NULL, bool, fromInt, toSigned } from "../value.js";
+/** Script, object and resource management. */
+export const coreKernels = {
+    // Resource loading is eager in this engine, so these only need to answer sensibly.
+    Load: (_vm, [, number = 0]) => number,
+    Unload: () => 0,
+    Lock: () => 0,
+    Purge: () => 0,
+    ResCheck: (vm, [type = 0, number = 0]) => bool(vm.resources.has({ type: (type & 0x7f), number })),
+    ScriptID: (vm, [script = 0, index = 0]) => {
+        if (!vm.resources.has({ type: ResourceType.Script, number: script }))
+            return NULL;
+        return vm.exportAddress(script, index);
+    },
+    // Unloads the script (see Vm.disposeScript) and returns its optional second argument:
+    // scripts use it to hand a value back from code that's about to be unloaded (SRDialog
+    // returns the chosen save id this way).
+    DisposeScript: (vm, args) => {
+        vm.disposeScript(args[0] & 0xffff);
+        return args.length >= 2 ? args[1] : undefined;
+    },
+    Clone: (vm, [obj = 0]) => vm.memory.clone(vm.object(obj)).address,
+    DisposeClone: (vm, [obj = 0]) => {
+        const o = vm.memory.object(obj);
+        if (o)
+            vm.memory.disposeClone(o);
+    },
+    RespondsTo: (vm, [obj = 0, selector = 0]) => {
+        const o = vm.memory.object(obj);
+        return bool(!!o && vm.respondsTo(o, selector));
+    },
+};
+let seed = 0x1234;
+const bootDate = Date.now();
+/** Maths, time and the host platform. */
+export const mathKernels = {
+    Random: (_vm, args) => {
+        if (args.length === 1) {
+            seed = args[0]; // seed the generator
+            return 0;
+        }
+        seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+        if (args.length < 2)
+            return (seed >> 8) & 0xffff;
+        const lo = toSigned(args[0]), hi = toSigned(args[1]);
+        return fromInt(lo + ((seed >> 8) % (hi - lo + 1)));
+    },
+    Abs: (_vm, [n = 0]) => fromInt(Math.abs(toSigned(n))),
+    Sqrt: (_vm, [n = 0]) => Math.floor(Math.sqrt(Math.abs(toSigned(n)))),
+    GetAngle: (_vm, [x1 = 0, y1 = 0, x2 = 0, y2 = 0]) => sciAngle(toSigned(x2) - toSigned(x1), toSigned(y2) - toSigned(y1)),
+    GetDistance: (_vm, [x1 = 0, y1 = 0, x2 = 0, y2 = 0, perspective = 0]) => {
+        const dx = toSigned(x2) - toSigned(x1);
+        let dy = toSigned(y2) - toSigned(y1);
+        if (perspective)
+            dy = Math.trunc((dy * 3) / 2);
+        return Math.round(Math.sqrt(dx * dx + dy * dy)) & 0xffff;
+    },
+    ATan: (_vm, [x1 = 0, y1 = 0, x2 = 0, y2 = 0]) => sciAngle(toSigned(x2) - toSigned(x1), toSigned(y2) - toSigned(y1)),
+    SinMult: (_vm, [angle = 0, n = 0]) => fromInt(Math.round(Math.sin(rad(angle)) * toSigned(n))),
+    CosMult: (_vm, [angle = 0, n = 0]) => fromInt(Math.round(Math.cos(rad(angle)) * toSigned(n))),
+    SinDiv: (_vm, [angle = 0, n = 0]) => {
+        const s = Math.sin(rad(angle));
+        return s === 0 ? 0 : fromInt(Math.round(toSigned(n) / s));
+    },
+    CosDiv: (_vm, [angle = 0, n = 0]) => {
+        const c = Math.cos(rad(angle));
+        return c === 0 ? 0 : fromInt(Math.round(toSigned(n) / c));
+    },
+    GetTime: (vm, [mode = 0]) => {
+        // All modes follow vm.clock so headless runs see time pass consistently.
+        const now = new Date(bootDate + vm.clock());
+        switch (mode) {
+            case 0: return Math.floor((vm.clock() * 60) / 1000) & 0xffff; // ticks (1/60 s)
+            case 1: return ((now.getHours() % 12) << 12) | (now.getMinutes() << 6) | now.getSeconds();
+            case 2: return (now.getHours() << 11) | (now.getMinutes() << 5) | (now.getSeconds() >> 1);
+            default: return ((now.getFullYear() - 1980) << 9) | ((now.getMonth() + 1) << 5) | now.getDate();
+        }
+    },
+    Platform: (_vm, [op = 0]) => (op === 0 ? 1 /* DOS */ : op === 2 ? 2 /* 256 colours */ : 0),
+};
+const rad = (deg) => (toSigned(deg) * Math.PI) / 180;
+/** SCI angles: 0 = north (up), clockwise, 0..359. */
+function sciAngle(dx, dy) {
+    const deg = (Math.atan2(dx, -dy) * 180) / Math.PI;
+    return Math.round((deg + 360) % 360);
+}

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

@@ -0,0 +1,91 @@
+import { ResourceType } from "../../resource/types.ts";
+import type { KernelFn } from "../vm.ts";
+import { NULL, bool, fromInt, toSigned } from "../value.ts";
+
+/** Script, object and resource management. */
+export const coreKernels: Record<string, KernelFn> = {
+  // Resource loading is eager in this engine, so these only need to answer sensibly.
+  Load: (_vm, [, number = 0]) => number,
+  Unload: () => 0,
+  Lock: () => 0,
+  Purge: () => 0,
+  ResCheck: (vm, [type = 0, number = 0]) => bool(vm.resources.has({ type: (type & 0x7f) as ResourceType, number })),
+
+  ScriptID: (vm, [script = 0, index = 0]) => {
+    if (!vm.resources.has({ type: ResourceType.Script, number: script })) return NULL;
+    return vm.exportAddress(script, index);
+  },
+  // Unloads the script (see Vm.disposeScript) and returns its optional second argument:
+  // scripts use it to hand a value back from code that's about to be unloaded (SRDialog
+  // returns the chosen save id this way).
+  DisposeScript: (vm, args) => {
+    vm.disposeScript(args[0]! & 0xffff);
+    return args.length >= 2 ? args[1] : undefined;
+  },
+
+  Clone: (vm, [obj = 0]) => vm.memory.clone(vm.object(obj)).address,
+  DisposeClone: (vm, [obj = 0]) => {
+    const o = vm.memory.object(obj);
+    if (o) vm.memory.disposeClone(o);
+  },
+  RespondsTo: (vm, [obj = 0, selector = 0]) => {
+    const o = vm.memory.object(obj);
+    return bool(!!o && vm.respondsTo(o, selector));
+  },
+};
+
+let seed = 0x1234;
+const bootDate = Date.now();
+
+/** Maths, time and the host platform. */
+export const mathKernels: Record<string, KernelFn> = {
+  Random: (_vm, args) => {
+    if (args.length === 1) {
+      seed = args[0]!; // seed the generator
+      return 0;
+    }
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+    if (args.length < 2) return (seed >> 8) & 0xffff;
+    const lo = toSigned(args[0]!), hi = toSigned(args[1]!);
+    return fromInt(lo + ((seed >> 8) % (hi - lo + 1)));
+  },
+  Abs: (_vm, [n = 0]) => fromInt(Math.abs(toSigned(n))),
+  Sqrt: (_vm, [n = 0]) => Math.floor(Math.sqrt(Math.abs(toSigned(n)))),
+  GetAngle: (_vm, [x1 = 0, y1 = 0, x2 = 0, y2 = 0]) => sciAngle(toSigned(x2) - toSigned(x1), toSigned(y2) - toSigned(y1)),
+  GetDistance: (_vm, [x1 = 0, y1 = 0, x2 = 0, y2 = 0, perspective = 0]) => {
+    const dx = toSigned(x2) - toSigned(x1);
+    let dy = toSigned(y2) - toSigned(y1);
+    if (perspective) dy = Math.trunc((dy * 3) / 2);
+    return Math.round(Math.sqrt(dx * dx + dy * dy)) & 0xffff;
+  },
+  ATan: (_vm, [x1 = 0, y1 = 0, x2 = 0, y2 = 0]) => sciAngle(toSigned(x2) - toSigned(x1), toSigned(y2) - toSigned(y1)),
+  SinMult: (_vm, [angle = 0, n = 0]) => fromInt(Math.round(Math.sin(rad(angle)) * toSigned(n))),
+  CosMult: (_vm, [angle = 0, n = 0]) => fromInt(Math.round(Math.cos(rad(angle)) * toSigned(n))),
+  SinDiv: (_vm, [angle = 0, n = 0]) => {
+    const s = Math.sin(rad(angle));
+    return s === 0 ? 0 : fromInt(Math.round(toSigned(n) / s));
+  },
+  CosDiv: (_vm, [angle = 0, n = 0]) => {
+    const c = Math.cos(rad(angle));
+    return c === 0 ? 0 : fromInt(Math.round(toSigned(n) / c));
+  },
+  GetTime: (vm, [mode = 0]) => {
+    // All modes follow vm.clock so headless runs see time pass consistently.
+    const now = new Date(bootDate + vm.clock());
+    switch (mode) {
+      case 0: return Math.floor((vm.clock() * 60) / 1000) & 0xffff; // ticks (1/60 s)
+      case 1: return ((now.getHours() % 12) << 12) | (now.getMinutes() << 6) | now.getSeconds();
+      case 2: return (now.getHours() << 11) | (now.getMinutes() << 5) | (now.getSeconds() >> 1);
+      default: return ((now.getFullYear() - 1980) << 9) | ((now.getMonth() + 1) << 5) | now.getDate();
+    }
+  },
+  Platform: (_vm, [op = 0]) => (op === 0 ? 1 /* DOS */ : op === 2 ? 2 /* 256 colours */ : 0),
+};
+
+const rad = (deg: number) => (toSigned(deg) * Math.PI) / 180;
+
+/** SCI angles: 0 = north (up), clockwise, 0..359. */
+function sciAngle(dx: number, dy: number): number {
+  const deg = (Math.atan2(dx, -dy) * 180) / Math.PI;
+  return Math.round((deg + 360) % 360);
+}

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

@@ -0,0 +1,141 @@
+import type { Cel } from "../../gfx/cel.ts";
+import { type Palette } from "../../gfx/palette.ts";
+import { type Pic } from "../../gfx/pic.ts";
+import { type View } from "../../gfx/view.ts";
+import { type KernelFn, type Vm } from "../vm.ts";
+import { type Value } from "../value.ts";
+export declare const SCREEN_WIDTH = 320;
+export declare const SCREEN_HEIGHT = 200;
+/**
+ * SCI32 graphics model: the scripts create Plane objects (layers with a rect, a background
+ * pic or colour, and a priority) and register View-like objects as screen items in a plane.
+ * Each FrameOut composes planes by priority, then items within a plane by priority.
+ * The kernel only remembers *which* objects are registered; their current state (x, y,
+ * view, loop, cel...) is read from the objects' properties at compose time.
+ */
+export declare class Graphics {
+    private readonly vm;
+    readonly planes: Set<number>;
+    readonly items: Set<number>;
+    frames: number;
+    private readonly views;
+    private readonly pics;
+    readonly basePalette: Palette;
+    /** Called on every FrameOut with the composed frame. */
+    onFrame?: (frame: Frame) => void;
+    /** Drops parsed views and pictures (their resources were replaced). */
+    forgetResources(): void;
+    constructor(vm: Vm);
+    /**
+     * View numbers are unsigned (SCI32's system views live at 64xxx), but scripts store them
+     * in signed properties; only 0xFFFF (-1) means "no view".
+     */
+    view(n: number): View | undefined;
+    pic(n: number): Pic | undefined;
+    cel(viewNo: number, loopNo: number, celNo: number): {
+        cel: Cel;
+        mirror: boolean;
+    } | undefined;
+    /** Reads a numeric property (signed), 0 if absent. */
+    prop(obj: Value, name: string): number;
+    /** Palette built from every palette submitted so far (base, scripts, pics, views). */
+    private source;
+    /** Picture each plane last submitted, and view each item last submitted. */
+    private readonly planePictures;
+    private readonly itemViews;
+    /** The palette after PalVary/PalCycle (before fades), as of the last frame. */
+    currentPalette: Palette;
+    /** Active show-style transitions, by plane. */
+    readonly transitions: Map<number, Transition>;
+    /** The mouse cursor: a view cel drawn on top at the mouse position (its origin = hotspot). */
+    cursor: {
+        view: number;
+        loop: number;
+        cel: number;
+        visible: boolean;
+        x: number;
+        y: number;
+    };
+    /** Palette range affected by fade show styles (SetPalStyleRange). */
+    styleRange: {
+        from: number;
+        to: number;
+    };
+    lastFrame: Frame | undefined;
+    get sourcePalette(): Palette | undefined;
+    set sourcePalette(pal: Palette | undefined);
+    submitPalette(pal: Palette | undefined): void;
+    /** Forgets submitted palettes (restart/restore); they're resubmitted as things are drawn. */
+    resetPalette(): void;
+    /**
+     * Where a view item's cel lands, in its plane's coordinates. Scripts scale cels for
+     * perspective (the hero shrinks with distance) and to stretch UI backgrounds (dialog boxes)
+     * to fit their contents.
+     */
+    viewRect(item: Value): {
+        cel: Cel;
+        mirror: boolean;
+        sx: number;
+        sy: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | undefined;
+    /**
+     * Composes the current frame in three phases, because remap colours (shadows) depend on
+     * the final palette: collect what each plane draws (submitting palettes as pictures and
+     * views change, like the original), apply palette effects, then blit.
+     */
+    compose(): Frame;
+}
+type Clip = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+export interface Frame {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+    palette: Palette;
+    /** Set during wipes/dissolves, which mix two differently-coloured images: RGB per pixel. */
+    rgb?: Uint8Array;
+}
+/** SCI32 show styles (SetShowStyle): how a plane's new content appears. */
+export declare const ShowStyle: {
+    readonly None: 0;
+    readonly HShutterOut: 1;
+    readonly HShutterIn: 2;
+    readonly VShutterOut: 3;
+    readonly VShutterIn: 4;
+    readonly WipeLeft: 5;
+    readonly WipeRight: 6;
+    readonly WipeUp: 7;
+    readonly WipeDown: 8;
+    readonly IrisOut: 9;
+    readonly IrisIn: 10;
+    readonly DissolveNoMorph: 11;
+    readonly Dissolve: 12;
+    readonly FadeOut: 13;
+    readonly FadeIn: 14;
+};
+interface Transition {
+    style: number;
+    start: number;
+    duration: number;
+    rect: Clip;
+    /** The screen as it was when the transition started (RGB), for wipes and dissolves. */
+    from: Uint8Array | undefined;
+}
+/** Converts an indexed frame to RGB. */
+export declare function frameRgb(f: Frame): Uint8Array;
+/** View cel anchor point, relative to the cel's top-left. */
+export declare function celOrigin(cel: Cel, mirror?: boolean): {
+    x: number;
+    y: number;
+};
+export declare const graphics: (vm: Vm) => Graphics;
+export declare const graphicsKernels: Record<string, KernelFn>;
+export {};