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

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

@@ -0,0 +1,4 @@
+export { Machine, GameAborted } from './machine';
+export { runGame, loadGameFile, gameNameOf, type RunOptions } from './game';
+export { GameFiles, normalize, cdName, type FileStream } from '../project/gameFiles';
+export { AudioEngine } from '../audio/engine';

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,26 @@
+import { type PlayerPatches } from '../dosPlayer/patchRules';
+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;
+}
+/** 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;
+/** The CD player's own look. */
+export declare const STOCK_LOOK: PlayerLook;
+export {};

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

@@ -0,0 +1,60 @@
+import { type RecordedKey } from '../formats/recording';
+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[];
+    /**
+     * 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';
+import { type World } from './world';
+/** 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,156 @@
+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';
+/** 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;
+    /** 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;
+    /** 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'> & {
+    m: {
+        files: {
+            get(name: string): Uint8Array | undefined;
+        };
+    };
+}, scnum: number, prev?: World): LoadedScene | string[];
+/** 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,16 @@
+import { type World } from './world';
+/**
+ * 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. */
+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';
+import { type PlayerLook } from './playerLook';
+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,62 @@
+/**
+ * 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;
+}
+/** 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. */
+export declare function tickCost(pc: PcCosts, monsters: number): number;
+/** What one DrawScroll call costs when it drew `strips` new 4 pixel strips. */
+export declare function scrollCost(pc: PcCosts, strips: number): number;

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

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

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

@@ -0,0 +1,215 @@
+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';
+export { BLEN, BACKBL, MONBL, CHARBL, LASTMM, LASTMON, MLEN, MWID, MAXSEQ, MAXINV, INF_REPEAT, LASTSND };
+export declare const SIZEX = 320;
+export declare const SIZEY = 200;
+export declare const MAXKEYS = 20;
+export declare const MAXGRAV = 11;
+export declare const SCRNBLEN = 16;
+export declare const SCRNBWID = 10;
+export declare const GRAVSPEED = 1;
+export declare const MONMOVESPEED = 1;
+export declare const JSTICKKEY = 1;
+export declare const ATTACKX = 8;
+export declare const ATTACKY = 5;
+export declare const OFFSCRN = -100;
+export declare const SCRSPDX = 40;
+export declare const SCRSPDY = 40;
+export declare const SCROLLPERMOVE = 6;
+export declare const MAXMONSSHOWN = 50;
+export declare const CHARPOWER = 100;
+export declare const NEVER = 4294967295;
+export interface Coord {
+    x: number;
+    y: number;
+}
+/** cinfo: the player's state that persists across scenes. */
+export interface CharInfo {
+    score: number;
+    update: boolean;
+    topthere: boolean;
+    bottomthere: boolean;
+    curtop: number;
+    curbottom: number;
+    /** Where the character will be on screen next; scrx/scry where it is drawn; oldx/oldy where it is erased. */
+    nextx: number;
+    nexty: number;
+    scrx: number;
+    scry: number;
+    oldx: number;
+    oldy: number;
+    /** Delta of the character's last 2 moves. */
+    netx: number;
+    nety: number;
+    /** Current velocity due to gravity. */
+    gravx: number;
+    gravy: number;
+    hitpts: number;
+    /** Lives left; -1 before the first scene sets it from the character's meter. */
+    lives: number;
+    /** Game clock tick at which the character next moves. */
+    nextAni: number;
+    /** Inventory block numbers (BACKBL+1 in inv[0] = not filled in yet). */
+    inv: number[];
+    /** Repetition counters, MAXSEQ + 10 of them; meter[0] is hit points, meter[1] lives. */
+    meter: number[];
+    seqon: boolean[];
+}
+/** minfo: one live monster. */
+export interface MonInfo {
+    /** Born from the character, so it can't hurt the character. */
+    fromchar: number;
+    /** Bresenham's algorithm: dx = (curpos - dest). */
+    delta: Coord;
+    /** [0] map block, [1] pixel position within the block. */
+    curx: [number, number];
+    cury: [number, number];
+    /** Where the monster is going when on a path. */
+    target: Coord;
+    /** xy ratios in Bresenham's line algorithm. */
+    offl: number;
+    offs: number;
+    /** 0 normal, 1 attack pattern. */
+    curMarch: number;
+    /** Index into mon[].pic. */
+    curPic: number;
+    /** How to flip and rotate the picture. */
+    orient: number;
+    picDrawn: boolean;
+    scrPos: Coord;
+    oldPos: Coord;
+    /** Index of the next position in the monster's path. */
+    dest: number;
+    /** Game clock ticks of the next animation frame, next move, and when it was born. */
+    nextAni: number;
+    nextMove: number;
+    birthTime: number;
+}
+/** mm[]: monster number per slot (LASTMON = empty). */
+interface MonSlot {
+    monnum: number;
+    curx: number;
+    cury: number;
+}
+interface KeyStackEntry {
+    key: number;
+    seq: number;
+    frame: number;
+}
+export interface BresScroll {
+    dscroll: number;
+    ctr: number;
+    iters: number;
+}
+interface ScrollState {
+    /** Pixel offset of the screen edge within the edge block (mx, my). */
+    nx: number;
+    ny: number;
+    /** How far to move the screen this game tick; negative is up or left. */
+    totalx: number;
+    totaly: number;
+    /** Character's offset from the screen center (pixels; the C comment says blocks). */
+    distx: number;
+    disty: number;
+    /** SOLLEF/SOLRIG/SOLTOP/SOLBOT flags of the directions currently scrolling. */
+    inMotion: number;
+    maxX: number;
+    maxY: number;
+    minX: number;
+    minY: number;
+    leftStop: number;
+    rightStop: number;
+    upStop: number;
+    downStop: number;
+    /** Pixels waiting to be scrolled; whole 4 pixel steps are taken, 0..3 remain as the pan. */
+    movx: number;
+    movy: number;
+    /** 0..3 pixel hardware pan (an absolute position, not a delta). */
+    littleShiftx: number;
+    littleShifty: number;
+    /** 0xff where the scene allows scrolling that way (mirrored from the .gam file). */
+    up: number;
+    down: number;
+    left: number;
+    right: number;
+    bx: BresScroll;
+    by: BresScroll;
+}
+export interface TouchBlocks {
+    blks: [number, number][];
+    blknum: number[];
+}
+interface SoundHooks {
+    /** DoSound: returns true if a sound was started. */
+    play(n: number): boolean;
+}
+export interface World {
+    palette: Uint8Array;
+    map: Uint8Array;
+    mapMon: Uint8Array;
+    bg: Block[];
+    mblk: Block[];
+    cblk: Block[];
+    mon: Monster[];
+    chr: Character;
+    noMons: boolean;
+    ci: CharInfo;
+    mi: MonInfo[];
+    mm: MonSlot[];
+    firstEmptyMM: number;
+    monsolid: number;
+    mmSolid: number;
+    blkMon: {
+        blnum: number;
+        nexttime: number;
+    }[];
+    /** Per-block "birth this tick" flag (bit 0x4000 of Birthtime in the original). */
+    birthFlag: Uint8Array;
+    nxtchg: number[];
+    blkmap: Uint8Array;
+    mx: number;
+    my: number;
+    scroll: ScrollState;
+    clock: number;
+    keydn: Uint8Array;
+    keystack: KeyStackEntry[];
+    keystkptr: number;
+    curkey: number;
+    gclk: number;
+    joyOldTime: number;
+    joyOldBut: number;
+    sound: SoundHooks;
+    rand: () => number;
+    /** GetJoyPos: position 0 (center) or 1..8 clockwise from up, buttons bit 0/1. */
+    joystick?: () => {
+        pos: number;
+        buttons: number;
+    } | null;
+    jstickOn: boolean;
+    /**
+     * Not PLAYGAME's: told when the character's touch did something to map cell (x, y), shown as
+     * block `bnum` (it changed into its touch block, or was picked up). The web's tin heart
+     * tracking listens here; nothing in play reads it.
+     */
+    onTouched?: (x: number, y: number, bnum: number) => void;
+}
+export declare function newCharInfo(): CharInfo;
+/** Pads a block list with empty blocks so out-of-range numbers are harmless. */
+export declare function padBlocks(list: Block[] | undefined, count: number): Block[];
+export declare function mapBlock(w: World, x: number, y: number): number;
+export declare function mapMonAt(w: World, x: number, y: number): number;
+export declare function setMapMon(w: World, x: number, y: number, v: number): void;
+/** blks[0][blkmap[n]]: the currently displayed variant of background block n. */
+export declare function shownBlock(w: World, n: number): Block;
+export declare function bgBlock(w: World, n: number): Block;
+export declare function createWorld(map: GameMap, sound: SoundHooks, rand?: () => number): World;
+export declare const random: (w: World, n: number) => number;
+export declare const sign: (v: number) => 0 | 1 | -1;
+/** C int (16-bit) wrap. */
+export declare const i16: (v: number) => number;
+/** C unsigned int (16-bit). */
+export declare const u16: (v: number) => number;