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

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

@@ -0,0 +1,11 @@
+export interface PlayGain {
+    /** Points from the stretches F6 closed. */
+    banked: number;
+    /** The score the current stretch started from (0, or the score a load put in place). */
+    base: number;
+}
+export declare const newPlayGain: () => PlayGain;
+/** F6 loaded a save: the score went from `before` to the save's `after`. */
+export declare function gainAtLoad(g: PlayGain, before: number, after: number): void;
+/** The points this play scored, ending on `score`. */
+export declare const gainAtEnd: (g: PlayGain, score: number) => number;

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

@@ -0,0 +1,44 @@
+import { type PlayerPatches } from '../player/patchRules.js';
+import { type PlayTuning } from './world.js';
+/**
+ * An imported game's own player About page (F10), as that player drew it: read-only, since it is
+ * RSD's or the original author's attribution (dosPlayer/playerOrigin.ts).
+ */
+export interface PlayerAbout {
+    /** Its pages, each a list of [y, text] lines drawn at x 40; left out, this edition's own words. */
+    pages?: [number, string][][];
+    /** The build it was first made with, as lines for the last page ("Originally made with" / "Game-Maker 2.02."). */
+    origin?: string[];
+}
+type Rgb = [number, number, number];
+type Frame = [number, number, number, number];
+export interface PlayerLook {
+    /** A word or line (str.*). */
+    text(id: string): string;
+    /** A printf format (str.*) filled in as sprintf would. */
+    format(id: string, ...args: (number | string)[]): string;
+    /** The palette index a screen's color selector (color.select.*) matches in `pal`. */
+    color(pal: Uint8Array, select: string): number;
+    /** A color's levels (color.rgb.*, color.missing.*). */
+    rgb(id: string): Rgb;
+    frame(id: string): Frame;
+    /** A position or count (layout.*, border.marker.width). */
+    num(id: string): number;
+    /** A wait in seconds (timing.*); -1 is PauseTimeKey's unsigned 65535 (until a key). */
+    seconds(id: string): number;
+    /** False when the player's patches turned this F-key off. */
+    fkeyOn(key: number): boolean;
+    /** An imported game's own About page and first build, when it has them. */
+    about?: PlayerAbout;
+}
+/** sprintf for the player's formats: %d, %ld, %s with a width and the 0 and - flags. */
+export declare function sprintf(format: string, args: (number | string)[]): string;
+export declare function playerLook(patches?: PlayerPatches, about?: PlayerAbout): PlayerLook;
+/**
+ * The gameplay constants `look`'s patches give, for World.tune: with none, PLAYGAME.C's own
+ * #defines (STOCK_TUNING), so play is exactly as before.
+ */
+export declare function playTuning(look: PlayerLook): PlayTuning;
+/** The CD player's own look. */
+export declare const STOCK_LOOK: PlayerLook;
+export {};

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

@@ -0,0 +1,67 @@
+import { type RecordedKey } from '../formats/recording.js';
+export declare const RECORD = 1;
+export declare class Recorder {
+    mode: number;
+    private keys;
+    private index;
+    private timer;
+    private lastKeyPress;
+    private paused;
+    initRecord(): void;
+    /**
+     * Whether waits for a key count toward playback time. PLAYGAME's GetKey called
+     * DoPlayBack on every poll, so while a "hit any key" screen waited the timer raced
+     * ahead (thousands of polls a second), and a demo recorded in DOS stores those polls
+     * as one huge DeltaTime before the key that dismissed the screen (Nebula's 26058).
+     * Demos recorded here count game ticks only, so for them waits must not count.
+     */
+    countsWaits: boolean;
+    initPlayback(bytes: Uint8Array | undefined): boolean;
+    stop(): void;
+    restart(): void;
+    pause(): void;
+    unpause(): void;
+    /** Game ticks counted since the recording or playback (re)started; the playback position. */
+    get tick(): number;
+    get playing(): boolean;
+    /** Paused: play has left the levels (the won/lost pictures and score table follow). */
+    get halted(): boolean;
+    /** DoPlayBack: advance one tick; returns the keys that become pending now. */
+    doPlayback(): number[];
+    /**
+     * GetKey polls while a screen waits for a key: `polls` calls to DoPlayBack at once.
+     * Returns the recorded keys that become pending (only for recordings made in DOS).
+     */
+    advanceWait(polls: number): number[];
+    /**
+     * One GetKey poll (DoPlayBack) by a key screen in a tick-counted recording, where waits
+     * otherwise don't count (advanceWait): the keys a demo gave that screen one tick after
+     * its opening key (DropBloc's Enter) become pending. Recordings made in DOS count their waits.
+     */
+    pollOnce(): number[];
+    private advanceByTick;
+    /**
+     * A screen that read keys has finished. In DOS the next key may have come during it
+     * (the recording shows a gap of many thousands of polls), however fast that PC polled;
+     * catch up to it, and to keys a poll or two behind it (taken by the keyboard flush that
+     * follows every screen), so gameplay resumes in step. Only for DOS recordings.
+     */
+    finishWait(): number[];
+    /**
+     * DoRecord: called when a key is actually applied to the character (keys held back
+     * while a sequence can't be interrupted are recorded on the tick they take effect).
+     * DeltaTime is a 16-bit uint in the C, and at most RECLEN keys are kept.
+     */
+    doRecord(key: number): void;
+    /** The recording so far, in .rec format. */
+    save(): Uint8Array;
+    /** For save games (the C wrote the Recording object and its keys into the .sav). */
+    snapshot(): unknown;
+    restore(s: {
+        mode: number;
+        keys: RecordedKey[];
+        index: number;
+        timer: number;
+        lastKeyPress: number;
+    }): void;
+}

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

@@ -0,0 +1,8 @@
+import type { Screen } from '../gfx/screen.js';
+import { type World } from './world.js';
+/** CropScreen: the CRTC was reprogrammed to show only 312x196 pixels while playing. */
+export declare const VISIBLE_W = 312;
+export declare const VISIBLE_H = 196;
+/** drawchars' bookkeeping without the drawing: whether top/bottom blocks are shown (used by GetTouchbl). */
+export declare function updateCharDrawState(w: World): void;
+export declare function renderWorld(screen: Screen, w: World): void;

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

@@ -0,0 +1,188 @@
+import type { Machine } from './machine.js';
+import type { Recorder } from './recorder.js';
+import { type PlayerLook } from './playerLook.js';
+import { type CharInfo, type Coord, type World } from './world.js';
+import { type SoundSet } from '../formats/sound.js';
+import { type Game } from '../formats/game.js';
+import { type PcCosts } from './slowPc.js';
+import { type PlayGain } from './playGain.js';
+/** How a play ended: the Game Won scene, no lives left, or Esc (or a scene that could not load). */
+type PlayEnd = 'won' | 'lost' | 'quit';
+/** Everything that lives across scenes (playgame's globals outside a level). */
+export interface Session {
+    m: Machine;
+    game: Game;
+    gameName: string;
+    ci: CharInfo;
+    /** The `colors` global: the palette of the current scene or menu screen. */
+    colors: Uint8Array;
+    rec: Recorder;
+    sndClock: number;
+    timerCounter: number;
+    soundOn: boolean;
+    musicOn: boolean;
+    /** Use the PC speaker even when a .voc name is given (no Sound Blaster). */
+    speakerOnly: boolean;
+    joystick?: () => {
+        pos: number;
+        buttons: number;
+    } | null;
+    /** Called every rendered frame with the live world (for HUD overlays, touch controls…). */
+    onFrame?: (w: World) => void;
+    /** Emulated PC speed; read every tick so it can change while playing. */
+    speed: SpeedSetting;
+    /** Milliseconds a voice read still owes the emulated PC (SpeedSetting.slowPc); playscene charges it. */
+    vocStall?: number;
+    /** The last scene load the emulated slow disk was charged for (sceneLoadMs): files opened, bytes read, milliseconds. Cleared by a load that costs nothing. */
+    sceneLoad?: {
+        files: number;
+        bytes: number;
+        ms: number;
+    };
+    /** A voice read from the emulated slow disk that has not started yet: the last one asked for, its total wait, the time it is due. */
+    vocLate?: {
+        bytes: Uint8Array;
+        wait: number;
+        due?: number;
+    };
+    /** RunOptions.gmHelp: Game-Maker's own GMHELP.TXT, which F1 shows first (PLAYGAME.EXE only). */
+    gmHelp?: Uint8Array;
+    /** RunOptions.player as the screens use it (engine/playerLook.ts); left out, the CD player's look. */
+    look?: PlayerLook;
+    /** The random numbers a level's monsters get as it loads (default Math.random; a walkthrough seeds them). */
+    rand?: () => () => number;
+    /** Told the scene number each time play() enters a scene (before its picture). */
+    onScene?: (scene: number) => void;
+    /** Not PLAYGAME's: a touch in `scene` changed map cell (x, y), shown as block `bnum` (World.onTouched). */
+    onTouched?: (scene: number, x: number, y: number, bnum: number) => void;
+    /**
+     * Not PLAYGAME's: play ended (won, lost, or left with Esc) with this score, just before the
+     * high score table. Never told during a demo's playback. It only listens: nothing changes.
+     * `gained` is the points the play scored itself, leaving out those F6 loaded (playGain.ts).
+     */
+    onPlayEnd?: (score: number, how: PlayEnd, gained: number) => void;
+    /** A player death, including the final life. Never called during recorded playback. */
+    onLifeLost?: () => void;
+    /** Not PLAYGAME's: the stretches of this play between F6 loads (playGain.ts). */
+    gain?: PlayGain;
+    /**
+     * The last level played. loadscene loads into globals, so a level that leaves its
+     * palette, block or character slot blank keeps the previous level's (PLAYGAME.C 4239).
+     */
+    lastWorld?: World;
+}
+/**
+ * How fast the emulated PC is. The game clock always runs at 18.2 Hz, but playgame
+ * skips (rather than catches up) ticks its main loop was too slow to handle, and loses
+ * the scroll steps of interrupts that went by while it was busy. `slowPc` (see slowPc.ts)
+ * charges each pass of the loop what it cost on a slower PC; left out, the PC is fast
+ * enough for every pass (a 486 in turbo).
+ */
+export interface SpeedSetting {
+    slowPc?: PcCosts;
+}
+export declare function sceneFile(game: Game, scene: number, slot: number): string | undefined;
+interface LoadedScene {
+    world: World;
+    sounds?: SoundSet;
+    song?: Uint8Array;
+}
+/**
+ * loadscene: returns the names of missing files on failure. Scene file slots are
+ * 0 palette, 1 map, 2 background blocks, 3 monsters, 4 monster blocks, 5 character,
+ * 6 character blocks, 7 sound set, 8 song. In the C a slot left blank keeps whatever
+ * the previous scene loaded into the globals; `prev` stands in for those globals.
+ */
+export declare function loadScene(s: Pick<Session, 'game' | 'rand' | 'onTouched' | 'look'> & {
+    m: {
+        files: {
+            get(name: string): Uint8Array | undefined;
+        };
+    };
+}, scnum: number, prev?: World): LoadedScene | string[];
+export declare const LOADGAME_SLOTS: readonly number[];
+/**
+ * The byte count of each file a scene load reads from disk, in the order it reads them: every named slot of
+ * `slots`, then the song when there is a card to play it on (loadscene only calls InitMusic with CARDEXIST).
+ * A blank slot opens nothing. A named file the disk does not have costs its directory search (0 bytes).
+ * The .snd counts whole (loadspecsnd reads its 2,430 byte table, which is the whole file). Nothing is cached:
+ * PLAYGAME reads a scene afresh every time it starts one, after a lost life too.
+ */
+export declare function sceneReads(s: {
+    game: Game;
+    m: {
+        files: {
+            get(name: string): Uint8Array | undefined;
+        };
+    };
+}, scnum: number, card: boolean, slots?: readonly number[]): number[];
+/** StartGameInits */
+export declare function startGameInits(s: Session): void;
+/** StartSceneInits */
+export declare function startSceneInits(w: World, start: Coord): void;
+/**
+ * keydn[CHRSEQ.key] = 1 at the end of the C's scene inits (PLAYGAME.C). keydn is a 128 byte
+ * array indexed by scan code, but a sequence's key is the whole 16 bit word (scan code in the
+ * high byte, ASCII in the low byte, CHAR.H), so the C only set a keydn entry when the key had
+ * no scan code: key 0 (no key, which every idle sequence on the CD has) sets keydn[0], and
+ * the idle sequence's "quit if key lifted" test (keydn[key>>8]==0) then reads it as held.
+ * For a real key the write landed key bytes past keydn (DGROUP:4C4E in PLAYGAME.MAP), never
+ * on another keydn entry: scan 1..4 in dirtrect.c's DirtyBoxes, scan 5 in the next modules'
+ * buffers, scan 5..0x48 in gifc.c's decoder tables, 0x49..0x4A in the atexit table and higher
+ * in the far end of the 15000 byte stack. Those are all written before they are read, so the
+ * stray byte had no effect: the key does not read as held (keydn[scan] stays 0).
+ */
+export declare function setStartKey(keydn: Uint8Array, key: number): void;
+/** changeblks: animate background blocks. */
+export declare function changeBlocks(w: World): void;
+interface SceneResult {
+    ok: boolean;
+    link: number;
+    /**
+     * The level played at the end and the one before it: another level's after F6 loaded a game
+     * saved there (LoadGame sets play's curscene and oldscene, globals in the C).
+     */
+    doscene?: number;
+    prevscene?: number;
+}
+/** What F5 writes to game<n>.sav (this port's JSON in place of SaveGame's binary records). */
+export interface Saved {
+    version: 1;
+    prevscene: number;
+    doscene: number;
+    linkin: number;
+    sndClock: number;
+    world: Pick<World, 'nxtchg' | 'ci' | 'mx' | 'my' | 'mi' | 'mm' | 'noMons' | 'blkMon'> & {
+        blkmap: number[];
+        map: number[];
+        mapMon: number[];
+        chr: {
+            x: number[];
+            y: number[];
+            cframe: number;
+            cseq: number;
+        };
+    };
+    rec: ReturnType<Recorder['snapshot']>;
+}
+/** playscene: plays one level. link in/out follows the original's conventions. */
+export declare function playScene(s: Session, dosc: number, prev: number, linkIn: number): Promise<SceneResult>;
+/** The save of a game at this moment (F5; project/saveData's newGameSave makes one at the start). */
+export declare function savedState(w: World, where: {
+    prevscene: number;
+    doscene: number;
+    linkin: number;
+}, sndClock: number, rec: Pick<Recorder, 'snapshot'>): Saved;
+/**
+ * F6's LoadGame once the save is read: the saved level loaded fresh, then the saved state put
+ * over it (also how project/saveData's tests check a save it made). Undefined when the
+ * level's files are missing.
+ */
+export declare function restoreSaved(s: Pick<Session, 'game' | 'rand' | 'ci' | 'rec' | 'sndClock' | 'onTouched'> & {
+    m: {
+        files: {
+            get(name: string): Uint8Array | undefined;
+        };
+    };
+}, w: World | undefined, data: Saved): LoadedScene | undefined;
+export {};

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

@@ -0,0 +1,24 @@
+import { type World } from './world.js';
+/**
+ * Scene setup: Scroll.up/down/left/right are stored mirrored in the .gam file (the
+ * flags here name the way the map moves, e.g. `left` lets the map slide left as the
+ * character walks right). 0xff means that direction is allowed.
+ */
+export declare function initScroll(w: World, s: {
+    up: number;
+    down: number;
+    left: number;
+    right: number;
+}): void;
+/** ChangeScroll: decide scrolling speed from how far the character is from center. */
+/**
+ * PLAYGAME.C ChangeScroll's `((dist)*SPD)/span` (negated first for the right and down scrolls).
+ * Everything there is a Borland 16-bit `int`, so the product wraps once the character is more
+ * than 819 pixels past the stop line (SPD is 40), and the speed flips sign or shrinks. We wrap
+ * the same way, then divide as a signed 16-bit division truncating toward zero.
+ * Credit: chiguire (upstream gandrewstone/GameMaker PR #4) found this overflow in a DOS run.
+ */
+export declare function dosSpeed(dist: number, spd: number, span: number, negate?: boolean): number;
+export declare function changeScroll(w: World): number;
+/** DrawScroll: one 1/145.6 s scroll step. Returns how many new 4 pixel edge strips it took. */
+export declare function drawScroll(w: World): number;

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

@@ -0,0 +1,39 @@
+import type { Machine } from './machine.js';
+import { type PlayerLook } from './playerLook.js';
+export declare const RGB_RED: [number, number, number];
+export declare const RGB_BLUE: [number, number, number];
+export declare const RGB_YELLOW: [number, number, number];
+export declare const RGB_PURPLE: [number, number, number];
+export declare const match: (pal: Uint8Array, c: [number, number, number]) => number;
+interface GraphicOptions {
+    /** Receives the palette of the shown picture (the NewCols argument). */
+    cols?: Uint8Array;
+    /** Seconds to wait for a key; -1 = the default for the file type. */
+    pause?: number;
+    /** The game's current palette, used to pick text colors (`colors` global). */
+    gamePalette: Uint8Array;
+    /** The player's look (RunOptions.player): text page colors, default times. */
+    look?: PlayerLook;
+}
+/** Returns false when the player pressed Esc (which aborts slide shows). */
+export declare function showGraphic(m: Machine, file: string, opts: GraphicOptions): Promise<boolean>;
+/**
+ * FLI::View: every frame once, `speed` vertical retraces (1/70 s) apart. The C drew
+ * straight onto the VGA screen, so the animation starts over whatever is shown.
+ *
+ * A speed of 0 waits no retrace at all: the C's delay loop is
+ *   for (uint Delay=0;Delay<Head.FrameSpd;Delay++) { wait out retrace; wait for retrace; }
+ * so with FrameSpd 0 the next frame was decoded into video memory straight away, as fast
+ * as the PC could read and draw it, and the monitor showed whatever was in video memory at
+ * each refresh (frames in between were never seen). The port does the same: it draws the
+ * next frame at once, only yielding to the event loop (no frame wait) so the page stays
+ * responsive, and each browser repaint shows the frame that is current then. Speed 0 FLIs
+ * on the CD (black.fli, menubkg.fli, textbkg.fli, ...) are one or two frame backgrounds.
+ */
+export declare function playFli(m: Machine, file: string): Promise<boolean>;
+/**
+ * Display_File: text pages over the current picture, 16 lines (rows 5..20 of 8 pixels)
+ * per page. fgets(…, 32) read at most 31 characters at a time, so long lines wrap.
+ */
+export declare function displayFile(m: Machine, file: string, col: number, pause: number, gamePalette: Uint8Array, bytes?: Uint8Array<ArrayBufferLike> | undefined, look?: PlayerLook): Promise<boolean>;
+export {};

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

@@ -0,0 +1,124 @@
+/**
+ * The emulated slow PC behind the desk's TURBO button (turbo off).
+ *
+ * A 486DX2-66's turbo switch did not make it a 286. On most boards turbo off turned off
+ * the CPU cache (some also dropped the bus or core clock), which left the machine at
+ * roughly 286-16 to 386-25 speed, depending on the board. So turbo off here is "about a
+ * fast 286": the PC Lewis played these games on, where they ran fine.
+ *
+ * Why they ran fine: playgame's main loop (PLAYGAME.C playscene) does two kinds of work.
+ *  - Once per NewTimer interrupt (8 per game tick, 145.6 Hz), DrawScroll while the view
+ *    scrolls. On a VGA/SVGA card this is hardware scrolling: it moves the CRTC start
+ *    address, draws only the new 4 pixel strips at the edge (drawhorizside/
+ *    drawvertside: 320x4 or 4x200 pixels each) and erases/redraws the character. It never
+ *    redraws the whole screen.
+ *  - Once per 18.2 Hz game tick: move and redraw the character and the monsters on screen,
+ *    animate blocks, copy the dirty rectangles to the screen, check links.
+ * On a 286-class PC a still tick costs about 15 ms plus a millisecond or so per monster on
+ * screen, well under the 55 ms a tick lasts, so the game keeps full pace. Scrolling only
+ * runs once per pass of the loop, and the pass that runs the game tick takes several
+ * interrupts' worth of time; DrawScroll is called with a step of 1 however many
+ * interrupts went by (its `speed` argument is commented out), so those scroll steps are
+ * simply lost and the view trails the character a little more. Only a crowded screen
+ * that is also scrolling can take longer than a tick, and then playgame skips the missed
+ * tick (OldClock jumps to TimerCounter) instead of catching up.
+ *
+ * The figures below are estimates for that machine, in milliseconds. They are kept
+ * deliberately simple and deterministic (no wall clock): the same keys give the same
+ * game, and recordings replay the same way.
+ */
+export interface PcCosts {
+    /** A game tick with nothing on screen but the character. */
+    tickMs: number;
+    /** Each monster drawn on screen that tick (move, erase, masked draw, dirty rect). */
+    monsterMs: number;
+    /** One DrawScroll call (Bresenham step, CRTC update, character erase/redraw). */
+    scrollPassMs: number;
+    /** Each new 4 pixel edge strip DrawScroll draws and copies to the screen. */
+    stripMs: number;
+    /** Each animated map cell redrawn on screen that tick (up to 170 dirty rectangles, DIRTRECT.C MAXDIRTY). */
+    cellMs?: number;
+    /**
+     * Disk read of a .voc (PlaySbVocFile reads the whole file on the game's own thread): fixed cost to open it
+     * (directory lookup, FAT, seek to the data). It is also what each scene file costs to open: loadscene
+     * (PLAYGAME.C 4239) reads a scene's files from this same disk while the screen is black, and F6's LoadGame
+     * reads most of them again (sceneLoadMs). One disk per machine, so a sound and a level never disagree about
+     * how fast it is. Left out (TURBO_OFF), sounds and scenes load in no time.
+     */
+    vocOpenMs?: number;
+    /** ...and how many bytes a millisecond the disk then delivers. */
+    vocBytesPerMs?: number;
+    /**
+     * The largest .voc the far heap still has room for (PlaySbVocFile `new`s the whole file; when that
+     * fails it returns FALSE and the game goes on without the sound). An estimate: 640 KB less DOS,
+     * drivers and PLAYGAME's own data. Left out, any size fits.
+     */
+    vocHeapBytes?: number;
+    /**
+     * Optional custom-PC assumption: a disk BIOS masks the timer for the whole read, so PlayIt cannot
+     * advance and the FM chip holds its notes. The built-in presets leave the timer running: Lewis's
+     * PS/1 Model 2011 observation in 86Box (November 6, 2026) found a gameplay pause without a music hold.
+     * That observation does not establish IRQ behavior for every historical BIOS.
+     */
+    readHoldsMusic?: boolean;
+    /** The timer interrupt itself (entry, EOI, PlayIt's bookkeeping; the BIOS clock every 8th), per interrupt. */
+    isrMs?: number;
+    /** Each CMF event PlayIt hands the FM driver (the driver call, without its register writes). */
+    fmEventMs?: number;
+    /** Each OPL2 register write: about 3.3 µs after the address and 23 µs after the data, waited out on the ISA bus. */
+    fmWriteMs?: number;
+}
+/** A 486DX2-66 with turbo off: about a 286-16. */
+export declare const TURBO_OFF: PcCosts;
+/**
+ * Keeps track of the time the slow PC still owes on work it started, counted in NewTimer
+ * interrupts. While it owes a whole interrupt or more, that loop pass never happens.
+ */
+export declare class SlowCpu {
+    private readonly interruptMs;
+    /** Milliseconds of work still running. */
+    owed: number;
+    constructor(interruptMs: number);
+    /**
+     * Called once per NewTimer interrupt: true when the PC is still busy with earlier work
+     * and this interrupt's pass of the main loop (scroll step, game tick) is lost.
+     */
+    busy(): boolean;
+    spend(ms: number): void;
+    reset(): void;
+}
+/** What one game tick costs with `monsters` drawn on screen and `cells` animated map cells redrawn. */
+export declare function tickCost(pc: PcCosts, monsters: number, cells?: number): number;
+/** What one DrawScroll call costs when it drew `strips` new 4 pixel strips. */
+export declare function scrollCost(pc: PcCosts, strips: number): number;
+/**
+ * "Run like a..." in the player: the same cost model as TURBO_OFF for three machines of the
+ * period. Every number is an ESTIMATE from period hardware figures, not a measurement
+ * (programmer's guide chapters 10b and 12). A quiet tick is the game's work plus the copy of
+ * the changed rectangles to the screen. The timer interrupt and the music (about 1% of a 286)
+ * are charged per interrupt (songIsrMs). Today (no costs) is a fast modern machine.
+ */
+export type SpeedChoice = 'today' | '486' | '386' | '286' | 'ps1';
+export declare const SPEED_CHOICES: readonly SpeedChoice[];
+export declare const SPEED_PRESETS: Record<Exclude<SpeedChoice, 'today'>, PcCosts>;
+/** The costs for a choice; undefined for Today (nothing is charged). */
+export declare function costsFor(choice: SpeedChoice): PcCosts | undefined;
+/**
+ * How long reading a voice of `bytes` freezes the game: open plus transfer. PLAYGAME reads
+ * the whole file before the tick goes on, so game time stops, and the sound only starts once the
+ * read is over (the player waits that long). On a PC with readHoldsMusic the music stops for it too
+ * (musicHoldMs). 0 when the PC has no disk figures (TURBO_OFF) or on Today.
+ */
+export declare function vocStallMs(pc: PcCosts | undefined, bytes: number): number;
+/** How long the music stands still for a disk read of `readMs` (0 on Today, the desk turbo, or a PC whose timer keeps going). */
+export declare function musicHoldMs(pc: PcCosts | undefined, readMs: number): number;
+/** True when the far heap cannot hold a .voc of `bytes`: PlaySbVocFile returns FALSE and nothing plays. */
+export declare function vocWontFit(pc: PcCosts | undefined, bytes: number): boolean;
+/**
+ * How long a scene load keeps the screen black on this PC: each file opened costs vocOpenMs, then its
+ * bytes at vocBytesPerMs (`reads` is the byte count of each file read, 0 for one that failed to open).
+ * Game time does not move: playscene sets TimerCounter back to its value from before the load (PLAYGAME.C
+ * 1404), and LoadGame puts back the saved clock. Every preset (486, 386, 286, PS/1) has disk figures; 0 on a
+ * PC without them (TURBO_OFF) or on Today.
+ */
+export declare function sceneLoadMs(pc: PcCosts | undefined, reads: readonly number[]): number;

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

@@ -0,0 +1,18 @@
+import type { PcCosts } from './slowPc.js';
+export interface SongLoad {
+    /** Interrupts in one pass of the song. */
+    interrupts: number;
+    events: number;
+    writes: number;
+    /** The most events and register writes due on one interrupt. */
+    peakEvents: number;
+    peakWrites: number;
+}
+/** One pass through a CMF's music, walked as PlayIt walks it; undefined for a song PLAYGAME refuses. */
+export declare function songLoad(cmf: Uint8Array | undefined): SongLoad | undefined;
+/** The song's average cost per timer interrupt on `pc`, in ms (0 without music figures or a song). */
+export declare function songIsrMs(pc: PcCosts | undefined, load: SongLoad | undefined): number;
+/** The busiest interrupt of the song on `pc`, in ms: what it would take to make the timer lose a beat. */
+export declare function songPeakIsrMs(pc: PcCosts, load: SongLoad): number;
+/** Milliseconds between two timer interrupts (6.87). */
+export declare const INTERRUPT_MS: number;

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

@@ -0,0 +1,33 @@
+import type { Block } from '../formats/blocks.js';
+import { type Coord, type TouchBlocks, type World } from './world.js';
+export declare const KILLSOUND = 1;
+export declare function doSound(w: World, n: number): boolean;
+/** ScrnLowBnd/ScrnUpBnd ({1,1} to {SIZEX-BLEN,SIZEY-BLEN}): where a 20x20 sprite is considered on screen. */
+export declare function inScreenBounds(p: Coord): boolean;
+/**
+ * onscrn: screen position of map block (x, y); true if inside the screen bounds.
+ * Cells left of / above the scroll origin (mx, my) are taken as wrapped around the map.
+ */
+export declare function onscrn(w: World, x: number, y: number, ret: Coord): boolean;
+/**
+ * GetTouchbl: the up to 6 map cells the (two block high) character overlaps:
+ * 0/1 the top row (only while the top half is drawn), 2/3 its own row, 4/5 the
+ * row below, left then right. The right/lower cells count only when the pixel
+ * offset is past 0. Unused cells keep x = MLEN and BACKBL; blknum is the
+ * displayed variant (blkmap) of the map block.
+ */
+export declare function getTouchBlocks(w: World): TouchBlocks;
+/** checkseq_fortie: turns on/off every sequence tied to `block` (picked up or dropped). */
+export declare function checkSeqForTie(w: World, block: number, setting: boolean): void;
+/**
+ * DoBlockTouchChar: applies a block's (or monster block's) effects to the character.
+ * Returns 0 when blocked by an empty counter, otherwise (sound played ? 2 : 1).
+ * Effect 1 is lives and 3 is money; effects 3 and up are counters (ci.meter), and
+ * 3 or 20 and up refuse the touch when they would leave the counter at 0 or less.
+ * i16/u16 keep the C's 16-bit int wrap and its unsigned overflow checks.
+ */
+export declare function doBlockTouchChar(w: World, blk: Block): number;
+/** really_checktouch: 2 = touch refused (counter empty), else true. x === MLEN is an unused touch cell. */
+export declare function reallyCheckTouch(w: World, x: number, y: number, bnum: number): number;
+/** CheckTouch: touches every overlapped cell except objects, which only PickupBloc takes. */
+export declare function checkTouch(w: World): void;