minimojs 1.0.0-alpha.4 → 1.0.0-alpha.41

package/README.md

@@ -10,7 +10,7 @@ This README is intentionally high-level. It explains what the project is and how
 
 - ESM-only TypeScript-first engine
 - Single `Game` entry point
-- Emoji-based sprite rendering
+- Image-backed sprite rendering, with emoji as a zero-asset alternative
 - rAF-driven loop (timers/animations/updates)
 - Responsive auto-centered canvas
 
@@ -21,12 +21,13 @@ 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
 
-- Scene manager/ECS architecture
+- Heavy scene-manager/ECS architecture
 - Heavy physics engine features
-- Image spritesheets and asset pipelines
+- Spritesheets, texture atlases, and asset pipelines
 - Nested subsystem APIs
 - `setTimeout` / `setInterval` game loops
 
@@ -39,29 +40,58 @@ npm install minimojs
 ## Quick Start
 
 ```ts
-import { Game, Sprite } from "minimojs";
+import { DrawSprite, EmojiSprite, Game, type IScene } from "minimojs";
 
-const game = new Game(800, 600);
+const game = new Game(720, 1280);
 game.gravityY = 980;
 
-const player = game.add(new Sprite("🐢", 400, 300, 48));
-player.x = 400;
-player.y = 300;
-player.gravityScale = 1;
-
-game.onUpdate = (dt) => {
-  if (game.isKeyDown("ArrowLeft")) player.vx = -200;
-  else if (game.isKeyDown("ArrowRight")) player.vx = 200;
-  else player.vx = 0;
+class MeterSprite extends DrawSprite {
+  public value = 0.5;
+
+  constructor(x: number, y: number) {
+    super(160, 28, x, y);
+  }
+
+  redraw(ctx: CanvasRenderingContext2D) {
+    ctx.fillStyle = "#1a2236";
+    ctx.fillRect(0, 0, this.width, this.height);
+    ctx.fillStyle = "#7ce7ff";
+    ctx.fillRect(0, 0, this.width * this.value, this.height);
+  }
+}
+
+class DemoScene implements IScene {
+  private player: EmojiSprite | null = null;
+  private meter: MeterSprite | null = null;
+
+  onCreate() {
+    this.player = game.add(new EmojiSprite("🐢", 360, 640, 48));
+    this.player.gravityScale = 1;
+    this.meter = game.add(new MeterSprite(360, 80));
+    this.meter.ignoreScroll = true;
+  }
+
+  onUpdate(dt: number) {
+    if (!this.player) return;
+
+    if (game.isKeyDown("ArrowLeft")) this.player.vx = -200;
+    else if (game.isKeyDown("ArrowRight")) this.player.vx = 200;
+    else this.player.vx = 0;
+
+    if (game.isKeyPressed(" ")) this.player.vy = -600;
+    if (this.meter) this.meter.value = Math.abs(this.player.vx) / 200;
+    game.drawText("MinimoJS", 10, 10, 16);
+  }
+}
+
+game.start(new DemoScene());
+```
 
-  if (game.isKeyPressed(" ")) player.vy = -600;
-  game.drawText("MinimoJS", 10, 10, 16);
-};
+Note: text defaults to `monospace`, so a game that names no font downloads none. To use a web font, declare it in your HTML, register it with `game.requireFont(...)`, and set it as a `TextSprite`'s `fontFamily`.
 
-game.start();
-```
+Load images in `game.onPreload`, once, at boot. Only a game with many scenes that each carry many images of their own, such as one with many levels, should give scenes an `onPreload()` so each loads its images when the player reaches it; see `examples/level-loading/`.
 
-Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTML if you want pixel-font styling.
+Sounds come from files too. Declare them as `sound` entries in an asset file, or load them with `game.loadSound(key, src)`, and play them with `game.playSound(key)`, which returns a playback you can `pause()`, `resume()`, and `stop()`; pass `{ loop: true }` for music. MP3 plays in every browser. `game.sound` and `game.soundSequence` still synthesize tones with no file at all; see `examples/sound-files/`.
 
 ## Examples
 
@@ -70,6 +100,14 @@ Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTM
 - `examples/space-invader/`
 - `examples/super-minimo-bros/`
 - `examples/scale-shift/`
+- `examples/background-desert/`
+- `examples/scene-lab/`
+- `examples/image-sprite-sad-plush/`
+- `examples/draw-sprite/`
+- `examples/pseudo-3d-racer/`
+- `examples/animations/`
+- `examples/level-loading/`
+- `examples/sound-files/`
 
 Run locally from the `minimojs` directory:
 

package/dist/internal/AnimationSystem.js

@@ -0,0 +1,345 @@
+/** @internal */
+export class AnimationSystem {
+    constructor() {
+        /** @internal */
+        this._animations = [];
+        /** @internal */
+        this._deformAnimations = [];
+        /** @internal */
+        this._motionAnimations = [];
+        /** @internal */
+        this._shakeAnimations = [];
+        /** @internal */
+        this._blinkAnimations = [];
+        /** @internal */
+        this._flickerAnimations = [];
+        /** @internal */
+        this._renderDataSprites = new Set();
+    }
+    update(dtMs) {
+        const animations = this._animations;
+        const toRemove = [];
+        for (let i = 0; i < animations.length; i++) {
+            const anim = animations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            anim.sprite[anim.property] = anim.from + (anim.to - anim.from) * t;
+            if (t >= 1) {
+                toRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = toRemove.length - 1; i >= 0; i--) {
+            animations.splice(toRemove[i], 1);
+        }
+        const deformAnimations = this._deformAnimations;
+        const deformToRemove = [];
+        for (let i = 0; i < deformAnimations.length; i++) {
+            const anim = deformAnimations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            if (t >= 1) {
+                deformToRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = deformToRemove.length - 1; i >= 0; i--) {
+            deformAnimations.splice(deformToRemove[i], 1);
+        }
+        const motionAnimations = this._motionAnimations;
+        const motionToRemove = [];
+        for (let i = 0; i < motionAnimations.length; i++) {
+            const anim = motionAnimations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            if (anim.kind === "arc") {
+                anim.sprite.x = anim.fromX + (anim.toX - anim.fromX) * t;
+                anim.sprite.y =
+                    anim.fromY +
+                        (anim.toY - anim.fromY) * t -
+                        anim.magnitude * 4 * t * (1 - t);
+            }
+            else if (anim.kind === "bounce") {
+                anim.sprite.x = anim.fromX;
+                anim.sprite.y = anim.fromY - anim.magnitude * 4 * t * (1 - t);
+            }
+            else {
+                anim.sprite.x = anim.fromX;
+                anim.sprite.y = anim.fromY - Math.sin(t * Math.PI) * anim.magnitude;
+            }
+            if (t >= 1) {
+                motionToRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = motionToRemove.length - 1; i >= 0; i--) {
+            motionAnimations.splice(motionToRemove[i], 1);
+        }
+        this.rebuildRenderData(dtMs);
+    }
+    animateAlpha(sprite, to, durationMs, onComplete) {
+        const animations = this._animations.filter((a) => !(a.sprite === sprite && a.property === "alpha"));
+        animations.push({
+            sprite,
+            property: "alpha",
+            from: sprite.alpha,
+            to,
+            durationMs,
+            elapsed: 0,
+            onComplete,
+        });
+        this._animations = animations;
+    }
+    animateRotation(sprite, to, durationMs, onComplete) {
+        const animations = this._animations.filter((a) => !(a.sprite === sprite && a.property === "rotation"));
+        animations.push({
+            sprite,
+            property: "rotation",
+            from: sprite.rotation,
+            to,
+            durationMs,
+            elapsed: 0,
+            onComplete,
+        });
+        this._animations = animations;
+    }
+    animateDeform(sprite, toScaleX, toScaleY, pivotX, pivotY, durationMs, onComplete) {
+        const current = sprite._renderData;
+        const fromScaleX = current?.scaleX ?? 1;
+        const fromScaleY = current?.scaleY ?? 1;
+        const deformAnimations = this._deformAnimations.filter((a) => a.sprite !== sprite);
+        deformAnimations.push({
+            sprite,
+            fromScaleX,
+            fromScaleY,
+            toScaleX: this.sanitizeScale(toScaleX),
+            toScaleY: this.sanitizeScale(toScaleY),
+            pivotX: this.sanitizePivot(pivotX),
+            pivotY: this.sanitizePivot(pivotY),
+            durationMs,
+            elapsed: 0,
+            onComplete,
+        });
+        this._deformAnimations = deformAnimations;
+    }
+    animateShake(sprite, intensity, durationMs, onComplete) {
+        const animations = this._shakeAnimations.filter((a) => a.sprite !== sprite);
+        animations.push({
+            sprite,
+            intensity: this.sanitizeNonNegative(intensity),
+            durationMs: this.sanitizeDuration(durationMs),
+            elapsed: 0,
+            onComplete,
+        });
+        this._shakeAnimations = animations;
+    }
+    animateBounce(sprite, height, durationMs, onComplete) {
+        this.replaceMotionAnimation({
+            sprite,
+            kind: "bounce",
+            fromX: sprite.x,
+            fromY: sprite.y,
+            toX: sprite.x,
+            toY: sprite.y,
+            magnitude: this.sanitizeNonNegative(height),
+            durationMs: this.sanitizeDuration(durationMs),
+            elapsed: 0,
+            onComplete,
+        });
+    }
+    animateFloat(sprite, distance, durationMs, onComplete) {
+        this.replaceMotionAnimation({
+            sprite,
+            kind: "float",
+            fromX: sprite.x,
+            fromY: sprite.y,
+            toX: sprite.x,
+            toY: sprite.y,
+            magnitude: this.sanitizeNonNegative(distance),
+            durationMs: this.sanitizeDuration(durationMs),
+            elapsed: 0,
+            onComplete,
+        });
+    }
+    animateArc(sprite, toX, toY, arcHeight, durationMs, onComplete) {
+        this.replaceMotionAnimation({
+            sprite,
+            kind: "arc",
+            fromX: sprite.x,
+            fromY: sprite.y,
+            toX,
+            toY,
+            magnitude: this.sanitizeNonNegative(arcHeight),
+            durationMs: this.sanitizeDuration(durationMs),
+            elapsed: 0,
+            onComplete,
+        });
+    }
+    animateBlink(sprite, times, durationMs, onComplete) {
+        const animations = this._blinkAnimations.filter((a) => a.sprite !== sprite);
+        animations.push({
+            sprite,
+            times: Math.max(1, Math.round(Number.isFinite(times) ? times : 1)),
+            durationMs: this.sanitizeDuration(durationMs),
+            elapsed: 0,
+            onComplete,
+        });
+        this._blinkAnimations = animations;
+    }
+    animateFlicker(sprite, durationMs, onComplete) {
+        const animations = this._flickerAnimations.filter((a) => a.sprite !== sprite);
+        animations.push({
+            sprite,
+            durationMs: this.sanitizeDuration(durationMs),
+            elapsed: 0,
+            onComplete,
+        });
+        this._flickerAnimations = animations;
+    }
+    clearSpriteAnimations(sprite) {
+        this._animations = this._animations.filter((a) => a.sprite !== sprite);
+        this._deformAnimations = this._deformAnimations.filter((a) => a.sprite !== sprite);
+        this._motionAnimations = this._motionAnimations.filter((a) => a.sprite !== sprite);
+        this._shakeAnimations = this._shakeAnimations.filter((a) => a.sprite !== sprite);
+        this._blinkAnimations = this._blinkAnimations.filter((a) => a.sprite !== sprite);
+        this._flickerAnimations = this._flickerAnimations.filter((a) => a.sprite !== sprite);
+        this._renderDataSprites.delete(sprite);
+        sprite._renderData = null;
+    }
+    clearAll() {
+        for (const sprite of this._renderDataSprites) {
+            sprite._renderData = null;
+        }
+        this._animations = [];
+        this._deformAnimations = [];
+        this._motionAnimations = [];
+        this._shakeAnimations = [];
+        this._blinkAnimations = [];
+        this._flickerAnimations = [];
+        this._renderDataSprites.clear();
+    }
+    /** @internal */
+    sanitizeScale(value) {
+        if (!Number.isFinite(value))
+            return 1;
+        return Math.max(0, value);
+    }
+    /** @internal */
+    sanitizeDuration(value) {
+        if (!Number.isFinite(value))
+            return 1;
+        return Math.max(1, value);
+    }
+    /** @internal */
+    sanitizeNonNegative(value) {
+        if (!Number.isFinite(value))
+            return 0;
+        return Math.max(0, value);
+    }
+    /** @internal */
+    sanitizePivot(value) {
+        if (!Number.isFinite(value))
+            return 0.5;
+        return Math.max(0, Math.min(1, value));
+    }
+    /** @internal */
+    replaceMotionAnimation(entry) {
+        const animations = this._motionAnimations.filter((a) => a.sprite !== entry.sprite);
+        animations.push(entry);
+        this._motionAnimations = animations;
+    }
+    /** @internal */
+    rebuildRenderData(dtMs) {
+        const next = new Map();
+        const nextSprites = new Set();
+        const upsert = (sprite) => {
+            let state = next.get(sprite);
+            if (!state) {
+                state = {
+                    scaleX: 1,
+                    scaleY: 1,
+                    pivotX: 0.5,
+                    pivotY: 0.5,
+                    offsetX: 0,
+                    offsetY: 0,
+                    alphaMultiplier: 1,
+                };
+                next.set(sprite, state);
+                nextSprites.add(sprite);
+            }
+            return state;
+        };
+        for (const anim of this._deformAnimations) {
+            const state = upsert(anim.sprite);
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            state.scaleX = anim.fromScaleX + (anim.toScaleX - anim.fromScaleX) * t;
+            state.scaleY = anim.fromScaleY + (anim.toScaleY - anim.fromScaleY) * t;
+            state.pivotX = anim.pivotX;
+            state.pivotY = anim.pivotY;
+        }
+        const shakeToRemove = [];
+        for (let i = 0; i < this._shakeAnimations.length; i++) {
+            const anim = this._shakeAnimations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            const decay = 1 - t;
+            const state = upsert(anim.sprite);
+            state.offsetX += (Math.random() * 2 - 1) * anim.intensity * decay;
+            state.offsetY += (Math.random() * 2 - 1) * anim.intensity * decay;
+            if (t >= 1) {
+                shakeToRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = shakeToRemove.length - 1; i >= 0; i--) {
+            this._shakeAnimations.splice(shakeToRemove[i], 1);
+        }
+        const blinkToRemove = [];
+        for (let i = 0; i < this._blinkAnimations.length; i++) {
+            const anim = this._blinkAnimations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            const state = upsert(anim.sprite);
+            const step = Math.floor(t * anim.times * 2);
+            state.alphaMultiplier *= step % 2 === 0 ? 1 : 0;
+            if (t >= 1) {
+                blinkToRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = blinkToRemove.length - 1; i >= 0; i--) {
+            this._blinkAnimations.splice(blinkToRemove[i], 1);
+        }
+        const flickerToRemove = [];
+        for (let i = 0; i < this._flickerAnimations.length; i++) {
+            const anim = this._flickerAnimations[i];
+            anim.elapsed += dtMs;
+            const t = Math.min(anim.elapsed / anim.durationMs, 1);
+            const state = upsert(anim.sprite);
+            state.alphaMultiplier *= 0.25 + Math.random() * 0.75;
+            if (t >= 1) {
+                flickerToRemove.push(i);
+                anim.onComplete?.();
+            }
+        }
+        for (let i = flickerToRemove.length - 1; i >= 0; i--) {
+            this._flickerAnimations.splice(flickerToRemove[i], 1);
+        }
+        for (const sprite of this._renderDataSprites) {
+            if (!nextSprites.has(sprite)) {
+                sprite._renderData = null;
+            }
+        }
+        for (const [sprite, state] of next.entries()) {
+            const isDefault = state.scaleX === 1 &&
+                state.scaleY === 1 &&
+                state.pivotX === 0.5 &&
+                state.pivotY === 0.5 &&
+                state.offsetX === 0 &&
+                state.offsetY === 0 &&
+                state.alphaMultiplier === 1;
+            sprite._renderData = isDefault ? null : state;
+        }
+        this._renderDataSprites = nextSprites;
+    }
+}

package/dist/internal/AssetSystem.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fetches and decodes one audio file. The engine passes one backed by its
+ * `AudioContext`; the asset system only stores what it returns, so it needs no
+ * audio API of its own and runs in tests without a browser.
+ */
+export type SoundLoader = (src: string) => Promise<unknown>;