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

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