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

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.22",
+  "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",