@lewismoten/gamemaker-sandbox-engine 3.1.0 → 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/cmfPlayer.d.ts

@@ -1,4 +1,4 @@
-import { Opl2 } from './opl';
+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.

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

@@ -1,6 +1,14 @@
 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?;
@@ -8,12 +16,23 @@ export declare class AudioEngine {
     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;
     /**
@@ -28,6 +47,8 @@ export declare class AudioEngine {
     /** 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;

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

@@ -8,6 +8,14 @@ export type MusicMessage = {
     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/engine/character.d.ts

@@ -1,5 +1,5 @@
-import { type Frame } from '../formats/character';
-import { type World } from './world';
+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>;
 /**
@@ -8,7 +8,7 @@ type DropPicker = () => Promise<number>;
  */
 export declare function currentFrame(w: World): Frame;
 /**
- * MoveCharGrav: every GRAVSPEED ticks, accelerate by one pixel a tick in each
+ * 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.
  */

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

@@ -1,7 +1,7 @@
-import type { Machine } from './machine';
-import type { Screen } from '../gfx/screen';
-import { type PlayerLook } from './playerLook';
-import { type World } from './world';
+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'>;
@@ -16,8 +16,10 @@ export declare function helpScreen(m: Machine, w: World, instructions: string |
 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>;
-/** GMabout's first page (this web edition's words); returns the text color. */
-export declare function drawAbout(screen: Screen, palette: Uint8Array, look: PlayerLook): number;
+/** 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. */

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

@@ -1,7 +1,8 @@
-import { Machine } from './machine';
-import { type Session, type SpeedSetting } from './scene';
-import type { PlayerPatches } from '../dosPlayer/patchRules';
-import { type Game } from '../formats/game';
+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;
@@ -31,10 +32,14 @@ export interface RunOptions {
      * 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

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

@@ -1,5 +1,5 @@
-import { type Frame, type Sequence } from '../formats/character';
-import { type World } from './world';
+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;

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

@@ -1,7 +1,7 @@
-import { Screen } from '../gfx/screen';
-import { Keyboard, type TypedKey } from '../input/keyboard';
-import { AudioEngine } from '../audio/engine';
-import { GameFiles } from '../project/gameFiles';
+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();
@@ -29,6 +29,8 @@ export declare class Machine {
     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. */
@@ -85,6 +87,8 @@ export declare class Machine {
     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;
     /**

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

@@ -1,7 +1,7 @@
-import type { Machine } from './machine';
-import type { Screen } from '../gfx/screen';
-import { type PlayerLook } from './playerLook';
-import { type HighScore } from '../formats/highscore';
+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

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

@@ -1,4 +1,4 @@
-import { type MonInfo, type World } from './world';
+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 */

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

@@ -1,4 +1,15 @@
-import { type PlayerPatches } from '../dosPlayer/patchRules';
+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 {
@@ -17,10 +28,17 @@ export interface PlayerLook {
     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): PlayerLook;
+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

@@ -1,4 +1,4 @@
-import { type RecordedKey } from '../formats/recording';
+import { type RecordedKey } from '../formats/recording.js';
 export declare const RECORD = 1;
 export declare class Recorder {
     mode: number;
@@ -33,6 +33,13 @@ export declare class Recorder {
      * 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;

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

@@ -1,5 +1,5 @@
-import type { Screen } from '../gfx/screen';
-import { type World } from './world';
+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;

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

@@ -1,11 +1,11 @@
-import type { Machine } from './machine';
-import type { Recorder } from './recorder';
-import { type PlayerLook } from './playerLook';
-import { type CharInfo, type Coord, type World } from './world';
-import { type SoundSet } from '../formats/sound';
-import { type Game } from '../formats/game';
-import { type PcCosts } from './slowPc';
-import { type PlayGain } from './playGain';
+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). */
@@ -31,6 +31,20 @@ export interface Session {
     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. */
@@ -47,6 +61,8 @@ export interface Session {
      * `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;
     /**
@@ -77,13 +93,29 @@ interface LoadedScene {
  * 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'> & {
+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 */

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

@@ -1,4 +1,4 @@
-import { type World } from './world';
+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
@@ -11,6 +11,14 @@ export declare function initScroll(w: World, s: {
     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

@@ -1,5 +1,5 @@
-import type { Machine } from './machine';
-import { type PlayerLook } from './playerLook';
+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];

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

@@ -36,6 +36,37 @@ export interface PcCosts {
     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;
@@ -56,7 +87,38 @@ export declare class SlowCpu {
     spend(ms: number): void;
     reset(): void;
 }
-/** What one game tick costs with `monsters` drawn on screen. */
-export declare function tickCost(pc: PcCosts, monsters: number): number;
+/** 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

@@ -1,5 +1,5 @@
-import type { Block } from '../formats/blocks';
-import { type Coord, type TouchBlocks, type World } from './world';
+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. */

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

@@ -1,9 +1,9 @@
-import { BACKBL, BLEN, CHARBL, MONBL, type Block } from '../formats/blocks';
-import type { Character } from '../formats/character';
-import { INF_REPEAT, MAXINV, MAXSEQ } from '../formats/character';
-import { LASTMON, type Monster } from '../formats/monster';
-import { LASTMM, MLEN, MWID, type GameMap } from '../formats/map';
-import { LASTSND } from '../formats/sound';
+import { BACKBL, BLEN, CHARBL, MONBL, type Block } from '../formats/blocks.js';
+import type { Character } from '../formats/character.js';
+import { INF_REPEAT, MAXINV, MAXSEQ } from '../formats/character.js';
+import { LASTMON, type Monster } from '../formats/monster.js';
+import { LASTMM, MLEN, MWID, type GameMap } from '../formats/map.js';
+import { LASTSND } from '../formats/sound.js';
 export { BLEN, BACKBL, MONBL, CHARBL, LASTMM, LASTMON, MLEN, MWID, MAXSEQ, MAXINV, INF_REPEAT, LASTSND };
 export declare const SIZEX = 320;
 export declare const SIZEY = 200;
@@ -23,6 +23,26 @@ export declare const SCROLLPERMOVE = 6;
 export declare const MAXMONSSHOWN = 50;
 export declare const CHARPOWER = 100;
 export declare const NEVER = 4294967295;
+/** The gameplay constants a DOS player patch can change (playerLook.ts playTuning); World.tune. */
+export interface PlayTuning {
+    /** MAXGRAV: the character's most pixels a move, either way. */
+    maxSpeed: number;
+    /** MAXGRAV*4: the most momentum gravity blocks build. */
+    gravityCap: number;
+    /** GRAVSPEED: ticks between gravity pulls. */
+    gravityTicks: number;
+    /** ATTACKX, ATTACKY: blocks within which a monster starts its attack path. */
+    attackX: number;
+    attackY: number;
+    /** SCRSPDX, SCRSPDY: the scroll speed at the screen edge. */
+    scrollSpeedX: number;
+    scrollSpeedY: number;
+    /** SCROLLPERMOVE: timer ticks one scroll move is spread over. */
+    scrollSteps: number;
+    /** FadeTo's and FadeAllTo's step count. */
+    fadeSteps: number;
+}
+export declare const STOCK_TUNING: Readonly<PlayTuning>;
 export interface Coord {
     x: number;
     y: number;
@@ -196,6 +216,8 @@ export interface World {
      * tracking listens here; nothing in play reads it.
      */
     onTouched?: (x: number, y: number, bnum: number) => void;
+    /** The gameplay constants, STOCK_TUNING unless the player's patches change them (playerLook.ts playTuning). */
+    tune: PlayTuning;
 }
 export declare function newCharInfo(): CharInfo;
 /** Pads a block list with empty blocks so out-of-range numbers are harmless. */