@lewismoten/gamemaker-sandbox-engine 3.1.0 → 3.3.0

package/README.md

@@ -2,7 +2,13 @@
 
 `@lewismoten/gamemaker-sandbox-engine` runs RSD Game-Maker games from their original DOS files in a browser. It is the same TypeScript engine used by the Game-Maker: Sandbox Edition web player. The package includes its audio worklet and TypeScript declarations; it does not include games or the site's editor and catalog.
 
-Build a tarball from this repository with `cd web/packages/engine && npm pack`. The package has not been published to the npm registry. Install the tarball with `npm install ./lewismoten-gamemaker-sandbox-engine-3.1.0.tgz`.
+Install from your configured npm registry:
+
+```sh
+npm install @lewismoten/gamemaker-sandbox-engine
+```
+
+If your registry requires authentication or a scope mapping, configure npm using that registry's instructions.
 
 Pass the files from one game's DOS directory to `GameFiles`. Names are case insensitive and use DOS 8.3 names. `GameFiles.mainGame()` finds a `.GAM` file. Keep the original file names and bytes; the game refers to its other files by name.
 
@@ -51,16 +57,94 @@ play.addEventListener('click', async () => {
 
 `Machine` owns the screen, keyboard and audio. Call `machine.destroy()` when play finishes or the containing page closes. `runGame` accepts `RunOptions` for callbacks, joystick input, playback and the optional DOS player appearance. The game may write saves or high scores into `GameFiles`; use `files.onChange` to persist those bytes. The package targets modern browsers and ES modules.
 
+`machine.screen.dosCropped` is observer metadata for PLAYGAME’s CropScreen state: true during level rendering and its fades, false for function-key screens and after a level. `sceneNumber` identifies the last rendered level. These fields do not change rendering or game timing.
+
+## Read a game file in Node.js
+
+The format modules need no browser. This reads a `.GAM` file from the original CD (run it from the repository root) and lists its scene titles:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { parseGame } from '@lewismoten/gamemaker-sandbox-engine/formats/game';
+import { fromCp437 } from '@lewismoten/gamemaker-sandbox-engine/text/cp437';
+
+const game = parseGame(readFileSync('cd/gameware/peach/peach.gam'));
+console.log(`${game.scenes.length} scenes: ${game.scenes.slice(2, 4).map((s) => fromCp437(s.desc)).join(' and ')}`);
+// prints: 20 scenes: Grasslands 1 and Grasslands 2
+```
+
+A test (`web/test/readmeExamples.test.ts`) runs this block in Node against the built package and compares what it prints with the `// prints:` line.
+
+Parsed descriptions are DOS byte strings, not Unicode. For a game name outside DOS use
+`gameTitle(game)` from `formats/game`: it decodes CP437 and trims decorative menu frames.
+For other DOS labels use `fromCp437`; for DOS text-file bytes use `cp437Text` from `text/cp437`,
+which retains ASCII controls so the caller can handle line endings and DOS EOF. Neither API
+is for already decoded Unicode, JSON, HTML or UTF-8 text. Keep the parsed fields and original
+bytes for DOS rendering and round trips; convert only at the presentation boundary.
+
+## Native player screens
+
+The package includes the complete DOS player front end. The example above shows
+its title images or animation and menu before play. The menu offers instructions,
+storyline, credits, top scores and quitting; during play the native function keys
+open help, inventory, load and save screens. Include the files named by the game's
+`.GAM` file, along with any saved games or high scores you want to keep.
+
+`runGame` uses these screens by default. For a direct play test, pass
+`{ skipTitle: true }` to start a new game at its initial scene link; its normal
+ending screens and menu still follow when play ends. `RunOptions.player` accepts
+DOS player customizations for words, colors, frames, positions, timing and function
+keys. `gmHelp` optionally supplies Game-Maker's own help text before the game's
+instructions. See the exported `RunOptions` type for these settings and callbacks.
+
+Observe actual life loss with `onLifeLost`, including the last life, or the final
+result and score with `onPlayEnd`. Recorded demo playback does not emit either
+callback. Persist `GameFiles.onChange` to retain save files and high scores between
+visits.
+
 The source is MIT licensed; see `LICENSE` and `NOTICE.md` for credits.
 
-## Publishing
+Hosts can call `machine.audio.setSoundCard(enabled)` to change the optional sound-card
+output during play. Removing it pauses FM and cuts digital effects without stopping the
+PC speaker. Restoring it resumes the loaded song, or starts the latest song requested
+while absent. `soundCardEnabled` reports the current card state; returning the card
+preserves a disabled music preference. An explicit song stop remains stopped. Normal DOS-compatible startup
+behavior is unchanged unless the host opts into live card control.
+Set the audio card state before `runGame` and call the same method for later switches;
+effects then use the PC speaker while the card is absent. `RunOptions.noSoundCard` retains
+the original startup-only detection, including its fixed speaker-only choice for that run.
+
+## Incremental picture decoding
+
+`formats/jpeg` exports `decodePartialJpeg(bytes)` for baseline and progressive Huffman JPEGs.
+Pass only the bytes received so far. `shown` marks pixels with completed luminance/DC blocks;
+`pixels` holds grayscale or RGB data. A partial first progressive scan reveals only its
+completed blocks; later scans retain the previous coefficients until each MCU is complete.
+Restart markers preserve already decoded MCUs. `scans` counts fully delimited scans and
+`complete` reports an end-of-image marker. The decoder does not invent data for unread blocks.
+
+`RunOptions.onLifeLost` observes each player death, including the final life.
+`onPlayEnd(score, how, gained)` reports `won`, `lost`, or `quit` once a play ends.
+Neither callback runs during demo or walkthrough playback. These callbacks do not
+change DOS gameplay or the game files.
+
+`Machine.onItem` is an observer hook: `showGraphic` calls it as each picture, cartoon, text page or slide list begins (the walkthrough player's item marks). It never changes timing or behavior.
+
+## Subpath exports
+
+Everything is also importable from its own subpath, for example `import { parseBlocks } from '@lewismoten/gamemaker-sandbox-engine/formats/blocks'`, so a Node script or a bundler can take one module without the player:
+
+- `formats/*`: readers and writers for the DOS files: `blocks`, `character`, `cmf`, `cmfEdit`, `cmfPreview`, `cmfSong`, `fli`, `fliFrames`, `fliLimits`, `game`, `gif`, `gifProgressive`, `graphicScripts`, `highscore`, `jpeg`, `map`, `monster`, `palette`, `recording`, `sound`, `voc`, and `binary` (byte helpers).
+- `engine/*`: the PLAYGAME port: `machine`, `game`, `world`, `scene`, `scroll`, `render`, `showGraphic`, `menus`, `monsters`, `character`, `keys`, `funcKeys`, `touch`, `recorder`, `playGain`, `playerLook`, `slowPc`.
+- `audio/*`: OPL2 and CMF playback: `opl`, `cmfPlayer`, `cmfLoad`, `engine`, `mix`, `output`, `context`.
+- `gfx/*`: `screen`, `font8x8`, `cp437Glyphs`, `colorVision` (color-vision simulation matrices); `text/cp437`.
+- `input/*`: `keyboard`, `scancodes`, `chords`, `deskMouse`.
+- `core/gameFiles` (`GameFiles`) and `player/*` (`fileExtensions`, `patchRules`, `patchTable`).
+
+## Supported environments
+
+Playback needs a browser with canvas, Web Audio and keyboard events (the `Machine` class owns them). The file-format, decoding and simulation modules have no DOM dependency and also run in Node.js 22.12 or later, which is the version the package declares in `engines`. It ships as ES modules with TypeScript declarations.
 
-The [release workflow](../../../.github/workflows/publish-engine.yml) publishes this package to
-GitHub Packages when an `engine-v<version>` tag is pushed. The tagged commit must be on
-`master`, and `<version>` must exactly match this package's `package.json` (for example,
-`engine-v3.1.0`). Merge the package changes to `master` before pushing the tag.
+## Developing
 
-The workflow uses GitHub's `GITHUB_TOKEN` with package write permission. It checks the source,
-builds the package, and publishes it to GitHub Packages. No package is published by ordinary
-branch pushes. Publishing to npm is a separate, manual decision; this workflow does not use
-an npm token.
+This package's source lives in [the project's repository](https://github.com/lewismoten/GameMaker-SandboxEdition), in `web/packages/engine`. The folder holds all its source in `src/`, plus its build configuration, license and notices. It can be copied outside the repository: run `npm install` and `npm run verify` there to build and test a packed consumer. Inside the repository, run `npm ci` at the root, then `npm run build -w @lewismoten/gamemaker-sandbox-engine`. Run `npm pack` in the package folder to inspect a local distribution. Tarballs are build artifacts and should not be committed. The [monorepo guide](https://github.com/lewismoten/GameMaker-SandboxEdition/blob/master/docs/monorepo.md) covers the workspace layout, and the [package release guide](https://github.com/lewismoten/GameMaker-SandboxEdition/blob/master/docs/package-releases.md) covers publishing.

package/dist/assets/{music.worklet-NqOeNo6T.js → music.worklet-aD2x7RRM.js}

@@ -1,4 +1,4 @@
-const g = [0.5, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 12, 12, 15, 15], M = [0, 9, 12, 13.875, 15, 16.125, 16.875, 17.625, 18, 18.75, 19.125, 19.5, 19.875, 20.25, 20.625, 21], v = [0, 0.5, 0.25, 1], O = 49716, l = 96, D = [0, 1, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 16, 17, 18, 19, 20, 21];
+const g = [0.5, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 12, 12, 15, 15], M = [0, 9, 12, 13.875, 15, 16.125, 16.875, 17.625, 18, 18.75, 19.125, 19.5, 19.875, 20.25, 20.625, 21], v = [0, 0.5, 0.25, 1], O = 49716, c = 96, D = [0, 1, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 16, 17, 18, 19, 20, 21];
 class b {
   am = !1;
   vib = !1;
@@ -17,7 +17,7 @@ class b {
   phase = 0;
   // cycles
   stage = 0;
-  envDb = l;
+  envDb = c;
   out = 0;
   prevOut = 0;
   keyOn() {
@@ -60,11 +60,11 @@ class b {
       default:
         return;
     }
-    this.envDb >= l && (this.envDb = l, this.stage = 0);
+    this.envDb >= c && (this.envDb = c, this.stage = 0);
   }
   decayDbPerSecond(t, s) {
     const e = this.rate(t, s);
-    return e === 0 ? 0 : l / (39.28 / Math.pow(2, (e - 4) / 4));
+    return e === 0 ? 0 : c / (39.28 / Math.pow(2, (e - 4) / 4));
   }
   /** Waveform value at phase (cycles): 0 sine, 1 half sine, 2 absolute sine, 3 pulse (quarter) sine. */
   wave01(t) {
@@ -119,7 +119,7 @@ class P {
     for (let t = 0; t < 256; t++) this.write(t, 0);
     for (const t of this.channels)
       for (const s of t.ops)
-        s.stage = 0, s.envDb = l;
+        s.stage = 0, s.envDb = c;
   }
   read(t) {
     return this.regs[t & 255];
@@ -198,14 +198,14 @@ class P {
       const r = this.noise & 1 ? 1 : -1;
       let n = 0;
       const f = this.rhythm ? 6 : 9;
-      for (let c = 0; c < f; c++) n += this.channelSample(this.channels[c], e, i, a);
+      for (let l = 0; l < f; l++) n += this.channelSample(this.channels[l], e, i, a);
       this.rhythm && (n += this.rhythmSample(e, i, a, r)), t[h] += n * s;
     }
   }
   /** Linear amplitude from the summed attenuation: envelope + TL (0.75 dB steps) + KSL + tremolo. */
   opLevel(t, s, e) {
     const h = s.envDb + s.tl * 0.75 + t.kslDb(s) + (s.am ? e : 0);
-    return h >= l ? 0 : Math.pow(10, -h / 20);
+    return h >= c ? 0 : Math.pow(10, -h / 20);
   }
   advance(t, s, e, h) {
     s.phase += t.freq * s.mult * (s.vib ? h : 1) * e, s.phase > 1e6 && (s.phase -= Math.floor(s.phase)), s.stepEnvelope(e, t.rof(this.noteSel));
@@ -227,18 +227,18 @@ class P {
   rhythmSample(t, s, e, h) {
     const [i, o, a] = [this.channels[6], this.channels[7], this.channels[8]];
     let r = this.channelSample(i, t, s, e) * 2;
-    const [n, f] = o.ops, [c, p] = a.ops;
+    const [n, f] = o.ops, [l, p] = a.ops;
     for (const [w, k] of [
       [o, n],
       [o, f],
-      [a, c],
+      [a, l],
       [a, p]
     ])
       this.advance(w, k, t, e);
-    return n.stage !== 0 && (r += h * 0.5 * this.opLevel(o, n, s) * (n.wave01(n.phase) > 0 ? 1 : 0.6) * 2), f.stage !== 0 && (r += (f.wave01(f.phase) * 0.6 + h * 0.4) * this.opLevel(o, f, s) * 2), c.stage !== 0 && (r += c.wave01(c.phase) * this.opLevel(a, c, s) * 2), p.stage !== 0 && (r += (p.wave01(p.phase) > 0 ? 0.5 : -0.5) * (h > 0 ? 1 : 0.7) * this.opLevel(a, p, s) * 2), r;
+    return n.stage !== 0 && (r += h * 0.5 * this.opLevel(o, n, s) * (n.wave01(n.phase) > 0 ? 1 : 0.6) * 2), f.stage !== 0 && (r += (f.wave01(f.phase) * 0.6 + h * 0.4) * this.opLevel(o, f, s) * 2), l.stage !== 0 && (r += l.wave01(l.phase) * this.opLevel(a, l, s) * 2), p.stage !== 0 && (r += (p.wave01(p.phase) > 0 ? 0.5 : -0.5) * (h > 0 ? 1 : 0.7) * this.opLevel(a, p, s) * 2), r;
   }
 }
-const y = [0, 1, 2, 8, 9, 10, 16, 17, 18], T = 1193180 / Math.floor(65535 / 8), u = { 11: 16, 12: 8, 13: 4, 14: 2, 15: 1 }, d = {
+const y = [0, 1, 2, 8, 9, 10, 16, 17, 18], T = 1193180 / Math.floor(65535 / 8), d = { 11: 16, 12: 8, 13: 4, 14: 2, 15: 1 }, u = {
   11: { ch: 6, ops: ["mod", "car"] },
   12: { ch: 7, ops: ["car"] },
   13: { ch: 8, ops: ["mod"] },
@@ -362,8 +362,8 @@ class K {
     this.programs[t] = s;
     const e = this.instruments[s];
     if (e) {
-      if (this.rhythm && d[t]) {
-        const h = d[t];
+      if (this.rhythm && u[t]) {
+        const h = u[t];
         h.ops.length === 2 ? this.loadVoice(h.ch, e) : this.loadOperator(y[h.ch] + (h.ops[0] === "car" ? 3 : 0), e, 0);
         return;
       }
@@ -405,7 +405,7 @@ class K {
     const e = this.instruments[this.programs[t]];
     if (!e) return;
     let h, i;
-    const o = this.rhythm ? d[t] : void 0;
+    const o = this.rhythm ? u[t] : void 0;
     if (o && o.ops.length === 1)
       h = y[o.ch] + (o.ops[0] === "car" ? 3 : 0), i = e[2];
     else {
@@ -417,17 +417,17 @@ class K {
     this.opl.write(64 + h, i & 192 | a);
   }
   noteOn(t, s, e = 127) {
-    if (this.applyVelocity(t, e), this.rhythm && u[t]) {
-      const h = u[t];
-      this.setPitch(d[t].ch, s, !1), this.rhythmKeys &= ~h, this.opl.write(189, 224 | this.rhythmKeys), this.rhythmKeys |= h, this.opl.write(189, 224 | this.rhythmKeys), this.notes[t] = s;
+    if (this.applyVelocity(t, e), this.rhythm && d[t]) {
+      const h = d[t];
+      this.setPitch(u[t].ch, s, !1), this.rhythmKeys &= ~h, this.opl.write(189, 224 | this.rhythmKeys), this.rhythmKeys |= h, this.opl.write(189, 224 | this.rhythmKeys), this.notes[t] = s;
       return;
     }
     t >= this.melodyVoices() || (this.notes[t] >= 0 && this.opl.write(176 + t, this.opl.read(176 + t) & -33), this.setPitch(t, s, !0), this.notes[t] = s);
   }
   noteOff(t, s) {
     if (this.notes[t] === s) {
-      if (this.notes[t] = -1, this.rhythm && u[t]) {
-        this.rhythmKeys &= ~u[t], this.opl.write(189, 224 | this.rhythmKeys);
+      if (this.notes[t] = -1, this.rhythm && d[t]) {
+        this.rhythmKeys &= ~d[t], this.opl.write(189, 224 | this.rhythmKeys);
         return;
       }
       t < this.melodyVoices() && this.opl.write(176 + t, this.opl.read(176 + t) & -33);
@@ -438,13 +438,15 @@ class L extends AudioWorkletProcessor {
   opl = new P(sampleRate);
   player = new K(this.opl);
   untilTick = 0;
+  /** Samples left of a hold: the chip renders, the sequencer does not move. */
+  held = 0;
   paused = !1;
   ended = !1;
   samplesPerTick = sampleRate / T;
   constructor() {
     super(), this.port.onmessage = (t) => {
       const s = t.data;
-      s.type === "load" ? (this.player.load(s.music, s.instruments), this.untilTick = 0) : s.type === "stop" ? this.player.stop() : s.type === "pause" ? this.paused = s.paused : s.type === "end" && (this.ended = !0);
+      s.type === "load" ? (this.player.load(s.music, s.instruments), this.untilTick = 0, this.held = 0) : s.type === "hold" ? this.held += s.ms * sampleRate / 1e3 : s.type === "stop" ? this.player.stop() : s.type === "pause" ? this.paused = s.paused : s.type === "end" && (this.ended = !0);
     };
   }
   process(t, s) {
@@ -453,7 +455,7 @@ class L extends AudioWorkletProcessor {
     if (!e || this.paused) return !0;
     let h = 0;
     for (; h < e.length; ) {
-      this.untilTick <= 0 && (this.player.tick(), this.untilTick += this.samplesPerTick);
+      this.untilTick <= 0 && (this.held > 0 ? this.held -= this.samplesPerTick : this.player.tick(), this.untilTick += this.samplesPerTick);
       const i = Math.min(e.length - h, Math.ceil(this.untilTick));
       this.opl.render(e.subarray(h, h + i)), this.untilTick -= i, h += i;
     }

package/dist/audio/cmfLoad.js

@@ -0,0 +1,10 @@
+import { isCmf as r, parseCmf as o, CMF_GAMEMAKER_CLOCK as m } from "../formats/cmf.js";
+function c(i) {
+  if (!i || !r(i) || (i[36] | i[37] << 8) * 16 & 32768) return;
+  const n = o(i);
+  if (n.clockTicks === m)
+    return { music: n.music, instruments: n.instruments };
+}
+export {
+  c as loadSong
+};

package/dist/audio/cmfPlayer.js

@@ -0,0 +1,201 @@
+import { MODULATOR_OFFSET as r } from "./opl.js";
+const m = 1193180 / Math.floor(65535 / 8), f = { 11: 16, 12: 8, 13: 4, 14: 2, 15: 1 }, l = {
+  11: { ch: 6, ops: ["mod", "car"] },
+  12: { ch: 7, ops: ["car"] },
+  13: { ch: 8, ops: ["mod"] },
+  14: { ch: 8, ops: ["car"] },
+  15: { ch: 7, ops: ["mod"] }
+};
+class n {
+  opl;
+  music = new Uint8Array(0);
+  instruments = [];
+  // PlayIt's statics: read position in the music block, ticks left before the next
+  // event, and the running status (channel and 8 = note off / 9 = note on).
+  offset = 0;
+  wait = 0;
+  channel = 0;
+  funct = 8;
+  rhythm = !1;
+  rhythmKeys = 0;
+  // Note sounding on each MIDI channel (-1 none), so a note off only releases its own note.
+  notes = new Int16Array(16).fill(-1);
+  programs = new Uint8Array(16);
+  playing = !1;
+  constructor(t) {
+    this.opl = t, this.init();
+  }
+  /** sbfd_init: enable waveform select, melody mode (0xBD = deep tremolo and vibrato, rhythm off). */
+  init() {
+    this.opl.reset(), this.opl.write(1, 32), this.opl.write(8, 0), this.opl.write(189, 192);
+  }
+  load(t, s) {
+    this.stop(), this.init(), this.music = t, this.instruments = s, this.rhythm = !1, this.rhythmKeys = 0;
+    for (let i = 0; i < 16; i++) this.programChange(i, i);
+    this.offset = 0, this.playing = t.length > 0;
+  }
+  /** sbfd_music_off + rewind. */
+  stop() {
+    this.allNotesOff(), this.offset = 0, this.playing = !1;
+  }
+  allNotesOff() {
+    for (let t = 0; t < 9; t++) this.opl.write(176 + t, this.opl.read(176 + t) & -33);
+    this.rhythmKeys = 0, this.opl.write(189, 192 | (this.rhythm ? 32 : 0)), this.notes.fill(-1);
+  }
+  /**
+   * *(APOS) in SBMUSIC.C. PlayIt read sbmusic+offset with no bounds check, so past the end of
+   * the farmalloc'd music block it read whatever heap memory followed. Every CMF ends with the
+   * FF 2F 00 end marker, which restarts the song before the read gets there; only a truncated
+   * file runs off the end, and for that the port reads 0xFF, which takes the same path as the
+   * end marker (sbfd_music_off, offset = 0).
+   */
+  byte(t) {
+    return this.music[t] ?? 255;
+  }
+  /**
+   * getpaws() in SBMUSIC.C: reads a MIDI variable length number (7 bits per byte, high bit
+   * set on every byte but the last), with no limit on the number of bytes:
+   *   do { offset++; value = (value << 7) | ((c=*(APOS)) & 0x07F); } while (c & 0x80);
+   * value is an unsigned long, so bits shifted past 32 are lost (>>> 0). The one difference:
+   * the loop stops at the end of the data, where DOS read on into unknown memory.
+   */
+  getPaws() {
+    let t = this.byte(this.offset);
+    if (t & 128) {
+      t &= 127;
+      let s;
+      do
+        this.offset++, s = this.byte(this.offset), t = (t << 7 | s & 127) >>> 0;
+      while (s & 128 && this.offset < this.music.length);
+    }
+    return this.offset++, t;
+  }
+  /** One timer tick of PlayIt(). */
+  tick() {
+    if (!this.playing) return;
+    this.offset === 0 && (this.wait = 1, this.getPaws()), this.wait--;
+    let t = 0;
+    for (; this.wait <= 0 && t++ < 1e5; ) {
+      const s = this.byte(this.offset);
+      switch (s & 240) {
+        case 144:
+          this.channel = s & 15, this.offset++, this.funct = 9;
+          break;
+        case 128:
+          this.channel = s & 15, this.offset++, this.funct = 8;
+          break;
+      }
+      const i = this.byte(this.offset);
+      if (i < 128) {
+        const h = this.byte(this.offset + 1);
+        this.funct === 8 || h === 0 ? this.noteOff(this.channel, i) : this.noteOn(this.channel, i, h), this.offset += 2;
+      } else
+        switch (i & 240) {
+          case 160:
+            this.offset += 3;
+            break;
+          case 176:
+            this.byte(this.offset + 1) === 103 && this.setMode(this.byte(this.offset + 2)), this.offset += 3;
+            break;
+          case 192:
+            this.programChange(i & 15, this.byte(this.offset + 1)), this.offset += 2;
+            break;
+          case 208:
+            this.offset += 2;
+            break;
+          case 224:
+            this.offset += 3;
+            break;
+          case 240:
+            i === 247 || i === 240 ? (this.offset++, this.offset += this.getPaws(), this.offset++) : (this.allNotesOff(), this.offset = 0);
+            break;
+          default:
+            this.allNotesOff(), this.offset = 0;
+        }
+      this.wait = this.getPaws();
+    }
+  }
+  /** sbfd_setmode: switch melody/rhythm mode and reload the drum channels' instruments. */
+  setMode(t) {
+    if (this.allNotesOff(), this.rhythm = t !== 0, this.opl.write(189, 192 | (this.rhythm ? 32 : 0)), this.rhythm) for (const s of [11, 12, 13, 14, 15]) this.programChange(s, this.programs[s]);
+  }
+  programChange(t, s) {
+    this.programs[t] = s;
+    const i = this.instruments[s];
+    if (i) {
+      if (this.rhythm && l[t]) {
+        const h = l[t];
+        h.ops.length === 2 ? this.loadVoice(h.ch, i) : this.loadOperator(r[h.ch] + (h.ops[0] === "car" ? 3 : 0), i, 0);
+        return;
+      }
+      t < this.melodyVoices() && this.loadVoice(t, i);
+    }
+  }
+  melodyVoices() {
+    return this.rhythm ? 6 : 9;
+  }
+  /**
+   * Writes one operator from a 16 byte SBI instrument record, whose bytes alternate
+   * modulator/carrier: 0/1 AM-VIB-EG-KSR-MULT, 2/3 KSL-TL, 4/5 AR-DR, 6/7 SL-RR, 8/9 waveform.
+   */
+  loadOperator(t, s, i) {
+    this.opl.write(32 + t, s[0 + i]), this.opl.write(64 + t, s[2 + i]), this.opl.write(96 + t, s[4 + i]), this.opl.write(128 + t, s[6 + i]), this.opl.write(224 + t, s[8 + i]);
+  }
+  loadVoice(t, s) {
+    const i = r[t];
+    this.loadOperator(i, s, 0), this.loadOperator(i + 3, s, 1), this.opl.write(192 + t, s[10]);
+  }
+  /**
+   * MIDI note -> OPL frequency: picks the lowest block (octave) whose F-number fits in 10 bits,
+   * which keeps the most pitch resolution (Hz = fnum * 49716 / 2^(20 - block)).
+   */
+  setPitch(t, s, i) {
+    const h = 440 * Math.pow(2, (s - 69) / 12);
+    let o, e = 0;
+    for (o = 0; o < 8 && (e = Math.round(h * Math.pow(2, 20 - o) / 49716), !(e < 1024)); o++)
+      ;
+    o = Math.min(o, 7), e = Math.min(e, 1023), this.opl.write(160 + t, e & 255), this.opl.write(176 + t, (i ? 32 : 0) | o << 2 | e >> 8);
+  }
+  /**
+   * SBFMDRV's loudness by velocity: it scales the instrument's carrier level (TL is an
+   * attenuation, 0 loudest .. 63 silent) and keeps the key-scaling bits:
+   * TL = 63 - floor((velocity + 128) * (63 - instrumentTL) / 256). So velocity 127 plays
+   * the instrument almost as loud as written and velocity 1 about half as loud in TL steps.
+   */
+  applyVelocity(t, s) {
+    const i = this.instruments[this.programs[t]];
+    if (!i) return;
+    let h, o;
+    const e = this.rhythm ? l[t] : void 0;
+    if (e && e.ops.length === 1)
+      h = r[e.ch] + (e.ops[0] === "car" ? 3 : 0), o = i[2];
+    else {
+      const a = e ? e.ch : t;
+      if (!e && a >= this.melodyVoices()) return;
+      h = r[a] + 3, o = i[3];
+    }
+    const p = 63 - Math.floor((Math.min(127, s) + 128) * (63 - (o & 63)) / 256);
+    this.opl.write(64 + h, o & 192 | p);
+  }
+  noteOn(t, s, i = 127) {
+    if (this.applyVelocity(t, i), this.rhythm && f[t]) {
+      const h = f[t];
+      this.setPitch(l[t].ch, s, !1), this.rhythmKeys &= ~h, this.opl.write(189, 224 | this.rhythmKeys), this.rhythmKeys |= h, this.opl.write(189, 224 | this.rhythmKeys), this.notes[t] = s;
+      return;
+    }
+    t >= this.melodyVoices() || (this.notes[t] >= 0 && this.opl.write(176 + t, this.opl.read(176 + t) & -33), this.setPitch(t, s, !0), this.notes[t] = s);
+  }
+  noteOff(t, s) {
+    if (this.notes[t] === s) {
+      if (this.notes[t] = -1, this.rhythm && f[t]) {
+        this.rhythmKeys &= ~f[t], this.opl.write(189, 224 | this.rhythmKeys);
+        return;
+      }
+      t < this.melodyVoices() && this.opl.write(176 + t, this.opl.read(176 + t) & -33);
+    }
+  }
+}
+export {
+  n as CmfPlayer,
+  m as TICK_RATE
+};

package/dist/audio/context.js

@@ -0,0 +1,75 @@
+let e, i = !1;
+const r = /* @__PURE__ */ new Set(), l = ["pointerup", "touchend", "click", "keydown", "mousedown"];
+function v() {
+  if (!(typeof window > "u"))
+    return window.AudioContext ?? window.webkitAudioContext;
+}
+function u() {
+  try {
+    const t = navigator.audioSession;
+    t && t.type !== "playback" && (t.type = "playback");
+  } catch {
+  }
+}
+function w() {
+  if (e) return e;
+  const t = v();
+  if (t) {
+    try {
+      u(), e = new t({ latencyHint: "interactive" });
+    } catch {
+      return;
+    }
+    return d(), e.addEventListener("statechange", () => {
+      e && e.state !== "running" && i && document.visibilityState === "visible" && e.resume().catch(() => {
+      });
+    }), navigator.userActivation?.isActive && s(), e;
+  }
+}
+function y() {
+  return i && !!e && e.state === "running";
+}
+function k(t) {
+  return r.add(t), () => r.delete(t);
+}
+function s() {
+  const t = w();
+  if (!t) return;
+  u();
+  const a = !i;
+  if (i = !0, t.state !== "running" && t.resume().catch(() => {
+  }), a)
+    try {
+      const n = t.createBufferSource();
+      n.buffer = t.createBuffer(1, 1, t.sampleRate), n.connect(t.destination), n.start(0);
+    } catch {
+    }
+  for (const n of [...r])
+    try {
+      n();
+    } catch (f) {
+      console.warn(f);
+    }
+}
+let c = !1;
+function p(t) {
+  t.type === "keydown" && (t.key === "Shift" || t.key === "Meta") || t.isTrusted && (y() || s());
+}
+function o() {
+  e && i && e.state !== "running" && document.visibilityState === "visible" && e.resume().catch(() => {
+  });
+}
+function d() {
+  if (!(c || typeof window > "u")) {
+    c = !0;
+    for (const t of l) window.addEventListener(t, p, { capture: !0, passive: !0 });
+    document.addEventListener("visibilitychange", o), window.addEventListener("pageshow", o), window.addEventListener("focus", o);
+  }
+}
+typeof window < "u" && d();
+export {
+  w as audioContext,
+  k as onSoundUnlocked,
+  y as soundUnlocked,
+  s as unlock
+};