minimojs 1.0.0-alpha.38 → 1.0.0-alpha.39

package/dist/minimo-fire.d.ts

@@ -0,0 +1,242 @@
+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);
+ * ```
+ */
+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;
+    /**
+     * 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 {};

package/dist/minimo-fire.js

@@ -0,0 +1,831 @@
+import { DrawSprite } from "./minimo.js";
+const KINDS = {
+    torch: { spread: 0.16, spreadY: 0.04, rise: 4.2, life: 0.62, radius: 0.42, rate: 46, smoke: 0.15, sparks: 0.25, light: true, width: 3.6, up: 3.8, down: 1.6, bodyWidth: 0.6, bodyHeight: 1.1, bodyRise: 0.5 },
+    campfire: { spread: 0.4, spreadY: 0.05, rise: 3.4, life: 0.72, radius: 0.34, rate: 80, smoke: 0.4, sparks: 0.5, light: true, width: 3.8, up: 3.8, down: 1.5, bodyWidth: 0.85, bodyHeight: 1, bodyRise: 0.45 },
+    burning: { spread: 0.45, spreadY: 0.35, rise: 2.1, life: 0.5, radius: 0.24, rate: 90, smoke: 0.3, sparks: 0.25, light: false, width: 2.4, up: 2.6, down: 1, bodyWidth: 0.9, bodyHeight: 0.9, bodyRise: 0.1 },
+    trail: { spread: 0.12, spreadY: 0.12, rise: 0.35, life: 0.45, radius: 0.55, rate: 160, smoke: 0.35, sparks: 0.3, light: false, width: 14, up: 7, down: 7, bodyWidth: 0.8, bodyHeight: 0.8, bodyRise: 0 },
+    burst: { spread: 0.42, spreadY: 0.06, rise: 3.2, life: 0.7, radius: 0.34, rate: 80, smoke: 0.5, sparks: 0.5, light: true, width: 4, up: 4, down: 1.8, bodyWidth: 0.85, bodyHeight: 1, bodyRise: 0.45 },
+    explosion: { spread: 0, spreadY: 0, rise: 0, life: 0.5, radius: 0.34, rate: 0, smoke: 0.7, sparks: 0.7, light: true, width: 3.2, up: 2.8, down: 1.7, bodyWidth: 0.8, bodyHeight: 0.8, bodyRise: 0 },
+};
+const PALETTES = {
+    fire: ["#fff4b8", "#ffab2e", "#e8401c"],
+    blue: ["#eef9ff", "#5cc8ff", "#2c4fff"],
+    green: ["#f2ffd2", "#8cff4a", "#14a038"],
+    purple: ["#ffe9ff", "#d27bff", "#7326ff"],
+};
+const DEFAULT_SMOKE = "#4a4440";
+const FLAME = 0;
+const SMOKE = 1;
+const SPARK = 2;
+/**
+ * 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);
+ * ```
+ */
+export class Fire {
+    constructor(game, options = {}) {
+        /** @internal */
+        this._particleCount = 0;
+        /** @internal */
+        this._flames = [];
+        this.game = game;
+        const { maxParticles, reducedMotion, wind, seed, ...look } = options;
+        this.look = look;
+        if (look.palette !== undefined)
+            resolvePalette(look.palette);
+        if (look.style !== undefined)
+            checkStyle(look.style);
+        this.wind = finiteOr(wind, 0);
+        this.reducedMotion = reducedMotion ?? prefersReducedMotion();
+        this._random = typeof seed === "number" && Number.isFinite(seed) ? seededRandom(seed) : Math.random;
+        let max = Math.max(0, Math.floor(finiteOr(maxParticles, 1200)));
+        const cores = typeof navigator !== "undefined" ? navigator.hardwareConcurrency ?? 8 : 8;
+        if (maxParticles === undefined && game.isMobileDevice() && cores <= 4)
+            max = Math.round(max * 0.6);
+        this._maxParticles = max;
+    }
+    /** The flames burning now, in the order they were made. */
+    get flames() {
+        return this._flames;
+    }
+    /** How many particles are alive across every flame. */
+    get particleCount() {
+        return this._particleCount;
+    }
+    /**
+     * 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, options = {}) {
+        checkKind(kind);
+        return this._add(new Flame(this, kind, options));
+    }
+    /**
+     * 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, options = {}) {
+        const kind = options.kind ?? "burning";
+        checkKind(kind);
+        const { kind: _kind, offsetX, offsetY, ms, ...rest } = options;
+        const size = options.size ?? (kind === "burning" ? Math.max(8, sprite.displayWidth) : kind === "trail" ? Math.max(8, sprite.displayWidth * 0.8) : 32);
+        const top = kind === "torch" || kind === "campfire" ? -sprite.displayHeight / 2 : 0;
+        const flame = new Flame(this, kind, { ...rest, size, layer: options.layer ?? sprite.layer });
+        flame._target = sprite;
+        flame._offsetX = finiteOr(offsetX, 0);
+        flame._offsetY = finiteOr(offsetY, top);
+        if (typeof ms === "number" && Number.isFinite(ms))
+            flame._expiresIn = Math.max(0, ms) / 1000;
+        flame._follow();
+        return this._add(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, y, options = {}) {
+        const { size, burnMs, layer, ...look } = options;
+        const flame = this._add(new Flame(this, "burst", { ...look, x, y, size: size ?? 48, layer }));
+        flame._blast(0.5);
+        flame._burnFor(Math.max(0, finiteOr(burnMs, 3000)) / 1000);
+        return flame._whenOut();
+    }
+    /**
+     * 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, y, options = {}) {
+        const { size, layer, ...look } = options;
+        const flame = this._add(new Flame(this, "explosion", { ...look, x, y, size: size ?? 96, layer, intensity: 0 }));
+        flame._blast(1);
+        flame._out = true;
+        return flame._whenOut();
+    }
+    /** Removes a flame at once, with no dying down. */
+    remove(flame) {
+        this.game.destroySprite(flame);
+        this._drop(flame);
+    }
+    /** Removes every flame at once. */
+    clear() {
+        for (const flame of [...this._flames])
+            this.remove(flame);
+    }
+    /** Advances every flame. Call it once per frame from `onUpdate`. */
+    update(dt) {
+        const seconds = Math.max(0, finiteOr(dt, 0));
+        if (this._flames.length === 0)
+            return;
+        // A flame the game destroyed, such as by game.reset(), is dropped, and a
+        // flame whose sprite was destroyed goes out.
+        const alive = new Set(this.game.getSprites());
+        for (const flame of [...this._flames]) {
+            if (!alive.has(flame)) {
+                this._drop(flame);
+                continue;
+            }
+            if (flame._target && !alive.has(flame._target)) {
+                flame._target = null;
+                void flame.extinguish(250);
+            }
+            flame._advance(seconds);
+            if (flame._finished())
+                this.remove(flame);
+        }
+    }
+    /** @internal */
+    _add(flame) {
+        this._flames.push(flame);
+        this.game.add(flame);
+        return flame;
+    }
+    /** @internal */
+    _drop(flame) {
+        const index = this._flames.indexOf(flame);
+        if (index < 0)
+            return;
+        this._flames.splice(index, 1);
+        this._particleCount -= flame._particles.length;
+        flame._particles.length = 0;
+        flame._settle();
+    }
+}
+/**
+ * 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 class Flame extends DrawSprite {
+    /**
+     * Use {@link Fire.create}, {@link Fire.attach}, {@link Fire.burst}, or
+     * {@link Fire.explosion} instead, which also add and advance the flame.
+     */
+    constructor(fire, kind, options = {}) {
+        const spec = KINDS[kind];
+        const size = Math.max(4, finiteOr(options.size, 32));
+        const width = Math.ceil(spec.width * size);
+        const height = Math.ceil((spec.up + spec.down) * size);
+        super(width, height, finiteOr(options.x, 0), finiteOr(options.y, 0));
+        /** Called once when the flame is out and removed. */
+        this.onOut = null;
+        /** @internal */
+        this._particles = [];
+        /** @internal */
+        this._target = null;
+        /** @internal */
+        this._offsetX = 0;
+        /** @internal */
+        this._offsetY = 0;
+        /** @internal Seconds left before an attached flame goes out by itself. */
+        this._expiresIn = Infinity;
+        /** @internal No more particles are emitted; the flame is removed once the last one is gone. */
+        this._out = false;
+        /** @internal */
+        this._tween = null;
+        /** @internal */
+        this._time = 0;
+        /** @internal */
+        this._flash = 0;
+        /** @internal */
+        this._emitFlames = 0;
+        /** @internal */
+        this._emitSmoke = 0;
+        /** @internal */
+        this._emitSparks = 0;
+        /** @internal */
+        this._burn = null;
+        /** @internal Going out once the intensity reaches 0. */
+        this._extinguishing = false;
+        /** @internal */
+        this._waiting = [];
+        /** @internal */
+        this._settled = false;
+        /** @internal */
+        this._heat = null;
+        /** @internal Where the flame was at the last frame, to spread a moving flame's particles along its path. */
+        this._lastX = NaN;
+        /** @internal */
+        this._lastY = NaN;
+        this._fire = fire;
+        this._spec = spec;
+        this.kind = kind;
+        this.size = size;
+        this._baseX = width / 2;
+        this._baseY = spec.up * size;
+        const look = { ...fire.look, ...definedOnly(options) };
+        this.palette = look.palette ?? "fire";
+        resolvePalette(this.palette);
+        this.style = look.style ?? "soft";
+        checkStyle(this.style);
+        this.smoke = clamp01(finiteOr(look.smoke, spec.smoke));
+        this.sparks = clamp01(finiteOr(look.sparks, spec.sparks));
+        this.smokeColor = look.smokeColor ?? DEFAULT_SMOKE;
+        this.light = options.light ?? spec.light;
+        this._intensity = clamp01(finiteOr(options.intensity, 1));
+        this.layer = finiteOr(options.layer, 0);
+        this.tags = ["fire"];
+        this.bodyWidth = spec.bodyWidth * size;
+        this.bodyHeight = spec.bodyHeight * size;
+        this.bodyOffsetY = -spec.bodyRise * size - this.getAnchorOffsetY();
+        const random = fire._random;
+        this._phases = [random() * 6.283, random() * 6.283, random() * 6.283];
+    }
+    /** How strongly it burns, from `0` to `1`. Setting it stops a change in progress. */
+    get intensity() {
+        return this._intensity;
+    }
+    set intensity(value) {
+        this._finishTween();
+        this._intensity = clamp01(finiteOr(value, this._intensity));
+    }
+    /** `true` once the flame is going out for good: it emits nothing more and is removed when its last particle is gone. */
+    get out() {
+        return this._out;
+    }
+    /** The sprite this flame follows, or `null`. */
+    get target() {
+        return this._target;
+    }
+    /**
+     * Changes the intensity over `ms` milliseconds.
+     * @returns A promise that resolves when it gets there, or when another change replaces it.
+     */
+    to(intensity, ms) {
+        this._finishTween();
+        const target = clamp01(finiteOr(intensity, this._intensity));
+        const seconds = Math.max(0, finiteOr(ms, 0)) / 1000;
+        if (seconds === 0) {
+            this._intensity = target;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this._tween = { from: this._intensity, to: target, seconds, elapsed: 0, resolve };
+        });
+    }
+    /**
+     * 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 = 600) {
+        const promise = this._whenOut();
+        if (this._out || this._settled)
+            return promise;
+        this._burn = null;
+        void this.to(0, ms);
+        this._extinguishing = true;
+        this._goOutWhenDown();
+        return promise;
+    }
+    getAnchorOffsetY() {
+        // The position is the flame's base, which sits low in its surface, so
+        // the surface's center is above it.
+        return this.height / 2 - this._baseY;
+    }
+    /** @internal Called by the fire once per frame. */
+    _advance(dt) {
+        this._time += dt;
+        this._advanceTween(dt);
+        this._goOutWhenDown();
+        if (this._burn) {
+            const burn = this._burn;
+            burn.elapsed = Math.min(burn.seconds, burn.elapsed + dt);
+            const u = burn.seconds > 0 ? burn.elapsed / burn.seconds : 1;
+            this._intensity = 1 - Math.pow(u, 1.6);
+            if (u >= 1) {
+                this._burn = null;
+                this._puff();
+                this._out = true;
+            }
+        }
+        if (this._target) {
+            this._follow();
+            this._expiresIn -= dt;
+            if (this._expiresIn <= 0) {
+                this._target = null;
+                void this.extinguish(500);
+            }
+        }
+        this._flash = Math.max(0, this._flash - dt);
+        if (!this._out && dt > 0)
+            this._emit(dt);
+        this._lastX = this.x;
+        this._lastY = this.y;
+        this._move(dt);
+        if (this._particles.length > 0 || this._glows())
+            this.frozen = false;
+    }
+    /** @internal */
+    _finished() {
+        return this._out && this._particles.length === 0 && this._flash <= 0;
+    }
+    /** @internal */
+    _follow() {
+        const target = this._target;
+        if (!target)
+            return;
+        this.x = target.x + this._offsetX;
+        this.y = target.y + this._offsetY;
+        this.visible = target.visible;
+    }
+    /** @internal Burns down from full intensity to out over `seconds`. */
+    _burnFor(seconds) {
+        this._burn = { seconds, elapsed: 0 };
+    }
+    /** @internal A fireball with sparks and smoke, at `strength` of an explosion's. */
+    _blast(strength) {
+        const random = this._fire._random;
+        const s = this.size;
+        const full = strength >= 1;
+        const flames = Math.round((full ? 30 : 14) * this._density());
+        for (let i = 0; i < flames; i++) {
+            const angle = random() * Math.PI * 2;
+            const speed = s * (full ? 1.6 + random() * 1.4 : 0.9 + random() * 0.9);
+            this._spawn(FLAME, this.x, this.y - s * 0.1, Math.cos(angle) * speed, Math.sin(angle) * speed * 0.8 - s * 0.4, 0.3 + random() * 0.3, s * (0.24 + random() * 0.16) * (full ? 1.2 : 1), 3.2, 0);
+        }
+        const sparks = Math.round((full ? 20 : 8) * this.sparks * this._density());
+        for (let i = 0; i < sparks; i++) {
+            const angle = random() * Math.PI * 2;
+            const speed = s * (2.6 + random() * 2.4);
+            this._spawn(SPARK, this.x, this.y, Math.cos(angle) * speed, Math.sin(angle) * speed - s, 0.4 + random() * 0.45, Math.max(1.5, s * 0.035), 1.8, 0);
+        }
+        const smoke = Math.round((full ? 10 : 5) * this.smoke * this._density());
+        for (let i = 0; i < smoke; i++) {
+            const angle = random() * Math.PI * 2;
+            const r = random() * s * 0.3;
+            const p = this._spawn(SMOKE, this.x + Math.cos(angle) * r, this.y + Math.sin(angle) * r - s * 0.2, Math.cos(angle) * s * 0.3, -s * (0.4 + random() * 0.4), 1.2 + random() * 0.6, s * (0.22 + random() * 0.1), 0.8, 0);
+            if (p)
+                p.age = -(0.08 + random() * 0.22);
+        }
+        this._flash = full ? 0.45 : 0.25;
+        this.frozen = false;
+    }
+    /** @internal Resolves when the flame is out and removed. */
+    _whenOut() {
+        if (this._settled)
+            return Promise.resolve();
+        return new Promise((resolve) => this._waiting.push(resolve));
+    }
+    /** @internal The flame is removed: answer every promise and call onOut once. */
+    _settle() {
+        if (this._settled)
+            return;
+        this._settled = true;
+        this._finishTween();
+        const waiting = this._waiting;
+        this._waiting = [];
+        for (const resolve of waiting)
+            resolve();
+        this.onOut?.();
+    }
+    redraw(ctx) {
+        if (this._particles.length === 0 && !this._glows()) {
+            this.frozen = true;
+            return;
+        }
+        const colors = resolvePalette(this.palette, PALETTES.fire);
+        if (this.style === "pixel")
+            this._drawPixel(ctx, colors);
+        else
+            this._drawSoft(ctx, colors);
+    }
+    // -------------------------------------------------------------------------
+    // Particles
+    // -------------------------------------------------------------------------
+    /** @internal The share of particles the device and the player's settings allow. */
+    _density() {
+        return this._fire.reducedMotion ? 0.5 : 1;
+    }
+    /** @internal */
+    _emit(dt) {
+        const spec = this._spec;
+        const random = this._fire._random;
+        const s = this.size;
+        const k = this._intensity;
+        if (k <= 0)
+            return;
+        const density = this._density();
+        this._emitFlames += spec.rate * k * density * dt;
+        this._emitSmoke += 14 * this.smoke * (0.35 + 0.65 * k) * density * dt;
+        this._emitSparks += 7 * this.sparks * k * density * dt;
+        const rise = spec.rise * s * (0.6 + 0.4 * k);
+        const radius = spec.radius * s * (0.55 + 0.45 * k);
+        // A flame that moved since the last frame emits along the way, so a fast
+        // fireball leaves a continuous trail rather than a row of dots.
+        const fromX = Number.isFinite(this._lastX) ? this._lastX : this.x;
+        const fromY = Number.isFinite(this._lastY) ? this._lastY : this.y;
+        const count = Math.floor(this._emitFlames);
+        for (let i = 0; this._emitFlames >= 1; this._emitFlames--, i++) {
+            const along = (i + 1) / count;
+            const across = random() * 2 - 1;
+            const x = fromX + (this.x - fromX) * along + across * spec.spread * s;
+            const y = fromY + (this.y - fromY) * along + (random() * 2 - 1) * spec.spreadY * s;
+            const life = spec.life * (0.75 + random() * 0.5);
+            // Flames lean in toward the middle as they rise, so they taper to a tip.
+            const vx = (-across * spec.spread * s * 0.8) / life + (random() - 0.5) * s * 0.3;
+            this._spawn(FLAME, x, y, vx, -rise * (0.8 + random() * 0.4), life, radius * (0.75 + random() * 0.4), 0, across);
+        }
+        const tip = spec.rise * s * spec.life * 0.55;
+        for (; this._emitSmoke >= 1; this._emitSmoke--) {
+            const x = this.x + (random() * 2 - 1) * spec.spread * s * 0.6;
+            this._spawn(SMOKE, x, this.y - tip, (random() - 0.5) * s * 0.25, -s * (0.7 + random() * 0.5), 1.3 + random() * 0.7, s * (0.18 + random() * 0.08), 0.3, 0);
+        }
+        for (; this._emitSparks >= 1; this._emitSparks--) {
+            const x = this.x + (random() * 2 - 1) * spec.spread * s;
+            this._spawn(SPARK, x, this.y - s * 0.2, (random() - 0.5) * s * 1.4, -rise * (1.3 + random() * 0.6), 0.5 + random() * 0.6, Math.max(1.5, s * 0.035), 0.6, 0);
+        }
+    }
+    /** @internal An extinguished flame goes out, in a puff of smoke, once it has died down. */
+    _goOutWhenDown() {
+        if (!this._extinguishing || this._out || this._tween)
+            return;
+        this._extinguishing = false;
+        this._puff();
+        this._out = true;
+    }
+    /** @internal */
+    _spawn(type, x, y, vx, vy, life, radius, drag, across) {
+        const fire = this._fire;
+        if (this._settled || fire._particleCount >= fire._maxParticles)
+            return null;
+        const p = { type, x, y, vx, vy, age: 0, life, radius, drag, across, phase: fire._random() * 6.283 };
+        this._particles.push(p);
+        fire._particleCount++;
+        return p;
+    }
+    /** @internal A puff of smoke where the flame was. */
+    _puff() {
+        const random = this._fire._random;
+        const s = this.size;
+        const count = Math.round(6 * this._density());
+        for (let i = 0; i < count; i++) {
+            this._spawn(SMOKE, this.x + (random() * 2 - 1) * s * 0.3, this.y - s * 0.3, (random() - 0.5) * s * 0.4, -s * (0.6 + random() * 0.5), 1 + random() * 0.6, s * (0.2 + random() * 0.1), 0.4, 0);
+        }
+    }
+    /** @internal */
+    _move(dt) {
+        const fire = this._fire;
+        const particles = this._particles;
+        const wind = fire.wind;
+        const s = this.size;
+        for (let i = particles.length - 1; i >= 0; i--) {
+            const p = particles[i];
+            p.age += dt;
+            if (p.age >= p.life) {
+                particles[i] = particles[particles.length - 1];
+                particles.pop();
+                fire._particleCount--;
+                continue;
+            }
+            if (p.age < 0)
+                continue;
+            const keep = Math.exp(-p.drag * dt);
+            p.vx *= keep;
+            p.vy *= keep;
+            const lean = p.type === SMOKE ? 0.45 : p.type === SPARK ? 0.35 : 0.25;
+            let vx = p.vx + wind * lean;
+            if (p.type === FLAME)
+                vx += Math.sin(this._time * 9 + p.phase) * s * 0.35;
+            if (p.type === SPARK)
+                p.vy += s * 1.2 * dt;
+            p.x += vx * dt;
+            p.y += p.vy * dt;
+        }
+    }
+    /** @internal */
+    _glows() {
+        return (this.light && this._intensity > 0 && !this._out) || this._flash > 0;
+    }
+    /** @internal A gentle flicker around 1: small and smooth, never a flash. */
+    _flicker() {
+        const [a, b, c] = this._phases;
+        const t = this._time;
+        const amount = this._fire.reducedMotion ? 0.5 : 1;
+        return 1 + amount * (0.07 * Math.sin(t * 11 + a) + 0.05 * Math.sin(t * 17.3 + b) + 0.04 * Math.sin(t * 6.1 + c));
+    }
+    /** @internal How bright the glow is, and how far it reaches, in pixels. */
+    _glow() {
+        const s = this.size;
+        const flicker = this._flicker();
+        let alpha = this.light && !this._out ? 0.3 * this._intensity * flicker : 0;
+        let radius = s * 1.6 * (0.8 + 0.2 * this._intensity) * flicker;
+        if (this._flash > 0) {
+            // An explosion or a burst brightens once and fades.
+            const total = this.kind === "explosion" ? 0.45 : 0.25;
+            const u = 1 - this._flash / total;
+            alpha = Math.max(alpha, 0.8 * (1 - u));
+            radius = Math.max(radius, s * (0.9 + 0.5 * u));
+        }
+        return { alpha: Math.min(1, alpha), radius };
+    }
+    /** @internal The particle's place in the surface, and how much the surface's edge fades it. */
+    _local(p) {
+        const lx = p.x - this.x + this._baseX;
+        const ly = p.y - this.y + this._baseY;
+        const band = this.size * 0.6;
+        const edge = Math.min(lx, this.width - lx, ly, this.height - ly);
+        return [lx, ly, Math.max(0, Math.min(1, edge / band))];
+    }
+    // -------------------------------------------------------------------------
+    // Soft style
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _drawSoft(ctx, colors) {
+        const glow = this._glow();
+        const cx = this._baseX;
+        const cy = this._baseY - this.size * this._spec.bodyRise;
+        ctx.globalCompositeOperation = "lighter";
+        if (glow.alpha > 0.004) {
+            ctx.globalAlpha = glow.alpha;
+            ctx.drawImage(blob(colors[2], 0.9), cx - glow.radius, cy - glow.radius, glow.radius * 2, glow.radius * 2);
+        }
+        ctx.globalCompositeOperation = "source-over";
+        const smoke = blob(this.smokeColor, 0.55);
+        for (const p of this._particles) {
+            if (p.type !== SMOKE || p.age < 0)
+                continue;
+            const a = p.age / p.life;
+            const [lx, ly, fade] = this._local(p);
+            const alpha = 0.32 * Math.min(1, a / 0.2) * (1 - a) * fade;
+            if (alpha <= 0.004)
+                continue;
+            const r = p.radius * (1 + a * 2.2);
+            ctx.globalAlpha = alpha;
+            ctx.drawImage(smoke, lx - r, ly - r, r * 2, r * 2);
+        }
+        ctx.globalCompositeOperation = "lighter";
+        for (const p of this._particles) {
+            if (p.type === SMOKE || p.age < 0)
+                continue;
+            const a = p.age / p.life;
+            const [lx, ly, fade] = this._local(p);
+            if (p.type === SPARK) {
+                const alpha = (1 - a) * fade * (0.7 + 0.3 * Math.sin(p.phase + this._time * 30));
+                if (alpha <= 0.004)
+                    continue;
+                const r = p.radius * 2;
+                ctx.globalAlpha = alpha;
+                ctx.drawImage(blob(a < 0.5 ? colors[0] : colors[1], 1), lx - r, ly - r, r * 2, r * 2);
+                continue;
+            }
+            const r = p.radius * Math.pow(1 - a, 0.6);
+            if (r < 0.5)
+                continue;
+            const alpha = 0.55 * Math.pow(1 - a, 0.8) * fade;
+            // Hot at birth, cooling to the edge color: two neighbouring stops, mixed.
+            const [inner, outer, mix] = a < 0.2 ? [0, 1, a / 0.2] : [1, 2, Math.min(1, (a - 0.2) / 0.45)];
+            ctx.globalAlpha = alpha * (1 - mix);
+            ctx.drawImage(blob(colors[inner], 0.75), lx - r, ly - r, r * 2, r * 2);
+            ctx.globalAlpha = alpha * mix;
+            ctx.drawImage(blob(colors[outer], 0.75), lx - r, ly - r, r * 2, r * 2);
+        }
+        ctx.globalAlpha = 1;
+        ctx.globalCompositeOperation = "source-over";
+    }
+    // -------------------------------------------------------------------------
+    // Pixel style
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _drawPixel(ctx, colors) {
+        const cell = Math.max(2, Math.round(this.size / 9));
+        const columns = Math.ceil(this.width / cell);
+        const rows = Math.ceil(this.height / cell);
+        const glow = this._glow();
+        const cx = this._baseX;
+        const cy = this._baseY - this.size * this._spec.bodyRise;
+        // The glow: two stepped discs of the edge color.
+        if (glow.alpha > 0.004) {
+            ctx.fillStyle = colors[2];
+            for (const [share, alpha] of [[1, 0.35], [0.6, 0.45]]) {
+                ctx.globalAlpha = glow.alpha * alpha;
+                pixelDisc(ctx, cx, cy, glow.radius * share, cell);
+            }
+        }
+        // Smoke: squares on the grid, in three steps of transparency.
+        ctx.fillStyle = this.smokeColor;
+        for (const p of this._particles) {
+            if (p.type !== SMOKE || p.age < 0)
+                continue;
+            const a = p.age / p.life;
+            const [lx, ly, fade] = this._local(p);
+            const alpha = 0.4 * Math.min(1, a / 0.2) * (1 - a) * fade;
+            const step = Math.round(alpha * 6) / 6;
+            if (step <= 0)
+                continue;
+            const half = Math.max(1, Math.round((p.radius * (1 + a * 2.2)) / cell)) * cell;
+            ctx.globalAlpha = step;
+            ctx.fillRect(snap(lx - half, cell), snap(ly - half, cell), half * 2, half * 2);
+        }
+        ctx.globalAlpha = 1;
+        // Flames: each particle heats the cells under it, and each cell takes the
+        // palette color of its heat.
+        const size = columns * rows;
+        if (!this._heat || this._heat.length !== size)
+            this._heat = new Float32Array(size);
+        const heat = this._heat;
+        heat.fill(0);
+        let any = false;
+        for (const p of this._particles) {
+            if (p.type !== FLAME || p.age < 0)
+                continue;
+            const a = p.age / p.life;
+            const r = p.radius * Math.pow(1 - a, 0.6);
+            if (r < 0.5)
+                continue;
+            const [lx, ly, fade] = this._local(p);
+            const hot = (1 - a) * fade * 1.25;
+            const reach = r / cell;
+            const col = lx / cell;
+            const row = ly / cell;
+            const c0 = Math.max(0, Math.floor(col - reach));
+            const c1 = Math.min(columns - 1, Math.ceil(col + reach));
+            const r0 = Math.max(0, Math.floor(row - reach));
+            const r1 = Math.min(rows - 1, Math.ceil(row + reach));
+            for (let y = r0; y <= r1; y++) {
+                for (let x = c0; x <= c1; x++) {
+                    const d = Math.hypot(x + 0.5 - col, y + 0.5 - row) / reach;
+                    if (d < 1) {
+                        heat[y * columns + x] += hot * (1 - d);
+                        any = true;
+                    }
+                }
+            }
+        }
+        if (any) {
+            const bands = [[0.25, colors[2]], [0.7, colors[1]], [1.5, colors[0]]];
+            for (const [threshold, color] of bands) {
+                ctx.fillStyle = color;
+                ctx.beginPath();
+                for (let i = 0; i < size; i++) {
+                    if (heat[i] >= threshold)
+                        ctx.rect((i % columns) * cell, Math.floor(i / columns) * cell, cell, cell);
+                }
+                ctx.fill();
+            }
+        }
+        // Sparks: one cell each.
+        for (const p of this._particles) {
+            if (p.type !== SPARK || p.age < 0)
+                continue;
+            const a = p.age / p.life;
+            const [lx, ly, fade] = this._local(p);
+            if (fade <= 0)
+                continue;
+            ctx.fillStyle = a < 0.5 ? colors[0] : colors[1];
+            ctx.fillRect(snap(lx, cell), snap(ly, cell), cell, cell);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Intensity changes
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _advanceTween(dt) {
+        const tween = this._tween;
+        if (!tween)
+            return;
+        tween.elapsed = Math.min(tween.seconds, tween.elapsed + dt);
+        const u = tween.elapsed / tween.seconds;
+        this._intensity = tween.from + (tween.to - tween.from) * u;
+        if (u >= 1)
+            this._finishTween();
+    }
+    /** @internal */
+    _finishTween() {
+        const tween = this._tween;
+        if (!tween)
+            return;
+        this._tween = null;
+        this._intensity = tween.to;
+        tween.resolve();
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const blobs = new Map();
+/** A round, soft dot of `color`, drawn once and kept: the soft style's particle. */
+function blob(color, core) {
+    const key = `${color}|${core}`;
+    let canvas = blobs.get(key);
+    if (!canvas) {
+        canvas = document.createElement("canvas");
+        canvas.width = 64;
+        canvas.height = 64;
+        const ctx = canvas.getContext("2d");
+        if (ctx) {
+            const gradient = ctx.createRadialGradient(32, 32, 0, 32, 32, 32);
+            gradient.addColorStop(0, color);
+            gradient.addColorStop(core * 0.5, color);
+            gradient.addColorStop(1, "rgba(0, 0, 0, 0)");
+            ctx.fillStyle = gradient;
+            ctx.globalAlpha = 1;
+            ctx.fillRect(0, 0, 64, 64);
+            // The gradient's last stop is transparent black; redraw its color into
+            // the fade so the edge does not darken.
+            ctx.globalCompositeOperation = "source-in";
+            ctx.fillStyle = color;
+            ctx.fillRect(0, 0, 64, 64);
+        }
+        blobs.set(key, canvas);
+    }
+    return canvas;
+}
+/** A disc made of grid cells, row by row. */
+function pixelDisc(ctx, cx, cy, radius, cell) {
+    const rows = Math.floor(radius / cell);
+    ctx.beginPath();
+    for (let r = -rows; r <= rows; r++) {
+        const y = cy + r * cell;
+        const half = Math.sqrt(Math.max(0, radius * radius - (r * cell) ** 2));
+        const left = snap(cx - half, cell);
+        const right = snap(cx + half, cell);
+        if (right > left)
+            ctx.rect(left, snap(y, cell), right - left, cell);
+    }
+    ctx.fill();
+}
+function snap(value, cell) {
+    return Math.round(value / cell) * cell;
+}
+function checkKind(kind) {
+    if (kind !== "torch" && kind !== "campfire" && kind !== "burning" && kind !== "trail") {
+        throw new Error(`MinimoJS: There is no fire kind "${String(kind)}"; the kinds are torch, campfire, burning, and trail.`);
+    }
+}
+function checkStyle(style) {
+    if (style !== "soft" && style !== "pixel") {
+        throw new Error(`MinimoJS: There is no fire style "${String(style)}"; the styles are soft and pixel.`);
+    }
+}
+function resolvePalette(palette, fallback) {
+    if (Array.isArray(palette) && palette.length === 3 && palette.every((c) => typeof c === "string")) {
+        return palette;
+    }
+    if (typeof palette === "string" && Object.prototype.hasOwnProperty.call(PALETTES, palette)) {
+        return PALETTES[palette];
+    }
+    if (fallback)
+        return fallback;
+    throw new Error(`MinimoJS: There is no fire palette ${JSON.stringify(palette)}; use fire, blue, green, purple, or three colors from the core to the edge.`);
+}
+function definedOnly(value) {
+    const out = {};
+    for (const [key, field] of Object.entries(value))
+        if (field !== undefined)
+            out[key] = field;
+    return out;
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function finiteOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function prefersReducedMotion() {
+    try {
+        return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+    }
+    catch {
+        return false;
+    }
+}
+function seededRandom(seed) {
+    let state = Math.floor(seed) >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.38",
+  "version": "1.0.0-alpha.39",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",