minimojs 1.0.0-alpha.23 → 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.d.ts

@@ -186,9 +186,45 @@ export type BackgroundFit = "none" | "stretch" | "contain" | "cover";
  * scenes keep their expected `this` value.
  */
 export interface IScene {
+    /**
+     * Registers images this scene needs that the rest of the game does not.
+     *
+     * **Only for games with many scenes that each carry many assets of their
+     * own**, such as a game with many levels, where a player does not reach
+     * every scene in a session and loading all of them at boot would make the
+     * first wait needlessly long. Every other game should load its images in
+     * {@link Game.onPreload}, once, at boot.
+     *
+     * Called whenever the scene is entered — by {@link Game.start},
+     * {@link Game.reset}, or {@link Game.transitionTo} — before
+     * {@link IScene.onCreate}. Call {@link Game.loadImage} inside it, as inside
+     * `game.onPreload`. Images that are already loaded are skipped, so replaying
+     * a scene loads nothing.
+     *
+     * When images are pending, the scene being left freezes under a progress
+     * ring until they load, and only then is this scene created. Because of
+     * that, `reset()` and `transitionTo()` may return before this scene exists:
+     * continue in `onCreate()`, not in the code after the call.
+     *
+     * @example
+     * ```ts
+     * class Level {
+     *   constructor(n) { this.n = n; }
+     *   onPreload() {
+     *     game.loadImage(`level-${this.n}-bg`, `assets/level-${this.n}-bg.png`);
+     *   }
+     *   onCreate() {
+     *     game.addBackground(new BackgroundLayer(`level-${this.n}-bg`));
+     *   }
+     * }
+     * ```
+     */
+    onPreload?(): void;
     /**
      * Called when the scene is created, before the first frame and again after
-     * each {@link Game.reset} that targets this scene.
+     * each {@link Game.reset} that targets this scene. When the scene has an
+     * {@link IScene.onPreload} with images still loading, it is called once they
+     * have loaded.
      */
     onCreate?(): void;
     /**
@@ -570,6 +606,10 @@ export declare class TextSprite extends Sprite {
     anchorX: "left" | "center" | "right";
     anchorY: "top" | "middle" | "bottom";
     text: string;
+    /**
+     * CSS font family. Default: `monospace`, which needs no download. Name a web
+     * font here, and register it with {@link Game.requireFont}, to use one.
+     */
     fontFamily: string;
     fontSize: number;
     fontWeight: string;
@@ -793,12 +833,12 @@ export interface CollisionInfo {
  *
  * ---
  *
- * ## Required Font Setup
+ * ## Font Setup
  *
- * `drawText()` and `TextSprite` default to `"Press Start 2P", monospace`.
- * MinimoJS automatically waits for that default family before the first frame.
- * If you use additional families, register them with {@link Game.requireFont}
- * before calling {@link Game.start}.
+ * `drawText()` and `TextSprite` default to `monospace`, which every device
+ * has, so a game that names no font downloads none and waits for none. To use
+ * a web font, declare it in your page, register it with {@link Game.requireFont}
+ * before calling {@link Game.start}, and name it in {@link TextSprite.fontFamily}.
  *
  * Prefer {@link TextSprite} for persistent UI text, interactive labels,
  * buttons, fixed-size text boxes, and styled text elements. Keep
@@ -1018,6 +1058,15 @@ export interface CollisionInfo {
  * Legacy `game.onCreate` / `game.onUpdate` callbacks still work when no active
  * {@link IScene} is set.
  *
+ * ### Loading a Scene's Own Images
+ *
+ * Load images in {@link Game.onPreload}: once, at boot. Only a game with many
+ * scenes that each carry many assets of their own — typically a game with many
+ * levels, whose player does not reach every level in a session — should give
+ * scenes an {@link IScene.onPreload}. Entering such a scene loads its images
+ * first, with the scene being left frozen under a progress ring, so `reset()`
+ * and `transitionTo()` may return before the new scene's `onCreate()` runs.
+ *
  * ---
  *
  * ## EmojiSprite Lifecycle Ownership
@@ -1164,11 +1213,15 @@ export declare class Game {
     /**
      * Asset registration callback invoked once before the first scene is created.
      *
-     * Use this to register images with {@link Game.loadImage}. The callback is
-     * synchronous: it should only queue assets, not await network work.
+     * This is the normal place to load a game's images. Use it to register them
+     * with {@link Game.loadImage}. The callback is synchronous: it should only
+     * queue assets, not await network work.
      *
-     * After `onPreload` returns, MinimoJS loads the queued images automatically
-     * and shows a default loading screen until they are ready.
+     * After `onPreload` returns, MinimoJS loads the queued images, together with
+     * those of the first scene's {@link IScene.onPreload} if it has one, and
+     * shows a loading line until they are ready. If any image fails, it asks the
+     * player with `window.confirm` whether to retry them; declining leaves the
+     * game on the loading screen and reports the failed images on the console.
      *
      * @example
      * ```ts
@@ -1223,6 +1276,13 @@ export declare class Game {
      * Returns `true` while a full-screen scene transition is playing.
      */
     get isTransitioning(): boolean;
+    /**
+     * Returns `true` while images are loading: at boot, or while a scene with
+     * pending images in its {@link IScene.onPreload} is being entered. While a
+     * scene loads, the scene being left is frozen and `reset()` and
+     * `transitionTo()` are ignored.
+     */
+    get isLoading(): boolean;
     /**
      * Creates a new MinimoJS game instance.
      *
@@ -1369,7 +1429,8 @@ export declare class Game {
      * This method registers the asset only. The actual network/image fetch begins
      * after `onPreload` returns and is managed automatically by the engine.
      *
-     * `loadImage` may only be called from within {@link Game.onPreload}.
+     * `loadImage` may only be called from within {@link Game.onPreload} or a
+     * scene's {@link IScene.onPreload}.
      *
      * @param key - Stable key used later by {@link BackgroundLayer.imageKey} or {@link Game.getImage}.
      * @param src - Image URL or relative path.
@@ -2122,14 +2183,8 @@ export declare class Game {
      * The text overlay list is cleared after each render. Call this inside `onUpdate`.
      *
      * **Layer:** Text is always drawn on top of all sprites.
-     * **Font:** Text uses `"Press Start 2P", monospace` by default.
-     * You MUST declare that font yourself in `index.html` (for example via Google
-     * Fonts) before calling {@link Game.start}. MinimoJS does NOT inject or
-     * download external fonts for you.
-     *
-     * `Game.start()` waits for the default font and for any extra families you
-     * registered with {@link Game.requireFont}. If a font is unavailable, the
-     * browser falls back to `monospace`.
+     * **Font:** Text always uses `monospace`. Use {@link TextSprite} for any
+     * other family.
      *
      * Prefer {@link TextSprite} for UI buttons or labels that need persistent
      * bounds, hit testing, fixed sizes, backgrounds, borders, or text stroke.
@@ -2236,6 +2291,12 @@ export declare class Game {
      * `onCreate()` (or legacy {@link Game.onCreate} if no scene is active) so it
      * can rebuild synchronously.
      *
+     * The exception is a scene whose {@link IScene.onPreload} registers images
+     * that are not loaded yet. Then the current scene freezes under a progress
+     * ring, nothing is cleared until the images load, and `reset()` returns
+     * before the scene is rebuilt; its `onCreate()` runs once they have loaded.
+     * A `reset()` called while a scene is loading is ignored.
+     *
      * @param scene - Optional new scene to make active before rebuilding.
      *
      * @example
@@ -2263,7 +2324,17 @@ export declare class Game {
      *
      * While the transition is active, gameplay updates are paused.
      *
-     * If the game loop is not running yet, this falls back to an immediate
+     * If the target scene's {@link IScene.onPreload} registers images that are
+     * not loaded yet, the current scene first freezes under a progress ring
+     * until they load, and the transition plays after that. `transitionTo()`
+     * then returns before the target scene exists; continue in its
+     * `onCreate()` or in `onComplete`. If the player declines to retry failed
+     * images, the game stays on the current scene and `onComplete` is not
+     * called.
+     *
+     * A call made while a transition plays or a scene loads is ignored.
+     *
+     * If the game loop is not running yet, this falls back to
      * {@link Game.reset}.
      *
      * @param scene - Target scene to make active.
@@ -2274,12 +2345,11 @@ export declare class Game {
     /**
      * Starts the `requestAnimationFrame` game loop.
      * Safe to call multiple times — does nothing if already running.
-     * On the first start, if {@link Game.onPreload} is set, MinimoJS first runs
-     * asset registration, loads queued images, waits for all fonts registered via
-     * {@link Game.requireFont}, and only then, if images were queued, shows a
-     * default loading screen while those image assets are still loading.
-     * After preload completes, the active scene's `onCreate()` is called before
-     * the first frame.
+     * On the first start, MinimoJS runs {@link Game.onPreload} and the active
+     * scene's {@link IScene.onPreload}, loads the images they queued while
+     * showing a thin loading line, and waits for all fonts registered via
+     * {@link Game.requireFont}. After that, the active scene's `onCreate()` is
+     * called before the first frame.
      *
      * The loop calls the active scene's `onUpdate(dt)` (or legacy
      * {@link Game.onUpdate}) once per frame, then renders all sprites and text

package/dist/minimo.js

@@ -22,6 +22,8 @@ import { TextSystem } from "./internal/TextSystem.js";
 import { TrailSystem } from "./internal/TrailSystem.js";
 import { TransitionSystem } from "./internal/TransitionSystem.js";
 import { TimerSystem } from "./internal/TimerSystem.js";
+/** How long a scene may load before its progress ring appears, so a fast load shows none. */
+const SCENE_LOADING_INDICATOR_DELAY_MS = 250;
 // ---------------------------------------------------------------------------
 // EmojiSprite
 // ---------------------------------------------------------------------------
@@ -535,7 +537,11 @@ export class TextSprite extends Sprite {
         super();
         this.anchorX = "center";
         this.anchorY = "middle";
-        this.fontFamily = '"Press Start 2P", monospace';
+        /**
+         * CSS font family. Default: `monospace`, which needs no download. Name a web
+         * font here, and register it with {@link Game.requireFont}, to use one.
+         */
+        this.fontFamily = "monospace";
         this.fontWeight = "400";
         this.lineHeight = 1.2;
         this.maxWidth = 0;
@@ -866,12 +872,12 @@ export class BackgroundLayer {
  *
  * ---
  *
- * ## Required Font Setup
+ * ## Font Setup
  *
- * `drawText()` and `TextSprite` default to `"Press Start 2P", monospace`.
- * MinimoJS automatically waits for that default family before the first frame.
- * If you use additional families, register them with {@link Game.requireFont}
- * before calling {@link Game.start}.
+ * `drawText()` and `TextSprite` default to `monospace`, which every device
+ * has, so a game that names no font downloads none and waits for none. To use
+ * a web font, declare it in your page, register it with {@link Game.requireFont}
+ * before calling {@link Game.start}, and name it in {@link TextSprite.fontFamily}.
  *
  * Prefer {@link TextSprite} for persistent UI text, interactive labels,
  * buttons, fixed-size text boxes, and styled text elements. Keep
@@ -1091,6 +1097,15 @@ export class BackgroundLayer {
  * Legacy `game.onCreate` / `game.onUpdate` callbacks still work when no active
  * {@link IScene} is set.
  *
+ * ### Loading a Scene's Own Images
+ *
+ * Load images in {@link Game.onPreload}: once, at boot. Only a game with many
+ * scenes that each carry many assets of their own — typically a game with many
+ * levels, whose player does not reach every level in a session — should give
+ * scenes an {@link IScene.onPreload}. Entering such a scene loads its images
+ * first, with the scene being left frozen under a progress ring, so `reset()`
+ * and `transitionTo()` may return before the new scene's `onCreate()` runs.
+ *
  * ---
  *
  * ## EmojiSprite Lifecycle Ownership
@@ -1210,6 +1225,15 @@ export class Game {
     get isTransitioning() {
         return this._transitionSystem.isActive;
     }
+    /**
+     * Returns `true` while images are loading: at boot, or while a scene with
+     * pending images in its {@link IScene.onPreload} is being entered. While a
+     * scene loads, the scene being left is frozen and `reset()` and
+     * `transitionTo()` are ignored.
+     */
+    get isLoading() {
+        return this._preloadPromise !== null || this._sceneLoad !== null;
+    }
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------
@@ -1238,6 +1262,7 @@ export class Game {
         /** @internal */ this._isRegisteringPreloadAssets = false;
         /** @internal */ this._hasCompletedPreload = false;
         /** @internal */ this._preloadPromise = null;
+        /** @internal */ this._sceneLoad = null;
         /** @internal */ this._onCreate = null;
         /** @internal */ this._currentScene = null;
         /**
@@ -1313,11 +1338,15 @@ export class Game {
         /**
          * Asset registration callback invoked once before the first scene is created.
          *
-         * Use this to register images with {@link Game.loadImage}. The callback is
-         * synchronous: it should only queue assets, not await network work.
+         * This is the normal place to load a game's images. Use it to register them
+         * with {@link Game.loadImage}. The callback is synchronous: it should only
+         * queue assets, not await network work.
          *
-         * After `onPreload` returns, MinimoJS loads the queued images automatically
-         * and shows a default loading screen until they are ready.
+         * After `onPreload` returns, MinimoJS loads the queued images, together with
+         * those of the first scene's {@link IScene.onPreload} if it has one, and
+         * shows a loading line until they are ready. If any image fails, it asks the
+         * player with `window.confirm` whether to retry them; declining leaves the
+         * game on the loading screen and reports the failed images on the console.
          *
          * @example
          * ```ts
@@ -1376,9 +1405,6 @@ export class Game {
         this._loopSystem = new LoopSystem(this._onLoopFrameCallback.bind(this));
         this._loopSystem.onCreate = this._invokeCreate.bind(this);
         this._inputSystem.bindInputEvents();
-        this.requireFont('"Press Start 2P"', {
-            sampleText: "Loading... SCORE LIVES GAME OVER YOU WIN",
-        });
         this.applyGlobalFontRequirements();
     }
     // -------------------------------------------------------------------------
@@ -1537,7 +1563,8 @@ export class Game {
      * This method registers the asset only. The actual network/image fetch begins
      * after `onPreload` returns and is managed automatically by the engine.
      *
-     * `loadImage` may only be called from within {@link Game.onPreload}.
+     * `loadImage` may only be called from within {@link Game.onPreload} or a
+     * scene's {@link IScene.onPreload}.
      *
      * @param key - Stable key used later by {@link BackgroundLayer.imageKey} or {@link Game.getImage}.
      * @param src - Image URL or relative path.
@@ -1551,7 +1578,7 @@ export class Game {
      */
     loadImage(key, src) {
         if (!this._isRegisteringPreloadAssets) {
-            throw new Error("MinimoJS: loadImage() may only be called inside game.onPreload.");
+            throw new Error("MinimoJS: loadImage() may only be called inside game.onPreload or a scene's onPreload().");
         }
         this._assetSystem.queueImage(key, src);
     }
@@ -2415,14 +2442,8 @@ export class Game {
      * The text overlay list is cleared after each render. Call this inside `onUpdate`.
      *
      * **Layer:** Text is always drawn on top of all sprites.
-     * **Font:** Text uses `"Press Start 2P", monospace` by default.
-     * You MUST declare that font yourself in `index.html` (for example via Google
-     * Fonts) before calling {@link Game.start}. MinimoJS does NOT inject or
-     * download external fonts for you.
-     *
-     * `Game.start()` waits for the default font and for any extra families you
-     * registered with {@link Game.requireFont}. If a font is unavailable, the
-     * browser falls back to `monospace`.
+     * **Font:** Text always uses `monospace`. Use {@link TextSprite} for any
+     * other family.
      *
      * Prefer {@link TextSprite} for UI buttons or labels that need persistent
      * bounds, hit testing, fixed sizes, backgrounds, borders, or text stroke.
@@ -2558,6 +2579,12 @@ export class Game {
      * `onCreate()` (or legacy {@link Game.onCreate} if no scene is active) so it
      * can rebuild synchronously.
      *
+     * The exception is a scene whose {@link IScene.onPreload} registers images
+     * that are not loaded yet. Then the current scene freezes under a progress
+     * ring, nothing is cleared until the images load, and `reset()` returns
+     * before the scene is rebuilt; its `onCreate()` runs once they have loaded.
+     * A `reset()` called while a scene is loading is ignored.
+     *
      * @param scene - Optional new scene to make active before rebuilding.
      *
      * @example
@@ -2574,6 +2601,31 @@ export class Game {
      * ```
      */
     reset(scene) {
+        if (this._sceneLoad !== null) {
+            return;
+        }
+        if (!this._hasCompletedPreload) {
+            if (scene !== undefined) {
+                this._currentScene = scene;
+            }
+            // Boot builds the active scene once its images load, so a scene chosen
+            // now is only recorded. Before start(), a scene with images of its own
+            // waits for start() to load them.
+            if (this._preloadPromise !== null || this._currentScene?.onPreload) {
+                return;
+            }
+            this._resetNow();
+            return;
+        }
+        this._registerSceneAssets(scene ?? this._currentScene);
+        if (this._assetSystem.getQueuedImageCount() === 0) {
+            this._resetNow(scene);
+            return;
+        }
+        this._beginSceneLoad(() => this._resetNow(scene));
+    }
+    /** @internal */
+    _resetNow(scene) {
         if (scene !== undefined) {
             this._currentScene = scene;
         }
@@ -2601,7 +2653,17 @@ export class Game {
      *
      * While the transition is active, gameplay updates are paused.
      *
-     * If the game loop is not running yet, this falls back to an immediate
+     * If the target scene's {@link IScene.onPreload} registers images that are
+     * not loaded yet, the current scene first freezes under a progress ring
+     * until they load, and the transition plays after that. `transitionTo()`
+     * then returns before the target scene exists; continue in its
+     * `onCreate()` or in `onComplete`. If the player declines to retry failed
+     * images, the game stays on the current scene and `onComplete` is not
+     * called.
+     *
+     * A call made while a transition plays or a scene loads is ignored.
+     *
+     * If the game loop is not running yet, this falls back to
      * {@link Game.reset}.
      *
      * @param scene - Target scene to make active.
@@ -2614,11 +2676,20 @@ export class Game {
             onComplete?.();
             return;
         }
-        if (this._transitionSystem.isActive) {
+        if (this._transitionSystem.isActive || this._sceneLoad !== null) {
             return;
         }
+        this._registerSceneAssets(scene);
+        if (this._assetSystem.getQueuedImageCount() === 0) {
+            this._transitionNow(scene, options, onComplete);
+            return;
+        }
+        this._beginSceneLoad(() => this._transitionNow(scene, options, onComplete));
+    }
+    /** @internal */
+    _transitionNow(scene, options, onComplete) {
         const fromCanvas = this._captureFrameSnapshot();
-        this.reset(scene);
+        this._resetNow(scene);
         const toCanvas = this._captureFrameSnapshot();
         this._transitionSystem.start(fromCanvas, toCanvas, this.width, this.height, options, onComplete);
     }
@@ -2628,12 +2699,11 @@ export class Game {
     /**
      * Starts the `requestAnimationFrame` game loop.
      * Safe to call multiple times — does nothing if already running.
-     * On the first start, if {@link Game.onPreload} is set, MinimoJS first runs
-     * asset registration, loads queued images, waits for all fonts registered via
-     * {@link Game.requireFont}, and only then, if images were queued, shows a
-     * default loading screen while those image assets are still loading.
-     * After preload completes, the active scene's `onCreate()` is called before
-     * the first frame.
+     * On the first start, MinimoJS runs {@link Game.onPreload} and the active
+     * scene's {@link IScene.onPreload}, loads the images they queued while
+     * showing a thin loading line, and waits for all fonts registered via
+     * {@link Game.requireFont}. After that, the active scene's `onCreate()` is
+     * called before the first frame.
      *
      * The loop calls the active scene's `onUpdate(dt)` (or legacy
      * {@link Game.onUpdate}) once per frame, then renders all sprites and text
@@ -2680,51 +2750,57 @@ export class Game {
                 this._isRegisteringPreloadAssets = false;
             }
         }
-        const totalAssets = this._assetSystem.getQueuedImageCount();
-        let fontsReady = false;
-        let loadingLoaded = 0;
-        let loadingCurrentKey = null;
-        const renderLoadingProgress = () => {
-            if (!fontsReady || totalAssets === 0) {
+        const preloadPromise = Promise.all([
+            this._loadBootImages(),
+            this.waitForDocumentFonts(),
+        ]).then(([loaded]) => {
+            if (this._preloadPromise !== preloadPromise)
                 return;
-            }
-            this._renderLoadingScreen(loadingLoaded, totalAssets, loadingCurrentKey);
-        };
-        const fontReadyPromise = this.waitForDocumentFonts().then(() => {
-            fontsReady = true;
-            renderLoadingProgress();
-        });
-        if (totalAssets === 0) {
-            this._preloadPromise = fontReadyPromise
-                .then(() => {
-                this._hasCompletedPreload = true;
-                this._preloadPromise = null;
-                this._loopSystem.start();
-            })
-                .catch((error) => {
-                this._preloadPromise = null;
-                throw error;
-            });
-            return;
-        }
-        const assetPromise = this._assetSystem.loadQueuedImages((loaded, total, currentKey) => {
-            loadingLoaded = loaded;
-            loadingCurrentKey = currentKey;
-            if (!fontsReady)
+            this._preloadPromise = null;
+            if (!loaded)
                 return;
-            this._renderLoadingScreen(loaded, total, currentKey);
-        });
-        this._preloadPromise = Promise.all([assetPromise, fontReadyPromise])
-            .then(() => {
             this._hasCompletedPreload = true;
-            this._preloadPromise = null;
             this._loopSystem.start();
-        })
-            .catch((error) => {
-            this._preloadPromise = null;
+        });
+        this._preloadPromise = preloadPromise;
+        preloadPromise.catch((error) => {
+            if (this._preloadPromise === preloadPromise) {
+                this._preloadPromise = null;
+            }
             throw error;
         });
     }
+    /**
+     * Loads the boot images, then those of any scene made active while they
+     * loaded, retrying failures while the player agrees. Resolves `false` when
+     * the player declines, which leaves the game on the loading screen.
+     *
+     * @internal
+     */
+    async _loadBootImages() {
+        let registeredScene = undefined;
+        for (;;) {
+            if (registeredScene !== this._currentScene) {
+                registeredScene = this._currentScene;
+                this._registerSceneAssets(registeredScene);
+            }
+            const failed = await this._assetSystem.loadQueuedImages((settled, total) => {
+                if (total > 0)
+                    this._renderLoadingScreen(settled / total);
+            });
+            if (failed.length > 0) {
+                this._reportFailedImages(failed);
+                if (!this._confirmImageRetry(failed.length)) {
+                    this._assetSystem.discardQueuedImages();
+                    return false;
+                }
+                continue;
+            }
+            if (registeredScene === this._currentScene) {
+                return true;
+            }
+        }
+    }
     /**
      * Stops the game loop. The canvas retains its last rendered frame.
      * Call {@link Game.start} to resume.
@@ -2737,6 +2813,10 @@ export class Game {
     // -------------------------------------------------------------------------
     /** @internal */ _onLoopFrameCallback(dt, dtMs) {
         this._renderSystem.beginDynamicSurfacePass();
+        if (this._sceneLoad !== null) {
+            this._renderInterruption();
+            return;
+        }
         if (this._transitionSystem.isActive) {
             this._transitionSystem.update(dtMs);
             if (this._transitionSystem.isActive) {
@@ -2750,29 +2830,23 @@ export class Game {
             return;
         }
         this._timerSystem.update(dtMs);
-        if (this._transitionSystem.isActive) {
-            this._renderTransition();
-            this._inputSystem.clearFramePressedState();
-            this._textSystem.clear();
+        if (this._isSceneChangeInterrupting()) {
+            this._renderInterruption();
             return;
         }
         this._animationSystem.update(dtMs);
         this._explosionSystem.update(dt, dtMs);
         this._physicsSystem.update(this._spriteSystem.getMutableSprites(), dt);
-        if (this._transitionSystem.isActive) {
-            this._renderTransition();
-            this._inputSystem.clearFramePressedState();
-            this._textSystem.clear();
+        if (this._isSceneChangeInterrupting()) {
+            this._renderInterruption();
             return;
         }
         if (this._currentScene?.onUpdate)
             this._currentScene.onUpdate(dt);
         else if (this.onUpdate)
             this.onUpdate(dt);
-        if (this._transitionSystem.isActive) {
-            this._renderTransition();
-            this._inputSystem.clearFramePressedState();
-            this._textSystem.clear();
+        if (this._isSceneChangeInterrupting()) {
+            this._renderInterruption();
             return;
         }
         this._trailSystem.update(dtMs, this._renderSystem.getSpriteRenderSnapshot.bind(this._renderSystem));
@@ -2781,6 +2855,118 @@ export class Game {
         this._textSystem.clear();
     }
     /** @internal */
+    _isSceneChangeInterrupting() {
+        return this._transitionSystem.isActive || this._sceneLoad !== null;
+    }
+    /**
+     * Draws a frame in which gameplay does not advance: a loading scene under
+     * its ring, or a transition.
+     *
+     * @internal
+     */
+    _renderInterruption() {
+        const load = this._sceneLoad;
+        if (load !== null) {
+            this._renderSystem.renderSceneLoading({
+                canvas: this._canvas,
+                context: this._ctx,
+                pageBackground: this.pageBackground,
+                snapshot: load.snapshot,
+                progress: load.progress,
+                showIndicator: performance.now() - load.startedAt >= SCENE_LOADING_INDICATOR_DELAY_MS,
+                ink: load.ink,
+            });
+        }
+        else {
+            this._renderTransition();
+        }
+        this._inputSystem.clearFramePressedState();
+        this._textSystem.clear();
+    }
+    /**
+     * Runs a scene's `onPreload()`, if it has one, with image registration
+     * allowed.
+     *
+     * @internal
+     */
+    _registerSceneAssets(scene) {
+        if (!scene?.onPreload)
+            return;
+        this._isRegisteringPreloadAssets = true;
+        try {
+            scene.onPreload();
+        }
+        finally {
+            this._isRegisteringPreloadAssets = false;
+        }
+    }
+    /**
+     * Freezes the current scene under a progress ring while the queued images
+     * load, then calls `finish` to enter the next scene. If images fail and the
+     * player declines to retry, the current scene resumes instead.
+     *
+     * @internal
+     */
+    _beginSceneLoad(finish) {
+        this._transitionSystem.clear();
+        const snapshot = document.createElement("canvas");
+        snapshot.width = this._canvas.width;
+        snapshot.height = this._canvas.height;
+        snapshot.getContext("2d")?.drawImage(this._canvas, 0, 0);
+        const load = {
+            snapshot,
+            ink: this._renderSystem.pickLoadingInk(snapshot),
+            progress: 0,
+            startedAt: performance.now(),
+        };
+        this._sceneLoad = load;
+        void this._loadSceneImages(load, finish);
+    }
+    /** @internal */
+    async _loadSceneImages(load, finish) {
+        for (;;) {
+            const failed = await this._assetSystem.loadQueuedImages((settled, total) => {
+                load.progress = total === 0 ? 1 : settled / total;
+            });
+            if (failed.length === 0)
+                break;
+            this._reportFailedImages(failed);
+            if (!this._confirmImageRetry(failed.length)) {
+                this._assetSystem.discardQueuedImages();
+                this._sceneLoad = null;
+                return;
+            }
+            load.progress = 0;
+        }
+        this._sceneLoad = null;
+        finish();
+    }
+    /** @internal */
+    _reportFailedImages(keys) {
+        const list = keys
+            .map((key) => `"${key}" (${this._assetSystem.getImageSource(key) ?? "no source"})`)
+            .join(", ");
+        console.error(`MinimoJS: ${keys.length} image${keys.length === 1 ? "" : "s"} failed to load: ${list}.`);
+    }
+    /**
+     * Asks the player whether to retry failed images, with the browser's own
+     * confirmation dialog. Returns `false` where no dialog can be shown.
+     *
+     * @internal
+     */
+    _confirmImageRetry(failedCount) {
+        if (typeof window === "undefined" || typeof window.confirm !== "function") {
+            return false;
+        }
+        const noun = failedCount === 1 ? "image" : "images";
+        try {
+            return window.confirm(`${failedCount} ${noun} could not be loaded. Try again?`);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** @internal */
     _invokeCreate() {
         if (this._currentScene?.onCreate)
             this._currentScene.onCreate();
@@ -2902,16 +3088,14 @@ export class Game {
         });
     }
     /** @internal */
-    _renderLoadingScreen(loaded, total, currentKey) {
+    _renderLoadingScreen(progress) {
         this._renderSystem.renderLoadingScreen({
             canvas: this._canvas,
             context: this._ctx,
             pageBackground: this.pageBackground,
             background: this.background,
             backgroundGradient: this.backgroundGradient,
-            loaded,
-            total,
-            currentKey,
+            progress,
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.23",
+  "version": "1.0.0-alpha.24",
   "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",