minimojs 1.0.0-alpha.11 → 1.0.0-alpha.13

package/README.md

@@ -21,6 +21,7 @@ This README is intentionally high-level. It explains what the project is and how
 - Runtime update delta (`dt`) is seconds
 - Coordinate system is center-based world space
 - Positive Y goes downward
+- For new mobile-first games, prefer a portrait canvas of `720x1280`
 
 ## What It Intentionally Avoids
 
@@ -41,14 +42,14 @@ npm install minimojs
 ```ts
 import { Game, Sprite, type IScene } from "minimojs";
 
-const game = new Game(800, 600);
+const game = new Game(720, 1280);
 game.gravityY = 980;
 
 class DemoScene implements IScene {
   private player: Sprite | null = null;
 
   onCreate() {
-    this.player = game.add(new Sprite("🐢", 400, 300, 48));
+    this.player = game.add(new Sprite("🐢", 360, 640, 48));
     this.player.gravityScale = 1;
   }
 

package/dist/internal/ExplosionSystem.js

@@ -1,4 +1,4 @@
-const DEFAULT_OPTIONS = {
+const DEFAULT_EXPLODE_OPTIONS = {
     rows: 3,
     cols: 3,
     durationMs: 500,
@@ -8,43 +8,299 @@ const DEFAULT_OPTIONS = {
     fade: true,
     destroySprite: true,
 };
+const DEFAULT_ASSEMBLE_OPTIONS = {
+    rows: 3,
+    cols: 3,
+    durationMs: 500,
+    speed: 260,
+    gravityY: 900,
+    spin: 220,
+    fade: true,
+};
+const DEFAULT_DISINTEGRATE_OPTIONS = {
+    rows: 4,
+    cols: 4,
+    durationMs: 420,
+    direction: "left-to-right",
+    distance: 42,
+    spin: 120,
+    fade: true,
+    destroySprite: true,
+};
+const DEFAULT_INTEGRATE_OPTIONS = {
+    rows: 4,
+    cols: 4,
+    durationMs: 420,
+    direction: "left-to-right",
+    distance: 42,
+    spin: 120,
+    fade: true,
+};
+const DEFAULT_WIPE_OPTIONS = {
+    mode: "reveal",
+    direction: "left-to-right",
+    durationMs: 360,
+    destroySprite: true,
+};
 /** @internal */
 export class ExplosionSystem {
     constructor() {
-        this._explosions = [];
+        this._pieceEffects = [];
+        this._wipes = [];
     }
     animateExplode(sprite, glyphCanvas, options, onComplete) {
-        this.clearSpriteExplosions(sprite);
-        const rows = this.sanitizeCount(options?.rows, DEFAULT_OPTIONS.rows);
-        const cols = this.sanitizeCount(options?.cols, DEFAULT_OPTIONS.cols);
-        const durationMs = this.sanitizeDuration(options?.durationMs, DEFAULT_OPTIONS.durationMs);
-        const speed = this.sanitizeNonNegative(options?.speed, DEFAULT_OPTIONS.speed);
-        const gravityY = this.sanitizeNumber(options?.gravityY, DEFAULT_OPTIONS.gravityY);
-        const spin = this.sanitizeNonNegative(options?.spin, DEFAULT_OPTIONS.spin);
-        const fade = options?.fade ?? DEFAULT_OPTIONS.fade;
-        const destroySprite = options?.destroySprite ?? DEFAULT_OPTIONS.destroySprite;
-        const originalVisible = sprite.visible;
-        const renderData = sprite._renderData;
-        const deformScaleX = this.getSafeScale(renderData?.scaleX);
-        const deformScaleY = this.getSafeScale(renderData?.scaleY);
-        const pivotX = this.getSafePivot(renderData?.pivotX);
-        const pivotY = this.getSafePivot(renderData?.pivotY);
-        const offsetX = this.getSafeNumber(renderData?.offsetX, 0);
-        const offsetY = this.getSafeNumber(renderData?.offsetY, 0);
-        const alphaMultiplier = this.getSafeNumber(renderData?.alphaMultiplier, 1);
-        const baseDisplayWidth = sprite.displayWidth;
-        const baseDisplayHeight = sprite.displayHeight;
-        const pivotOffsetX = (pivotX - 0.5) * baseDisplayWidth * (1 - deformScaleX);
-        const pivotOffsetY = (pivotY - 0.5) * baseDisplayHeight * (1 - deformScaleY);
-        const signedScaleX = this.getSafeScale(sprite.scale) * deformScaleX * (sprite.flipX ? -1 : 1);
-        const signedScaleY = this.getSafeScale(sprite.scale) * deformScaleY * (sprite.flipY ? -1 : 1);
-        const absScaleX = Math.abs(signedScaleX);
-        const absScaleY = Math.abs(signedScaleY);
-        const rotationRad = (sprite.rotation * Math.PI) / 180;
-        const baseX = sprite.renderX + pivotOffsetX + offsetX;
-        const baseY = sprite.renderY + pivotOffsetY + offsetY;
-        const baseAlpha = Math.max(0, Math.min(1, sprite.alpha * alphaMultiplier));
+        const context = this.buildPieceSpriteContext(sprite, glyphCanvas);
+        this.spawnRadialEffect("explode", sprite, glyphCanvas, context, {
+            rows: this.sanitizeCount(options?.rows, DEFAULT_EXPLODE_OPTIONS.rows),
+            cols: this.sanitizeCount(options?.cols, DEFAULT_EXPLODE_OPTIONS.cols),
+            durationMs: this.sanitizeDuration(options?.durationMs, DEFAULT_EXPLODE_OPTIONS.durationMs),
+            speed: this.sanitizeNonNegative(options?.speed, DEFAULT_EXPLODE_OPTIONS.speed),
+            gravityY: this.sanitizeNumber(options?.gravityY, DEFAULT_EXPLODE_OPTIONS.gravityY),
+            spin: this.sanitizeNonNegative(options?.spin, DEFAULT_EXPLODE_OPTIONS.spin),
+            fade: options?.fade ?? DEFAULT_EXPLODE_OPTIONS.fade,
+        }, false, options?.destroySprite === false, options?.destroySprite === false ? sprite.visible : false, onComplete);
+    }
+    animateAssemble(sprite, glyphCanvas, options, onComplete) {
+        const context = this.buildPieceSpriteContext(sprite, glyphCanvas);
+        this.spawnRadialEffect("assemble", sprite, glyphCanvas, context, {
+            rows: this.sanitizeCount(options?.rows, DEFAULT_ASSEMBLE_OPTIONS.rows),
+            cols: this.sanitizeCount(options?.cols, DEFAULT_ASSEMBLE_OPTIONS.cols),
+            durationMs: this.sanitizeDuration(options?.durationMs, DEFAULT_ASSEMBLE_OPTIONS.durationMs),
+            speed: this.sanitizeNonNegative(options?.speed, DEFAULT_ASSEMBLE_OPTIONS.speed),
+            gravityY: this.sanitizeNumber(options?.gravityY, DEFAULT_ASSEMBLE_OPTIONS.gravityY),
+            spin: this.sanitizeNonNegative(options?.spin, DEFAULT_ASSEMBLE_OPTIONS.spin),
+            fade: options?.fade ?? DEFAULT_ASSEMBLE_OPTIONS.fade,
+        }, true, true, true, onComplete);
+    }
+    animateDisintegrate(sprite, glyphCanvas, options, onComplete) {
+        const context = this.buildPieceSpriteContext(sprite, glyphCanvas);
+        this.spawnDirectionalEffect("disintegrate", sprite, glyphCanvas, context, {
+            rows: this.sanitizeCount(options?.rows, DEFAULT_DISINTEGRATE_OPTIONS.rows),
+            cols: this.sanitizeCount(options?.cols, DEFAULT_DISINTEGRATE_OPTIONS.cols),
+            durationMs: this.sanitizeDuration(options?.durationMs, DEFAULT_DISINTEGRATE_OPTIONS.durationMs),
+            direction: options?.direction ?? DEFAULT_DISINTEGRATE_OPTIONS.direction,
+            distance: this.sanitizeNonNegative(options?.distance, DEFAULT_DISINTEGRATE_OPTIONS.distance),
+            spin: this.sanitizeNonNegative(options?.spin, DEFAULT_DISINTEGRATE_OPTIONS.spin),
+            fade: options?.fade ?? DEFAULT_DISINTEGRATE_OPTIONS.fade,
+        }, false, options?.destroySprite === false, false, onComplete);
+    }
+    animateIntegrate(sprite, glyphCanvas, options, onComplete) {
+        const context = this.buildPieceSpriteContext(sprite, glyphCanvas);
+        this.spawnDirectionalEffect("integrate", sprite, glyphCanvas, context, {
+            rows: this.sanitizeCount(options?.rows, DEFAULT_INTEGRATE_OPTIONS.rows),
+            cols: this.sanitizeCount(options?.cols, DEFAULT_INTEGRATE_OPTIONS.cols),
+            durationMs: this.sanitizeDuration(options?.durationMs, DEFAULT_INTEGRATE_OPTIONS.durationMs),
+            direction: options?.direction ?? DEFAULT_INTEGRATE_OPTIONS.direction,
+            distance: this.sanitizeNonNegative(options?.distance, DEFAULT_INTEGRATE_OPTIONS.distance),
+            spin: this.sanitizeNonNegative(options?.spin, DEFAULT_INTEGRATE_OPTIONS.spin),
+            fade: options?.fade ?? DEFAULT_INTEGRATE_OPTIONS.fade,
+        }, true, true, true, onComplete);
+    }
+    animateWipe(sprite, snapshot, options, onComplete) {
+        this.clearSpriteEffects(sprite);
+        const mode = options?.mode ?? DEFAULT_WIPE_OPTIONS.mode;
+        const durationMs = this.sanitizeDuration(options?.durationMs, DEFAULT_WIPE_OPTIONS.durationMs);
+        const direction = options?.direction ?? DEFAULT_WIPE_OPTIONS.direction;
+        const destroySprite = options?.destroySprite ?? DEFAULT_WIPE_OPTIONS.destroySprite;
+        const restoreVisibility = mode === "reveal";
+        sprite.visible = false;
+        this._wipes.push({
+            sprite,
+            canvas: snapshot.canvas,
+            x: snapshot.x,
+            y: snapshot.y,
+            rotation: snapshot.rotation,
+            alpha: snapshot.alpha,
+            flipX: snapshot.flipX,
+            flipY: snapshot.flipY,
+            drawWidth: snapshot.drawWidth,
+            drawHeight: snapshot.drawHeight,
+            layer: snapshot.layer,
+            ignoreScroll: snapshot.ignoreScroll,
+            mode,
+            direction,
+            progress: mode === "reveal" ? 0 : 1,
+            elapsedMs: 0,
+            durationMs,
+            restoreVisibility,
+            finalVisible: mode === "reveal",
+            onComplete,
+        });
+    }
+    update(_dt, dtMs) {
+        const pieceToRemove = [];
+        for (let i = 0; i < this._pieceEffects.length; i++) {
+            const effect = this._pieceEffects[i];
+            effect.elapsedMs += dtMs;
+            const t = Math.min(effect.elapsedMs / effect.durationMs, 1);
+            for (const piece of effect.pieces) {
+                const localT = t <= piece.delayT ? 0 : Math.min(1, (t - piece.delayT) / (1 - piece.delayT));
+                const eased = this.easePieceProgress(effect.mode, localT);
+                piece.x = this.lerp(piece.startX, piece.endX, eased);
+                piece.y = this.lerp(piece.startY, piece.endY, eased);
+                piece.rotation = this.lerp(piece.startRotation, piece.endRotation, eased);
+                piece.alpha = this.lerp(piece.startAlpha, piece.endAlpha, eased);
+            }
+            if (t >= 1) {
+                pieceToRemove.push(i);
+                if (effect.restoreVisibility) {
+                    effect.sprite.visible = effect.finalVisible;
+                }
+                effect.onComplete?.();
+            }
+        }
+        for (let i = pieceToRemove.length - 1; i >= 0; i--) {
+            this._pieceEffects.splice(pieceToRemove[i], 1);
+        }
+        const wipeToRemove = [];
+        for (let i = 0; i < this._wipes.length; i++) {
+            const wipe = this._wipes[i];
+            wipe.elapsedMs += dtMs;
+            const t = Math.min(wipe.elapsedMs / wipe.durationMs, 1);
+            wipe.progress = wipe.mode === "reveal" ? t : 1 - t;
+            if (t >= 1) {
+                wipeToRemove.push(i);
+                if (wipe.restoreVisibility) {
+                    wipe.sprite.visible = wipe.finalVisible;
+                }
+                wipe.onComplete?.();
+            }
+        }
+        for (let i = wipeToRemove.length - 1; i >= 0; i--) {
+            this._wipes.splice(wipeToRemove[i], 1);
+        }
+    }
+    getRenderEntries() {
+        return this._pieceEffects;
+    }
+    getWipeEntries() {
+        return this._wipes;
+    }
+    clearAll() {
+        for (const effect of this._pieceEffects) {
+            if (effect.restoreVisibility) {
+                effect.sprite.visible = effect.finalVisible;
+            }
+        }
+        for (const wipe of this._wipes) {
+            if (wipe.restoreVisibility) {
+                wipe.sprite.visible = wipe.finalVisible;
+            }
+        }
+        this._pieceEffects = [];
+        this._wipes = [];
+    }
+    spawnRadialEffect(mode, sprite, glyphCanvas, context, options, forceHideSprite, restoreVisibility, finalVisible, onComplete) {
+        this.clearSpriteEffects(sprite);
+        if (forceHideSprite || restoreVisibility) {
+            sprite.visible = false;
+        }
+        const durationSeconds = options.durationMs / 1000;
+        const pieces = this.buildPieceGrid(glyphCanvas, context, options.rows, options.cols, (_row, _col, sx, sy, sw, sh, centerX, centerY) => {
+            const velocity = this.getRadialVelocity(centerX, centerY);
+            const distance = options.speed * durationSeconds * (0.65 + Math.random() * 0.7);
+            const targetX = context.baseX + centerX + velocity.x * distance;
+            const targetY = context.baseY +
+                centerY +
+                velocity.y * distance +
+                0.5 * options.gravityY * durationSeconds * durationSeconds;
+            const assembledX = context.baseX + centerX;
+            const assembledY = context.baseY + centerY;
+            const startRotation = mode === "explode"
+                ? context.rotation
+                : context.rotation + (Math.random() * 2 - 1) * options.spin * durationSeconds;
+            const endRotation = mode === "explode"
+                ? context.rotation + (Math.random() * 2 - 1) * options.spin * durationSeconds
+                : context.rotation;
+            return {
+                sx,
+                sy,
+                sw,
+                sh,
+                assembledX,
+                assembledY,
+                offsetX: targetX - assembledX,
+                offsetY: targetY - assembledY,
+                startRotation,
+                endRotation,
+                delayT: 0,
+                fade: options.fade,
+            };
+        }, mode);
+        this._pieceEffects.push({
+            sprite,
+            canvas: glyphCanvas,
+            layer: context.layer,
+            ignoreScroll: context.ignoreScroll,
+            pieces,
+            elapsedMs: 0,
+            durationMs: options.durationMs,
+            mode,
+            restoreVisibility,
+            finalVisible,
+            onComplete,
+        });
+    }
+    spawnDirectionalEffect(mode, sprite, glyphCanvas, context, options, forceHideSprite, restoreVisibility, finalVisible, onComplete) {
+        this.clearSpriteEffects(sprite);
+        if (forceHideSprite || restoreVisibility) {
+            sprite.visible = false;
+        }
+        const durationSeconds = options.durationMs / 1000;
+        const maxDelayT = 0.58;
+        const inPlace = options.direction === "in-place";
+        const directionalFlow = inPlace
+            ? "left-to-right"
+            : options.direction;
+        const directionVector = inPlace ? { x: 0, y: 0 } : this.getDirectionVector(directionalFlow);
+        const perpendicular = inPlace ? { x: 0, y: 0 } : { x: -directionVector.y, y: directionVector.x };
+        const pieces = this.buildPieceGrid(glyphCanvas, context, options.rows, options.cols, (row, col, sx, sy, sw, sh, centerX, centerY) => {
+            const baseDistance = inPlace ? 0 : options.distance * (0.45 + Math.random() * 0.75);
+            const sidewaysDistance = inPlace ? 0 : options.distance * 0.22 * (Math.random() * 2 - 1);
+            const offsetX = directionVector.x * baseDistance + perpendicular.x * sidewaysDistance;
+            const offsetY = directionVector.y * baseDistance + perpendicular.y * sidewaysDistance;
+            const assembledX = context.baseX + centerX;
+            const assembledY = context.baseY + centerY;
+            const delayT = inPlace
+                ? Math.random() * (maxDelayT + 0.05)
+                : this.getDirectionalProgress(row, col, options.rows, options.cols, directionalFlow) *
+                    maxDelayT +
+                    Math.random() * 0.05;
+            const rotationOffset = inPlace
+                ? 0
+                : (Math.random() * 2 - 1) * options.spin * durationSeconds;
+            return {
+                sx,
+                sy,
+                sw,
+                sh,
+                assembledX,
+                assembledY,
+                offsetX,
+                offsetY,
+                startRotation: mode === "disintegrate" ? context.rotation : context.rotation + rotationOffset,
+                endRotation: mode === "disintegrate" ? context.rotation + rotationOffset : context.rotation,
+                delayT: Math.min(maxDelayT + 0.05, delayT),
+                fade: options.fade,
+            };
+        }, mode);
+        this._pieceEffects.push({
+            sprite,
+            canvas: glyphCanvas,
+            layer: context.layer,
+            ignoreScroll: context.ignoreScroll,
+            pieces,
+            elapsedMs: 0,
+            durationMs: options.durationMs,
+            mode,
+            restoreVisibility,
+            finalVisible,
+            onComplete,
+        });
+    }
+    buildPieceGrid(glyphCanvas, context, rows, cols, builder, mode) {
         const pieces = [];
+        const rotationRad = (context.rotation * Math.PI) / 180;
         for (let row = 0; row < rows; row++) {
             const sy = Math.floor((row * glyphCanvas.height) / rows);
             const nextSy = Math.floor(((row + 1) * glyphCanvas.height) / rows);
@@ -53,102 +309,142 @@ export class ExplosionSystem {
                 const sx = Math.floor((col * glyphCanvas.width) / cols);
                 const nextSx = Math.floor(((col + 1) * glyphCanvas.width) / cols);
                 const sw = Math.max(1, nextSx - sx);
-                const localX = (sx + sw / 2 - glyphCanvas.width / 2) * signedScaleX;
-                const localY = (sy + sh / 2 - glyphCanvas.height / 2) * signedScaleY;
+                const localX = (sx + sw / 2 - glyphCanvas.width / 2) * context.signedScaleX;
+                const localY = (sy + sh / 2 - glyphCanvas.height / 2) * context.signedScaleY;
                 const rotated = this.rotate(localX, localY, rotationRad);
-                const velocity = this.getPieceVelocity(rotated.x, rotated.y, speed);
+                const generated = builder(row, col, sx, sy, sw, sh, rotated.x, rotated.y);
+                const startX = mode === "explode" || mode === "disintegrate"
+                    ? generated.assembledX
+                    : generated.assembledX + generated.offsetX;
+                const startY = mode === "explode" || mode === "disintegrate"
+                    ? generated.assembledY
+                    : generated.assembledY + generated.offsetY;
+                const endX = mode === "explode" || mode === "disintegrate"
+                    ? generated.assembledX + generated.offsetX
+                    : generated.assembledX;
+                const endY = mode === "explode" || mode === "disintegrate"
+                    ? generated.assembledY + generated.offsetY
+                    : generated.assembledY;
+                const startAlpha = mode === "explode" || mode === "disintegrate"
+                    ? context.baseAlpha
+                    : generated.fade
+                        ? 0
+                        : context.baseAlpha;
+                const endAlpha = mode === "explode" || mode === "disintegrate"
+                    ? generated.fade
+                        ? 0
+                        : context.baseAlpha
+                    : context.baseAlpha;
                 pieces.push({
-                    x: baseX + rotated.x,
-                    y: baseY + rotated.y,
-                    rotation: sprite.rotation,
-                    alpha: baseAlpha,
-                    flipX: sprite.flipX,
-                    flipY: sprite.flipY,
-                    sx,
-                    sy,
-                    sw,
-                    sh,
-                    drawWidth: sw * absScaleX,
-                    drawHeight: sh * absScaleY,
-                    vx: velocity.x,
-                    vy: velocity.y,
-                    angularVelocity: (Math.random() * 2 - 1) * spin,
+                    x: startX,
+                    y: startY,
+                    rotation: generated.startRotation,
+                    alpha: startAlpha,
+                    flipX: context.flipX,
+                    flipY: context.flipY,
+                    sx: generated.sx,
+                    sy: generated.sy,
+                    sw: generated.sw,
+                    sh: generated.sh,
+                    drawWidth: generated.sw * context.absScaleX,
+                    drawHeight: generated.sh * context.absScaleY,
+                    startX,
+                    startY,
+                    endX,
+                    endY,
+                    startRotation: generated.startRotation,
+                    endRotation: generated.endRotation,
+                    startAlpha,
+                    endAlpha,
+                    delayT: generated.delayT,
                 });
             }
         }
-        if (!destroySprite) {
-            sprite.visible = false;
-        }
-        this._explosions.push({
-            sprite,
-            canvas: glyphCanvas,
+        return pieces;
+    }
+    buildPieceSpriteContext(sprite, glyphCanvas) {
+        const renderData = sprite._renderData;
+        const deformScaleX = this.getSafeScale(renderData?.scaleX);
+        const deformScaleY = this.getSafeScale(renderData?.scaleY);
+        const pivotX = this.getSafePivot(renderData?.pivotX);
+        const pivotY = this.getSafePivot(renderData?.pivotY);
+        const offsetX = this.getSafeNumber(renderData?.offsetX, 0);
+        const offsetY = this.getSafeNumber(renderData?.offsetY, 0);
+        const alphaMultiplier = this.getSafeNumber(renderData?.alphaMultiplier, 1);
+        const baseDisplayWidth = sprite.displayWidth;
+        const baseDisplayHeight = sprite.displayHeight;
+        const pivotOffsetX = (pivotX - 0.5) * baseDisplayWidth * (1 - deformScaleX);
+        const pivotOffsetY = (pivotY - 0.5) * baseDisplayHeight * (1 - deformScaleY);
+        const signedScaleX = this.getSafeScale(sprite.scale) * deformScaleX * (sprite.flipX ? -1 : 1);
+        const signedScaleY = this.getSafeScale(sprite.scale) * deformScaleY * (sprite.flipY ? -1 : 1);
+        return {
             layer: sprite.layer,
             ignoreScroll: sprite.ignoreScroll,
-            pieces,
-            elapsedMs: 0,
-            durationMs,
-            gravityY,
-            fade,
-            baseAlpha,
-            restoreVisibility: !destroySprite,
-            originalVisible,
-            onComplete,
-        });
+            baseX: sprite.renderX + pivotOffsetX + offsetX,
+            baseY: sprite.renderY + pivotOffsetY + offsetY,
+            rotation: sprite.rotation,
+            baseAlpha: Math.max(0, Math.min(1, sprite.alpha * alphaMultiplier)),
+            flipX: sprite.flipX,
+            flipY: sprite.flipY,
+            signedScaleX,
+            signedScaleY,
+            absScaleX: Math.abs(signedScaleX),
+            absScaleY: Math.abs(signedScaleY),
+        };
     }
-    update(dt, dtMs) {
-        const explosions = this._explosions;
-        const toRemove = [];
-        for (let i = 0; i < explosions.length; i++) {
-            const explosion = explosions[i];
-            explosion.elapsedMs += dtMs;
-            const t = Math.min(explosion.elapsedMs / explosion.durationMs, 1);
-            for (const piece of explosion.pieces) {
-                piece.vy += explosion.gravityY * dt;
-                piece.x += piece.vx * dt;
-                piece.y += piece.vy * dt;
-                piece.rotation += piece.angularVelocity * dt;
-                piece.alpha = explosion.fade
-                    ? explosion.baseAlpha * (1 - t)
-                    : explosion.baseAlpha;
-            }
-            if (t >= 1) {
-                toRemove.push(i);
-                if (explosion.restoreVisibility) {
-                    explosion.sprite.visible = explosion.originalVisible;
+    clearSpriteEffects(sprite) {
+        const remainingPieces = [];
+        for (const effect of this._pieceEffects) {
+            if (effect.sprite === sprite) {
+                if (effect.restoreVisibility) {
+                    effect.sprite.visible = effect.finalVisible;
                 }
-                explosion.onComplete?.();
             }
-        }
-        for (let i = toRemove.length - 1; i >= 0; i--) {
-            explosions.splice(toRemove[i], 1);
-        }
-    }
-    getRenderEntries() {
-        return this._explosions;
-    }
-    clearAll() {
-        for (const explosion of this._explosions) {
-            if (explosion.restoreVisibility) {
-                explosion.sprite.visible = explosion.originalVisible;
+            else {
+                remainingPieces.push(effect);
             }
         }
-        this._explosions = [];
-    }
-    clearSpriteExplosions(sprite) {
-        const remaining = [];
-        for (const explosion of this._explosions) {
-            if (explosion.sprite === sprite) {
-                if (explosion.restoreVisibility) {
-                    explosion.sprite.visible = explosion.originalVisible;
+        this._pieceEffects = remainingPieces;
+        const remainingWipes = [];
+        for (const wipe of this._wipes) {
+            if (wipe.sprite === sprite) {
+                if (wipe.restoreVisibility) {
+                    wipe.sprite.visible = wipe.finalVisible;
                 }
             }
             else {
-                remaining.push(explosion);
+                remainingWipes.push(wipe);
             }
         }
-        this._explosions = remaining;
+        this._wipes = remainingWipes;
+    }
+    getDirectionalProgress(row, col, rows, cols, direction) {
+        const rowProgress = rows <= 1 ? 0 : row / (rows - 1);
+        const colProgress = cols <= 1 ? 0 : col / (cols - 1);
+        switch (direction) {
+            case "left-to-right":
+                return colProgress;
+            case "right-to-left":
+                return 1 - colProgress;
+            case "top-to-bottom":
+                return rowProgress;
+            case "bottom-to-top":
+                return 1 - rowProgress;
+        }
     }
-    getPieceVelocity(x, y, speed) {
+    getDirectionVector(direction) {
+        switch (direction) {
+            case "left-to-right":
+                return { x: 1, y: 0 };
+            case "right-to-left":
+                return { x: -1, y: 0 };
+            case "top-to-bottom":
+                return { x: 0, y: 1 };
+            case "bottom-to-top":
+                return { x: 0, y: -1 };
+        }
+    }
+    getRadialVelocity(x, y) {
         const magnitude = Math.hypot(x, y);
         let dirX = 0;
         let dirY = 0;
@@ -162,12 +458,18 @@ export class ExplosionSystem {
             dirY = Math.sin(angle);
         }
         const jitterAngle = (Math.random() - 0.5) * (Math.PI / 2);
-        const jittered = this.rotate(dirX, dirY, jitterAngle);
-        const pieceSpeed = speed * (0.65 + Math.random() * 0.7);
-        return {
-            x: jittered.x * pieceSpeed,
-            y: jittered.y * pieceSpeed,
-        };
+        return this.rotate(dirX, dirY, jitterAngle);
+    }
+    easePieceProgress(mode, t) {
+        const clamped = Math.max(0, Math.min(1, t));
+        switch (mode) {
+            case "explode":
+            case "disintegrate":
+                return 1 - (1 - clamped) * (1 - clamped);
+            case "assemble":
+            case "integrate":
+                return clamped * clamped * (3 - 2 * clamped);
+        }
     }
     rotate(x, y, radians) {
         const cos = Math.cos(radians);
@@ -177,6 +479,9 @@ export class ExplosionSystem {
             y: x * sin + y * cos,
         };
     }
+    lerp(from, to, t) {
+        return from + (to - from) * t;
+    }
     getSafeScale(value) {
         if (!Number.isFinite(value))
             return 1;

package/dist/internal/RenderSystem.js

@@ -95,6 +95,31 @@ export class RenderSystem {
             ctx.drawImage(snapshot.canvas, -snapshot.drawWidth / 2, -snapshot.drawHeight / 2, snapshot.drawWidth, snapshot.drawHeight);
             ctx.restore();
         }
+        const wipeEntries = [...options.wipes].sort((a, b) => a.layer - b.layer);
+        for (const entry of wipeEntries) {
+            const visibleProgress = Math.max(0, Math.min(1, entry.progress));
+            if (visibleProgress <= 0)
+                continue;
+            ctx.save();
+            ctx.globalAlpha = entry.alpha;
+            const drawX = Math.round(entry.ignoreScroll ? entry.x : entry.x - options.scrollX);
+            const drawY = Math.round(entry.ignoreScroll ? entry.y : entry.y - options.scrollY);
+            ctx.translate(drawX, drawY);
+            if (entry.rotation !== 0) {
+                ctx.rotate((entry.rotation * Math.PI) / 180);
+            }
+            if (entry.flipX || entry.flipY) {
+                ctx.scale(entry.flipX ? -1 : 1, entry.flipY ? -1 : 1);
+            }
+            const clip = this.getWipeClipRect(entry.drawWidth, entry.drawHeight, entry.direction, visibleProgress);
+            if (clip.width > 0 && clip.height > 0) {
+                ctx.beginPath();
+                ctx.rect(clip.x, clip.y, clip.width, clip.height);
+                ctx.clip();
+                ctx.drawImage(entry.canvas, -entry.drawWidth / 2, -entry.drawHeight / 2, entry.drawWidth, entry.drawHeight);
+            }
+            ctx.restore();
+        }
         const explosionEntries = [...options.explosions].sort((a, b) => a.layer - b.layer);
         for (const entry of explosionEntries) {
             for (const piece of entry.pieces) {
@@ -278,6 +303,44 @@ export class RenderSystem {
     isImageSprite(sprite) {
         return "imageKey" in sprite && "setTexture" in sprite;
     }
+    getWipeClipRect(drawWidth, drawHeight, direction, progress) {
+        const halfWidth = drawWidth / 2;
+        const halfHeight = drawHeight / 2;
+        switch (direction) {
+            case "left-to-right":
+                return {
+                    x: -halfWidth,
+                    y: -halfHeight,
+                    width: drawWidth * progress,
+                    height: drawHeight,
+                };
+            case "right-to-left": {
+                const width = drawWidth * progress;
+                return {
+                    x: halfWidth - width,
+                    y: -halfHeight,
+                    width,
+                    height: drawHeight,
+                };
+            }
+            case "top-to-bottom":
+                return {
+                    x: -halfWidth,
+                    y: -halfHeight,
+                    width: drawWidth,
+                    height: drawHeight * progress,
+                };
+            case "bottom-to-top": {
+                const height = drawHeight * progress;
+                return {
+                    x: -halfWidth,
+                    y: halfHeight - height,
+                    width: drawWidth,
+                    height,
+                };
+            }
+        }
+    }
     asEmojiSprite(sprite) {
         if ("sprite" in sprite && "size" in sprite) {
             return sprite;

package/dist/minimo.d.ts

@@ -30,6 +30,102 @@ export interface ExplodeOptions {
     /** Whether the original sprite is destroyed instead of restored after the effect. */
     destroySprite?: boolean;
 }
+/**
+ * Cardinal flow direction used by directional visual effects.
+ */
+export type FlowDirection = "left-to-right" | "right-to-left" | "top-to-bottom" | "bottom-to-top";
+/**
+ * Direction used by piece-based local integration and disintegration effects.
+ *
+ * - Cardinal values apply a directional sweep across the sprite.
+ * - `"in-place"` keeps pieces in their final positions and only randomizes
+ *   when each piece appears or disappears.
+ */
+export type PieceFlowDirection = FlowDirection | "in-place";
+/**
+ * Optional tuning values for {@link Game.animateAssemble}.
+ *
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface AssembleOptions {
+    /** Number of vertical slices used to reconstruct the sprite. */
+    rows?: number;
+    /** Number of horizontal slices used to reconstruct the sprite. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Initial outward distance magnitude in pixels per second equivalent. */
+    speed?: number;
+    /** Downward pull applied while pieces converge, in pixels per second squared. */
+    gravityY?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade in while assembling. */
+    fade?: boolean;
+}
+/**
+ * Optional tuning values for {@link Game.animateDisintegrate}.
+ *
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface DisintegrateOptions {
+    /** Number of vertical slices used to dissolve the sprite. */
+    rows?: number;
+    /** Number of horizontal slices used to dissolve the sprite. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Primary sweep direction across the sprite. */
+    direction?: PieceFlowDirection;
+    /** Maximum local travel distance in pixels for each piece. */
+    distance?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade out as they disintegrate. */
+    fade?: boolean;
+    /** Whether the original sprite is destroyed instead of left hidden after the effect. */
+    destroySprite?: boolean;
+}
+/**
+ * Optional tuning values for {@link Game.animateIntegrate}.
+ *
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface IntegrateOptions {
+    /** Number of vertical slices used to reconstruct the sprite. */
+    rows?: number;
+    /** Number of horizontal slices used to reconstruct the sprite. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Primary sweep direction across the sprite. */
+    direction?: PieceFlowDirection;
+    /** Maximum local travel distance in pixels for each piece. */
+    distance?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade in while integrating. */
+    fade?: boolean;
+}
+/**
+ * Wipe mode used by {@link Game.animateWipe}.
+ */
+export type WipeMode = "reveal" | "cover";
+/**
+ * Optional tuning values for {@link Game.animateWipe}.
+ *
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface WipeOptions {
+    /** Whether the wipe reveals the sprite or covers it away. */
+    mode?: WipeMode;
+    /** Primary wipe direction. */
+    direction?: FlowDirection;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Whether the original sprite is destroyed for `mode: "cover"`. */
+    destroySprite?: boolean;
+}
 /**
  * Optional tuning values for {@link Game.animateTrail}.
  *
@@ -576,7 +672,7 @@ export interface CollisionInfo {
  * Example custom font registration:
  *
  * ```ts
- * const game = new Game(800, 600);
+ * const game = new Game(720, 1280);
  * game.requireFont('"Bangers"', { weight: "400" });
  * game.start();
  * ```
@@ -588,7 +684,7 @@ export interface CollisionInfo {
  * ```ts
  * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  *
- * const game = new Game(800, 600);
+ * const game = new Game(720, 1280);
  *
  * const player = new Sprite("🐢", 400, 500, 48);
  * game.add(player);
@@ -935,15 +1031,16 @@ export declare class Game {
      * The engine creates its own `<canvas>`, sets its dimensions, and appends it
      * to `document.body`. The canvas is automatically centered and responsively
      * scaled to use the maximum available viewport space while preserving aspect ratio.
+     * For new mobile-first Minimo Games, prefer a portrait canvas such as `720x1280`.
      *
-     * @param width - Canvas width in pixels. Default: `800`.
-     * @param height - Canvas height in pixels. Default: `600`.
+     * @param width - Canvas width in pixels. Default: `720`.
+     * @param height - Canvas height in pixels. Default: `1280`.
      *
      * @throws Error if a 2D context cannot be obtained.
      *
      * @example
      * ```ts
-     * const game = new Game(800, 600);
+     * const game = new Game(720, 1280);
      * game.physics = true;
      * ```
      */
@@ -1681,6 +1778,69 @@ export declare class Game {
      * ```
      */
     animateExplode(sprite: BaseSprite, options?: ExplodeOptions, onComplete?: () => void): void;
+    /**
+     * Spawns visual pieces around a sprite and converges them back into its
+     * current rendered appearance.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * The original sprite is hidden while the assembly plays and is restored when
+     * the effect finishes.
+     *
+     * @param sprite - The sprite to assemble.
+     * @param options - Optional assembly tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateAssemble(sprite: BaseSprite, options?: AssembleOptions, onComplete?: () => void): void;
+    /**
+     * Breaks a sprite apart locally inside its own bounds using a directional
+     * dissolve sweep.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * By default, the original sprite is destroyed immediately after the effect
+     * is spawned. Set `destroySprite: false` to leave the sprite hidden instead.
+     *
+     * @param sprite - The sprite to disintegrate.
+     * @param options - Optional disintegration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateDisintegrate(sprite: BaseSprite, options?: DisintegrateOptions, onComplete?: () => void): void;
+    /**
+     * Reconstructs a sprite locally inside its own bounds using a directional
+     * integration sweep.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * The original sprite is hidden while the integration plays and is restored
+     * when the effect finishes.
+     *
+     * @param sprite - The sprite to integrate.
+     * @param options - Optional integration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateIntegrate(sprite: BaseSprite, options?: IntegrateOptions, onComplete?: () => void): void;
+    /**
+     * Reveals or covers a sprite with a directional wipe mask.
+     *
+     * This is a render-only effect that captures the sprite's current appearance
+     * and animates a clipping region over that snapshot.
+     *
+     * For `mode: "reveal"`, the original sprite is hidden during the wipe and is
+     * restored when the effect finishes.
+     *
+     * For `mode: "cover"`, the effect hides the sprite over time. If
+     * `destroySprite` is omitted or `true`, the sprite is destroyed immediately
+     * after the wipe starts and only the wipe snapshot remains visible.
+     *
+     * @param sprite - The sprite to wipe.
+     * @param options - Optional wipe tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateWipe(sprite: BaseSprite, options?: WipeOptions, onComplete?: () => void): void;
     /**
      * Schedules a callback to fire after `delayMs` milliseconds, driven by the
      * rAF loop (not `setTimeout`). Timers accumulate elapsed time each frame and
@@ -1882,7 +2042,7 @@ export declare class Game {
      * overlays. Order per frame:
      * 1. Accumulate timer elapsed time; fire ready callbacks.
      * 2. Advance animations (linear interpolation).
-     * 3. Advance active explosion effects.
+     * 3. Advance active piece and wipe effects.
      * 4. Apply gravity to sprite velocities.
      * 5. Apply velocities to sprite positions.
      * 6. Call `onUpdate(dt)`.

package/dist/minimo.js

@@ -693,7 +693,7 @@ export class BackgroundLayer {
  * Example custom font registration:
  *
  * ```ts
- * const game = new Game(800, 600);
+ * const game = new Game(720, 1280);
  * game.requireFont('"Bangers"', { weight: "400" });
  * game.start();
  * ```
@@ -705,7 +705,7 @@ export class BackgroundLayer {
  * ```ts
  * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  *
- * const game = new Game(800, 600);
+ * const game = new Game(720, 1280);
  *
  * const player = new Sprite("🐢", 400, 500, 48);
  * game.add(player);
@@ -981,19 +981,20 @@ export class Game {
      * The engine creates its own `<canvas>`, sets its dimensions, and appends it
      * to `document.body`. The canvas is automatically centered and responsively
      * scaled to use the maximum available viewport space while preserving aspect ratio.
+     * For new mobile-first Minimo Games, prefer a portrait canvas such as `720x1280`.
      *
-     * @param width - Canvas width in pixels. Default: `800`.
-     * @param height - Canvas height in pixels. Default: `600`.
+     * @param width - Canvas width in pixels. Default: `720`.
+     * @param height - Canvas height in pixels. Default: `1280`.
      *
      * @throws Error if a 2D context cannot be obtained.
      *
      * @example
      * ```ts
-     * const game = new Game(800, 600);
+     * const game = new Game(720, 1280);
      * game.physics = true;
      * ```
      */
-    constructor(width = 800, height = 600) {
+    constructor(width = 720, height = 1280) {
         /** @internal */ this._requiredFonts = new Map();
         /** @internal */ this._hasAppliedGlobalFontRequirements = false;
         /** @internal */ this._isRegisteringPreloadAssets = false;
@@ -1981,6 +1982,87 @@ export class Game {
             this.destroySprite(sprite);
         }
     }
+    /**
+     * Spawns visual pieces around a sprite and converges them back into its
+     * current rendered appearance.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * The original sprite is hidden while the assembly plays and is restored when
+     * the effect finishes.
+     *
+     * @param sprite - The sprite to assemble.
+     * @param options - Optional assembly tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateAssemble(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateAssemble(sprite, glyphCanvas, options, onComplete);
+    }
+    /**
+     * Breaks a sprite apart locally inside its own bounds using a directional
+     * dissolve sweep.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * By default, the original sprite is destroyed immediately after the effect
+     * is spawned. Set `destroySprite: false` to leave the sprite hidden instead.
+     *
+     * @param sprite - The sprite to disintegrate.
+     * @param options - Optional disintegration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateDisintegrate(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateDisintegrate(sprite, glyphCanvas, options, onComplete);
+        if (options?.destroySprite !== false) {
+            this.destroySprite(sprite);
+        }
+    }
+    /**
+     * Reconstructs a sprite locally inside its own bounds using a directional
+     * integration sweep.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * The original sprite is hidden while the integration plays and is restored
+     * when the effect finishes.
+     *
+     * @param sprite - The sprite to integrate.
+     * @param options - Optional integration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateIntegrate(sprite, options, onComplete) {
+        const glyphCanvas = this._renderSystem.getSpriteGlyphCanvasForEffects(sprite);
+        this._explosionSystem.animateIntegrate(sprite, glyphCanvas, options, onComplete);
+    }
+    /**
+     * Reveals or covers a sprite with a directional wipe mask.
+     *
+     * This is a render-only effect that captures the sprite's current appearance
+     * and animates a clipping region over that snapshot.
+     *
+     * For `mode: "reveal"`, the original sprite is hidden during the wipe and is
+     * restored when the effect finishes.
+     *
+     * For `mode: "cover"`, the effect hides the sprite over time. If
+     * `destroySprite` is omitted or `true`, the sprite is destroyed immediately
+     * after the wipe starts and only the wipe snapshot remains visible.
+     *
+     * @param sprite - The sprite to wipe.
+     * @param options - Optional wipe tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateWipe(sprite, options, onComplete) {
+        const snapshot = this._renderSystem.getSpriteRenderSnapshot(sprite);
+        this._explosionSystem.animateWipe(sprite, snapshot, options, onComplete);
+        if ((options?.mode ?? "reveal") === "cover" && options?.destroySprite !== false) {
+            this.destroySprite(sprite);
+        }
+    }
     // -------------------------------------------------------------------------
     // Timers
     // -------------------------------------------------------------------------
@@ -2239,7 +2321,7 @@ export class Game {
      * overlays. Order per frame:
      * 1. Accumulate timer elapsed time; fire ready callbacks.
      * 2. Advance animations (linear interpolation).
-     * 3. Advance active explosion effects.
+     * 3. Advance active piece and wipe effects.
      * 4. Apply gravity to sprite velocities.
      * 5. Apply velocities to sprite positions.
      * 6. Call `onUpdate(dt)`.
@@ -2424,6 +2506,7 @@ export class Game {
             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,

package/package.json

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