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

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

@@ -0,0 +1,237 @@
+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;
+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;
+/** 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;
+}
+/** 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;
+    /** 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. */
+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;

package/dist/types/formats/binary.d.ts

@@ -0,0 +1,44 @@
+export declare class Reader {
+    readonly bytes: Uint8Array;
+    offset: number;
+    constructor(bytes: Uint8Array, offset?: number);
+    get length(): number;
+    get eof(): boolean;
+    skip(n: number): this;
+    u8(): number;
+    i8(): number;
+    u16(): number;
+    i16(): number;
+    u32(): number;
+    i32(): number;
+    /** Copies n bytes (zero padded when the source is short). */
+    bytesOf(n: number): Uint8Array;
+    /** Reads a fixed size, NUL terminated string field. */
+    cstr(n: number): string;
+}
+export declare class Writer {
+    private buf;
+    offset: number;
+    constructor(initial?: number);
+    private ensure;
+    u8(v: number): this;
+    i8(v: number): this;
+    u16(v: number): this;
+    i16(v: number): this;
+    u32(v: number): this;
+    i32(v: number): this;
+    bytes(b: ArrayLike<number>, length?: number): this;
+    /** Writes a string into a fixed size NUL padded field (truncated to leave room for the NUL). */
+    cstr(s: string, length: number): this;
+    /**
+     * Writes a fixed size string field. When the text is unchanged the original raw
+     * bytes (including any garbage after the NUL) are kept so files round-trip exactly.
+     */
+    cstrOver(s: string, original: Uint8Array | undefined, length: number): this;
+    toBytes(): Uint8Array;
+}
+/** Decodes a NUL terminated string; the whole array when there is no NUL. */
+export declare function cString(bytes: Uint8Array): string;
+export declare function latin1Text(bytes: Uint8Array): string;
+/** One byte per character (low 8 bits of each UTF-16 code unit). */
+export declare function textBytes(text: string): Uint8Array;

package/dist/types/formats/blocks.d.ts

@@ -0,0 +1,52 @@
+export declare const BLEN = 20;
+export declare const BLOCK_SIZE = 420;
+export declare const BACKBL = 150;
+export declare const MONBL = 100;
+export declare const CHARBL = 50;
+export declare const TRANSPARENT = 255;
+export declare const SOLTOP = 1;
+export declare const SOLRIG = 2;
+export declare const SOLBOT = 4;
+export declare const SOLLEF = 8;
+export type BlockKind = 'bbl' | 'mbl' | 'cbl';
+export declare const BLOCK_COUNTS: Record<BlockKind, number>;
+export interface Block {
+    /** 20x20 palette indices, row major (y * 20 + x). 255 is transparent for sprites. */
+    pixels: Uint8Array;
+    /** Monster number to give birth to (background blocks). */
+    birthMon: number;
+    /** Clock ticks between monster births; 0 = never. */
+    birthTime: number;
+    xtra: Uint8Array;
+    /** Solid sides: SOLTOP | SOLRIG | SOLBOT | SOLLEF. */
+    solid: number;
+    /** Sides that hurt (unused by playgame, kept for fidelity). */
+    hitpt: number;
+    /** Score points when touched. */
+    scorePts: number;
+    /** Hit points added (negative hurts) when touched. */
+    chHitPt: number;
+    /** Block this one animates into after ntime ticks (== self means never). */
+    nextBl: number;
+    ntime: number;
+    /** Block this one becomes when touched (== self means unchanged). */
+    touchBl: number;
+    /** Gravity direction bits: 1 up, 2 right, 4 down, 8 left. */
+    grav: number;
+    /** Non-zero if the character can pick this block up. */
+    obj: number;
+    /** Which counter is affected: 1 lives, 3 money, 5..19 sequence counters, 20..29 extra counters. */
+    effect: number;
+    /** Amount the effect counter changes. */
+    eamt: number;
+}
+export declare function emptyBlock(index: number, transparent?: boolean): Block;
+export declare function parseBlocks(bytes: Uint8Array, count: number): Block[];
+export declare function serializeBlocks(blocks: Block[]): Uint8Array;
+export declare function newBlockSet(kind: BlockKind): Block[];
+/**
+ * Pixel lookup for a block drawn with one of the 8 orientations used by playgame
+ * (rotations/mirrors; see Sdrawspbloc in PLAYGAME.C). Returns the source index for
+ * destination (x, y).
+ */
+export declare function orientIndex(orient: number, x: number, y: number): number;

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

@@ -0,0 +1,65 @@
+export declare const MAXSEQ = 20;
+export declare const MAXFRAME = 10;
+export declare const MAXINV = 10;
+export declare const METERS: number;
+export declare const INF_REPEAT = 32767;
+export declare const CHR_RECORD_SIZE = 3784;
+export declare const IDLESEQ = 0;
+export declare const DIESEQ = 1;
+export declare const HURTSEQ = 2;
+export declare const PICKUPSEQ = 3;
+export declare const DROPSEQ = 4;
+export declare const SEQUENCE_NAMES: string[];
+export interface Frame {
+    /** Pixel offset from the previous frame. */
+    x: number;
+    y: number;
+    /** Low nibble: orientation of top block. High nibble: orientation of bottom block. */
+    orient: number;
+    /** Top block number (CHARBL = none). When pic2 == MONBL, pic1 is the monster to give birth to. */
+    pic1: number;
+    /** Bottom block number. CHARBL+1 marks the end of the sequence. */
+    pic2: number;
+    /** Clock ticks (1/18.2 s) to wait before the next frame. */
+    pause: number;
+    extra: Uint8Array;
+}
+export interface Sequence {
+    frames: Frame[];
+    /** Activation key: high byte = PC scan code, low byte = ASCII. */
+    key: number;
+    /** Sound effect number (>= 30 means none). */
+    sound: number;
+    on: number;
+    /** Background block required in inventory to use this sequence (150 = none). */
+    bloc: number;
+    /** Non-zero: sequence cannot be interrupted. */
+    ground: number;
+    /** Joystick button (0 any, 1/2 button, 4 none). */
+    jstkBut: number;
+    /** Joystick direction (0 none, 1-8 directions, 9 any). */
+    jstkMov: number;
+    /** Non-zero: one run per key press. */
+    norepeat: number;
+    /** Non-zero: motion adds to momentum instead of moving directly. */
+    momentum: number;
+    xtra: Uint8Array;
+}
+export interface Character {
+    sequences: Sequence[];
+    x: number[];
+    y: number[];
+    cframe: number;
+    cseq: number;
+    inv: Uint8Array;
+    /** Repetition counters: 0 hit points, 1 lives, 3 money, 5..19 sequence counters, 20..29 extra. */
+    meter: number[];
+    /** Raw bytes of the unused second player record. */
+    rest: Uint8Array;
+}
+export declare function parseCharacter(bytes: Uint8Array): Character;
+export declare function serializeCharacter(c: Character): Uint8Array;
+export declare function emptyFrame(end?: boolean): Frame;
+export declare function newCharacter(): Character;
+/** Number of frames before the end marker. */
+export declare function frameCount(s: Sequence): number;

package/dist/types/formats/cmf.d.ts

@@ -0,0 +1,33 @@
+export declare const CMF_GAMEMAKER_CLOCK = 146;
+interface CmfFile {
+    version: number;
+    ticksPerBeat: number;
+    /** Ticks per second the song was converted for. */
+    clockTicks: number;
+    channelUsed: Uint8Array;
+    /** 16 byte SBI instrument records. */
+    instruments: Uint8Array[];
+    basicTempo: number;
+    /** The event stream (music block to end of file). */
+    music: Uint8Array;
+}
+export declare function isCmf(bytes: Uint8Array): boolean;
+export declare function parseCmf(bytes: Uint8Array): CmfFile;
+/** One event of a song: when (in ticks from the start) and its MIDI bytes. */
+export interface CmfEvent {
+    tick: number;
+    data: number[];
+}
+interface CmfSong {
+    /** 16-byte SBI FM instruments; instrument n starts on MIDI channel n. */
+    instruments: Uint8Array[];
+    events: CmfEvent[];
+    ticksPerBeat?: number;
+    basicTempo?: number;
+}
+/**
+ * Writes a Creative Music File at Game-Maker's 146 ticks a second (PLAYGAME refuses any
+ * other clock). Events are sorted by tick; the song ends with an end-of-track marker.
+ */
+export declare function encodeCmf(song: CmfSong): Uint8Array;
+export {};

package/dist/types/formats/cmfEdit.d.ts

@@ -0,0 +1,53 @@
+import { type Ev, type Note, type CmfSong } from './cmfSong.js';
+/** Notes on one channel, by start. */
+export declare function channelNotes(song: CmfSong, ch: number): Note[];
+export declare function addNote(song: CmfSong, ch: number, key: number, start: number, len: number, vel?: number): Note;
+export declare const DEFAULT_VELOCITY = 100;
+/** Clamps a velocity to what a note-on can carry (0 would turn the note off). */
+export declare function clampVelocity(v: number): number;
+/** Sets how loud notes play (1..127). Unchanged notes keep their bytes. */
+export declare function setVelocity(notes: Iterable<Note>, v: number): void;
+/** Scales velocities by a factor (and/or adds an offset), clamped to 1..127. */
+export declare function scaleVelocities(notes: Iterable<Note>, factor: number, add?: number): number;
+/**
+ * The carrier's total level (TL, 0 loudest .. 63 silent) SBFMDRV plays a note at, for the
+ * instrument's own TL: 63 - floor((velocity + 128) * (63 - TL) / 256). Velocity 127 keeps
+ * the level nearly as written; velocity 1 is about half as loud in TL steps.
+ */
+export declare function velocityLevel(velocity: number, tl: number): number;
+/** Moves and/or resizes a note (start, length in ticks, note number). */
+export declare function setNote(song: CmfSong, n: Note, start: number, len: number, key: number): void;
+export declare function deleteNotes(song: CmfSong, notes: Iterable<Note>): void;
+/** The song end never comes before the last event. */
+export declare function extendEnd(song: CmfSong): void;
+export declare function lastEventTick(song: CmfSong): number;
+/** Moves where the song repeats (never before the last event). */
+export declare function setEnd(song: CmfSong, tick: number): void;
+/** Mode in effect at the start (before any note). */
+export declare function startMode(song: CmfSong): boolean;
+export declare function modeChanges(song: CmfSong): Ev[];
+/** Sets melody (false) or rhythm (true) mode from the start of the song. */
+export declare function setStartMode(song: CmfSong, rhythm: boolean): void;
+/** Instrument changes on a channel, by time. */
+export declare function programChanges(song: CmfSong, ch: number): Ev[];
+/** The instrument a channel starts with (its first note's instrument). */
+export declare function startProgram(song: CmfSong, ch: number): number;
+/** Picks the instrument a channel starts with. */
+export declare function setStartProgram(song: CmfSong, ch: number, program: number): void;
+/** Adds (or changes) an instrument change on a channel at a time. */
+export declare function setProgramAt(song: CmfSong, ch: number, tick: number, program: number): Ev;
+export declare function removeEvent(song: CmfSong, ev: Ev): void;
+/** Channels that have notes or instrument changes. */
+export declare function usedChannels(song: CmfSong): number[];
+/** Removes a channel's notes and events (mode switches stay: they affect the whole song). */
+export declare function removeChannel(song: CmfSong, ch: number): void;
+/** Changes the speed: every time is multiplied by factor (the beat length too). */
+export declare function scaleTime(song: CmfSong, factor: number): void;
+/** Removes events PlayIt ignores (pitch bend, other controllers, stray note-offs...). */
+export declare function stripIgnored(song: CmfSong): number;
+export declare function ignoredCount(song: CmfSong): number;
+/**
+ * Which FM voice a channel sounds on, given the mode: melody mode has voices 0..8 on
+ * channels 0..8; rhythm mode has 0..5 and drums on 11..15. Other channels are silent.
+ */
+export declare function channelSounds(ch: number, rhythm: boolean): boolean;

package/dist/types/formats/cmfPreview.d.ts

@@ -0,0 +1,19 @@
+import { type CmfSong } from './cmfSong.js';
+export interface Preview {
+    bytes: Uint8Array;
+    /** Length of one pass of the preview in ticks. */
+    length: number;
+    /** Song tick (or -1 in a gap) for a tick since the preview started. */
+    songTick: (t: number) => number;
+}
+/**
+ * A copy of the song to listen to: some channels muted, starting from a point, or looping a
+ * region. Built from the same events, so it plays through the same PlayIt code.
+ */
+export declare function buildPreview(song: CmfSong, opts?: {
+    muted?: Set<number>;
+    from?: number;
+    loop?: [number, number];
+}): Preview;
+/** A tiny song that plays one note with an instrument (for "try it"). */
+export declare function auditionSong(song: CmfSong, ch: number, program: number, key: number, ticks?: number, vel?: number): Uint8Array;

package/dist/types/formats/cmfSong.d.ts

@@ -0,0 +1,74 @@
+type EvType = 'on' | 'off' | 'program' | 'mode' | 'raw';
+/** One event of the stream. */
+export interface Ev {
+    type: EvType;
+    tick: number;
+    /** Order among events at the same tick (original stream order; new events go around them). */
+    seq: number;
+    /** MIDI channel 0..15. */
+    ch: number;
+    /** on/off: note number; program: instrument number; mode: 0 = melody, otherwise rhythm. */
+    a: number;
+    /** on: velocity 1..127 (how loud; 0 would be a note off); off: the release byte (kept as read). */
+    b: number;
+    /** off: written as 0x8n (8) or as 0x9n with velocity 0 (9). */
+    fn?: 8 | 9;
+    /** notes: whether the original wrote a status byte (undefined for new events). */
+    status?: boolean;
+    /** A stray 0x8n/0x9n status byte written just before a non-note event. */
+    prefix?: number;
+    /** raw: the whole event. */
+    bytes?: number[];
+    /** The original encoding of the delta time before this event. */
+    delta?: number[];
+}
+export interface Note {
+    on: Ev;
+    /** No off event: the note sounds until it is cut or the song repeats. */
+    off?: Ev;
+}
+export interface CmfSong {
+    /** Everything before the instruments (header, title strings); fields are rewritten on save. */
+    header: Uint8Array;
+    ticksPerBeat: number;
+    clockTicks: number;
+    channelUsed: Uint8Array;
+    /** Which channels had events when read (to keep channelUsed as it was). */
+    hadEvents: boolean[];
+    /** 16-byte SBI records; instrument n starts on channel n. */
+    instruments: Uint8Array[];
+    /** Bytes between the instruments and the music (normally none). */
+    gap: Uint8Array;
+    /** Silence before the song starts again when it repeats (the first delta). */
+    leadIn: number;
+    leadInBytes?: number[];
+    notes: Note[];
+    /** program, mode, raw and stray off events. */
+    events: Ev[];
+    /** Where the song repeats. */
+    end: {
+        tick: number;
+        delta?: number[];
+        bytes: number[];
+    };
+    /** Counter for ordering new events. */
+    counter: number;
+}
+export declare const RHYTHM_CHANNELS: number[];
+export declare const DRUM_NAMES: Record<number, string>;
+export declare function noteEnd(song: CmfSong, n: Note): number;
+/** Reads a CMF the way PlayIt() does. */
+export declare function readSong(bytes: Uint8Array): CmfSong;
+/** All events in stream order. */
+export declare function streamEvents(song: CmfSong): Ev[];
+/** Writes the song back to a CMF file. */
+export declare function writeSong(song: CmfSong): Uint8Array;
+/**
+ * The driver calls PlayIt() makes over `ticks` timer ticks, as "tick:call" strings
+ * (on/off/program/mode/restart). With `velocity`, note-ons end in "@velocity" (how loud
+ * SBFMDRV plays them). Two songs that give the same trace with velocities sound the same.
+ */
+export declare function traceMusic(music: Uint8Array, ticks: number, velocity?: boolean): string[];
+/** The music block of a CMF file. */
+export declare function musicOf(bytes: Uint8Array): Uint8Array;
+export {};

package/dist/types/formats/fli.d.ts

@@ -0,0 +1,56 @@
+interface FliAnimation {
+    width: number;
+    height: number;
+    frameCount: number;
+    /** Delay per frame in 1/70 s (FLI) — FLC files are converted from milliseconds. */
+    speed: number;
+    /** Byte offsets of each frame record. */
+    frames: number[];
+    bytes: Uint8Array;
+}
+interface FliCanvas {
+    pixels: Uint8Array;
+    /** 6-bit palette, 768 bytes. */
+    palette: Uint8Array;
+}
+/** A picture bigger than this (4096 x 4096) is a lie in the header, not an animation: refused before any canvas is made. */
+export declare const FLI_MAX_PIXELS: number;
+export declare function isFli(bytes: Uint8Array): boolean;
+export declare function parseFli(bytes: Uint8Array): FliAnimation;
+export declare function newFliCanvas(anim: FliAnimation): FliCanvas;
+/** Applies frame n to the canvas. Returns true if the palette changed. */
+export declare function applyFliFrame(anim: FliAnimation, n: number, c: FliCanvas): boolean;
+/**
+ * The most bytes a chunk (with its 6-byte header) may take. PLAYGAME reads an .FLI through
+ * FileRead (code/DRV/FILECLSS.CPP): one buffer of up to 0xFFF0 bytes, 2 bytes smaller each
+ * time `new` fails, and FrameHeader::View (code/Image/FLI/FLI.CPP) hands each chunk to its
+ * decoder only when the whole chunk fits in that buffer (FileRead::Peek). With a game loaded
+ * through XFERPLAY there is less memory, and a 63K chunk drew garbage where a 32.7K one
+ * played. 16,000 bytes is under half of that 32.7K, so it fits with a quarter of the 64K
+ * buffer PLAYGAME asks for; splitting a full 64,000-pixel frame into bands this size costs a
+ * few dozen bytes of headers.
+ */
+export declare const FLI_CHUNK_MAX = 16000;
+/**
+ * Writes an Autodesk Animator .FLI (Game-Maker shows 320x200): each frame run-length coded
+ * or as the lines that changed, the 6-bit palette in the first frame, and a closing "ring"
+ * frame that leads back to the start. No chunk is bigger than FLI_CHUNK_MAX: a bigger frame
+ * is split into bands of lines. `speed` is the delay after each frame in 1/70 s.
+ * `noLoopFrame` leaves the ring frame out: PLAYGAME's FLI::View (code/Image/FLI/FLI.CPP)
+ * plays only the header's frame count, so the ring frame is never shown there.
+ */
+export declare function encodeFli(frames: Uint8Array[], palette: Uint8Array, opts?: {
+    width?: number;
+    height?: number;
+    speed?: number;
+    /** A palette per frame (fades, flashes); changes are stored where they happen. */ palettes?: Uint8Array[];
+    /** Code runs of a color inside changed spans as run packets too (smaller deltas for drawn art). */ runs?: boolean;
+    /** Leave out the closing ring frame (nothing that plays the file shows it). */ noLoopFrame?: boolean;
+    /**
+     * After the first frame, send a palette change only for the colors the frame draws (a fade
+     * of a picture that uses 90 colors sends 90, not 256); a color the player still holds
+     * stale goes out in the first frame that draws it. What shows is the same.
+     */
+    sparsePalettes?: boolean;
+}): Uint8Array;
+export {};

package/dist/types/formats/fliFrames.d.ts

@@ -0,0 +1,18 @@
+export interface FliFrame {
+    pixels: Uint8Array;
+    /** 6-bit palette, 768 bytes. */
+    palette: Uint8Array;
+}
+export interface FliFrames {
+    width: number;
+    height: number;
+    /** Delay after each frame in 1/70 s. */
+    speed: number;
+    frames: FliFrame[];
+}
+/** Plays the animation through, keeping a copy of every frame (not the closing ring frame). */
+export declare function decodeFliFrames(bytes: Uint8Array): FliFrames;
+/** Writes the frames as an .FLI; palette changes are stored on the frames where they happen. */
+export declare function encodeFliFrames(a: FliFrames): Uint8Array;
+/** Places a picture on a width x height frame: centered, cropped or padded with color 0. */
+export declare function fitPicture(pixels: Uint8Array, pw: number, ph: number, width: number, height: number): Uint8Array;

package/dist/types/formats/fliLimits.d.ts

@@ -0,0 +1,13 @@
+type FliFaultKind = 'big' | 'packets' | 'black' | 'type';
+interface FliFault {
+    kind: FliFaultKind;
+    /** The frame it is in (0 the first; the last is the ring frame back to the start). */
+    frame: number;
+    /** The chunk's size with its header ('big'), the packet count ('packets') or the chunk type ('type'). */
+    value: number;
+}
+/** Every fault in an .FLI, the first of each kind per frame. A file that isn't an FLI has none. */
+export declare function fliFaults(bytes: Uint8Array): FliFault[];
+/** A fault in words, for a finding or a health issue. */
+export declare function describeFliFault(f: FliFault): string;
+export {};