@lewismoten/gamemaker-sandbox-engine 0.0.0-stage → 3.3.0

package/dist/text/cp437.js

@@ -0,0 +1,44 @@
+const r = "\0☺☻♥♦♣♠•◘○◙♂♀♪♫☼►◄↕‼¶§▬↨↑↓→←∟↔▲▼ !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~⌂ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■ ", c = /* @__PURE__ */ new Map();
+for (let t = 1; t < 256; t++) (t < 32 || t > 126) && c.set(r[t], t);
+for (const [t, o] of [
+  ["β", 225],
+  // β beta for ß
+  ["μ", 230],
+  // μ mu for µ
+  ["Ω", 234],
+  // Ω ohm for Ω
+  ["∑", 228],
+  // ∑ sum for Σ
+  ["ϕ", 237],
+  // ϕ for φ
+  ["∈", 238]
+  // ∈ for ε
+])
+  c.set(t, o);
+const l = { "–": "-", "—": "--", "‘": "'", "’": "'", "“": '"', "”": '"', "…": "...", "×": "x" };
+function C(t) {
+  let o = "";
+  for (const e of t) {
+    const n = c.get(e);
+    o += n !== void 0 ? String.fromCharCode(n) : l[e] ?? e;
+  }
+  return o;
+}
+const f = /* @__PURE__ */ new Map(), i = new TextDecoder("latin1");
+for (let t = 128; t < 160; t++) f.set(i.decode(Uint8Array.of(t)), t);
+function s(t) {
+  let o = "";
+  for (let e = 0; e < t.length; e++) {
+    const n = f.get(t[e]) ?? t.charCodeAt(e);
+    o += n < 256 ? r[n] : t[e];
+  }
+  return o;
+}
+function a(t) {
+  return i.decode(t).replace(/[^\x00-\x7f]/g, (o) => s(o));
+}
+export {
+  a as cp437Text,
+  s as fromCp437,
+  C as toCp437
+};

package/dist/types/audio/cmfLoad.d.ts

@@ -0,0 +1,7 @@
+interface LoadedSong {
+    music: Uint8Array;
+    /** The records load_file read; any past the end of the file are zeros here (DOS left whatever was in memory). */
+    instruments: Uint8Array[];
+}
+export declare function loadSong(bytes: Uint8Array | undefined): LoadedSong | undefined;
+export {};

package/dist/types/audio/cmfPlayer.d.ts

@@ -0,0 +1,69 @@
+import { Opl2 } from './opl.js';
+/**
+ * Timer ticks per second: 1193180 / (65535 / 8). PLAYGAME.C reprograms PIT channel 0 with
+ * divisor 65535/8 (8 times the normal 18.2 Hz), giving about 145.67 ticks per second.
+ */
+export declare const TICK_RATE: number;
+export declare class CmfPlayer {
+    private opl;
+    private music;
+    private instruments;
+    private offset;
+    private wait;
+    private channel;
+    private funct;
+    private rhythm;
+    private rhythmKeys;
+    private notes;
+    private programs;
+    playing: boolean;
+    constructor(opl: Opl2);
+    /** sbfd_init: enable waveform select, melody mode (0xBD = deep tremolo and vibrato, rhythm off). */
+    private init;
+    load(music: Uint8Array, instruments: Uint8Array[]): void;
+    /** sbfd_music_off + rewind. */
+    stop(): void;
+    private allNotesOff;
+    /**
+     * *(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).
+     */
+    private byte;
+    /**
+     * 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.
+     */
+    private getPaws;
+    /** One timer tick of PlayIt(). */
+    tick(): void;
+    /** sbfd_setmode: switch melody/rhythm mode and reload the drum channels' instruments. */
+    private setMode;
+    private programChange;
+    private melodyVoices;
+    /**
+     * 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.
+     */
+    private loadOperator;
+    private loadVoice;
+    /**
+     * 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)).
+     */
+    private setPitch;
+    /**
+     * 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.
+     */
+    private applyVelocity;
+    private noteOn;
+    private noteOff;
+}

package/dist/types/audio/context.d.ts

@@ -0,0 +1,12 @@
+/** The page's AudioContext (made on first use; undefined where there is no Web Audio). */
+export declare function audioContext(): AudioContext | undefined;
+/** True once a gesture has let the page's sound start (the context is running, or was). */
+export declare function soundUnlocked(): boolean;
+/** Calls `f` (inside the gesture's handler, so it may create and start nodes) each time sound unlocks. */
+export declare function onSoundUnlocked(f: () => void): () => void;
+/**
+ * Resumes the context; must run inside a user gesture's handler the first time (iOS).
+ * Called by the page's own gesture listeners; call it too from a handler that also starts
+ * a sound, before any await.
+ */
+export declare function unlock(): void;

package/dist/types/audio/engine.d.ts

@@ -0,0 +1,60 @@
+export declare class AudioEngine {
+    private ctx?;
+    private master?;
+    /** Music and effects each go through their own gain, set by the visitor's sound settings (mix.ts). */
+    private musicGain?;
+    private sfxGain?;
+    /** Music and effects of a game being played also pass the Games setting (setGame). */
+    private gameGain?;
+    private game;
+    private level;
+    private unmix?;
+    private music?;
+    private musicReady?;
+    private speaker?;
+    private voc?;
+    private vocCache;
+    musicEnabled: boolean;
+    soundEnabled: boolean;
+    private cardEnabled;
+    private requestedSong?;
+    private loadedSong?;
+    get soundCardEnabled(): boolean;
+    /** Optional live host control: card removal pauses FM and stops digital effects, leaving the PC speaker alone. */
+    setSoundCard(enabled: boolean): void;
+    /**
+     * Starts the sound. The first time, call it from a user gesture's handler (iOS: inside
+     * the touchend/click itself, before any await); the page's one AudioContext (context.ts)
+     * is resumed there.
+     */
+    resume(): Promise<void>;
+    /** Marks this engine as a game's: its sound also follows the Games setting (live). */
+    setGame(game: boolean): void;
+    /** A fixed trim (0 to 1) under the visitor's settings, for sound meant to sit quietly in the background. */
+    setLevel(level: number): void;
+    private gameLevel;
+    /** Where this engine's sound leaves it (for recording just this game's sound). */
+    get node(): AudioNode | undefined;
+    /**
+     * Stops everything and lets go of the page's context (it is shared, so it stays open);
+     * a later resume() starts afresh.
+     */
+    dispose(): void;
+    get context(): AudioContext | undefined;
+    private post;
+    /** PlaySong: returns false (silently, as the original did) for invalid songs. */
+    playSong(bytes: Uint8Array | undefined): Promise<boolean>;
+    /** Counts songs asked for, so one still waiting for the worklet doesn't start after a newer one (or a stop). */
+    private songs;
+    stopSong(): void;
+    /** The song stands still for `ms` (its notes keep sounding), then goes on from where it was: a slow PC's disk read. */
+    holdMusic(ms: number): void;
+    pauseMusic(paused: boolean): void;
+    /** DoSound's PC speaker path: one frequency per 1/145.6 s tick; 0 = silence. */
+    playSpeaker(freqs: ArrayLike<number>): void;
+    stopSpeaker(): void;
+    /** PlaySbVocFile: a new digital sound cuts off the previous one. */
+    playVoc(bytes: Uint8Array | undefined): boolean;
+    stopVoc(): void;
+    stopAll(): void;
+}

package/dist/types/audio/mix.d.ts

@@ -0,0 +1,14 @@
+export type Channel = 'music' | 'voice' | 'sfx' | 'games';
+export interface ChannelMix {
+    on: boolean;
+    /** 0 to 100. */
+    volume: number;
+}
+export type Mix = Record<Channel, ChannelMix>;
+export declare const CHANNELS: readonly Channel[];
+export declare const getMix: () => Mix;
+/** The gain (0 to 1) a channel plays at now: 0 when it is off. */
+export declare const channelGain: (c: Channel) => number;
+export declare function setChannel(c: Channel, change: Partial<ChannelMix>): void;
+/** Calls `f` whenever a setting changes; returns a function that stops it. */
+export declare function onMix(f: (m: Mix) => void): () => void;

package/dist/types/audio/music.worklet.d.ts

@@ -0,0 +1,22 @@
+export type MusicMessage = {
+    type: 'load';
+    music: Uint8Array;
+    instruments: Uint8Array[];
+} | {
+    type: 'stop';
+} | {
+    type: 'pause';
+    paused: boolean;
+}
+/**
+ * An emulated slow PC is reading the disk with the timer held (engine/slowPc.ts readHoldsMusic): PlayIt
+ * gets no interrupts for `ms`, so the song stands still while the FM chip keeps sounding its notes.
+ */
+ | {
+    type: 'hold';
+    ms: number;
+}
+/** The engine is done with this node (the page's context lives on): stop processing. */
+ | {
+    type: 'end';
+};

package/dist/types/audio/opl.d.ts

@@ -0,0 +1,37 @@
+export declare class Opl2 {
+    readonly sampleRate: number;
+    private channels;
+    private regs;
+    private waveSelect;
+    private noteSel;
+    private amDepth;
+    private vibDepth;
+    private rhythm;
+    private time;
+    private noise;
+    constructor(sampleRate: number);
+    reset(): void;
+    read(reg: number): number;
+    write(reg: number, value: number): void;
+    private rhythmKeys;
+    /**
+     * Register 0xBD: bit 7 tremolo depth, bit 6 vibrato depth, bit 5 rhythm mode, bits 0-4 the
+     * drum keys. In rhythm mode channels 6-8 become the bass drum (both operators of channel 6),
+     * hi-hat and snare (channel 7) and tom-tom and cymbal (channel 8).
+     */
+    private writeRhythm;
+    /** Renders mono samples into out (added to existing content). */
+    render(out: Float32Array, gain?: number): void;
+    /** Linear amplitude from the summed attenuation: envelope + TL (0.75 dB steps) + KSL + tremolo. */
+    private opLevel;
+    private advance;
+    private channelSample;
+    /**
+     * Approximates the five drums. The bass drum is a normal FM channel (at double level); the
+     * hi-hat, snare and cymbal mix operator tone with LFSR noise, and the tom-tom is a plain tone.
+     * The mixing weights are this port's approximation, not the chip's exact phase logic.
+     */
+    private rhythmSample;
+}
+/** Register offsets of the modulator for each FM channel (carrier = +3). */
+export declare const MODULATOR_OFFSET: number[];

package/dist/types/audio/output.d.ts

@@ -0,0 +1,13 @@
+export declare const getVolume: () => number;
+/** 0 (silent) to 1 (full). */
+export declare function setVolume(v: number): void;
+/** Where a context's sound should go: its destination, through the volume. */
+export declare function output(ctx: BaseAudioContext): AudioNode;
+type Tap = (ctx: BaseAudioContext, node: AudioNode) => void;
+/**
+ * Calls `f` for every context's line out, now and as new ones appear (for recording the
+ * sound). Like a capture card on the sound card's line out, a recording has the PC's sound
+ * whatever the speakers' volume knob is set to, even turned all the way down.
+ */
+export declare function tapOutputs(f: Tap): () => void;
+export {};

package/dist/types/core/gameFiles.d.ts

@@ -0,0 +1,49 @@
+/** Files of a game still on their way from the site (project/streamGame.ts). */
+export interface FileStream {
+    /** Resolves once these files are in, or known not to come; undefined when none is still coming. */
+    need(names: string[]): Promise<void> | undefined;
+    /** Fetches these next, without waiting for them. */
+    want(names: string[]): void;
+}
+export declare class GameFiles {
+    private files;
+    /** Notified after any change. */
+    onChange?: (name: string) => void;
+    /** Set while files are still arriving: the game waits for one it needs (engine/machine.ts, need). */
+    stream?: FileStream;
+    /** Asked before set or delete changes a file; throws to refuse (a game opened to look inside, editor/core/readOnly.ts). */
+    guard?: (name: string) => void;
+    constructor(entries?: Iterable<[string, Uint8Array]>);
+    get(name: string | undefined): Uint8Array | undefined;
+    has(name: string | undefined): boolean;
+    /** The stored name a reference opens (see cdName), or undefined when there is none. */
+    resolve(name: string | undefined): string | undefined;
+    set(name: string, bytes: Uint8Array): void;
+    /**
+     * A copy of these files to change freely. While files are still arriving here, the copy
+     * gets them too as it needs them (its own changes stay).
+     */
+    copy(): GameFiles;
+    /** Adds a file that arrived (not one the game wrote): onChange is not told, and a file already here stays. */
+    put(name: string, bytes: Uint8Array): void;
+    delete(name: string): void;
+    names(): string[];
+    entries(): [string, Uint8Array][];
+    byExtension(ext: string): string[];
+    get size(): number;
+    /** The .gam file to play: the one named like the folder, else the first. */
+    mainGame(preferred?: string): string | undefined;
+}
+/**
+ * File names as DOS saw them: lower case, without folders, and cut to 8.3. DOS dropped the
+ * extra letters silently, so games could name "nejillian.gif" and open NEJILLIA.GIF.
+ */
+export declare function normalize(name: string): string;
+/**
+ * The name a file got on the Game-Maker CD. Its ISO 9660 copy allowed only A-Z, 0-9 and _,
+ * so A-J.BKD, PARSEC-W.GIF and CAN'T.GIF are a_j.bkd, parsec_w.gif and can_t.gif there,
+ * while the games still name them the DOS way. A name not found as is is looked up this way.
+ */
+export declare function cdName(name: string): string;
+/** Files only meaningful to DOS. */
+export declare const IGNORED_FILE: RegExp;

package/dist/types/engine/character.d.ts

@@ -0,0 +1,30 @@
+import { type Frame } from '../formats/character.js';
+import { type World } from './world.js';
+/** Asks the player which inventory slot to drop; resolves -1 for Esc. */
+type DropPicker = () => Promise<number>;
+/**
+ * CHRFRAME with the original's out-of-range behavior: frame -1 read the 17 bytes
+ * before the sequence's first frame (the tail of the previous sequence record).
+ */
+export declare function currentFrame(w: World): Frame;
+/**
+ * MoveCharGrav: every GRAVSPEED ticks (w.tune), accelerate by one pixel a tick in each
+ * direction the block's grav bits name (1 up, 2 right, 4 down, 8 left), capped at
+ * MAXGRAV * 4. Returns true while there is any gravity momentum.
+ */
+export declare function moveCharGrav(w: World, reset?: boolean): boolean;
+/** HandleJStick: joystick directions/buttons can trigger sequences too. */
+export declare function handleJoystick(w: World, reset?: boolean): boolean;
+/** movechars: one game tick of character animation and movement. Returns true when dead. */
+export declare function moveChars(w: World, pickDrop: DropPicker): Promise<boolean>;
+/**
+ * Screen coordinates of the character's bottom block (nextx/nexty), the tail of
+ * movechars (PLAYGAME.C 2593-2601; the func-key return at 1643 is the same with
+ * scroll.nx 0). The strict < matches the C: column mx itself counts as MLEN blocks
+ * away, so nextx is 2000+ (row my likewise). chkScrnBounds keeps a walk from
+ * entering it, but a solid monster's push (C 2508) can put the character there;
+ * the C then draws it off screen and ChangeScroll scrolls hard toward it. The port
+ * keeps that. test/charScreenColumn.test.ts covers it, across the map wrap too.
+ */
+export declare function updateCharScreenPos(w: World): void;
+export {};

package/dist/types/engine/funcKeys.d.ts

@@ -0,0 +1,35 @@
+import type { Machine } from './machine.js';
+import type { Screen } from '../gfx/screen.js';
+import { type PlayerLook } from './playerLook.js';
+import { type World } from './world.js';
+/** What the status and drop screens read of a level: its palette, blocks, inventory and clock. */
+export type InventoryWorld = Pick<World, 'palette' | 'bg' | 'clock'> & {
+    ci: Pick<World['ci'], 'inv' | 'score' | 'meter' | 'hitpts' | 'lives'>;
+};
+/**
+ * F1: HelpFiles. XFERPLAY.EXE (PLAYGAME.C built with TRANSFER, the player of every transferred
+ * game) shows the game's instructions, or one red line; it never reads GMHELP.TXT. PLAYGAME.EXE,
+ * run from Game-Maker, first shows Game-Maker's own GMHELP.TXT (`gmHelp`) in a blue frame.
+ */
+export declare function helpScreen(m: Machine, w: World, instructions: string | undefined, gmHelp?: Uint8Array, look?: PlayerLook): Promise<void>;
+/** Display_Invent's page (F2). */
+export declare function drawStatus(screen: Screen, w: InventoryWorld, look: PlayerLook): void;
+/** F2: Display_Invent */
+export declare function statusScreen(m: Machine, w: World, look?: PlayerLook): Promise<void>;
+/** How many pages GMabout shows (two, as the DOS player does). */
+export declare const aboutPages: (look: PlayerLook) => number;
+/** One page of GMabout (0: the first, as F10 opens it), framed; returns the text color. */
+export declare function drawAbout(screen: Screen, palette: Uint8Array, look: PlayerLook, page?: number): number;
+/** F10: GMabout */
+export declare function aboutScreen(m: Machine, w: World, look?: PlayerLook): Promise<void>;
+/** DropBloc's picker screen, with the selection box on slot (j, k); returns the box's color. */
+export declare function drawDropPicker(screen: Screen, w: InventoryWorld, look: PlayerLook, j?: number, k?: number): number;
+/** DropBloc's picker: arrows choose a slot, Enter drops, Esc cancels (-1). */
+export declare function pickDropSlot(m: Machine, w: World, look?: PlayerLook): Promise<number>;
+/** The load or save heading and slot marks, drawn when the game has no load or save picture. */
+export declare function drawLoadHeading(screen: Screen, look: PlayerLook, cols: Uint8Array): void;
+export declare function drawSaveHeading(screen: Screen, look: PlayerLook, cols: Uint8Array): void;
+/** The ten slot names, in the load or save screen's color. */
+export declare function drawSaveSlots(screen: Screen, look: PlayerLook, pal: Uint8Array, names: string[], saving: boolean): number;
+/** SelectGameToLoad / SelectGameToSave: returns the slot (0..9) or -1. */
+export declare function pickSaveSlot(m: Machine, pal: Uint8Array, saving: boolean, look?: PlayerLook): Promise<number>;

package/dist/types/engine/game.d.ts

@@ -0,0 +1,57 @@
+import { Machine } from './machine.js';
+import { type Session, type SpeedSetting } from './scene.js';
+import { type PlayerAbout } from './playerLook.js';
+import type { PlayerPatches } from '../player/patchRules.js';
+import { type Game } from '../formats/game.js';
+export interface RunOptions {
+    /** Called when the player picks Quit; return true to show the menu again. */
+    onQuit?: () => Promise<boolean> | boolean;
+    speakerOnly?: boolean;
+    /** No Sound Blaster (PLAYGAME's SoundCard() found none): no songs, every sound on the PC speaker. */
+    noSoundCard?: boolean;
+    joystick?: Session['joystick'];
+    /** Play a .rec demo immediately instead of showing the menu. */
+    playback?: Uint8Array;
+    /** Start playing at once, recording the keys (for making a demo); the menu is skipped. */
+    record?: boolean;
+    /** Receives the game session as it starts (e.g. to read the recording so far). */
+    onSession?: (s: Session) => void;
+    /** Called every frame while a level is being played. */
+    onFrame?: Session['onFrame'];
+    /** Emulated PC speed (shared object: change slowPc at any time). */
+    speed?: SpeedSetting;
+    /**
+     * Play as PLAYGAME.EXE, Game-Maker's own player: F1 shows this file (GMHELP.TXT from
+     * Game-Maker's directory) before the game's instructions. Left out, the game plays as
+     * XFERPLAY.EXE, the stand-alone player every transferred game runs on, whose F1 shows only
+     * the instructions (PLAYGAME.C HelpFiles: the gmhelp.txt part is #ifndef TRANSFER).
+     */
+    gmHelp?: Uint8Array;
+    /**
+     * The project's DOS player customizations (dosPlayer/): XFERPLAY's words, colors, frames,
+     * positions, times and F-keys as its patched .EXE shows them. Left out, the CD's player.
+     */
+    player?: PlayerPatches;
+    /** An imported game's own player About page and first build (F10 shows them, read-only). */
+    playerAbout?: PlayerAbout;
+    /** A touch changed a map cell while the player played (never during a demo's playback). */
+    onTouched?: Session['onTouched'];
+    /** Play ended with this score (never during a demo's playback; see Session.onPlayEnd). */
+    onPlayEnd?: Session['onPlayEnd'];
+    /** A player lost a life, including game over; never reported during playback. */
+    onLifeLost?: Session['onLifeLost'];
+    /**
+     * The editor's Play Level test only (never a saved, exported or DOS game): skip the title, its
+     * song and the menu, and start play at once by scene 0's first link (which the test copy points
+     * at the picked level and spot, editor/editors/integrator/startAt.ts) with a new game's
+     * character, as the menu's Play would. When that play ends (won, lost or Esc), the usual end
+     * follows (the won or dead picture, the high scores) and then the menu, as after any play.
+     */
+    skipTitle?: boolean;
+}
+export declare function gameNameOf(gamFile: string): string;
+export declare function loadGameFile(m: Machine, gamFile: string): Game;
+/** Runs a game until the player quits. */
+export declare function runGame(m: Machine, gamFile: string, opts?: RunOptions): Promise<void>;
+/** play(curlink): from scene 0's link to the end. */
+export declare function play(s: Session, startLink: number): Promise<void>;

package/dist/types/engine/keys.d.ts

@@ -0,0 +1,17 @@
+import { type Frame, type Sequence } from '../formats/character.js';
+import { type World } from './world.js';
+export declare function chrSeq(w: World): Sequence;
+/** CHRFRAME. cframe can be -1 between sequences; the original then read stray memory. */
+export declare function chrFrame(w: World): Frame;
+/**
+ * SimKeyPress. A press starts the matching sequence only if the character isn't dying,
+ * the running sequence can be interrupted (not `ground`), the sequence still has uses
+ * (meter > 0) and is turned on (seqon, e.g. its inventory block is carried).
+ */
+export declare function simKeyPress(w: World, key: number): void;
+/** PushKey. The overflow handling is the port's; the C pushed without a bounds check. */
+export declare function pushKey(w: World): void;
+/** PopKey: drop `key` from the stack and resume what is under it, or idle when empty. */
+export declare function popKey(w: World, key: number): void;
+/** The key down and key stack reset at the end of StartSceneInits (also used after F-keys). */
+export declare function resetKeys(w: World): void;

package/dist/types/engine/machine.d.ts

@@ -0,0 +1,103 @@
+import { Screen } from '../gfx/screen.js';
+import { Keyboard, type TypedKey } from '../input/keyboard.js';
+import { AudioEngine } from '../audio/engine.js';
+import { GameFiles } from '../core/gameFiles.js';
+/** Thrown to unwind the game when the player is closed. */
+export declare class GameAborted extends Error {
+    constructor();
+}
+interface PointerState {
+    /** Screen coordinates (0..319, 0..199) of the last pointer position. */
+    x: number;
+    y: number;
+    clicks: number;
+}
+/** How a Machine is driven (the defaults are a live player's). */
+interface MachineOptions {
+    /**
+     * 'manual': no animation frame loop; whoever made the Machine calls presentFrame() for
+     * each frame, and now() is theirs too (a walkthrough steps the game on a clock of its own).
+     */
+    frames?: 'auto' | 'manual';
+    /** False: the pointer, the desk mouse and the keyboard never reach the game. */
+    input?: boolean;
+}
+export declare class Machine {
+    readonly screen: Screen;
+    readonly keyboard: Keyboard;
+    readonly audio: AudioEngine;
+    files: GameFiles;
+    readonly pointer: PointerState;
+    aborted: boolean;
+    /** Observer only (the walkthrough player's item marks): a picture, cartoon, text page or slide list is about to be shown. Never changes timing. */
+    onItem?: (kind: 'picture' | 'cartoon' | 'text' | 'slides', name: string) => void;
+    private frameWaiters;
+    private raf;
+    /** The ball mouse on the desk moves the pointer and clicks too. */
+    private offDeskMouse;
+    /** The engine was made here (not passed in): it goes with the Machine. */
+    private ownsAudio;
+    constructor(canvas: HTMLCanvasElement, files: GameFiles, audio?: AudioEngine, opts?: MachineOptions);
+    private listen;
+    /** The time in ms the game goes by (waits, fades, animations, the game clock). */
+    now(): number;
+    /** One display frame: the screen is shown (unless `show` is false) and everything waiting for a frame goes on. */
+    presentFrame(show?: boolean): void;
+    /** How many are waiting for the next frame (a stepped Machine's game is idle when one is). */
+    get frameWaiting(): number;
+    private toScreen;
+    private onPointer;
+    private onMove;
+    destroy(): void;
+    /** Told when the game waits for files still on their way (true) and when they are in. */
+    onLoading?: (loading: boolean) => void;
+    /**
+     * Waits for game files still on their way from the site (a hosted game starts before
+     * all its files are in, project/streamGame.ts); a short wait shows no cue. Names the
+     * game doesn't have, or that are in already, return at once.
+     */
+    need(...names: (string | undefined)[]): Promise<void>;
+    /** Fetches these game files next, if they are still on their way, without waiting. */
+    want(...names: (string | undefined)[]): void;
+    checkAbort(): void;
+    /** Waits for the next animation frame (the screen is presented every frame). */
+    frame(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    takeClick(): boolean;
+    /**
+     * PauseTimeKey: waits up to `seconds` (forever if omitted) for a key or click.
+     * Returns the key, a pseudo key for a click (ascii 1, as the C returned 1 for a mouse
+     * button; scan 28 is Enter's), or undefined on time out (the C returned FALSE).
+     */
+    pauseTimeKey(seconds?: number): Promise<TypedKey | undefined>;
+    private waitDepth;
+    private polledAt;
+    /**
+     * Runs `fn` as PLAYGAME code that read keys through GetKey (key waits, pictures,
+     * animations, text pages): while it runs, each frame hands the demo recorder the polls
+     * the DOS PC would have made meanwhile (keyPoll). Gameplay itself stole the keyboard
+     * interrupt and never called GetKey, so it does not count.
+     */
+    waiting<T>(fn: () => Promise<T>): Promise<T>;
+    private pollKeys;
+    /**
+     * Demo playback: called while a screen waits for a key with how many GetKey polls the
+     * DOS PC would have made meanwhile; returns recorded keys that become pending.
+     */
+    keyPoll?: (polls: number) => number[];
+    /** Demo playback: a key-reading screen ended; returns recorded keys it must have taken. */
+    keyPollEnd?: () => number[];
+    /** Demo playback: one GetKey poll by a screen (tick-counted recordings); returns the recorded keys now due. */
+    keyPollOnce?: () => number[];
+    /** Clears keyboard input (while (GetKey(1)) GetKey(0)). */
+    flushKeys(): void;
+    /**
+     * FadeTo: 65 retrace-synchronized steps from the current palette to `dest`. The C
+     * waited for one VGA vertical retrace (70 Hz in mode 13h) per step, hence steps/70 s;
+     * it stepped each channel Bresenham-style, which the truncated d*step/steps matches
+     * at every step.
+     */
+    fadeTo(dest: ArrayLike<number>, steps?: number): Promise<void>;
+    fadeAllTo(r: number, g: number, b: number, steps?: number): Promise<void>;
+}
+export {};

package/dist/types/engine/menus.d.ts

@@ -0,0 +1,46 @@
+import type { Machine } from './machine.js';
+import type { Screen } from '../gfx/screen.js';
+import { type PlayerLook } from './playerLook.js';
+import { type HighScore } from '../formats/highscore.js';
+/**
+ * GVertMenu: a marker box left of `count` rows (`dy` pixels apart starting at y).
+ * Returns 1..count, 0 for Esc, count+1 when idle for `idleSeconds`. The C timed the
+ * idle wait in game ticks (IdleTime*18 of TimerCounter); this uses wall-clock time.
+ *
+ * The C cleared only the mouse buttons (mouclearbut), not the keyboard: a key typed
+ * while the menu picture faded in (after the one ShowGraphic's PauseTimeKey(0) took)
+ * was the menu's. `flushKeys` false keeps that; the default clears keys too, for menus
+ * opened mid-level, where this port's keyboard also queues the keys gameplay used
+ * (PLAYGAME's own keyboard interrupt kept those out of the BIOS buffer).
+ */
+export declare function gVertMenu(m: Machine, x: number, y: number, dy: number, count: number, color: number, idleSeconds?: number, choice?: number, flushKeys?: boolean, 
+/** The marker's width minus 1 (the player's border.marker.width patch). */
+markerWidth?: number): Promise<number>;
+/** GGet: line editor with a blinking box cursor. Returns null on Esc. */
+export declare function gGet(m: Machine, x: number, y: number, col: number, bcol: number, initial: string, maxlen: number): Promise<string | null>;
+/** DrawDefaultScrn: concentric colored frames when a game has no menu graphic. */
+export declare function drawDefaultScreen(m: {
+    screen: Screen;
+}, colors: Uint8Array, rand?: () => number): void;
+export declare function highScoreFile(gamename: string): string;
+export declare function readHighScores(m: Machine, gamename: string): HighScore[];
+/** The main menu's words over the menu picture: the game's name and the six choices (DoGame). Returns their color. */
+export declare function drawMenu(screen: Screen, look: PlayerLook, colors: Uint8Array, title: string): number;
+/** The menu's GVertMenu call (x, first y, spacing, idle seconds, marker width), as the player's patches set them. */
+export declare function menuMarker(look: PlayerLook): {
+    x: number;
+    y: number;
+    dy: number;
+    idle: number;
+    width: number;
+};
+/** One of the menu's "No game-specific ..." lines (they share one GWrite: one position, one color). */
+export declare function drawNoFile(screen: Screen, look: PlayerLook, colors: Uint8Array, id: 'noInstructions' | 'noStoryline' | 'noCredits'): void;
+/** The high score table's words and rows; the rows get closer together further down. */
+export declare function drawHighScores(screen: Screen, look: PlayerLook, colors: Uint8Array, top: HighScore[], score: number): void;
+/** ShowHighScores (HISCOREL.C). */
+export declare function showHighScores(m: Machine, gamename: string, colors: Uint8Array, score?: number, look?: PlayerLook): Promise<void>;
+/** CheckHighScores' words for a new high score (place is 1-based); returns the name's color. */
+export declare function drawNewHighScore(screen: Screen, look: PlayerLook, colors: Uint8Array, place: number): number;
+/** CheckHighScores: asks for a name when the score makes the top ten; returns the 1-based place or 0. */
+export declare function checkHighScores(m: Machine, gamename: string, colors: Uint8Array, score: number, look?: PlayerLook): Promise<number>;

package/dist/types/engine/monsters.d.ts

@@ -0,0 +1,19 @@
+import { type MonInfo, type World } from './world.js';
+export declare function resetMonInfo(mi: MonInfo): void;
+export declare function monPicNum(w: World, mm: number): number;
+/** minfo::CalcDraw */
+export declare function calcDraw(w: World, mi: MonInfo): boolean;
+/** BirthMon: puts monster `mon` in slot mm (or the first empty slot when mm >= LASTMM). */
+export declare function birthMon(w: World, mm: number, mon: number, x: number, y: number): number;
+/** BlocBirthMon: blocks that give birth to monsters near the screen. */
+export declare function blockBirthMonsters(w: World): void;
+/** CharBirthMon: a character sequence frame that fires a monster (a shot, a bomb…). */
+export declare function charBirthMon(w: World, x: number, y: number, monNum: number): void;
+/**
+ * PicChkTouch: pixel-exact overlap of two 20x20 sprites (255 = transparent).
+ * Both positions are shifted so the overlap is measured from the nearer corner;
+ * each of the four branches handles one relative placement of sprite 2.
+ */
+export declare function picChkTouch(x1: number, y1: number, pic1: Uint8Array, x2: number, y2: number, pic2: Uint8Array): boolean;
+/** moveallmons: animate and move every live monster one game tick. */
+export declare function moveAllMonsters(w: World): void;