minimojs 1.0.0-alpha.22 → 1.0.0-alpha.24

package/README.md

@@ -87,7 +87,9 @@ class DemoScene implements IScene {
 game.start(new DemoScene());
 ```
 
-Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTML if you want pixel-font styling.
+Note: text defaults to `monospace`, so a game that names no font downloads none. To use a web font, declare it in your HTML, register it with `game.requireFont(...)`, and set it as a `TextSprite`'s `fontFamily`.
+
+Load images in `game.onPreload`, once, at boot. Only a game with many scenes that each carry many images of their own, such as one with many levels, should give scenes an `onPreload()` so each loads its images when the player reaches it; see `examples/level-loading/`.
 
 ## Examples
 
@@ -102,6 +104,7 @@ Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTM
 - `examples/draw-sprite/`
 - `examples/pseudo-3d-racer/`
 - `examples/animations/`
+- `examples/level-loading/`
 
 Run locally from the `minimojs` directory:
 

package/dist/internal/AssetSystem.js

@@ -67,20 +67,52 @@ export class AssetSystem {
         }
         return total;
     }
+    /**
+     * Loads every queued image that is not loaded yet, settling all of them
+     * before returning instead of stopping at the first failure.
+     *
+     * Loaded images leave the queue; failed ones stay in it, so a retry loads
+     * only them. Returns the keys that failed, empty when all loaded.
+     */
     async loadQueuedImages(onProgress) {
         const entries = [...this._queuedImages.entries()].filter(([key]) => !this._loadedImages.has(key));
         const total = entries.length;
-        let loaded = 0;
+        let settled = 0;
+        const failed = [];
         onProgress?.(0, total, null);
-        if (total === 0)
-            return;
+        if (total === 0) {
+            this._queuedImages.clear();
+            return failed;
+        }
         await Promise.all(entries.map(async ([key, src]) => {
-            const image = await this.loadImage(src);
-            this._loadedImages.set(key, image);
-            this.bumpImageVersion(key);
-            loaded += 1;
-            onProgress?.(loaded, total, key);
+            try {
+                const image = await this.loadImage(src);
+                this._loadedImages.set(key, image);
+                this.bumpImageVersion(key);
+                this._queuedImages.delete(key);
+            }
+            catch {
+                failed.push(key);
+            }
+            settled += 1;
+            onProgress?.(settled, total, key);
         }));
+        for (const key of [...this._queuedImages.keys()]) {
+            if (this._loadedImages.has(key)) {
+                this._queuedImages.delete(key);
+            }
+        }
+        return failed;
+    }
+    /** Returns the source registered for an image key, if any. */
+    getImageSource(key) {
+        return this._imageSources.get(key);
+    }
+    /**
+     * Drops queued images that were not loaded, so a later load does not pick
+     * them up. Their keys may be registered again.
+     */
+    discardQueuedImages() {
         this._queuedImages.clear();
     }
     /** @internal */

package/dist/internal/RenderSystem.js

@@ -6,6 +6,8 @@ export class RenderSystem {
         /** @internal */
         this._lastAppliedPageBackground = undefined;
         /** @internal */
+        this._bootInk = null;
+        /** @internal */
         this._transitionScratchCanvas = null;
         /** @internal */
         this._transitionScratchContext = null;
@@ -199,7 +201,7 @@ export class RenderSystem {
         }
         for (const entry of options.textEntries) {
             ctx.save();
-            ctx.font = `${entry.fontSize}px "Press Start 2P", monospace`;
+            ctx.font = `${entry.fontSize}px monospace`;
             ctx.fillStyle = entry.color;
             ctx.textAlign = entry.centered ? "center" : "left";
             ctx.textBaseline = entry.centered ? "middle" : "top";
@@ -263,35 +265,114 @@ export class RenderSystem {
         }
         ctx.restore();
     }
+    /**
+     * Draws the boot loading screen: the game's background and one thin
+     * progress line across its middle, with no text, so it needs no font.
+     */
     renderLoadingScreen(options) {
         const ctx = options.context;
         const W = options.canvas.width;
         const H = options.canvas.height;
-        const safeTotal = Math.max(0, options.total);
-        const safeLoaded = Math.max(0, Math.min(options.loaded, safeTotal));
-        const progress = safeTotal === 0 ? 1 : safeLoaded / safeTotal;
-        const barWidth = Math.min(420, Math.max(220, Math.floor(W * 0.46)));
-        const barHeight = 18;
-        const barX = Math.round((W - barWidth) / 2);
-        const barY = Math.round(H / 2 + 24);
+        const progress = this.clampProgress(options.progress);
         this.applyPageBackground(options.pageBackground);
         this.paintCanvasBackground(ctx, W, H, options.background ?? "#101820", options.backgroundGradient);
+        // The line is redrawn on every settled image; read the background once.
+        const inkKey = `${options.background}|${options.backgroundGradient?.from}|${options.backgroundGradient?.to}`;
+        if (this._bootInk === null || this._bootInk.key !== inkKey) {
+            this._bootInk = { key: inkKey, ink: this.pickLoadingInk(options.canvas) };
+        }
+        const ink = this._bootInk.ink;
+        const lineWidth = Math.round(Math.min(320, Math.max(160, W * 0.4)));
+        const x = Math.round((W - lineWidth) / 2);
+        const y = Math.round(H / 2);
         ctx.save();
-        ctx.fillStyle = "rgba(8, 18, 28, 0.76)";
-        ctx.fillRect(0, 0, W, H);
-        ctx.font = `26px "Press Start 2P", monospace`;
-        ctx.textAlign = "center";
-        ctx.textBaseline = "middle";
-        ctx.fillStyle = "#ffffff";
-        ctx.fillText("Loading...", W / 2, H / 2 - 28);
-        ctx.fillStyle = "rgba(255, 255, 255, 0.16)";
-        ctx.fillRect(barX, barY, barWidth, barHeight);
-        ctx.fillStyle = "#f7fbff";
-        ctx.fillRect(barX, barY, Math.round(barWidth * progress), barHeight);
-        ctx.strokeStyle = "rgba(255, 255, 255, 0.35)";
-        ctx.strokeRect(barX, barY, barWidth, barHeight);
+        ctx.lineWidth = RenderSystem.LOADING_STROKE;
+        ctx.lineCap = "round";
+        ctx.strokeStyle = ink;
+        ctx.globalAlpha = 0.22;
+        ctx.beginPath();
+        ctx.moveTo(x, y);
+        ctx.lineTo(x + lineWidth, y);
+        ctx.stroke();
+        if (progress > 0) {
+            ctx.globalAlpha = 1;
+            ctx.beginPath();
+            ctx.moveTo(x, y);
+            ctx.lineTo(x + lineWidth * progress, y);
+            ctx.stroke();
+        }
         ctx.restore();
     }
+    /**
+     * Draws the frozen scene being left and, over its center, a ring whose
+     * outline fills with the share of images loaded. The ring has no fill.
+     */
+    renderSceneLoading(options) {
+        const ctx = options.context;
+        const W = options.canvas.width;
+        const H = options.canvas.height;
+        this.applyPageBackground(options.pageBackground);
+        ctx.clearRect(0, 0, W, H);
+        ctx.drawImage(options.snapshot, 0, 0, W, H);
+        if (!options.showIndicator)
+            return;
+        const progress = this.clampProgress(options.progress);
+        const radius = Math.round(Math.min(44, Math.max(20, Math.min(W, H) * 0.06)));
+        const start = -Math.PI / 2;
+        const isDarkInk = options.ink !== "#ffffff";
+        ctx.save();
+        ctx.lineWidth = RenderSystem.LOADING_STROKE;
+        ctx.lineCap = "round";
+        ctx.strokeStyle = options.ink;
+        // A soft halo in the opposite tone keeps the ring legible over busy art.
+        ctx.shadowColor = isDarkInk ? "rgba(255, 255, 255, 0.5)" : "rgba(0, 0, 0, 0.5)";
+        ctx.shadowBlur = 6;
+        ctx.globalAlpha = 0.25;
+        ctx.beginPath();
+        ctx.arc(W / 2, H / 2, radius, 0, Math.PI * 2);
+        ctx.stroke();
+        if (progress > 0) {
+            ctx.globalAlpha = 1;
+            ctx.beginPath();
+            ctx.arc(W / 2, H / 2, radius, start, start + Math.PI * 2 * progress);
+            ctx.stroke();
+        }
+        ctx.restore();
+    }
+    /**
+     * Chooses white or near-black loading ink from the average brightness at the
+     * center of `source`. Falls back to white when the pixels cannot be read,
+     * which happens when a cross-origin image has tainted the canvas.
+     */
+    pickLoadingInk(source) {
+        const size = Math.max(1, Math.min(96, source.width, source.height));
+        const x = Math.floor((source.width - size) / 2);
+        const y = Math.floor((source.height - size) / 2);
+        try {
+            const ctx = source.getContext("2d");
+            if (!ctx)
+                return "#ffffff";
+            const data = ctx.getImageData(x, y, size, size).data;
+            let luminance = 0;
+            let weight = 0;
+            for (let i = 0; i < data.length; i += 4) {
+                const alpha = data[i + 3] / 255;
+                luminance +=
+                    alpha * (0.2126 * data[i] + 0.7152 * data[i + 1] + 0.0722 * data[i + 2]);
+                weight += alpha;
+            }
+            if (weight === 0)
+                return "#ffffff";
+            return luminance / weight / 255 > 0.6 ? "#101820" : "#ffffff";
+        }
+        catch {
+            return "#ffffff";
+        }
+    }
+    /** @internal */
+    clampProgress(progress) {
+        return Number.isFinite(progress) ? Math.max(0, Math.min(1, progress)) : 0;
+    }
     /** @internal */
     drawFadeTransition(ctx, transition, width, height, progress) {
         const firstHalf = progress < 0.5;
@@ -908,3 +989,5 @@ export class RenderSystem {
 }
 /** @internal */
 RenderSystem.MAX_SURFACE_CACHE_ENTRIES = 256;
+/** @internal Stroke of the boot line and the scene ring, which match. */
+RenderSystem.LOADING_STROKE = 3;

package/dist/minimo-ambient.d.ts

@@ -0,0 +1,299 @@
+import { Game, Sprite } from "./minimo.js";
+/**
+ * The weather and light of an {@link Ambient}.
+ *
+ * Every number runs from `0` to `1`, except {@link AmbientState.wind}, which
+ * runs from `-1` to `1`. Change it with {@link Ambient.set},
+ * {@link Ambient.to}, or {@link Ambient.preset}; read it from
+ * {@link Ambient.state}.
+ */
+export interface AmbientState {
+    /** Wind direction and strength: `1` is strong wind to the right, `-1` to the left. */
+    wind: number;
+    /** How irregularly the wind blows around {@link AmbientState.wind}. */
+    gusts: number;
+    /** Rain intensity. Rain splashes on the ambient's surfaces. */
+    rain: number;
+    /** Snow intensity. With {@link Ambient.snowSettles}, snow builds up on surfaces. */
+    snow: number;
+    /** Fog: drifting bands of mist and a haze over the scene. */
+    fog: number;
+    /** Lightning frequency. Flashes never exceed the safe rate, whatever the value. */
+    storm: number;
+    /** How dark the scene is: `1` is deep night. */
+    darkness: number;
+    /** How strongly {@link AmbientState.tintColor} colors the scene: `1` lays it at 50% over it. */
+    tint: number;
+    /** How many stars show in the sky. Clouds from rain, snow, and fog hide them. */
+    stars: number;
+    /** Hex color of the tint, such as `"#1b2a55"`. Interpolated in RGB by {@link Ambient.to}. */
+    tintColor: string;
+}
+/** The numeric fields of {@link AmbientState}. */
+export type AmbientField = Exclude<keyof AmbientState, "tintColor">;
+/** A partial state for {@link Ambient.set} and {@link Ambient.to}. */
+export type AmbientChange = Partial<AmbientState>;
+/**
+ * A named weather for {@link Ambient.preset}. Presets are geometric only, so
+ * every one works in any game without art.
+ */
+export type AmbientPreset = "clear" | "drizzle" | "rain" | "storm" | "snow" | "blizzard" | "mist" | "windy";
+/** A horizontal line in world space that rain splashes on and snow settles on. */
+export interface AmbientLine {
+    /** World X of the line's left end. */
+    left: number;
+    /** World X of the line's right end. */
+    right: number;
+    /** World Y of the line. */
+    y: number;
+}
+/** A rectangle in world space where no rain, snow, or falling drift is drawn. */
+export interface AmbientRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Something rain splashes on and snow settles on. A sprite counts by the top
+ * edge of its collision body, and is followed if it moves.
+ */
+export type AmbientSurface = Sprite | AmbientLine;
+/**
+ * A covered area, such as a cave, a roof, or an awning. A sprite counts by its
+ * collision body, and is followed if it moves.
+ */
+export type AmbientShelter = Sprite | AmbientRect;
+/** Options for {@link Ambient}. Every field is optional. */
+export interface AmbientOptions {
+    /** Sprite layer of the surface drawn behind the play field. Default `5`. */
+    backLayer?: number;
+    /**
+     * Sprite layer of the surface drawn in front of the play field: the nearest
+     * particles, splashes, settled snow, haze, darkness, and flashes. Put the
+     * HUD above it. Default `900`.
+     */
+    frontLayer?: number;
+    /** Share of particles that are nearer than the play field and drawn in front of it. Default `0.25`. */
+    front?: number;
+    /** Seed for reproducible weather. Omit it for different weather on every load. */
+    seed?: number;
+    /** Hard cap on rain, snow, and drift particles together. Lowered on weak devices. Default `900`. */
+    maxParticles?: number;
+    /** Wind speed in pixels per second at `wind: 1`. Default `600`. */
+    windStrength?: number;
+    /** Initial {@link Ambient.surfaces}. */
+    surfaces?: AmbientSurface[];
+    /** Initial {@link Ambient.shelters}. */
+    shelters?: AmbientShelter[];
+    /** Initial {@link Ambient.snowSettles}. Default `false`. */
+    snowSettles?: boolean;
+    /** Deepest settled snow, in pixels. Default `16`. */
+    maxSnowDepth?: number;
+    /** Hex color of the fog. Default `"#dde5ee"`; a sand color makes a sandstorm. */
+    fogColor?: string;
+    /** Hex color of rain. Default `"#c8d6ea"`. */
+    rainColor?: string;
+    /** Hex color of snow, falling and settled. Default `"#ffffff"`. */
+    snowColor?: string;
+    /**
+     * Forces reduced motion on or off. By default it follows the player's
+     * `prefers-reduced-motion` setting: fewer particles and softer lightning.
+     */
+    reducedMotion?: boolean;
+    /** Initial state. Fields left out start at `0`, and `tintColor` at `"#1b2a55"`. */
+    state?: AmbientChange;
+}
+/** A lightning strike, passed to {@link Ambient.onLightning}. */
+export interface AmbientStrike {
+    /** `0` is overhead, `1` is far away. Use it to delay and soften the thunder. */
+    distance: number;
+    /** Screen X of the bolt, in pixels. */
+    x: number;
+}
+/** A glowing dot, the art of a drift that uses no image: fireflies, embers, dust. */
+export interface AmbientDot {
+    /** Hex color of the dot, such as `"#fff6a0"`. */
+    color: string;
+    /** Radius of the solid core, in pixels. Default `2`. */
+    radius?: number;
+    /** Radius of the soft halo around the core, in pixels. Default `0`. */
+    glow?: number;
+}
+/**
+ * How a drift moves.
+ *
+ * - `"fall"`: sways and tumbles downward, like leaves, petals, or ash. Rests a
+ *   moment where it lands on a surface.
+ * - `"rise"`: floats upward, like embers or bubbles.
+ * - `"hover"`: wanders slowly in place, like fireflies or dust.
+ */
+export type AmbientDriftMotion = "fall" | "rise" | "hover";
+/** Options for {@link Ambient.addDrift}. Give either `images` or `dot`. */
+export interface AmbientDriftOptions {
+    /** How the drift moves. */
+    motion: AmbientDriftMotion;
+    /** Image keys the game loaded or created; each particle picks one. */
+    images?: string[];
+    /** A glowing dot, for drifts that need no image. */
+    dot?: AmbientDot;
+    /** Density from `0` to `1`, like the state fields. Default `0.5`. */
+    amount?: number;
+    /**
+     * Size of an image particle, as the pixel length of its longest side, or a
+     * `[min, max]` range. Nearer particles are drawn larger. Default `[16, 32]`.
+     * Ignored for dots, which use their own radius.
+     */
+    size?: number | [number, number];
+    /** Speed multiplier. Default `1`. */
+    speed?: number;
+    /** How much images tumble and turn: `0` keeps them upright. Default `1` for `"fall"`, `0` otherwise. */
+    spin?: number;
+    /** Side-to-side swing. Default `1`. */
+    sway?: number;
+    /** How much the wind carries the drift, `0` for none, as underwater. Default `1` for `"fall"`, `0.5` otherwise. */
+    wind?: number;
+    /** Brightness flicker from `0` to `1`. Default `0`. */
+    twinkle?: number;
+    /**
+     * Draw the drift above the darkness, so it glows at night. Default `true`
+     * for a dot with a glow, `false` otherwise.
+     */
+    lit?: boolean;
+    /** Fade out while rising instead of leaving through the top. Default `true` for dots, `false` for images. */
+    fade?: boolean;
+}
+/**
+ * A stream of leaves, petals, embers, bubbles, fireflies, or dust, created by
+ * {@link Ambient.addDrift}. It shares the ambient's wind and parallax.
+ */
+export declare class AmbientDrift {
+    /** How the drift moves. */
+    get motion(): AmbientDriftMotion;
+    /** Density from `0` to `1`. Setting it stops a running {@link AmbientDrift.to}. */
+    get amount(): number;
+    set amount(value: number);
+    /**
+     * Changes the density over `durationMs` milliseconds. The promise resolves
+     * when the amount arrives, or when a later change takes over.
+     */
+    to(amount: number, durationMs: number): Promise<void>;
+}
+/**
+ * Weather and atmosphere for a game: rain, snow, wind, fog, lightning,
+ * drifting leaves or fireflies, and the light of the hour.
+ *
+ * One shared state of intensities drives every effect, and every effect reads
+ * the same wind. All particles are painted into two canvas-sized surfaces, one
+ * behind the play field and one in front of it, so the module adds two sprites
+ * to the game whatever the weather.
+ *
+ * The ambient never moves a game sprite. The wind reaches the game only through
+ * {@link Ambient.windX}, which the game applies where it wants.
+ *
+ * Call {@link Ambient.update} once per frame. An ambient survives
+ * {@link Game.reset}: it puts its surfaces back on its next update and keeps
+ * its weather, so one ambient can serve every scene. Creating a new one in a
+ * scene's `onCreate` also works.
+ *
+ * @example
+ * ```ts
+ * const ambient = new Ambient(game, { surfaces: [ground], seed: 7 });
+ * ambient.preset("rain");
+ *
+ * // in onUpdate(dt)
+ * ambient.update(dt);
+ *
+ * // later: a storm rolls in over four seconds
+ * await ambient.to({ rain: 1, storm: 0.6, wind: 0.5 }, 4000);
+ * ```
+ */
+export declare class Ambient {
+    /**
+     * Things rain splashes on and snow settles on: sprites, by the top of their
+     * collision body, or {@link AmbientLine}s in world space.
+     */
+    surfaces: AmbientSurface[];
+    /**
+     * Covered areas where no rain, snow, or falling drift is drawn: sprites, by
+     * their collision body, or {@link AmbientRect}s in world space.
+     */
+    shelters: AmbientShelter[];
+    /** When `true`, snow builds up on surfaces while it snows and melts when it stops. */
+    snowSettles: boolean;
+    /** Softer lightning and fewer particles. Follows the player's system setting unless the game sets it. */
+    reducedMotion: boolean;
+    /**
+     * Called on every lightning strike, for thunder, a camera shake, or a
+     * gameplay reaction.
+     */
+    onLightning: ((strike: AmbientStrike) => void) | null;
+    /**
+     * Creates an ambient and adds its two surfaces to the game.
+     *
+     * @param game - The game to draw into.
+     * @param options - Layers, surfaces, shelters, seed, colors, and initial state.
+     */
+    constructor(game: Game, options?: AmbientOptions);
+    /** The current state. Read-only: change it with {@link Ambient.set}, {@link Ambient.to}, or {@link Ambient.preset}. */
+    get state(): Readonly<AmbientState>;
+    /**
+     * The wind at this frame, gusts included, in pixels per second. Positive
+     * blows right. This is the only way the weather reaches the game's sprites:
+     *
+     * ```ts
+     * player.vx += ambient.windX * 0.3 * dt;
+     * ```
+     */
+    get windX(): number;
+    /** `true` while any {@link Ambient.to} or {@link Ambient.preset} transition is running. */
+    get isTransitioning(): boolean;
+    /** Changes state fields at once. Fields left out keep their value. */
+    set(change: AmbientChange): void;
+    /**
+     * Changes state fields over `durationMs` milliseconds with an ease in and
+     * out. Fields left out keep their value and any transition they are in.
+     *
+     * A field that is already moving starts from wherever it is, so a new call
+     * can interrupt an old one without a jump. The promise resolves when every
+     * field arrives, or when later calls have taken all of them over.
+     */
+    to(change: AmbientChange, durationMs: number): Promise<void>;
+    /**
+     * Moves to a named weather. The preset's fields are set, and the other
+     * weather fields (`wind`, `gusts`, `rain`, `snow`, `fog`, `storm`) go to `0`.
+     * Light fields are left alone, because weather and time of day are
+     * independent.
+     *
+     * @param name - The preset.
+     * @param durationMs - Transition length in milliseconds. `0`, the default, changes at once.
+     */
+    preset(name: AmbientPreset, durationMs?: number): Promise<void>;
+    /**
+     * Adds a stream of drifting things: leaves, petals, embers, bubbles,
+     * fireflies, or dust. Images must already be loaded or created.
+     *
+     * @example
+     * ```ts
+     * const leaves = ambient.addDrift({ images: ["leaf-red", "leaf-gold"], motion: "fall", amount: 0.5 });
+     * const fireflies = ambient.addDrift({ dot: { color: "#fff6a0", glow: 8 }, motion: "hover", twinkle: 1 });
+     * ```
+     */
+    addDrift(options: AmbientDriftOptions): AmbientDrift;
+    /** Removes a drift at once. Fade it out first with `drift.to(0, ms)` for a gentle exit. */
+    removeDrift(drift: AmbientDrift): void;
+    /** Removes all settled snow at once. */
+    clearSnow(): void;
+    /**
+     * Depth of settled snow in pixels on a surface at world X, `0` where there
+     * is none. Useful for footprints, or for slowing a player in deep snow.
+     */
+    snowDepthAt(surface: AmbientSurface, worldX: number): number;
+    /**
+     * Advances the weather by `dt` seconds. Call it once per frame from the
+     * scene's `onUpdate`. Transition promises resolve from here.
+     */
+    update(dt: number): void;
+    /** Removes both surfaces from the game and resolves every pending transition. The ambient does nothing afterwards. */
+    destroy(): void;
+}