minimojs 1.0.0-alpha.24 → 1.0.0-alpha.25

package/dist/internal/RenderSystem.js

@@ -304,18 +304,21 @@ export class RenderSystem {
         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.
+     * Draws the frozen scene being left, dimmed so it reads as paused, 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;
+        const reveal = this.clampProgress(options.reveal);
         this.applyPageBackground(options.pageBackground);
         ctx.clearRect(0, 0, W, H);
         ctx.drawImage(options.snapshot, 0, 0, W, H);
-        if (!options.showIndicator)
+        if (reveal === 0)
             return;
+        this.dimScene(ctx, W, H, reveal);
         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;
@@ -327,18 +330,41 @@ export class RenderSystem {
         // 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.globalAlpha = 0.25 * reveal;
         ctx.beginPath();
         ctx.arc(W / 2, H / 2, radius, 0, Math.PI * 2);
         ctx.stroke();
         if (progress > 0) {
-            ctx.globalAlpha = 1;
+            ctx.globalAlpha = reveal;
             ctx.beginPath();
             ctx.arc(W / 2, H / 2, radius, start, start + Math.PI * 2 * progress);
             ctx.stroke();
         }
         ctx.restore();
     }
+    /**
+     * Chooses the ring's color against the frozen frame as it looks once fully
+     * dimmed, since that is what the ring is drawn over.
+     */
+    pickSceneLoadingInk(snapshot) {
+        const dimmed = document.createElement("canvas");
+        dimmed.width = snapshot.width;
+        dimmed.height = snapshot.height;
+        const ctx = dimmed.getContext("2d");
+        if (!ctx)
+            return "#ffffff";
+        ctx.drawImage(snapshot, 0, 0);
+        this.dimScene(ctx, dimmed.width, dimmed.height, 1);
+        return this.pickLoadingInk(dimmed);
+    }
+    /** @internal */
+    dimScene(ctx, width, height, reveal) {
+        ctx.save();
+        ctx.globalAlpha = RenderSystem.SCENE_LOADING_DIM * reveal;
+        ctx.fillStyle = "#000000";
+        ctx.fillRect(0, 0, width, height);
+        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,
@@ -991,3 +1017,5 @@ export class RenderSystem {
 RenderSystem.MAX_SURFACE_CACHE_ENTRIES = 256;
 /** @internal Stroke of the boot line and the scene ring, which match. */
 RenderSystem.LOADING_STROKE = 3;
+/** @internal Opacity of the black veil over a scene that is loading the next one. */
+RenderSystem.SCENE_LOADING_DIM = 0.4;

package/dist/minimo.d.ts

@@ -201,10 +201,10 @@ export interface IScene {
      * `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.
+     * When images are pending, the scene being left freezes, dimmed, 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
@@ -1064,7 +1064,7 @@ export interface CollisionInfo {
  * 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()`
+ * first, with the scene being left frozen and dimmed under a progress ring, so `reset()`
  * and `transitionTo()` may return before the new scene's `onCreate()` runs.
  *
  * ---
@@ -2292,7 +2292,7 @@ export declare class Game {
      * 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
+     * that are not loaded yet. Then the current scene freezes and dims 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.
@@ -2325,7 +2325,7 @@ export declare class Game {
      * While the transition is active, gameplay updates are paused.
      *
      * If the target scene's {@link IScene.onPreload} registers images that are
-     * not loaded yet, the current scene first freezes under a progress ring
+     * not loaded yet, the current scene first freezes and dims 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

package/dist/minimo.js

@@ -22,8 +22,10 @@ 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. */
+/** How long a scene may load before it dims and its progress ring appears, so a fast load shows neither. */
 const SCENE_LOADING_INDICATOR_DELAY_MS = 250;
+/** How long the dimming and the ring take to fade in once they appear. */
+const SCENE_LOADING_FADE_MS = 200;
 // ---------------------------------------------------------------------------
 // EmojiSprite
 // ---------------------------------------------------------------------------
@@ -1103,7 +1105,7 @@ export class BackgroundLayer {
  * 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()`
+ * first, with the scene being left frozen and dimmed under a progress ring, so `reset()`
  * and `transitionTo()` may return before the new scene's `onCreate()` runs.
  *
  * ---
@@ -2580,7 +2582,7 @@ export class Game {
      * 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
+     * that are not loaded yet. Then the current scene freezes and dims 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.
@@ -2654,7 +2656,7 @@ export class Game {
      * While the transition is active, gameplay updates are paused.
      *
      * If the target scene's {@link IScene.onPreload} registers images that are
-     * not loaded yet, the current scene first freezes under a progress ring
+     * not loaded yet, the current scene first freezes and dims 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
@@ -2873,7 +2875,8 @@ export class Game {
                 pageBackground: this.pageBackground,
                 snapshot: load.snapshot,
                 progress: load.progress,
-                showIndicator: performance.now() - load.startedAt >= SCENE_LOADING_INDICATOR_DELAY_MS,
+                reveal: (performance.now() - load.startedAt - SCENE_LOADING_INDICATOR_DELAY_MS) /
+                    SCENE_LOADING_FADE_MS,
                 ink: load.ink,
             });
         }
@@ -2915,7 +2918,7 @@ export class Game {
         snapshot.getContext("2d")?.drawImage(this._canvas, 0, 0);
         const load = {
             snapshot,
-            ink: this._renderSystem.pickLoadingInk(snapshot),
+            ink: this._renderSystem.pickSceneLoadingInk(snapshot),
             progress: 0,
             startedAt: performance.now(),
         };

package/package.json

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