@lewismoten/gamemaker-sandbox-engine 3.1.0 → 3.3.0

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

@@ -13,6 +13,8 @@ interface FliCanvas {
     /** 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;
@@ -34,6 +36,8 @@ export declare const FLI_CHUNK_MAX = 16000;
  * 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;
@@ -41,5 +45,12 @@ export declare function encodeFli(frames: Uint8Array[], palette: Uint8Array, opt
     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 {};

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

@@ -66,6 +66,13 @@ export declare function defaultHeader(): Uint8Array;
 export declare function newGame(title?: string): Game;
 export declare function parseGame(bytes: Uint8Array): Game;
 export declare function serializeGame(g: Game): Uint8Array;
+/**
+ * The game's name for showing outside DOS: the start scene's description, which holds CP437
+ * byte codes (the menu draws them with the PC font), as the Unicode a PC showed, without the
+ * spaces and frame characters (box lines, blocks) authors put around it to center or box it.
+ * Empty when there is none.
+ */
+export declare function gameTitle(game: Game): string;
 export declare function sceneKind(s: Scene): 'start' | 'end' | 'adventure' | 'unused';
 export declare function fileSlotsFor(s: Scene): readonly string[];
 export declare function slotExtensions(s: Scene): readonly string[];

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

@@ -1,4 +1,4 @@
-import { type Palette } from './palette';
+import { type Palette } from './palette.js';
 export interface IndexedImage {
     width: number;
     height: number;

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

@@ -0,0 +1,46 @@
+import { type IndexedImage } from './gif.js';
+import { type Palette } from './palette.js';
+/** A GIF read from as many of its bytes as there are so far. */
+interface PartialGif {
+    width: number;
+    height: number;
+    /** 6-bit VGA values (the DAC), as decodeGif() gives them. */
+    palette: Palette;
+    /** How many colors the file's color table has. */
+    colors: number;
+    interlaced: boolean;
+    /** Indexes in file order: row by row as stored (interlaced files store their passes in turn). */
+    stored: Uint8Array;
+    /** How many pixels of `stored` have arrived. */
+    received: number;
+    /** All the pixels have arrived. */
+    complete: boolean;
+    /** Pixel width/height ratio from the GIF89a header (1 when not given). */
+    aspect: number;
+}
+/** The picture row each stored row is, and how many rows it covers until finer rows arrive. */
+export declare function storedRows(height: number, interlaced: boolean): {
+    y: number;
+    span: number;
+}[];
+/**
+ * Reads the start of a GIF. Undefined until the header, color table and image descriptor
+ * have all arrived (a viewer can't draw anything before that).
+ */
+export declare function decodePartialGif(bytes: Uint8Array): PartialGif | undefined;
+/**
+ * The picture as far as it has arrived, rows in screen order. Rows not yet received are
+ * `blank`, or, in an interlaced file, a copy of the coarser row above them.
+ */
+export declare function partialPixels(g: PartialGif, blank?: number): Uint8Array;
+/**
+ * Encodes an image as GIF89a: interlaced if asked, with a color table just big enough for
+ * `colors` and an optional pixel aspect byte ((n + 15) / 64 = pixel width / height; 38 is
+ * the tall pixels of 320x200 and 640x400 on a 4:3 screen).
+ */
+export declare function encodeGif89(img: IndexedImage, opts?: {
+    interlaced?: boolean;
+    colors?: number;
+    aspect?: number;
+}): Uint8Array;
+export {};

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

@@ -0,0 +1,20 @@
+/** A JPEG decoded from as much of it as there is. */
+export interface PartialJpeg {
+    width: number;
+    height: number;
+    /** 1 (grayscale) or 3 (RGB). */
+    channels: number;
+    /** width * height * channels bytes. */
+    pixels: Uint8Array;
+    /** Per pixel: 1 once that part of the picture has arrived (a progressive file: all of it after its first scan). */
+    shown: Uint8Array;
+    progressive: boolean;
+    /** Scans that have fully arrived. */
+    scans: number;
+    complete: boolean;
+    /** Pixel width / height from the JFIF header (1 when not given). */
+    aspect: number;
+}
+export declare function isJpeg(bytes: Uint8Array): boolean;
+/** Decodes as much of a JPEG as there is; undefined until the frame header has arrived. */
+export declare function decodePartialJpeg(data: Uint8Array): PartialJpeg | undefined;

package/dist/types/gfx/colorVision.d.ts

@@ -0,0 +1,26 @@
+export type Rgb = [number, number, number];
+export type Vision = 'protan' | 'deutan' | 'tritan';
+/** Machado et al. 2009, Table 1, severity 1.0 (rows give linear R, G, B out). */
+export declare const MACHADO: {
+    readonly protan: readonly [0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998];
+    readonly deutan: readonly [0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881];
+    readonly tritan: readonly [1.255528, -0.076749, -0.178779, -0.078411, 0.930809, 0.147602, 0.004733, 0.691367, 0.3039];
+};
+/** An sRGB value (0..1) as linear light (0..1). */
+export declare const srgbToLinear: (c: number) => number;
+/** Linear light as an sRGB value (0..1), clamped first. */
+export declare function linearToSrgb(l: number): number;
+/** A linear RGB color as the given kind of color vision sees it, each channel clamped to 0..1. */
+export declare function simulateLinear(rgb: Rgb, matrix: readonly number[]): Rgb;
+/** Linear RGB to CIELAB (D65 white). */
+export declare function lab([r, g, b]: Rgb): Rgb;
+/** CIELAB back to linear RGB (unclamped). */
+export declare function unlab([L, a, b]: Rgb): Rgb;
+/** How far apart two CIELAB colors look (CIE76 delta E: about 2.3 is just noticeable side by side). */
+export declare const deltaELab: (a: Rgb, b: Rgb) => number;
+/** A color (0-255 per channel) as the given kind of color vision sees it. */
+export declare function simulateBytes(c: Rgb, v: Vision): Rgb;
+/** How far apart two colors (0-255 per channel) look: CIE76 delta E; about 2 is just noticeable, over 25 plainly different. */
+export declare const deltaEBytes: (a: Rgb, b: Rgb) => number;
+/** A whole VGA palette (768 bytes of 6-bit values) as the given kind of color vision sees it. */
+export declare function simulatePalette(pal: Uint8Array, v: Vision): Uint8Array;

package/dist/types/gfx/screen.d.ts

@@ -1,6 +1,10 @@
 export declare const SIZEX = 320;
 export declare const SIZEY = 200;
 export declare class Screen {
+    /** Observer metadata only: PLAYGAME's CropScreen is active (no effect on rendering). */
+    dosCropped: boolean;
+    /** Level number for screen captures; retained during function-key screens. */
+    sceneNumber: number;
     readonly pixels: Uint8Array<ArrayBuffer>;
     /** Palette currently shown by the "DAC" (6-bit components). */
     readonly palette: Uint8Array<ArrayBuffer>;

package/dist/types/index.d.ts

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

package/dist/types/input/keyboard.d.ts

@@ -1,4 +1,4 @@
-import { ArrowChords } from './chords';
+import { ArrowChords } from './chords.js';
 export interface TypedKey {
     scan: number;
     /** ASCII code (0 for extended keys such as arrows). */

package/dist/types/{dosPlayer → player}/patchRules.d.ts

@@ -1,4 +1,4 @@
-import { type FramePatch, type PatchEntry } from './patchTable';
+import { type FramePatch, type PatchEntry } from './patchTable.js';
 export type PatchValue = string | number | number[];
 /** A project's DOS player choices: patch id -> value (patchTable.ts says what each takes). */
 export type PlayerPatches = Record<string, PatchValue>;

package/dist/types/{dosPlayer → player}/patchTable.d.ts

@@ -1,7 +1,7 @@
 /** The editor panel's groups. */
-export type PatchGroup = 'words' | 'colors' | 'frames' | 'positions' | 'times' | 'keys';
-/** The screen a patch shows on, which the panel previews while it is edited. */
-export type PatchScreen = 'menu' | 'hiscores' | 'newHiscore' | 'status' | 'load' | 'save' | 'drop' | 'help' | 'text' | 'missing' | 'about' | 'play' | 'all';
+export type PatchGroup = 'words' | 'colors' | 'frames' | 'positions' | 'times' | 'keys' | 'play';
+/** The screen a patch shows on, which the panel previews while it is edited ('gameplay': every scene, no preview). */
+export type PatchScreen = 'menu' | 'hiscores' | 'newHiscore' | 'status' | 'load' | 'save' | 'drop' | 'help' | 'text' | 'missing' | 'about' | 'play' | 'gameplay' | 'all';
 /**
  * The color targets RGBdata::Match looks for, by name, with the DGROUP offset of each object
  * (what a color selector's push imm16 names).
@@ -16,10 +16,12 @@ export declare const COLOR_TARGETS: {
     readonly hsGreen: 5632;
 };
 export type ColorName = keyof typeof COLOR_TARGETS;
-/** One immediate in the code: its file offset and size (1: push imm8, sign-extended; 2: imm16). */
+/** One immediate in the code: its file offset and size (1: imm8, sign-extended; 2: imm16). */
 export interface ImmField {
     offset: number;
     size: number;
+    /** It holds the value's negative (the -MAXGRAV of `if (tx < -MAXGRAV) tx = -MAXGRAV`). */
+    negate?: true;
 }
 interface Base {
     id: string;
@@ -27,7 +29,8 @@ interface Base {
     screen: PatchScreen;
     label: string;
     note?: string;
-    safety: 'safe' | 'caution';
+    /** experimental: changes how every scene plays (the `play` group); test it in DOSBox. */
+    safety: 'safe' | 'caution' | 'experimental';
     /** The web player shows it too (false: DOS only). */
     web: boolean;
 }

package/dist/types/text/cp437.d.ts

@@ -0,0 +1,6 @@
+/** Converts a string written with Unicode symbols, accents and box characters to CP437 byte codes. */
+export declare function toCp437(s: string): string;
+/** Converts CP437 byte strings (including binary.ts's Latin-1 aliases), never Unicode prose. */
+export declare function fromCp437(s: string): string;
+/** A DOS text file as Unicode, retaining ASCII controls (CR/LF, TAB, NUL, ^Z) for its reader. */
+export declare function cp437Text(bytes: Uint8Array): string;