sci2-ts 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+versions follow [Semantic Versioning](https://semver.org/), and the entries are generated
+from commit messages ([Conventional Commits](https://www.conventionalcommits.org/)).
+
+## [0.2.1] - 2026-10-01
+
+### Fixed
+
+- **tools:** Publish as sci2-ts
+
+## [0.2.0] - 2026-10-01
+
+### Added
+
+- **tools:** An art tool for PNGs exported from a paint program (pnpm art)
+- **tools:** Sci-ts as a package, with the sci-ts command
+- **tools:** Publish sci-ts to npm
+
+### Fixed
+
+- **viewer:** Play games without an AdLib bank or a SoundFont
+- **viewer:** A neutral sample text in the font preview
+
+### Changed
+
+- **game:** Sherlock moves to its own repository, sci-sherlock
+
+### Documentation
+
+- A game in its own repository, and the art tool
+- The README shows the tools, and the package is on npm
+
+## [0.1.0] - 2026-10-01
+
+### Added
+
+- SCI2 engine, content compiler, viewer and tools
+- **sci:** Resource archive, vocab and font writers
+- **tools:** Build games from nothing with pnpm game build
+- **sci:** Script compiler
+- **sci:** Global declarations and computed selectors
+- **lib:** The class library
+- **game:** Hello on the class library
+- **lib:** Talkers, portraits, conversations, flags and cutscenes
+- **tools:** YAML and Yarn rooms for the class library, and the editor for our games
+- **game:** Hello's road as a YAML room with someone to talk to
+- **sci:** Write sound resources, SOL clips and sound effects
+- **sci:** Switchto, @[buf i], selectors as values, and warnings for unknown sends
+- **tools:** Music and effects, new games, a static site, and editing scripts live
+- **game:** Music for hello, and a lantern that chimes
+
+### Changed
+
+- **tools:** Games/hello in the script language
+
+### Documentation
+
+- README, how SCI works, the plan and the Sherlock Holmes teaser
+- Making a game, and milestone 1 done
+- The script language, and milestone 2 done
+- The class library, and milestone 3 done
+- Rooms as YAML and Yarn, and milestone 4 done
+- Building a game from nothing, sound, the site and the tooling
+
+### Maintenance
+
+- Workspace, typecheck, tests and CI
+- Build every game, and publish the site to GitHub Pages by hand
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Lüder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# sci-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An engine for Sierra's SCI2 adventure games, written from scratch in TypeScript, and the
+tools to make new games with it: scripts in SCI's own Lisp-like language on a class library
+of our own, rooms written as YAML and [Yarn](https://docs.yarnspinner.dev), a live editor,
+and writers for every kind of resource.
+
+![A conversation in games/hello: the traveller's portrait beside his line](docs/screenshots/conversation-portrait.png)
+
+It runs in the browser and in Node. It was built by making one game, *Quest for Glory IV:
+Shadows of Darkness* (CD), play from its title screen on, and it now builds games that need
+nothing from Sierra: `games/hello` here, and a Sherlock Holmes teaser in progress.
+
+> **No game data here.** This repository contains no files, scripts, art, text or music from
+> any Sierra game, and none are needed to build, test or use it. To play a Sierra game, point
+> the tools at your own copy. Sierra, Quest for Glory and other names are trademarks of their
+> owners and are used only to say what the software works with.
+
+## Make a game
+
+```sh
+mkdir night-walk && cd night-walk
+npm init -y && npm install --save-dev sci2-ts
+npx sci-ts new .          # a room in YAML and Yarn, a hero, placeholder art
+npx sci-ts play           # build it and play it in the browser
+npx sci-ts edit           # the live editor for its rooms
+```
+
+A game is a folder: scripts (`scripts/<n>.sc`), rooms as data (`rooms/<n>.room.yaml` and
+`.yarn`), message files, music (MIDI files), sound effects (WAV files), and art drawn in code
+or exported from a paint program. `sci-ts build` turns it into the `RESOURCE.MAP` and
+`RESOURCE.000` an SCI interpreter opens. See [docs/games.md](docs/games.md).
+
+```lisp
+(instance lantern of Prop
+  (properties noun N_LANTERN view 100 x 160 y 172 cycleSpeed 12)
+
+  ;; It chimes when touched, then says its line.
+  (method (doVerb verb)
+    (if (== verb V_DO) (sfx number: 50 play:))
+    (super doVerb: verb)))
+```
+
+![games/hello: the hero on the hill, looking at the moon](docs/screenshots/hello.png)
+
+| | |
+|---|---|
+| [docs/games.md](docs/games.md) | a game's folder, the build, the `sci-ts` command and the package's imports |
+| [docs/language.md](docs/language.md) | the script language |
+| [docs/library.md](docs/library.md) | the class library: rooms, actors, walking, talking, conversations, flags, sound |
+| [docs/rooms.md](docs/rooms.md) | rooms as YAML and Yarn: features, exits, characters, topic menus, cutscenes |
+| [docs/art.md](docs/art.md) | art from a paint program: the manifest, the palette, the checks |
+
+## The tools
+
+**The player** plays a game in the page: saved games, a link to any room
+(`play.html#room/2`), music through a SoundFont or an emulated AdLib card.
+
+![A topic menu: talking to the traveller](docs/screenshots/conversation-menu.png)
+
+**The live editor** shows a room's YAML and Yarn, or its script, next to the running game.
+Saving (or a pause in typing) rebuilds the game and walks into the room again; errors are
+marked on their line. Outlines name the features, exits, props and walkable floor; in Move
+mode things are dragged into place and floors painted with a brush, as edits to the YAML.
+
+![The editor with a room written as YAML](docs/screenshots/editor-yaml.png)
+
+![The editor with a room written as a script](docs/screenshots/editor-script.png)
+
+**The resource viewer** lists every resource with a thumbnail and the name the game's
+scripts give it, searchable, with a player for sounds.
+
+![The resource viewer: the hero's walking loops](docs/screenshots/resource-viewer.png)
+
+**The explorer** maps a game's rooms and how they connect, its classes and objects, and
+inspects a running game.
+
+![The explorer's room map](docs/screenshots/explorer.png)
+
+**On the command line:** `sci-ts build`, `play`, `edit`, `new`, `site` (the game and its
+docs as a static site) and `art` (check and build exported art). The compiler warns about
+sends no class defines; `editors/vscode` highlights the language in VS Code.
+
+## Inside
+
+| | |
+|---|---|
+| `packages/sci` | the engine: resources, the SCI2 virtual machine and its kernel, graphics, text, motion, sound, saves; readers and byte-exact writers for every resource; the script compiler and assembler |
+| `packages/content` | the room compiler: YAML and Yarn to scripts and messages |
+| `lib` | the class library, in the script language |
+| `apps/viewer` | the player, editor, resource viewer and explorer |
+| `tools` | the `sci-ts` command, the game build, the art tool, and tools for reading SCI2 games |
+| `games/hello` | the example game |
+
+How SCI works, as far as we found out by running a game: [docs/sci](docs/sci/README.md).
+
+## Developing sci-ts
+
+```sh
+pnpm install
+pnpm check                 # typecheck and tests; no game files needed
+pnpm game build games/hello
+SCI_GAME=out/games/hello pnpm viewer
+```
+
+With an SCI2 game of your own in `original/` (or `SCI_GAME=<dir>`), `pnpm viewer` opens it,
+and `pnpm res`, `pnpm asm`, `pnpm msg` and `pnpm play` read, disassemble and run it.
+
+See [docs/plan.md](docs/plan.md) for where this is going and [CONTRIBUTING.md](CONTRIBUTING.md)
+for how to help. Changes are in [CHANGELOG.md](CHANGELOG.md), generated from commit messages.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/apps/viewer/editor.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Room Editor</title>
+    <link rel="stylesheet" href="/src/editor.css" />
+  </head>
+  <body>
+    <main class="editor">
+      <section class="source">
+        <header>
+          <label>Mod <select id="mod"></select></label>
+          <label>Room <select id="room"></select></label>
+          <span class="spacer"></span>
+          <label class="auto" title="Rebuild a moment after you stop typing"><input id="auto" type="checkbox" checked /> live</label>
+          <button id="save" type="button" title="Save and rebuild (⌘S / Ctrl+S)">Save ⌘S</button>
+        </header>
+        <nav id="tabs"></nav>
+        <div class="code" id="code"></div>
+        <div id="problems" hidden></div>
+      </section>
+      <section class="game">
+        <div class="stage"><div class="screen" id="screen-box"><canvas id="screen" width="320" height="200"></canvas></div></div>
+        <div class="bar">
+          <span id="status">Loading…</span>
+          <span class="spacer"></span>
+          <span class="modes" id="modes" role="radiogroup" aria-label="What the mouse does on the game">
+            <button type="button" data-mode="play" title="Clicks go to the game">Play</button>
+            <button type="button" data-mode="move" title="Drag features, exits, props, the hero's points and floor corners; Alt-click a corner to remove it">Move</button>
+            <button type="button" data-mode="floor" title="Paint the walkable floor's outline">Draw floor</button>
+            <button type="button" data-mode="obstacle" title="Paint an obstacle the hero walks around">Draw obstacle</button>
+          </span>
+          <label title="Outline features, exits, sprites and walk areas"><input id="outlines" type="checkbox" checked /> Outlines</label>
+          <span class="legend" id="legend"></span>
+          <button id="restart" type="button" title="Back to the moment before entering the room, then in again">Restart scene</button>
+          <button id="sound" type="button">Sound off</button>
+        </div>
+      </section>
+    </main>
+    <script type="module" src="/src/editor.ts"></script>
+  </body>
+</html>

package/apps/viewer/explore.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>SCI Explorer</title>
+    <link rel="stylesheet" href="/src/explore/explore.css" />
+  </head>
+  <body>
+    <header>
+      <strong>SCI Explorer</strong>
+      <nav>
+        <a href="#/map" data-tab="map">Room map</a>
+        <a href="#/classes" data-tab="classes">Classes</a>
+        <a href="#/live" data-tab="live">Live</a>
+        <a href="/index.html">Resources</a>
+        <a href="/play.html">Play</a>
+      </nav>
+      <input id="search" type="search" placeholder="Jump to room, class or object…" list="search-options" autocomplete="off" />
+      <datalist id="search-options"></datalist>
+      <span id="status"></span>
+    </header>
+    <main id="stage"></main>
+    <aside id="inspector"><p class="meta">Select a room or class.</p></aside>
+    <script type="module" src="/src/explore/explore.ts"></script>
+  </body>
+</html>

package/apps/viewer/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>SCI Resources</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <aside>
+      <select id="type"></select>
+      <input id="search" type="search" placeholder="Search: number, name, description  ( / )" autocomplete="off" spellcheck="false" />
+      <div class="keys" id="index-status">Indexing the scripts…</div>
+      <label class="opt"><input type="checkbox" id="aspect" checked /> 4:3 aspect</label>
+      <div class="keys">↑↓ resources · ←→ type · PgUp/PgDn · Home/End · / search</div>
+      <ul id="list"></ul>
+    </aside>
+    <main>
+      <h1 id="title">Pick a resource</h1>
+      <div id="uses"></div>
+      <div id="view"></div>
+      <details><summary>Hex</summary><pre id="hex"></pre></details>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/apps/viewer/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@sci-ts/viewer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/lint": "^6.9.7",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/theme-one-dark": "^6.1.3",
+    "@codemirror/view": "^6.43.13",
+    "@sci-ts/sci": "workspace:*",
+    "codemirror": "^6.0.2",
+    "cytoscape": "^3.34.3",
+    "spessasynth_lib": "^4.3.14",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "sirv": "^3.0.2",
+    "vite": "^8.3.1"
+  }
+}

package/apps/viewer/play.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>SCI Player</title>
+    <link rel="stylesheet" href="/src/play.css" />
+  </head>
+  <body>
+    <main>
+      <canvas id="screen" width="320" height="200"></canvas>
+      <div class="bar">
+        <div id="status">Loading game files…</div>
+        <details id="mods">
+          <summary>Mods</summary>
+          <div id="mod-list"></div>
+          <button id="mods-apply" type="button">Apply (restarts the game)</button>
+        </details>
+        <button id="export-saves" type="button" title="Download every saved game as JSON (for tools/explore.ts loadsaves:)">Export saves</button>
+        <button id="music" type="button">Music</button>
+      </div>
+      <pre id="error" hidden></pre>
+    </main>
+    <script type="module" src="/src/play.ts"></script>
+  </body>
+</html>

package/apps/viewer/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "vite";
+export interface SciGameOptions {
+    /** The built game's folder (RESOURCE.MAP, RESOURCE.000...), served as /game/. */
+    game: string;
+    /** Built mods (one folder each), served as /game/MODS/<name> and listed at /__mods. */
+    mods?: string;
+    /** SoundFonts for music, served as /soundfonts/ (GeneralUser-GS.sf2 is the one used). */
+    soundfonts?: string;
+    /** The live editor's routes (/__editor): edits and rebuilds the game being served. */
+    editor?: boolean;
+}
+/**
+ * A Vite plugin that serves an SCI game to pages using the player (`sci-ts/viewer`): the
+ * game's files under /game/ (Range requests too), directory listings at /__list, and
+ * optionally mods, SoundFonts and the editor's routes. Development only; a built site
+ * carries the game itself (see `sci-ts site`).
+ */
+export declare function sciGame(options: SciGameOptions): Plugin;

package/apps/viewer/plugin.js

@@ -0,0 +1,75 @@
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+const EDITOR_SERVER = resolve(import.meta.dirname, "../../tools/editor-server.ts");
+/**
+ * A Vite plugin that serves an SCI game to pages using the player (`sci-ts/viewer`): the
+ * game's files under /game/ (Range requests too), directory listings at /__list, and
+ * optionally mods, SoundFonts and the editor's routes. Development only; a built site
+ * carries the game itself (see `sci-ts site`).
+ */
+export function sciGame(options) {
+    const game = resolve(options.game);
+    const mods = options.mods && resolve(options.mods);
+    return {
+        name: "sci-game",
+        // Pages outside this repository import the player's sources from it.
+        config: () => ({ server: { fs: { allow: [resolve(import.meta.dirname, "../.."), process.cwd()] } } }),
+        async configureServer(server) {
+            const sirv = (await import("sirv")).default;
+            // Before /game: mods look like a MODS folder inside the game, as patch directories.
+            if (mods) {
+                server.middlewares.use("/game/MODS", sirv(mods, { dev: true }));
+                server.middlewares.use("/__mods", async (_req, res) => {
+                    const entries = await readdir(mods, { withFileTypes: true }).catch(() => []);
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify(entries.filter((e) => e.isDirectory()).map((e) => e.name).sort()));
+                });
+            }
+            // A file that isn't there is a 404, not the page (Vite's fallback for unknown paths):
+            // the player asks for files a game may not have (RESOURCE.SFX, the SoundFont).
+            const notFound = (_req, res) => ((res.statusCode = 404), res.end());
+            server.middlewares.use("/game", sirv(game, { dev: true }));
+            server.middlewares.use("/game", notFound);
+            if (options.soundfonts)
+                server.middlewares.use("/soundfonts", sirv(resolve(options.soundfonts), { dev: true }));
+            server.middlewares.use("/soundfonts", notFound);
+            if (options.editor) {
+                // Loaded through Vite so edits to the tools take effect; the game stays loaded in it.
+                const editor = () => server.ssrLoadModule(EDITOR_SERVER);
+                server.middlewares.use("/__editor", async (req, res) => {
+                    const url = new URL(req.url ?? "", "http://x");
+                    const json = (status, body) => {
+                        res.statusCode = status;
+                        res.setHeader("content-type", "application/json");
+                        res.end(JSON.stringify(body));
+                    };
+                    try {
+                        const mod = url.searchParams.get("mod") ?? "";
+                        if (req.method === "GET" && url.pathname === "/mods")
+                            return json(200, (await editor()).listMods());
+                        if (req.method === "GET" && url.pathname === "/files")
+                            return json(200, (await editor()).readFiles(mod));
+                        if (req.method === "POST" && url.pathname === "/save") {
+                            let body = "";
+                            for await (const chunk of req)
+                                body += chunk;
+                            const { files } = JSON.parse(body);
+                            return json(200, await (await editor()).save(mod, files));
+                        }
+                        json(404, { error: "unknown editor route" });
+                    }
+                    catch (e) {
+                        json(500, { error: e.message });
+                    }
+                });
+            }
+            server.middlewares.use("/__list", async (req, res) => {
+                const dir = new URL(req.url ?? "", "http://x").searchParams.get("dir") ?? "";
+                const base = mods && (dir === "MODS" || dir.startsWith("MODS/")) ? resolve(mods, dir.slice(5)) : resolve(game, dir);
+                const names = await readdir(base).catch(() => []);
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify(names));
+            });
+        },
+    };
+}

package/apps/viewer/plugin.ts

@@ -0,0 +1,84 @@
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { Plugin } from "vite";
+
+export interface SciGameOptions {
+  /** The built game's folder (RESOURCE.MAP, RESOURCE.000...), served as /game/. */
+  game: string;
+  /** Built mods (one folder each), served as /game/MODS/<name> and listed at /__mods. */
+  mods?: string;
+  /** SoundFonts for music, served as /soundfonts/ (GeneralUser-GS.sf2 is the one used). */
+  soundfonts?: string;
+  /** The live editor's routes (/__editor): edits and rebuilds the game being served. */
+  editor?: boolean;
+}
+
+const EDITOR_SERVER = resolve(import.meta.dirname, "../../tools/editor-server.ts");
+
+/**
+ * A Vite plugin that serves an SCI game to pages using the player (`sci-ts/viewer`): the
+ * game's files under /game/ (Range requests too), directory listings at /__list, and
+ * optionally mods, SoundFonts and the editor's routes. Development only; a built site
+ * carries the game itself (see `sci-ts site`).
+ */
+export function sciGame(options: SciGameOptions): Plugin {
+  const game = resolve(options.game);
+  const mods = options.mods && resolve(options.mods);
+  return {
+    name: "sci-game",
+    // Pages outside this repository import the player's sources from it.
+    config: () => ({ server: { fs: { allow: [resolve(import.meta.dirname, "../.."), process.cwd()] } } }),
+    async configureServer(server) {
+      const sirv = (await import("sirv")).default;
+      // Before /game: mods look like a MODS folder inside the game, as patch directories.
+      if (mods) {
+        server.middlewares.use("/game/MODS", sirv(mods, { dev: true }));
+        server.middlewares.use("/__mods", async (_req, res) => {
+          const entries = await readdir(mods, { withFileTypes: true }).catch(() => []);
+          res.setHeader("content-type", "application/json");
+          res.end(JSON.stringify(entries.filter((e) => e.isDirectory()).map((e) => e.name).sort()));
+        });
+      }
+      // A file that isn't there is a 404, not the page (Vite's fallback for unknown paths):
+      // the player asks for files a game may not have (RESOURCE.SFX, the SoundFont).
+      const notFound = (_req: unknown, res: { statusCode: number; end: () => void }) => ((res.statusCode = 404), res.end());
+      server.middlewares.use("/game", sirv(game, { dev: true }));
+      server.middlewares.use("/game", notFound);
+      if (options.soundfonts) server.middlewares.use("/soundfonts", sirv(resolve(options.soundfonts), { dev: true }));
+      server.middlewares.use("/soundfonts", notFound);
+      if (options.editor) {
+        // Loaded through Vite so edits to the tools take effect; the game stays loaded in it.
+        const editor = () => server.ssrLoadModule(EDITOR_SERVER) as Promise<typeof import("../../tools/editor-server.ts")>;
+        server.middlewares.use("/__editor", async (req, res) => {
+          const url = new URL(req.url ?? "", "http://x");
+          const json = (status: number, body: unknown) => {
+            res.statusCode = status;
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify(body));
+          };
+          try {
+            const mod = url.searchParams.get("mod") ?? "";
+            if (req.method === "GET" && url.pathname === "/mods") return json(200, (await editor()).listMods());
+            if (req.method === "GET" && url.pathname === "/files") return json(200, (await editor()).readFiles(mod));
+            if (req.method === "POST" && url.pathname === "/save") {
+              let body = "";
+              for await (const chunk of req) body += chunk;
+              const { files } = JSON.parse(body) as { files: Record<string, string> };
+              return json(200, await (await editor()).save(mod, files));
+            }
+            json(404, { error: "unknown editor route" });
+          } catch (e) {
+            json(500, { error: (e as Error).message });
+          }
+        });
+      }
+      server.middlewares.use("/__list", async (req, res) => {
+        const dir = new URL(req.url ?? "", "http://x").searchParams.get("dir") ?? "";
+        const base = mods && (dir === "MODS" || dir.startsWith("MODS/")) ? resolve(mods, dir.slice(5)) : resolve(game, dir);
+        const names = await readdir(base).catch(() => []);
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(names));
+      });
+    },
+  };
+}

package/apps/viewer/src/adlib.d.ts

@@ -0,0 +1,20 @@
+import { type AdLibBank, type MidiOutput } from "../../../packages/sci/src/index.ts";
+/**
+ * AdLib music: Sierra's driver runs here and batches OPL register writes to the chip
+ * emulator in an AudioWorklet (flushed once per microtask, i.e. per burst of MIDI events).
+ */
+export declare class AdLibOutput implements MidiOutput {
+    private readonly node;
+    private readonly bank;
+    private driver;
+    private queue;
+    private flushScheduled;
+    private constructor();
+    static create(ctx: AudioContext, bank: AdLibBank): Promise<AdLibOutput>;
+    private newDriver;
+    /** Silences the chip and starts from a clean driver (used when switching devices). */
+    reset(): void;
+    send(bytes: number[]): void;
+    claimVoices(channel: number, count: number): void;
+    setMasterVolume(volume: number): void;
+}

package/apps/viewer/src/adlib.js

@@ -0,0 +1,55 @@
+import { AdLibDriver } from "../../../packages/sci/src/index.js";
+import workletUrl from "./opl-worklet.ts?worker&url";
+/**
+ * AdLib music: Sierra's driver runs here and batches OPL register writes to the chip
+ * emulator in an AudioWorklet (flushed once per microtask, i.e. per burst of MIDI events).
+ */
+export class AdLibOutput {
+    node;
+    bank;
+    driver;
+    queue = [];
+    flushScheduled = false;
+    constructor(node, bank) {
+        this.node = node;
+        this.bank = bank;
+        this.driver = this.newDriver();
+    }
+    static async create(ctx, bank) {
+        await ctx.audioWorklet.addModule(workletUrl);
+        const node = new AudioWorkletNode(ctx, "opl2", { outputChannelCount: [2] });
+        node.connect(ctx.destination);
+        return new AdLibOutput(node, bank);
+    }
+    newDriver() {
+        const chip = {
+            write: (reg, value) => {
+                this.queue.push(reg, value);
+                if (!this.flushScheduled) {
+                    this.flushScheduled = true;
+                    queueMicrotask(() => {
+                        this.flushScheduled = false;
+                        this.node.port.postMessage(this.queue);
+                        this.queue = [];
+                    });
+                }
+            },
+        };
+        return new AdLibDriver(chip, this.bank);
+    }
+    /** Silences the chip and starts from a clean driver (used when switching devices). */
+    reset() {
+        this.queue = [];
+        this.node.port.postMessage("reset");
+        this.driver = this.newDriver();
+    }
+    send(bytes) {
+        this.driver.send(bytes);
+    }
+    claimVoices(channel, count) {
+        this.driver.claimVoices(channel, count);
+    }
+    setMasterVolume(volume) {
+        this.driver.setMasterVolume(volume);
+    }
+}