minimojs 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/minimo-fire.d.ts

@@ -0,0 +1,282 @@
+import { DrawSprite, Game, Sprite } from "./minimo.js";
+/**
+ * The kinds of fire {@link Fire.create} and {@link Fire.attach} make.
+ *
+ * - `"torch"`: a narrow, tall flame that glows. For torches, braziers, and
+ *   lamps.
+ * - `"campfire"`: a wide flame with smoke and sparks that glows. For
+ *   campfires, fireplaces, and burning debris.
+ * - `"burning"`: flames over a whole sprite, such as an enemy set alight or a
+ *   burning house. The default of {@link Fire.attach}.
+ * - `"trail"`: a ball of fire that leaves flames and smoke behind it as it
+ *   moves. For fireballs, flaming arrows, meteors, and exhausts.
+ */
+export type FlameKind = "torch" | "campfire" | "burning" | "trail";
+/** A named palette: orange fire, a blue gas flame, green poison, or purple magic. */
+export type FirePaletteName = "fire" | "blue" | "green" | "purple";
+/**
+ * The colors of a fire: a named palette, or three CSS colors for the core,
+ * the middle, and the edge of the flame, from hottest to coolest.
+ */
+export type FirePalette = FirePaletteName | readonly [string, string, string];
+/**
+ * How a fire is drawn: `"soft"`, glowing gradients that add up to light, or
+ * `"pixel"`, hard-edged squares in the palette's three colors, to match pixel
+ * art.
+ */
+export type FireStyle = "soft" | "pixel";
+/** The look of a fire. A {@link Fire} holds one for all its flames, and each flame can override any field. */
+export interface FireLook {
+    /** Default `"fire"`. */
+    palette?: FirePalette;
+    /** Default `"soft"`. */
+    style?: FireStyle;
+    /** How much smoke rises, from `0` to `1`. Default: by kind. */
+    smoke?: number;
+    /** How many sparks fly, from `0` to `1`. Default: by kind. */
+    sparks?: number;
+    /** CSS color of the smoke. Default `"#4a4440"`. */
+    smokeColor?: string;
+}
+/** Settings of a {@link Fire}, and the look every flame starts from. */
+export interface FireOptions extends FireLook {
+    /**
+     * The most particles alive at once, across every flame. Default `1200`,
+     * lowered on weak phones. A flame that would go over it emits fewer.
+     */
+    maxParticles?: number;
+    /**
+     * Fewer particles and a softer flicker. Default: the player's system
+     * `prefers-reduced-motion` setting.
+     */
+    reducedMotion?: boolean;
+    /** The first {@link Fire.wind}. Default `0`. */
+    wind?: number;
+    /**
+     * Seeds the module's own random source, so the same seed flickers the same
+     * way. Default: a different flicker every time. The module never calls
+     * `game.random()`, so drawing fire never changes a seeded game's sequence.
+     */
+    seed?: number;
+}
+/** Where a new flame burns, how big, and how it looks. */
+export interface FlameOptions extends FireLook {
+    /** X position in world space, in pixels: the base of the flame. Default `0`. */
+    x?: number;
+    /** Y position in world space, in pixels: the base of the flame, where it burns from. Default `0`. */
+    y?: number;
+    /**
+     * About how wide the flame is, in pixels. Default `32`, or the sprite's
+     * width for a `"burning"` flame made by {@link Fire.attach}. Its collision
+     * body covers the flame's core; its drawing surface is larger, to hold its
+     * glow, smoke, and trail.
+     */
+    size?: number;
+    /** How strongly it burns, from `0` to `1`. Default `1`. */
+    intensity?: number;
+    /** Paint a soft, flickering glow around the flame. Default `true` for a torch and a campfire. */
+    light?: boolean;
+    /** The flame's sprite layer. Default `0`, or the sprite's layer for {@link Fire.attach}. */
+    layer?: number;
+}
+/** How {@link Fire.attach} keeps a flame on a sprite. */
+export interface AttachOptions extends Omit<FlameOptions, "x" | "y"> {
+    /** Default `"burning"`. */
+    kind?: FlameKind;
+    /**
+     * Where the flame burns, from the sprite's position, in pixels. Default `0`;
+     * for a torch or a campfire, `offsetY` defaults to the sprite's top edge.
+     */
+    offsetX?: number;
+    offsetY?: number;
+    /** Put the flame out after this many milliseconds. Default: never. */
+    ms?: number;
+}
+/** How {@link Fire.burst} leaves fire where something was destroyed. */
+export interface BurstOptions extends FireLook {
+    /** About how wide the fire is, in pixels. Default `48`. */
+    size?: number;
+    /** How long it burns before it is out, in milliseconds. Default `3000`. */
+    burnMs?: number;
+    /** Default `0`. */
+    layer?: number;
+}
+/** How {@link Fire.explosion} blows up. */
+export interface ExplosionOptions extends FireLook {
+    /** About how wide the fireball grows, in pixels. Default `96`. */
+    size?: number;
+    /** Default `0`. */
+    layer?: number;
+}
+type InternalKind = FlameKind | "burst" | "explosion";
+/**
+ * Fire for a game: torches, campfires, burning sprites, fireballs, fire where
+ * something was destroyed, and explosions. It makes each flame and advances
+ * all of them with one {@link Fire.update} call per frame.
+ *
+ * Every flame is a sprite, a {@link Flame}, so the game places it, layers it,
+ * hides it, and destroys it as any other. Its particles are painted into its
+ * own surface, so a fire costs one sprite however many particles it has.
+ *
+ * The module draws fire; the game decides what catches fire, what it hurts,
+ * and what puts it out.
+ *
+ * @example
+ * ```ts
+ * const fire = new Fire(game, { style: "pixel" });
+ * game.onUpdate = (dt) => fire.update(dt);
+ *
+ * const torch = fire.create("torch", { x: 120, y: 200, size: 28 });
+ * fire.burst(crate.x, crate.y, { size: 48, burnMs: 4000 }); // where the crate was
+ * fire.attach(fireball, { kind: "trail", palette: "blue" });
+ * torch.extinguish(600);
+ * ```
+ *
+ * ## In a design
+ *
+ * A design can place `torch`, `campfire`, `burning`, and `trail` flames, so
+ * the creator moves and resizes them in the design editor. Each is a
+ * `module` object of a version 3 design. It takes `x`, `y`, `alpha`,
+ * `visible`, `layer`, `ignoreScroll`, and the collision body's properties,
+ * never `scale` or `rotation`: its `size` option resizes it. Its `options`
+ * are `size`, `intensity`, `palette` (a palette's name), `style`, `smoke`,
+ * `sparks`, `smokeColor`, and `light`, each as in {@link FlameOptions}.
+ *
+ * ```json
+ * { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200, "layer": 2, "options": { "size": 28, "palette": "blue" } }
+ * ```
+ *
+ * A placed flame looks as its options say and the module's defaults, never
+ * as the look given to `new Fire(game, …)`, so the game shows what the editor
+ * showed, and it is already burning when its screen opens. `burst` and
+ * `explosion` are moments, made in code. Create the fire in the scene's
+ * `onCreate()` before the design's objects, then find a flame by its name
+ * to change it while the game plays, and advance the fire every frame:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.fire = new Fire(game);
+ *   const room = game.createObjectList(dungeon.objects);
+ *   this.torch = room.findByName("left-torch"); // later: this.torch.extinguish()
+ *   room.findByName("barrel-fire").follow(room.findByName("barrel"));
+ * }
+ * onUpdate(dt) {
+ *   this.fire.update(dt);
+ * }
+ * ```
+ */
+export declare class Fire {
+    /** The game the flames are added to. */
+    readonly game: Game;
+    /** The look every flame starts from. */
+    readonly look: FireLook;
+    /**
+     * Wind in pixels per second, positive to the right. Every flame, its smoke,
+     * and its sparks lean with it. A game with an `ambient` can copy
+     * `ambient.windX` here every frame.
+     */
+    wind: number;
+    /** Fewer particles and a softer flicker. Follows the player's system setting unless the game sets it. */
+    reducedMotion: boolean;
+    constructor(game: Game, options?: FireOptions);
+    /** The flames burning now, in the order they were made. */
+    get flames(): readonly Flame[];
+    /** How many particles are alive across every flame. */
+    get particleCount(): number;
+    /**
+     * Makes a flame, adds it to the game, and returns it. It burns until the
+     * game puts it out with {@link Flame.extinguish} or removes it.
+     * @param kind - `"torch"`, `"campfire"`, `"burning"`, or `"trail"`.
+     * @param options - Position, size, intensity, and any look over the fire's.
+     */
+    create(kind: FlameKind, options?: FlameOptions): Flame;
+    /**
+     * Makes a flame that follows `sprite` every frame and adds it to the game.
+     * Its particles stay where they were emitted, so a moving sprite leaves a
+     * trail behind it and a still one does not. The flame goes out by itself
+     * when the sprite is destroyed, or after `ms`.
+     * @param sprite - A sprite already added to the game.
+     * @param options - The kind, `"burning"` by default, where on the sprite, for how long, and the look.
+     */
+    attach(sprite: Sprite, options?: AttachOptions): Flame;
+    /**
+     * Leaves fire where something was destroyed: a burst of flame, then flames
+     * that die down into smoke and are gone after `burnMs`.
+     * @returns A promise that resolves when the fire is out and removed.
+     */
+    burst(x: number, y: number, options?: BurstOptions): Promise<void>;
+    /**
+     * Blows up at a point: a fireball with sparks and a cloud of smoke, which
+     * brightens the scene once and is gone in about a second and a half.
+     * @returns A promise that resolves when the explosion is over and removed.
+     */
+    explosion(x: number, y: number, options?: ExplosionOptions): Promise<void>;
+    /** Removes a flame at once, with no dying down. */
+    remove(flame: Flame): void;
+    /** Removes every flame at once. */
+    clear(): void;
+    /** Advances every flame. Call it once per frame from `onUpdate`. */
+    update(dt: number): void;
+}
+/**
+ * One fire: a `DrawSprite` whose position is the base of the flame. It has
+ * everything a sprite has, layer, visibility, `ignoreScroll` for fire on the
+ * HUD, and a collision body over the flame's core, and it carries the tag
+ * `fire`. Do not rotate or scale it: its particles are placed in the world.
+ *
+ * Make flames with {@link Fire.create}, {@link Fire.attach},
+ * {@link Fire.burst}, or {@link Fire.explosion}, which also advance them.
+ */
+export declare class Flame extends DrawSprite {
+    /** The kind of fire. `"burst"` and `"explosion"` are the flames {@link Fire.burst} and {@link Fire.explosion} make. */
+    readonly kind: FlameKind | "burst" | "explosion";
+    /** About how wide the flame is, in pixels. */
+    readonly size: number;
+    /** The colors of this flame. */
+    palette: FirePalette;
+    /** How this flame is drawn. */
+    style: FireStyle;
+    /** How much smoke rises, from `0` to `1`. */
+    smoke: number;
+    /** How many sparks fly, from `0` to `1`. */
+    sparks: number;
+    /** CSS color of the smoke. */
+    smokeColor: string;
+    /** Paint a soft, flickering glow around the flame. */
+    light: boolean;
+    /** Called once when the flame is out and removed. */
+    onOut: (() => void) | null;
+    /**
+     * Use {@link Fire.create}, {@link Fire.attach}, {@link Fire.burst}, or
+     * {@link Fire.explosion} instead, which also add and advance the flame.
+     */
+    constructor(fire: Fire, kind: InternalKind, options?: FlameOptions);
+    /** How strongly it burns, from `0` to `1`. Setting it stops a change in progress. */
+    get intensity(): number;
+    set intensity(value: number);
+    /** `true` once the flame is going out for good: it emits nothing more and is removed when its last particle is gone. */
+    get out(): boolean;
+    /** The sprite this flame follows, or `null`. */
+    get target(): Sprite | null;
+    /**
+     * Makes the flame follow `sprite` every frame, keeping the offset it has
+     * from it now, as a flame placed over a sprite in a design keeps where the
+     * creator put it. It hides with the sprite and goes out when the sprite is
+     * destroyed. `null` stops following and leaves the flame where it is.
+     */
+    follow(sprite: Sprite | null): void;
+    /**
+     * Changes the intensity over `ms` milliseconds.
+     * @returns A promise that resolves when it gets there, or when another change replaces it.
+     */
+    to(intensity: number, ms: number): Promise<void>;
+    /**
+     * Puts the flame out: it dies down over `ms` milliseconds into a puff of
+     * smoke, and is removed from the game when the smoke is gone.
+     * @returns A promise that resolves when the flame is out and removed.
+     */
+    extinguish(ms?: number): Promise<void>;
+    protected getAnchorOffsetY(): number;
+    redraw(ctx: CanvasRenderingContext2D): void;
+}
+export {};