minimojs 1.0.0-alpha.13 → 1.0.0-alpha.14

package/dist/internal/LoopSystem.js

@@ -27,6 +27,9 @@ export class LoopSystem {
     set onCreate(callback) {
         this._onCreate = callback;
     }
+    get isRunning() {
+        return this._running;
+    }
     start() {
         if (this._running)
             return;

package/dist/internal/RenderSystem.js

@@ -3,6 +3,8 @@ export class RenderSystem {
     constructor() {
         this._surfaceCache = new Map();
         this._lastAppliedPageBackground = undefined;
+        this._transitionScratchCanvas = null;
+        this._transitionScratchContext = null;
     }
     clearSpriteCache() {
         this._surfaceCache.clear();
@@ -42,10 +44,57 @@ export class RenderSystem {
         };
     }
     render(options) {
+        this.applyPageBackground(options.pageBackground);
+        this.renderScene(options);
+    }
+    captureFrame(options) {
+        const snapshot = document.createElement("canvas");
+        snapshot.width = options.canvas.width;
+        snapshot.height = options.canvas.height;
+        const snapshotContext = snapshot.getContext("2d");
+        if (!snapshotContext) {
+            throw new Error("MinimoJS: Could not acquire a transition snapshot context.");
+        }
+        this.renderScene({
+            ...options,
+            canvas: snapshot,
+            context: snapshotContext,
+        });
+        return snapshot;
+    }
+    renderScreenTransition(options) {
+        const ctx = options.context;
+        const width = options.canvas.width;
+        const height = options.canvas.height;
+        const transition = options.transition;
+        const progress = this.easeTransitionProgress(transition.progress);
+        this.applyPageBackground(options.pageBackground);
+        ctx.clearRect(0, 0, width, height);
+        switch (transition.type) {
+            case "fade":
+                this.drawFadeTransition(ctx, transition, width, height, progress);
+                return;
+            case "wipe":
+                this.drawWipeTransition(ctx, transition, width, height, progress);
+                return;
+            case "slide":
+                this.drawSlideTransition(ctx, transition, width, height, progress);
+                return;
+            case "iris":
+                this.drawIrisTransition(ctx, transition, width, height, progress);
+                return;
+            case "pixelate":
+                this.drawPixelateTransition(ctx, transition, width, height, progress);
+                return;
+            case "flash":
+                this.drawFlashTransition(ctx, transition, width, height, progress);
+                return;
+        }
+    }
+    renderScene(options) {
         const ctx = options.context;
         const W = options.canvas.width;
         const H = options.canvas.height;
-        this.applyPageBackground(options.pageBackground);
         this.paintCanvasBackground(ctx, W, H, options.background, options.backgroundGradient);
         const backgrounds = [...options.backgroundLayers].sort((a, b) => a.layer - b.layer);
         for (const layer of backgrounds) {
@@ -177,6 +226,73 @@ export class RenderSystem {
         ctx.strokeRect(barX, barY, barWidth, barHeight);
         ctx.restore();
     }
+    drawFadeTransition(ctx, transition, width, height, progress) {
+        const firstHalf = progress < 0.5;
+        const localT = firstHalf ? progress / 0.5 : (progress - 0.5) / 0.5;
+        ctx.drawImage(firstHalf ? transition.fromCanvas : transition.toCanvas, 0, 0, width, height);
+        ctx.save();
+        ctx.globalAlpha = firstHalf ? localT : 1 - localT;
+        ctx.fillStyle = transition.color;
+        ctx.fillRect(0, 0, width, height);
+        ctx.restore();
+    }
+    drawWipeTransition(ctx, transition, width, height, progress) {
+        ctx.drawImage(transition.fromCanvas, 0, 0, width, height);
+        const clip = this.getScreenWipeClipRect(width, height, transition.direction, progress);
+        if (clip.width <= 0 || clip.height <= 0)
+            return;
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(clip.x, clip.y, clip.width, clip.height);
+        ctx.clip();
+        ctx.drawImage(transition.toCanvas, 0, 0, width, height);
+        ctx.restore();
+    }
+    drawSlideTransition(ctx, transition, width, height, progress) {
+        const offset = this.getSlideOffset(transition.direction, width, height, progress);
+        ctx.drawImage(transition.fromCanvas, offset.fromX, offset.fromY, width, height);
+        ctx.drawImage(transition.toCanvas, offset.toX, offset.toY, width, height);
+    }
+    drawIrisTransition(ctx, transition, width, height, progress) {
+        ctx.drawImage(transition.fromCanvas, 0, 0, width, height);
+        const maxRadius = Math.max(Math.hypot(transition.centerX, transition.centerY), Math.hypot(width - transition.centerX, transition.centerY), Math.hypot(transition.centerX, height - transition.centerY), Math.hypot(width - transition.centerX, height - transition.centerY));
+        ctx.save();
+        ctx.beginPath();
+        ctx.arc(transition.centerX, transition.centerY, maxRadius * progress, 0, Math.PI * 2);
+        ctx.clip();
+        ctx.drawImage(transition.toCanvas, 0, 0, width, height);
+        ctx.restore();
+    }
+    drawPixelateTransition(ctx, transition, width, height, progress) {
+        const firstHalf = progress < 0.5;
+        const localT = firstHalf ? progress / 0.5 : (progress - 0.5) / 0.5;
+        const source = firstHalf ? transition.fromCanvas : transition.toCanvas;
+        const pixelSize = firstHalf
+            ? this.lerp(1, transition.pixelSize, localT)
+            : this.lerp(transition.pixelSize, 1, localT);
+        this.drawPixelatedCanvas(ctx, source, width, height, pixelSize);
+    }
+    drawFlashTransition(ctx, transition, width, height, progress) {
+        const swapPoint = 0.28;
+        const overlayPeak = 0.52;
+        const source = progress < swapPoint ? transition.fromCanvas : transition.toCanvas;
+        let alpha = 0;
+        if (progress < swapPoint) {
+            alpha = progress / Math.max(0.001, swapPoint);
+        }
+        else if (progress < overlayPeak) {
+            alpha = 1;
+        }
+        else {
+            alpha = 1 - (progress - overlayPeak) / Math.max(0.001, 1 - overlayPeak);
+        }
+        ctx.drawImage(source, 0, 0, width, height);
+        ctx.save();
+        ctx.globalAlpha = Math.max(0, Math.min(1, alpha));
+        ctx.fillStyle = transition.color;
+        ctx.fillRect(0, 0, width, height);
+        ctx.restore();
+    }
     getRenderSurface(sprite) {
         const cacheKey = sprite.getRenderCacheKey();
         const cached = this._surfaceCache.get(cacheKey);
@@ -341,6 +457,42 @@ export class RenderSystem {
             }
         }
     }
+    getScreenWipeClipRect(width, height, direction, progress) {
+        switch (direction) {
+            case "left-to-right":
+                return {
+                    x: 0,
+                    y: 0,
+                    width: width * progress,
+                    height,
+                };
+            case "right-to-left": {
+                const clipWidth = width * progress;
+                return {
+                    x: width - clipWidth,
+                    y: 0,
+                    width: clipWidth,
+                    height,
+                };
+            }
+            case "top-to-bottom":
+                return {
+                    x: 0,
+                    y: 0,
+                    width,
+                    height: height * progress,
+                };
+            case "bottom-to-top": {
+                const clipHeight = height * progress;
+                return {
+                    x: 0,
+                    y: height - clipHeight,
+                    width,
+                    height: clipHeight,
+                };
+            }
+        }
+    }
     asEmojiSprite(sprite) {
         if ("sprite" in sprite && "size" in sprite) {
             return sprite;
@@ -501,6 +653,88 @@ export class RenderSystem {
         }
         return Math.max(scaleX, scaleY);
     }
+    easeTransitionProgress(t) {
+        const clamped = Math.max(0, Math.min(1, t));
+        return clamped * clamped * (3 - 2 * clamped);
+    }
+    getSlideOffset(direction, width, height, progress) {
+        switch (direction) {
+            case "left-to-right":
+                return {
+                    fromX: width * progress,
+                    fromY: 0,
+                    toX: width * (progress - 1),
+                    toY: 0,
+                };
+            case "right-to-left":
+                return {
+                    fromX: -width * progress,
+                    fromY: 0,
+                    toX: width * (1 - progress),
+                    toY: 0,
+                };
+            case "top-to-bottom":
+                return {
+                    fromX: 0,
+                    fromY: height * progress,
+                    toX: 0,
+                    toY: height * (progress - 1),
+                };
+            case "bottom-to-top":
+                return {
+                    fromX: 0,
+                    fromY: -height * progress,
+                    toX: 0,
+                    toY: height * (1 - progress),
+                };
+        }
+    }
+    drawPixelatedCanvas(ctx, source, width, height, pixelSize) {
+        const roundedPixelSize = Math.max(1, Math.round(pixelSize));
+        if (roundedPixelSize <= 1) {
+            ctx.drawImage(source, 0, 0, width, height);
+            return;
+        }
+        const scaledWidth = Math.max(1, Math.ceil(width / roundedPixelSize));
+        const scaledHeight = Math.max(1, Math.ceil(height / roundedPixelSize));
+        const scratch = this.getTransitionScratchSurface(scaledWidth, scaledHeight);
+        const scratchCtx = this._transitionScratchContext;
+        if (!scratchCtx) {
+            ctx.drawImage(source, 0, 0, width, height);
+            return;
+        }
+        scratch.width = scaledWidth;
+        scratch.height = scaledHeight;
+        scratchCtx.clearRect(0, 0, scaledWidth, scaledHeight);
+        scratchCtx.imageSmoothingEnabled = false;
+        scratchCtx.drawImage(source, 0, 0, scaledWidth, scaledHeight);
+        ctx.save();
+        ctx.imageSmoothingEnabled = false;
+        ctx.drawImage(scratch, 0, 0, scaledWidth, scaledHeight, 0, 0, width, height);
+        ctx.restore();
+    }
+    getTransitionScratchSurface(width, height) {
+        if (!this._transitionScratchCanvas) {
+            this._transitionScratchCanvas = document.createElement("canvas");
+            this._transitionScratchContext = this._transitionScratchCanvas.getContext("2d");
+            if (!this._transitionScratchContext) {
+                throw new Error("MinimoJS: Could not acquire a transition scratch context.");
+            }
+        }
+        if (this._transitionScratchCanvas.width !== width ||
+            this._transitionScratchCanvas.height !== height) {
+            this._transitionScratchCanvas.width = width;
+            this._transitionScratchCanvas.height = height;
+            this._transitionScratchContext = this._transitionScratchCanvas.getContext("2d");
+            if (!this._transitionScratchContext) {
+                throw new Error("MinimoJS: Could not acquire a transition scratch context.");
+            }
+        }
+        return this._transitionScratchCanvas;
+    }
+    lerp(from, to, t) {
+        return from + (to - from) * t;
+    }
     applyPageBackground(pageBackground) {
         if (!document.body)
             return;

package/dist/internal/TransitionSystem.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/TransitionSystem.js

@@ -0,0 +1,70 @@
+const DEFAULT_DURATION_MS = 420;
+const DEFAULT_DIRECTION = "left-to-right";
+const DEFAULT_PIXEL_SIZE = 28;
+/** @internal */
+export class TransitionSystem {
+    constructor() {
+        this._active = null;
+    }
+    get isActive() {
+        return this._active !== null;
+    }
+    start(fromCanvas, toCanvas, width, height, options, onComplete) {
+        const type = options.type;
+        const durationMs = this.sanitizeDuration(options.durationMs, DEFAULT_DURATION_MS);
+        const color = typeof options.color === "string" && options.color.trim()
+            ? options.color
+            : type === "flash"
+                ? "#ffffff"
+                : "#000000";
+        const centerX = this.sanitizeCoordinate(options.centerX, width / 2);
+        const centerY = this.sanitizeCoordinate(options.centerY, height / 2);
+        const pixelSize = this.sanitizePixelSize(options.pixelSize, DEFAULT_PIXEL_SIZE);
+        this._active = {
+            fromCanvas,
+            toCanvas,
+            type,
+            progress: 0,
+            color,
+            direction: options.direction ?? DEFAULT_DIRECTION,
+            centerX,
+            centerY,
+            pixelSize,
+            elapsedMs: 0,
+            durationMs,
+            onComplete,
+        };
+    }
+    update(dtMs) {
+        if (!this._active)
+            return;
+        this._active.elapsedMs += dtMs;
+        this._active.progress = Math.max(0, Math.min(1, this._active.elapsedMs / this._active.durationMs));
+        if (this._active.progress >= 1) {
+            const onComplete = this._active.onComplete;
+            this._active = null;
+            onComplete?.();
+        }
+    }
+    getRenderEntry() {
+        return this._active;
+    }
+    clear() {
+        this._active = null;
+    }
+    sanitizeDuration(value, fallback) {
+        if (!Number.isFinite(value))
+            return fallback;
+        return Math.max(1, value);
+    }
+    sanitizeCoordinate(value, fallback) {
+        if (!Number.isFinite(value))
+            return fallback;
+        return value;
+    }
+    sanitizePixelSize(value, fallback) {
+        if (!Number.isFinite(value))
+            return fallback;
+        return Math.max(2, Math.round(value));
+    }
+}

package/dist/minimo.d.ts

@@ -111,6 +111,10 @@ export interface IntegrateOptions {
  * Wipe mode used by {@link Game.animateWipe}.
  */
 export type WipeMode = "reveal" | "cover";
+/**
+ * Full-screen transition type used by {@link Game.transitionTo}.
+ */
+export type ScreenTransitionType = "fade" | "wipe" | "slide" | "iris" | "pixelate" | "flash";
 /**
  * Optional tuning values for {@link Game.animateWipe}.
  *
@@ -126,6 +130,29 @@ export interface WipeOptions {
     /** Whether the original sprite is destroyed for `mode: "cover"`. */
     destroySprite?: boolean;
 }
+/**
+ * Optional tuning values for {@link Game.transitionTo}.
+ *
+ * MinimoJS scene transitions operate on frozen snapshots of the outgoing and
+ * incoming scenes. The target scene is created immediately, then both
+ * snapshots are composited for the duration of the effect.
+ */
+export interface SceneTransitionOptions {
+    /** Required transition style. */
+    type: ScreenTransitionType;
+    /** Total transition duration in **milliseconds**. */
+    durationMs?: number;
+    /** Optional color used by `fade` and `flash`. */
+    color?: string;
+    /** Direction used by `wipe` and `slide`. */
+    direction?: FlowDirection;
+    /** Optional iris center X position in canvas pixels. */
+    centerX?: number;
+    /** Optional iris center Y position in canvas pixels. */
+    centerY?: number;
+    /** Maximum pixel block size used by `pixelate`. */
+    pixelSize?: number;
+}
 /**
  * Optional tuning values for {@link Game.animateTrail}.
  *
@@ -1025,6 +1052,10 @@ export declare class Game {
      * Currently active scene object, if any.
      */
     get currentScene(): IScene | null;
+    /**
+     * Returns `true` while a full-screen scene transition is playing.
+     */
+    get isTransitioning(): boolean;
     /**
      * Creates a new MinimoJS game instance.
      *
@@ -2027,6 +2058,25 @@ export declare class Game {
      * ```
      */
     reset(scene?: IScene): void;
+    /**
+     * Changes to a new scene using a full-screen transition between frozen scene
+     * snapshots.
+     *
+     * `transitionTo()` does not change the behavior of {@link Game.reset}. It
+     * captures the current scene as a snapshot, rebuilds the target scene
+     * immediately, captures the new scene as another snapshot, and then animates
+     * between those two images for the requested duration.
+     *
+     * While the transition is active, gameplay updates are paused.
+     *
+     * If the game loop is not running yet, this falls back to an immediate
+     * {@link Game.reset}.
+     *
+     * @param scene - Target scene to make active.
+     * @param options - Transition style and optional tuning values.
+     * @param onComplete - Optional callback invoked when the transition finishes.
+     */
+    transitionTo(scene: IScene, options: SceneTransitionOptions, onComplete?: () => void): void;
     /**
      * Starts the `requestAnimationFrame` game loop.
      * Safe to call multiple times — does nothing if already running.

package/dist/minimo.js

@@ -20,6 +20,7 @@ import { SoundSystem } from "./internal/SoundSystem.js";
 import { SpriteSystem } from "./internal/SpriteSystem.js";
 import { TextSystem } from "./internal/TextSystem.js";
 import { TrailSystem } from "./internal/TrailSystem.js";
+import { TransitionSystem } from "./internal/TransitionSystem.js";
 import { TimerSystem } from "./internal/TimerSystem.js";
 // ---------------------------------------------------------------------------
 // Sprite
@@ -972,6 +973,12 @@ export class Game {
     get currentScene() {
         return this._currentScene;
     }
+    /**
+     * Returns `true` while a full-screen scene transition is playing.
+     */
+    get isTransitioning() {
+        return this._transitionSystem.isActive;
+    }
     // -------------------------------------------------------------------------
     // Constructor
     // -------------------------------------------------------------------------
@@ -1120,6 +1127,7 @@ export class Game {
         this._renderSystem = new RenderSystem();
         this._explosionSystem = new ExplosionSystem();
         this._trailSystem = new TrailSystem();
+        this._transitionSystem = new TransitionSystem();
         this._loopSystem = new LoopSystem(this._onLoopFrameCallback.bind(this));
         this._loopSystem.onCreate = this._invokeCreate.bind(this);
         this._inputSystem.bindInputEvents();
@@ -2291,6 +2299,7 @@ export class Game {
         if (scene !== undefined) {
             this._currentScene = scene;
         }
+        this._transitionSystem.clear();
         this._backgroundSystem.clearAll();
         this._spriteSystem.clearAll();
         this._timerSystem.clearAll();
@@ -2303,6 +2312,38 @@ export class Game {
         this.scrollY = 0;
         this._loopSystem.invokeCreate();
     }
+    /**
+     * Changes to a new scene using a full-screen transition between frozen scene
+     * snapshots.
+     *
+     * `transitionTo()` does not change the behavior of {@link Game.reset}. It
+     * captures the current scene as a snapshot, rebuilds the target scene
+     * immediately, captures the new scene as another snapshot, and then animates
+     * between those two images for the requested duration.
+     *
+     * While the transition is active, gameplay updates are paused.
+     *
+     * If the game loop is not running yet, this falls back to an immediate
+     * {@link Game.reset}.
+     *
+     * @param scene - Target scene to make active.
+     * @param options - Transition style and optional tuning values.
+     * @param onComplete - Optional callback invoked when the transition finishes.
+     */
+    transitionTo(scene, options, onComplete) {
+        if (!this._loopSystem.isRunning || !this._hasCompletedPreload) {
+            this.reset(scene);
+            onComplete?.();
+            return;
+        }
+        if (this._transitionSystem.isActive) {
+            return;
+        }
+        const fromCanvas = this._captureFrameSnapshot();
+        this.reset(scene);
+        const toCanvas = this._captureFrameSnapshot();
+        this._transitionSystem.start(fromCanvas, toCanvas, this.width, this.height, options, onComplete);
+    }
     // -------------------------------------------------------------------------
     // Loop control
     // -------------------------------------------------------------------------
@@ -2417,14 +2458,44 @@ export class Game {
     // Private — rendering
     // -------------------------------------------------------------------------
     /** @internal */ _onLoopFrameCallback(dt, dtMs) {
+        if (this._transitionSystem.isActive) {
+            this._transitionSystem.update(dtMs);
+            if (this._transitionSystem.isActive) {
+                this._renderTransition();
+            }
+            else {
+                this._render();
+            }
+            this._inputSystem.clearFramePressedState();
+            this._textSystem.clear();
+            return;
+        }
         this._timerSystem.update(dtMs);
+        if (this._transitionSystem.isActive) {
+            this._renderTransition();
+            this._inputSystem.clearFramePressedState();
+            this._textSystem.clear();
+            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();
+            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();
+            return;
+        }
         this._trailSystem.update(dtMs, this._renderSystem.getSpriteRenderSnapshot.bind(this._renderSystem));
         this._render();
         this._inputSystem.clearFramePressedState();
@@ -2515,6 +2586,37 @@ export class Game {
             pageBackground: this.pageBackground,
         });
     }
+    /** @internal */ _renderTransition() {
+        const transition = this._transitionSystem.getRenderEntry();
+        if (!transition) {
+            this._render();
+            return;
+        }
+        this._renderSystem.renderScreenTransition({
+            canvas: this._canvas,
+            context: this._ctx,
+            pageBackground: this.pageBackground,
+            transition,
+        });
+    }
+    /** @internal */ _captureFrameSnapshot() {
+        return this._renderSystem.captureFrame({
+            canvas: this._canvas,
+            context: this._ctx,
+            backgroundLayers: this._backgroundSystem.getMutableLayers(),
+            resolveImage: this._assetSystem.getImage.bind(this._assetSystem),
+            sprites: this._spriteSystem.getMutableSprites(),
+            trails: this._trailSystem.getRenderEntries(),
+            explosions: this._explosionSystem.getRenderEntries(),
+            wipes: this._explosionSystem.getWipeEntries(),
+            textEntries: this._textSystem.getEntries(),
+            scrollX: this.scrollX,
+            scrollY: this.scrollY,
+            background: this.background,
+            backgroundGradient: this.backgroundGradient,
+            pageBackground: this.pageBackground,
+        });
+    }
     /** @internal */
     _renderLoadingScreen(loaded, total, currentKey) {
         this._renderSystem.renderLoadingScreen({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.14",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Emoji-only sprites, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",