@lewismoten/gamemaker-sandbox-tools 3.1.0 → 3.4.0

package/dist/types/kit/levelGen/needs.d.ts

@@ -0,0 +1,44 @@
+import { type Role, type RoleMap } from '../blockRoles.js';
+export type GenKind = 'dungeon' | 'forest' | 'home' | 'shop' | 'castle' | 'town' | 'overworld' | 'platform';
+export interface KindInfo {
+    id: GenKind;
+    label: string;
+    blurb: string;
+    /** The smallest area it can draw in (blocks). */
+    min: {
+        w: number;
+        h: number;
+    };
+    /** Roles the generator cannot run without. */
+    must: Role[];
+    /** Roles used when set; without them that part is skipped. */
+    want: {
+        role: Role;
+        use: string;
+        without: string;
+    }[];
+}
+export declare const KINDS: readonly KindInfo[];
+export declare const kindInfo: (kind: GenKind) => KindInfo;
+export interface NeedItem {
+    role: Role;
+    label: string;
+    must: boolean;
+    /** How many blocks hold the role. */
+    count: number;
+    /** For a "want": what it adds, and what happens without it. */
+    use?: string;
+    without?: string;
+}
+export interface NeedsReport {
+    kind: GenKind;
+    items: NeedItem[];
+    /** Every "must" is set. */
+    ok: boolean;
+    /** Plain words for a person when it is not ok (what to mark in the block editor). */
+    message: string;
+    /** Lines for the "wants" that are missing (skipped parts). */
+    skipped: string[];
+}
+/** Which of a kind's roles are set in `roles`, and whether it can run. */
+export declare function checkNeeds(kind: GenKind, roles: RoleMap): NeedsReport;

package/dist/types/kit/levelGen/overworld.d.ts

@@ -0,0 +1,21 @@
+import { type Area, type Stream } from './grid.js';
+import type { SceneLink } from './town.js';
+export declare const OVERWORLD_MIN: {
+    w: number;
+    h: number;
+};
+export interface Overworld {
+    area: Area;
+    entry: number;
+    exit: number;
+    links: SceneLink[];
+}
+export interface OverworldUses {
+    tree: boolean;
+    rock: boolean;
+    decor: boolean;
+    /** The map wraps over its edges: the land lines up across the seam. */
+    wrap: boolean;
+}
+/** An overworld filling a w by h area (at least 40 by 40). */
+export declare function overworld(w: number, h: number, r: Stream, u: OverworldUses): Overworld;

package/dist/types/kit/levelGen/platform.d.ts

@@ -0,0 +1,59 @@
+import { type Area, type Stream } from './grid.js';
+import type { HeroPhysics } from './jumpModel.js';
+import type { LockInfo } from './props.js';
+export interface PlatformOptions {
+    physics: HeroPhysics;
+    /** 0.1 to 1: the share of the hero's most (gap width and step height) the layout asks of him. */
+    difficulty: number;
+    /** Which blocks the set has. */
+    ladder: boolean;
+    hazard: boolean;
+    /** A solid-on-top-only ledge block. */
+    ledge: boolean;
+    /** The top of the ground is a different block (wall-top). */
+    cap: boolean;
+    /** Lock numbers that have both a locked-door block and a key block (the first is used). */
+    pairs: number[];
+    treasure: boolean;
+    life: boolean;
+    monsters: number[];
+    decorate: boolean;
+}
+export interface PlatformProof {
+    /** The exit can be reached by jump math (with the key picked up first when there is a lock). */
+    exit: boolean;
+    /** Every coin, the key and the heart were touched on some move. */
+    collectable: boolean;
+    /** With the lock shut he cannot reach the exit, and he can reach the key. True with no lock. */
+    lockHolds: boolean;
+}
+export interface PlatformLayout {
+    area: Area;
+    entry: number;
+    exit: number;
+    locks: LockInfo[];
+    /** Every cell of each locked door (a tall one), as area indexes. */
+    doorCells: number[];
+    treasure: number[];
+    life?: number;
+    monsters: {
+        cell: number;
+        monnum: number;
+    }[];
+    notes: string[];
+    proof: PlatformProof;
+    /** The difficulty the layout was finally drawn with (lower than asked when a harder one could not be proven). */
+    difficulty: number;
+    /** What the hero can do, in cells: the highest step and the widest gap on level ground. */
+    can: {
+        rise: number;
+        gap: number;
+    };
+    /** The tallest step and widest pit (cells) the layout actually asks him to jump (ladders and spikes not counted). */
+    asked: {
+        rise: number;
+        gap: number;
+    };
+}
+/** A side view filling a w by h area (at least 40 by 20). Draws again, easier, when a layout cannot be proven. */
+export declare function platform(w: number, h: number, r: Stream, o: PlatformOptions): PlatformLayout;

package/dist/types/kit/levelGen/platformCap.d.ts

@@ -0,0 +1,13 @@
+import type { HeroPhysics } from './jumpModel.js';
+export interface Capability {
+    /** The highest step up he can jump onto (cells), with no gap. */
+    maxRise: number;
+    /** The widest gap he clears on level ground (cells). */
+    maxGap: number;
+    /** `gapAt[r]`: the widest gap he clears to ground r cells higher (r from 0 to maxRise); 0 where none. */
+    gapAt: number[];
+    /** The widest run of spikes, one block high, he clears on level ground (cells). */
+    maxSpikes: number;
+}
+/** What the hero can cross; remembered for the same walk and jump. */
+export declare function capability(p: HeroPhysics): Capability;

package/dist/types/kit/levelGen/platformReach.d.ts

@@ -0,0 +1,37 @@
+import { type Area } from './grid.js';
+import { type HeroPhysics } from './jumpModel.js';
+/** One move of a route: from the node (X pixels, feet row) before it to the node it leads to. */
+export interface Step {
+    kind: 'walk' | 'jump' | 'fall' | 'climb';
+    dir: -1 | 0 | 1;
+    /** Jump or fall: how many ticks he steers. */
+    steerTicks: number;
+    from: {
+        X: number;
+        row: number;
+    };
+    to: {
+        X: number;
+        row: number;
+    };
+    /** Jump or fall: where the arc starts (a fall begins past the node's edge, after he has walked on to here). */
+    startX: number;
+}
+export interface Reach {
+    /** Cells the hero's body overlapped on some move he can make (row-major, as the area). */
+    touched: Uint8Array;
+    /** Cells he can stand in (his feet cell). */
+    stood: Uint8Array;
+    /** The moves, from the start to the first node standing in `cell` (a feet cell), when the search was asked to keep them. */
+    routeTo(cell: number): Step[] | undefined;
+}
+export interface ReachOptions {
+    /** A feet cell: stop as soon as he can stand there. */
+    goal?: number;
+    /** Keep the moves, so `routeTo` can say how to get somewhere. */
+    route?: boolean;
+}
+/** Plays every move from `start` (the feet cell) and says where he gets. `locksOpen`: the locked doors are open. */
+export declare function reachFrom(a: Area, p: HeroPhysics, start: number, locksOpen: boolean, opt?: ReachOptions): Reach;
+/** Whether a cell was touched. */
+export declare const touchedAt: (r: Reach, cell: number) => boolean;

package/dist/types/kit/levelGen/props.d.ts

@@ -0,0 +1,37 @@
+import { type Area, type Stream } from './grid.js';
+export interface LockInfo {
+    /** The door's cell and its key's cell (area-local indexes), and the lock number they share. */
+    cell: number;
+    key: number;
+    pair: number;
+    /** 0 is the nearest to the entry. */
+    order: number;
+}
+export interface PropsOptions {
+    /** Lock numbers that have both a locked-door block and a key block. */
+    pairs: number[];
+    treasure: boolean;
+    life: boolean;
+    /** Monster numbers to place (empty: none). */
+    monsters: number[];
+}
+export interface Props {
+    locks: LockInfo[];
+    treasure: number[];
+    life?: number;
+    monsters: {
+        cell: number;
+        monnum: number;
+    }[];
+}
+/** Adds the props to `a` (changing its cell codes) and says what went where. Uses its own random stream. */
+export declare function addProps(a: Area, entry: number, exit: number, r: Stream, o: PropsOptions): Props;
+/**
+ * Plays the keys out on the cell codes: from the entry, a locked door opens once the hero has picked up its
+ * key. `strict` also asks that each key can be reached with its own lock and every later one shut
+ * (the key-before-lock rule). Everything picked up and the exit must be reachable at the end.
+ */
+export declare function proveKeys(a: Area, entry: number, exit: number, locks: LockInfo[], pickups: number[]): {
+    ok: boolean;
+    strict: boolean;
+};

package/dist/types/kit/levelGen/town.d.ts

@@ -0,0 +1,24 @@
+import { type Area, type Stream } from './grid.js';
+export declare const TOWN_MIN: {
+    w: number;
+    h: number;
+};
+export interface SceneLink {
+    /** The door or site (area-local cell). */
+    cell: number;
+    /** What it could lead to. */
+    kind: 'home' | 'shop' | 'town' | 'dungeon' | 'castle' | 'overworld';
+    label: string;
+}
+export interface Town {
+    area: Area;
+    entry: number;
+    exit: number;
+    links: SceneLink[];
+}
+export interface TownUses {
+    tree: boolean;
+    decor: boolean;
+}
+/** A town filling a w by h area (at least 40 by 28). */
+export declare function town(w: number, h: number, r: Stream, u: TownUses): Town;

package/dist/types/kit/levelGrid.d.ts

@@ -0,0 +1,16 @@
+export declare class Grid {
+    readonly width: number;
+    readonly height: number;
+    private readonly cells;
+    constructor(width: number, height: number);
+    /** One block. */
+    put(x: number, y: number, ch: string): this;
+    /** A rectangle of `ch`, w blocks wide and h high. */
+    fill(x: number, y: number, w: number, h: number, ch: string): this;
+    /** Blocks `x0` to `x1` (both included) along row `y`. */
+    row(y: number, x0: number, x1: number, ch: string): this;
+    /** Blocks `y0` to `y1` (both included) down column `x`. */
+    col(x: number, y0: number, y1: number, ch: string): this;
+    /** The level as rows of text, for StarterMap. */
+    rows(): string[];
+}

package/dist/types/kit/levelPicture.d.ts

@@ -0,0 +1,9 @@
+import type { Block } from '@lewismoten/gamemaker-sandbox-engine/formats/blocks';
+import type { GameMap } from '@lewismoten/gamemaker-sandbox-engine/formats/map';
+import type { Monster } from '@lewismoten/gamemaker-sandbox-engine/formats/monster';
+import { Pixels } from './pixels.js';
+export declare function renderRegion(map: GameMap, bg: Block[], mbl: Block[], mons: Monster[], x0: number, y0: number, w: number, h: number, extra?: {
+    pixels: Uint8Array;
+    x: number;
+    y: number;
+}[]): Pixels;

package/dist/types/kit/menuVersion.d.ts

@@ -0,0 +1,7 @@
+/** Where a game wants its version instead of the corner: the text's top-left, or false for none. */
+export type MenuVersionSpot = {
+    x?: number;
+    y?: number;
+} | false;
+/** Stamps "v<version>" on the menu picture among `files` (a disk's files, lower-case names). */
+export declare function stampMenuVersion(files: Map<string, Uint8Array>, version: string, spot?: MenuVersionSpot): void;

package/dist/types/kit/microText.d.ts

@@ -0,0 +1,18 @@
+import { type MicroGlyphs } from '../microFont.js';
+import { Pixels } from './pixels.js';
+export interface MicroTextOptions {
+    glyphs?: MicroGlyphs;
+    fallback?: string;
+    /** Include the final one-pixel spacer in the returned advance. */
+    trailingGap?: boolean;
+    /** Match a glyph before uppercasing it (for symbols such as µ). */
+    glyphCase?: boolean;
+    /** Consumer-owned multicolor glyphs; clear pixels are 255. */
+    custom?: (character: string) => Pixels | undefined;
+}
+export declare function createMicroText(options?: MicroTextOptions): (p: Pixels, x: number, y: number, s: string, col: number, scale?: number) => number;
+/** Legacy cell advance with the final spacer omitted (including the historical empty-string value). */
+export declare const microAdvance: (s: string, scale?: number) => number;
+/** Visible-cell width; empty strings have no ink. */
+export declare const microWidth: (s: string, scale?: number) => number;
+export declare const micro: (p: Pixels, x: number, y: number, s: string, col: number, scale?: number) => number;

package/dist/types/kit/mumble.d.ts

@@ -0,0 +1,41 @@
+/** A vowel's first two formants in Hz. */
+declare const VOWEL: {
+    readonly a: readonly [800, 1250];
+    readonly e: readonly [520, 1850];
+    readonly i: readonly [310, 2250];
+    readonly o: readonly [520, 950];
+    readonly u: readonly [340, 850];
+};
+/** The vowels a syllable can have. */
+export type MumbleVowel = keyof typeof VOWEL;
+/** One syllable: a vowel, its pitch at the start and the end (Hz), how long it lasts (s), and a short pause after it (s). */
+export type Syllable = [vowel: MumbleVowel, from: number, to: number, seconds: number, rest?: number];
+/** How a line is voiced. */
+export interface MumbleOptions {
+    /** Samples per second. Default 11025. */
+    rate?: number;
+    /** Loudness before clipping. Default 1.6; samples are clamped to -1..1. */
+    gain?: number;
+    /** Seed of the breath noise at each syllable's start. Default 11. */
+    noiseSeed?: number;
+}
+/** A voice's settings for `syllablesFromText`. */
+export interface TextVoice {
+    /** Middle pitch in Hz. */
+    pitch: number;
+    /** 1 is normal; 2 is twice as fast. */
+    speed: number;
+}
+/** Ready-made voices: `syllablesFromText(text, MUMBLE_VOICES.deep)`. */
+export declare const MUMBLE_VOICES: Record<'bright' | 'deep' | 'small', TextVoice>;
+/** How long a line lasts, in seconds. */
+export declare function mumbleSeconds(line: Syllable[]): number;
+/** Renders a line of syllables as samples in -1..1 (never clipped past that). */
+export declare function mumble(line: Syllable[], opts?: MumbleOptions): Float32Array;
+/** Renders a line of syllables as a .VOC (8 bits, mono, 11 025 Hz unless `rate` says otherwise). */
+export declare function mumbleVoc(line: Syllable[], opts?: MumbleOptions): Uint8Array;
+/** Turns a line of text into syllables: one per vowel group in its words, the vowel taken from the letters, so the same line (and seed) always mumbles the same way. A question rises at the end; a period or an exclamation falls. */
+export declare function syllablesFromText(text: string, opts?: Partial<TextVoice> & {
+    seed?: number;
+}): Syllable[];
+export {};

package/dist/types/kit/music.d.ts

@@ -0,0 +1 @@
+export * from '../music/compose.js';

package/dist/types/kit/palMerge.d.ts

@@ -0,0 +1,10 @@
+export interface PalMerge {
+    /** Dropped file name -> the file kept in its place. */
+    merged: Map<string, string>;
+    /** Bytes the dropped files held. */
+    saved: number;
+}
+/** Groups of byte-identical palettes, each group in keep-first order; groups of one are left out. */
+export declare function identicalPalettes(files: ReadonlyMap<string, Uint8Array>): string[][];
+/** Merges the identical palettes in a disk's files in place (the map is changed; .gam files are rewritten only when a scene is repointed). */
+export declare function mergeIdenticalPalettes(files: Map<string, Uint8Array>): PalMerge;

package/dist/types/kit/palRamps.d.ts

@@ -0,0 +1,28 @@
+import { PaletteBuilder } from './palette.js';
+export interface Pal {
+    pal: Uint8Array;
+    r: (name: string) => number[];
+    /** Shade k of a ramp, clamped. */
+    c: (name: string, k: number) => number;
+}
+export declare function wrap(b: PaletteBuilder): Pal;
+/** A palette handle that also exposes its builder for consumer-owned extra ramps. */
+export interface PalWithBuilder extends Pal {
+    b: PaletteBuilder;
+}
+export declare const wrapWithBuilder: (b: PaletteBuilder) => PalWithBuilder;
+export type RampSpec = readonly [
+    name: string,
+    shades: number,
+    from: readonly [number, number, number],
+    to: readonly [number, number, number],
+    mid?: readonly [number, number, number],
+    glows?: boolean
+];
+export interface RampPaletteOptions {
+    designerColors?: boolean;
+    overrides?: Readonly<Record<string, readonly [readonly [number, number, number], readonly [number, number, number], (readonly [number, number, number])?]>>;
+    transform?: (name: string, color: readonly [number, number, number], glows: boolean) => readonly [number, number, number];
+}
+/** Build caller-supplied ramps, with optional endpoint transforms and named replacements. */
+export declare function buildRampPalette(ramps: readonly RampSpec[], options?: RampPaletteOptions): PalWithBuilder;

package/dist/types/kit/pcText.d.ts

@@ -0,0 +1,19 @@
+import { Pixels } from './pixels.js';
+export interface PcTextOptions {
+    custom?: (character: string, color: number, flat: boolean) => Pixels | undefined;
+    shadowOffsets?: readonly (readonly [number, number])[];
+    /** Absolute output-pixel offsets, when spacing is not proportional to glyph scale. */
+    shadowPixels?: (scale: number) => readonly (readonly [number, number])[];
+    outlineDistance?: (scale: number) => number;
+    /** Some older consumers measure code points rather than UTF-16 units. */
+    codePointWidth?: boolean;
+    /** Treat palette index zero as a valid shadow (default true). */
+    shadowZero?: boolean;
+}
+export declare const textWidth: (s: string, scale?: number) => number;
+export declare function createPcText(options?: PcTextOptions): {
+    text: (p: Pixels, x: number, y: number, s: string, col: number, scale?: number, flat?: boolean) => number;
+    outlined: (p: Pixels, x: number, y: number, s: string, col: number, edge: number, scale?: number, shadow?: number) => void;
+    centered: (p: Pixels, y: number, s: string, col: number, scale?: number, edge?: number, cx?: number, shadow?: number) => void;
+};
+export declare const text: (p: Pixels, x: number, y: number, s: string, col: number, scale?: number, flat?: boolean) => number, outlined: (p: Pixels, x: number, y: number, s: string, col: number, edge: number, scale?: number, shadow?: number) => void, centered: (p: Pixels, y: number, s: string, col: number, scale?: number, edge?: number, cx?: number, shadow?: number) => void;

package/dist/types/kit/photo.d.ts

@@ -0,0 +1,69 @@
+import { Pixels } from './pixels.js';
+/** True-color pixels, 3 bytes each, square. */
+export interface Scan {
+    w: number;
+    h: number;
+    rgb: Uint8Array;
+}
+/** Read a consumer-supplied JPEG file; no reference images are bundled. */
+export declare function readScan(file: string | URL): Scan;
+/**
+ * The part of a scan inside `crop` (fractions), resampled by area to w x h screen pixels.
+ * Pass h = 0 for the height that keeps its shape on a 4:3 monitor (tall VGA pixels).
+ */
+export declare function resample(s: Scan, w: number, h?: number, crop?: [number, number, number, number]): Scan;
+/** Each pixel through fn([r, g, b]) → [r, g, b] (0..255): tints, sepia, brightness. */
+export declare function tone(s: Scan, fn: (rgb: [number, number, number]) => [number, number, number]): Scan;
+/** An old print: gray, then toned from `dark` to `light` (8-bit RGB). */
+export declare function sepia(s: Scan, dark?: [number, number, number], light?: [number, number, number], contrast?: number): Scan;
+/** Median cut over a 5-bit histogram: `count` colors for the scan, as 6-bit VGA values. */
+export declare function medianCut(s: Scan, count: number): [number, number, number][];
+/** Palette entries a picture never uses (outside `skip`, a rectangle about to be painted over). */
+export declare function freeColors(p: Pixels, skip?: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, reserved?: number[]): number[];
+/**
+ * Floyd-Steinberg dithers the scan onto the palette, choosing only among `allowed` entries,
+ * with serpentine rows so the error doesn't streak. Returns the palette indices.
+ */
+export declare function ditherTo(s: Scan, pal: Uint8Array, allowed: number[]): Uint8Array;
+interface PasteOptions {
+    /** Most palette entries to give the photo (default: every free one). */
+    colors?: number;
+    /** Entries the picture needs kept as they are even though no pixel uses them yet. */
+    reserved?: number[];
+    /** Let the photo use the picture's own colors as well as its new ones (default true). */
+    share?: boolean;
+}
+/**
+ * Pastes a scan (already the size it will be on screen) into the picture at (x, y). The
+ * picture's unused palette entries get the photo's colors. Returns the new palette and the
+ * entries the photo was given.
+ */
+export declare function pastePhoto(p: Pixels, pal: Uint8Array, s: Scan, x: number, y: number, o?: PasteOptions): {
+    pal: Uint8Array;
+    slots: number[];
+};
+interface FrameColors {
+    /** The print's white border. */
+    paper: number;
+    /** Its outline. */
+    edge: number;
+    /** A drop shadow on what's under it (-1: none). */
+    shadow?: number;
+    /** Strips of tape over the top corners (-1: none), every other pixel so the print shows through. */
+    tape?: number;
+}
+/**
+ * An instant print with its photo area w x h at (x, y): a white border, deeper at the bottom
+ * for a caption, an outline, a drop shadow and tape at the top corners. Returns where the
+ * caption strip's middle is.
+ */
+export declare function polaroid(p: Pixels, x: number, y: number, w: number, h: number, c: FrameColors, bottom?: number): {
+    cx: number;
+    cy: number;
+};
+export {};

package/dist/types/kit/png.d.ts

@@ -0,0 +1,7 @@
+import { Pixels } from './pixels.js';
+/** Writes an indexed picture through a 6-bit VGA palette, scaled up `s` times. */
+export declare function writePng(file: string, p: Pixels, pal: Uint8Array, s?: number): void;
+/** A sheet of 20x20 blocks, `cols` across, with a 2 pixel gap. */
+export declare function blockSheet(blocks: {
+    pixels: Uint8Array;
+}[], cols?: number, bg?: number): Pixels;

package/dist/types/kit/quantize.d.ts

@@ -0,0 +1,20 @@
+/** 8-bit RGB pixels, 3 bytes each. */
+type Rgb = Uint8Array;
+/**
+ * A palette for these frames: `fixed` colors first (8-bit RGB, such as black), then median
+ * cut over a 5-bit-per-channel histogram fills the rest of the 256 entries. Returns 768
+ * bytes of 6-bit VGA components.
+ */
+export declare function medianCutPalette(frames: Rgb[], fixed?: [number, number, number][]): Uint8Array;
+/** Maps 8-bit RGB pixels to a 6-bit palette with a 4x4 ordered dither of `amount` (8-bit steps). */
+export declare class Quantizer {
+    readonly palette: Uint8Array;
+    readonly amount: number;
+    private readonly lut;
+    constructor(palette: Uint8Array, amount?: number);
+    /** The nearest palette entry to a 6-bit color. */
+    nearest(r: number, g: number, b: number): number;
+    /** A whole picture: `rgb` is w*h*3 bytes. */
+    apply(rgb: Rgb, w: number, h: number): Uint8Array;
+}
+export {};