minimojs 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/minimo.js

@@ -25,10 +25,7 @@
  * @example
  * ```ts
  * // Direct instantiation
- * const coin = new Sprite("🪙");
- * coin.x = 300;
- * coin.y = 200;
- * coin.size = 32;
+ * const coin = new Sprite("🪙", 300, 200, 32);
  * game.add(coin);
  * ```
  *
@@ -39,10 +36,7 @@
  *   health = 3;
  *
  *   constructor(x: number, y: number) {
- *     super("🐢");
- *     this.x = x;
- *     this.y = y;
- *     this.size = 48;
+ *     super("🐢", x, y, 48);
  *     this.gravityScale = 1;
  *   }
  * }
@@ -53,7 +47,25 @@
  */
 export class Sprite {
     /**
-     * Creates a new Sprite with the given emoji and optional position.
+     * Base width and height of this sprite in pixels.
+     *
+     * This value is read-only after construction and defines the glyph-cache
+     * render size. The visible and collision size during gameplay is exposed by
+     * {@link Sprite.displaySize}.
+     */
+    get size() {
+        return this._size;
+    }
+    /**
+     * Effective rendered/collision size in pixels.
+     * Computed as `size * scale` with non-negative clamping.
+     */
+    get displaySize() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this._size * Math.max(0, safeScale);
+    }
+    /**
+     * Creates a new Sprite with the given emoji, optional position, and base size.
      * All other properties use their defaults and can be set after construction.
      *
      * @param sprite - The emoji character to render. Must be a single emoji.
@@ -61,15 +73,15 @@ export class Sprite {
      *   @example "🔥", "⭐", "🐢", "💣", "👾"
      * @param x - Initial X position in world space (center), in pixels. Default: `0`.
      * @param y - Initial Y position in world space (center), in pixels. Default: `0`.
+     * @param size - Base sprite size in pixels. Default: `32`.
      *
      * @example
      * ```ts
-     * const enemy = new Sprite("👾", 200, 100);
-     * enemy.size = 40;
+     * const enemy = new Sprite("👾", 200, 100, 40);
      * game.add(enemy);
      * ```
      */
-    constructor(sprite, x = 0, y = 0) {
+    constructor(sprite, x = 0, y = 0, size = 32) {
         /**
          * X position in world space (horizontal center of the sprite), in pixels.
          * Positive X points right. Updated each frame by: `x += vx * dt`.
@@ -83,10 +95,34 @@ export class Sprite {
          */
         this.y = 0;
         /**
-         * Width and height of the sprite's bounding square, in pixels.
-         * Used for both canvas rendering (font size) and AABB collision detection.
+         * Visual scale multiplier applied to {@link Sprite.size}.
+         * Default: `1`.
+         *
+         * Set this at runtime to resize a sprite without changing its base cached
+         * glyph size.
+         */
+        this.scale = 1;
+        /**
+         * CSS text color used when rendering this sprite.
+         *
+         * This mainly affects monochrome glyphs and symbol-style sprites.
+         * Full-color emoji may ignore this and render with their native colors,
+         * depending on browser behavior.
+         */
+        this.color = "#000000";
+        /**
+         * Physics body type flag.
+         *
+         * - `false` (default): the sprite is dynamic and can be moved by velocity,
+         *   gravity, and explicit collision resolution.
+         * - `true`: the sprite is static and is not moved by the engine's built-in
+         *   velocity/gravity integration. Static sprites act as stable obstacles for
+         *   simple platform collisions.
+         *
+         * Static sprites can still be repositioned manually by setting `x` and `y`
+         * directly in your own game code.
          */
-        this.size = 32;
+        this.isStatic = false;
         /**
          * Visual rotation of the sprite in degrees.
          * `0` = upright. Positive values rotate clockwise.
@@ -154,6 +190,8 @@ export class Sprite {
         this.sprite = sprite;
         this.x = x;
         this.y = y;
+        const safeSize = Number.isFinite(size) ? size : 32;
+        this._size = Math.max(1, safeSize);
     }
 }
 // ---------------------------------------------------------------------------
@@ -168,17 +206,63 @@ export class Sprite {
  *
  * ---
  *
- * ## Quick Start
+ * ## ES Module Only
+ *
+ * MinimoJS is an **ES module only** package.
+ * You must import it with standard ESM syntax such as:
  *
  * ```ts
  * import { Game, Sprite } from "minimojs";
+ * ```
+ *
+ * In the browser, use it from a module script:
+ *
+ * ```html
+ * <script type="module">
+ *   import { Game, Sprite } from "./dist/minimo.js";
+ * </script>
+ * ```
+ *
+ * Or from a CDN:
+ *
+ * ```ts
+ * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
+ * ```
+ *
+ * Do NOT use a classic `<script>` tag without `type="module"`.
+ * Do NOT expect a global `window.MinimoJS`.
+ * Do NOT use `require("minimojs")` (CommonJS is not supported).
+ *
+ * ---
+ *
+ * ## Required Font Setup
+ *
+ * `drawText()` renders with `"Press Start 2P", monospace`.
+ * You MUST load `Press Start 2P` yourself in your `index.html` before starting
+ * the game. MinimoJS does NOT download, inject, or manage web fonts for you.
+ * If the font is missing, the browser falls back to `monospace`.
+ *
+ * Example `index.html` `<head>` setup:
+ *
+ * ```html
+ * <link rel="preconnect" href="https://fonts.googleapis.com" />
+ * <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ * <link
+ *   href="https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap"
+ *   rel="stylesheet"
+ * />
+ * ```
+ *
+ * ---
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  *
  * const game = new Game(800, 600);
  *
- * const player = new Sprite("🐢");
- * player.x = 400;
- * player.y = 500;
- * player.size = 48;
+ * const player = new Sprite("🐢", 400, 500, 48);
  * game.add(player);
  *
  * game.onUpdate = (dt) => {
@@ -205,7 +289,8 @@ export class Sprite {
  * ## Flat API
  *
  * ALL engine functionality is on the `game` object.
- * Do not look for sub-objects like `game.physics`, `game.input`, etc. They do not exist.
+ * Do not look for nested subsystem objects like `game.input.keyboard`,
+ * `game.physics.world`, etc. They do not exist in MinimoJS v1.
  *
  * ---
  *
@@ -311,8 +396,7 @@ export class Sprite {
  * ```ts
  * game.onCreate = () => {
  *   // scene init: add sprites, setup timers
- *   const skull = new Sprite("💀");
- *   skull.x = 400; skull.y = 300; skull.size = 96;
+ *   const skull = new Sprite("💀", 400, 300, 96);
  *   game.add(skull);
  * };
  *
@@ -349,7 +433,7 @@ export class Sprite {
  * - Text input / HTML form elements
  * - Parallax layers
  * - Multiple cameras
- * - Collision resolution (only detection is supported)
+ * - Full physics engine (only basic explicit AABB collision helpers are provided)
  * - Image sprites (PNG, SVG, canvas, etc.)
  * - `setTimeout` or `setInterval`
  */
@@ -372,6 +456,7 @@ export class Game {
      * @example
      * ```ts
      * const game = new Game(800, 600);
+     * game.physics = true;
      * ```
      */
     constructor(width = 800, height = 600) {
@@ -428,6 +513,20 @@ export class Game {
          * ```
          */
         this.gravityY = 0;
+        /**
+         * Enables the basic collision-resolution helpers (`collide` / `collideAny`).
+         *
+         * When `false` (default), overlap detection still works, but collision
+         * resolution helpers are unavailable.
+         *
+         * Set this to `true` for simple platformer-style collision handling.
+         *
+         * @example
+         * ```ts
+         * game.physics = true;
+         * ```
+         */
+        this.physics = false;
         /**
          * Horizontal scroll offset of the world camera, in pixels.
          * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -582,8 +681,9 @@ export class Game {
     // -------------------------------------------------------------------------
     /**
      * Registers a {@link Sprite} (or subclass instance) with the engine.
-     * After calling `add`, the sprite is rendered and receives physics updates
-     * every frame until {@link Game.destroySprite} or {@link Game.reset} is called.
+     * After calling `add`, the sprite is rendered and, if dynamic
+     * (`isStatic = false`), receives built-in velocity/gravity integration every
+     * frame until {@link Game.destroySprite} or {@link Game.reset} is called.
      *
      * **Ownership:** The game instance takes ownership of the sprite from this
      * point forward. It will appear in {@link Game.getSprites} on the same frame.
@@ -598,16 +698,14 @@ export class Game {
      * @example
      * ```ts
      * // Plain sprite
-     * const coin = new Sprite("🪙");
-     * coin.x = 300; coin.y = 200; coin.size = 32;
+     * const coin = new Sprite("🪙", 300, 200, 32);
      * game.add(coin);
      *
      * // Custom subclass
      * class Enemy extends Sprite {
      *   speed = 150;
      *   constructor(x: number, y: number) {
-     *     super("👾");
-     *     this.x = x; this.y = y; this.size = 40;
+     *     super("👾", x, y, 40);
      *   }
      * }
      * const enemy = game.add(new Enemy(600, 100));
@@ -666,10 +764,10 @@ export class Game {
      * collision detection.
      *
      * Each sprite's bounding box is a square centered at `(x, y)` with side
-     * length `size`. Rotation is **ignored** — the box is always axis-aligned.
+     * length `displaySize`. Rotation is **ignored** — the box is always axis-aligned.
      *
      * **No collision resolution is performed.** This method is detection-only.
-     * If you need bounce or push-apart behavior, implement it in `onUpdate`.
+     * Use {@link Game.collide} for the engine's basic explicit push-out helper.
      *
      * @param a - First sprite.
      * @param b - Second sprite.
@@ -683,8 +781,8 @@ export class Game {
      * ```
      */
     overlap(a, b) {
-        const halfA = a.size / 2;
-        const halfB = b.size / 2;
+        const halfA = a.displaySize / 2;
+        const halfB = b.displaySize / 2;
         return (Math.abs(a.x - b.x) < halfA + halfB &&
             Math.abs(a.y - b.y) < halfA + halfB);
     }
@@ -720,6 +818,95 @@ export class Game {
         }
         return null;
     }
+    /**
+     * Tests and resolves a basic AABB collision between two sprites.
+     *
+     * This helper is intended for simple platformer-style collision response.
+     * It uses the same axis-aligned square bounds as {@link Game.overlap}, but
+     * additionally pushes one sprite out of the collision and zeroes velocity on
+     * the resolved axis.
+     *
+     * **Resolution rules:**
+     * - If the first sprite is dynamic (`isStatic = false`), the first sprite is resolved.
+     * - Otherwise, if the second sprite is dynamic, the second sprite is resolved.
+     * - If both sprites are static, collision is reported but no movement occurs.
+     *
+     * The returned flags are always reported relative to the **first** sprite.
+     *
+     * @param a - First sprite. Usually the moving actor (for example, the player).
+     * @param b - Second sprite. Usually a static obstacle or platform.
+     * @returns Collision details, or `null` if the sprites do not overlap.
+     * @throws Error if the game's physics helpers are not enabled.
+     *
+     * @example
+     * ```ts
+     * const hit = game.collide(player, floorTile);
+     * if (hit?.grounded) {
+     *   canJump = true;
+     * }
+     * ```
+     */
+    collide(a, b) {
+        this._assertPhysicsEnabled();
+        if (a === b)
+            return null;
+        const collision = this._getCollisionResolution(a, b);
+        if (!collision)
+            return null;
+        if (!a.isStatic) {
+            a.x += collision.separationX;
+            a.y += collision.separationY;
+            if (collision.axis === "x") {
+                a.vx = 0;
+            }
+            else {
+                a.vy = 0;
+            }
+        }
+        else if (!b.isStatic) {
+            b.x -= collision.separationX;
+            b.y -= collision.separationY;
+            if (collision.axis === "x") {
+                b.vx = 0;
+            }
+            else {
+                b.vy = 0;
+            }
+        }
+        return collision.info;
+    }
+    /**
+     * Tests and resolves the first collision found between two groups of sprites.
+     *
+     * This behaves like {@link Game.overlapAny}, but uses the explicit collision
+     * rules from {@link Game.collide} and returns the collision details as the
+     * third tuple item.
+     *
+     * @param listA - First group of sprites.
+     * @param listB - Second group of sprites.
+     * @returns A `[Sprite, Sprite, CollisionInfo]` tuple for the first collision found,
+     *   or `null` if no pair overlaps.
+     * @throws Error if the game's physics helpers are not enabled.
+     *
+     * @example
+     * ```ts
+     * const hit = game.collideAny([player], floorTiles);
+     * if (hit?.[2].grounded) {
+     *   canJump = true;
+     * }
+     * ```
+     */
+    collideAny(listA, listB) {
+        this._assertPhysicsEnabled();
+        for (const a of listA) {
+            for (const b of listB) {
+                const info = this.collide(a, b);
+                if (info)
+                    return [a, b, info];
+            }
+        }
+        return null;
+    }
     // -------------------------------------------------------------------------
     // Input — Keyboard
     // -------------------------------------------------------------------------
@@ -803,14 +990,14 @@ export class Game {
      * Works with both mouse input and multiple simultaneous touches.
      *
      * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.size * radiusScale`. World-space sprites are tested against the
+     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
      * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
      * screen space.
      *
      * Use this for continuous virtual buttons such as touch movement controls.
      *
      * @param sprite - Target sprite to test. If `null` / `undefined`, returns `false`.
-     * @param radiusScale - Multiplier applied to `sprite.size` to define the hit radius.
+     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
      *   Default: `0.5`.
      * @returns `true` if any currently held pointer overlaps the sprite hit area.
      *
@@ -840,14 +1027,14 @@ export class Game {
      * sprite. Works with both mouse input and multiple simultaneous touches.
      *
      * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.size * radiusScale`. World-space sprites are tested against the
+     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
      * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
      * screen space.
      *
      * Use this for one-shot virtual buttons such as menu taps.
      *
      * @param sprite - Target sprite to test. If `null` / `undefined`, returns `false`.
-     * @param radiusScale - Multiplier applied to `sprite.size` to define the hit radius.
+     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
      *   Default: `0.5`.
      * @returns `true` if any pointer began pressing this frame over the sprite hit area.
      *
@@ -890,7 +1077,7 @@ export class Game {
      * const pointers = game.getPointers();
      * if (pointers.length > 0) {
      *   const first = pointers[0];
-     *   game.text(`Pointer: ${first.x}, ${first.y}`, 10, 10);
+     *   game.drawText(`Pointer: ${first.x}, ${first.y}`, 10, 10, 14);
      * }
      * ```
      */
@@ -902,7 +1089,7 @@ export class Game {
      * the target sprite.
      *
      * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.size * radiusScale`. World-space sprites are tested against the
+     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
      * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
      * screen space.
      *
@@ -910,7 +1097,7 @@ export class Game {
      * pointer position over a virtual joystick or draggable control.
      *
      * @param sprite - Target sprite to test. If `null` / `undefined`, returns an empty array.
-     * @param radiusScale - Multiplier applied to `sprite.size` to define the hit radius.
+     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
      *   Default: `0.5`.
      * @returns A read-only array of active pointer snapshots currently over the sprite.
      *
@@ -1142,8 +1329,11 @@ export class Game {
      * The text overlay list is cleared after each render. Call this inside `onUpdate`.
      *
      * **Layer:** Text is always drawn on top of all sprites.
-     * **Font:** Text always uses a fixed `monospace` font family.
-     * Font family cannot be customized in MinimoJS v1.
+     * **Font:** Text uses `"Press Start 2P", monospace`.
+     * You MUST load `Press Start 2P` yourself in `index.html` (for example via
+     * Google Fonts) before calling {@link Game.start}. MinimoJS does NOT load
+     * external fonts for you. If the font is unavailable, the browser falls back
+     * to `monospace`. Font family cannot be customized in MinimoJS v1.
      *
      * @param text - The string to render. Supports emoji and Unicode.
      * @param x - X position in **screen space** (pixels from canvas left edge).
@@ -1169,6 +1359,24 @@ export class Game {
     // -------------------------------------------------------------------------
     // Misc
     // -------------------------------------------------------------------------
+    /**
+     * Clears the internal sprite glyph cache.
+     *
+     * MinimoJS prerenders sprite glyphs into offscreen canvases for more stable
+     * emoji rendering and better performance. In long-running sessions, you can
+     * call this to release cached glyph variants and force them to be rebuilt on
+     * the next render.
+     *
+     * This does not change any sprite state. It only clears cached render data.
+     *
+     * @example
+     * ```ts
+     * game.clearSpriteCache();
+     * ```
+     */
+    clearSpriteCache() {
+        this._spriteGlyphCache.clear();
+    }
     /**
      * Returns a pseudo-random floating-point number in the range `[0, 1)`.
      * Delegates to `Math.random()`.
@@ -1219,8 +1427,7 @@ export class Game {
      *
      * game.onCreate = () => {
      *   // Scene init
-     *   const skull = new Sprite("💀");
-     *   skull.x = 400; skull.y = 300; skull.size = 96;
+     *   const skull = new Sprite("💀", 400, 300, 96);
      *   game.add(skull);
      *   game.addTimer(3000, false, () => game.reset()); // auto-restart
      * };
@@ -1387,7 +1594,7 @@ export class Game {
     /** @internal */
     _isScreenPointOverSprite(x, y, sprite, radiusScale) {
         const safeScale = Math.max(0, radiusScale);
-        const radius = sprite.size * safeScale;
+        const radius = sprite.displaySize * safeScale;
         const drawX = sprite.ignoreScroll ? sprite.x : sprite.x - this.scrollX;
         const drawY = sprite.ignoreScroll ? sprite.y : sprite.y - this.scrollY;
         const dx = x - drawX;
@@ -1448,6 +1655,78 @@ export class Game {
         this._pointerDown = this._mouseDown;
         this._pointerPressed = this._mousePressed;
     }
+    /** @internal */
+    _assertPhysicsEnabled() {
+        if (!this.physics) {
+            throw new Error("MinimoJS: collide() and collideAny() require game.physics = true.");
+        }
+    }
+    /** @internal */
+    _getCollisionResolution(a, b) {
+        const halfA = a.displaySize / 2;
+        const halfB = b.displaySize / 2;
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const overlapX = halfA + halfB - Math.abs(dx);
+        const overlapY = halfA + halfB - Math.abs(dy);
+        if (overlapX <= 0 || overlapY <= 0) {
+            return null;
+        }
+        let axis;
+        if (overlapX < overlapY) {
+            axis = "x";
+        }
+        else if (overlapY < overlapX) {
+            axis = "y";
+        }
+        else {
+            const relVX = Math.abs(a.vx - b.vx);
+            const relVY = Math.abs(a.vy - b.vy);
+            axis = relVX > relVY ? "x" : "y";
+        }
+        const info = {
+            left: false,
+            right: false,
+            top: false,
+            bottom: false,
+            grounded: false,
+        };
+        if (axis === "x") {
+            if (dx >= 0) {
+                info.right = true;
+                return {
+                    info,
+                    axis,
+                    separationX: -overlapX,
+                    separationY: 0,
+                };
+            }
+            info.left = true;
+            return {
+                info,
+                axis,
+                separationX: overlapX,
+                separationY: 0,
+            };
+        }
+        if (dy >= 0) {
+            info.bottom = true;
+            info.grounded = true;
+            return {
+                info,
+                axis,
+                separationX: 0,
+                separationY: -overlapY,
+            };
+        }
+        info.top = true;
+        return {
+            info,
+            axis,
+            separationX: 0,
+            separationY: overlapY,
+        };
+    }
     // -------------------------------------------------------------------------
     // Private — rAF loop
     // -------------------------------------------------------------------------
@@ -1521,6 +1800,9 @@ export class Game {
     /** @internal */
     _updatePhysics(dt) {
         for (const sprite of this._sprites) {
+            if (sprite.isStatic) {
+                continue;
+            }
             if (sprite.gravityScale !== 0) {
                 sprite.vx += this.gravityX * sprite.gravityScale * dt;
                 sprite.vy += this.gravityY * sprite.gravityScale * dt;
@@ -1535,7 +1817,8 @@ export class Game {
     /** @internal */
     _getSpriteGlyphCanvas(sprite) {
         const size = Math.max(1, Math.round(sprite.size));
-        const cacheKey = `${sprite.sprite}::${size}`;
+        const color = sprite.color;
+        const cacheKey = `${sprite.sprite}::${size}::${color}`;
         const cached = this._spriteGlyphCache.get(cacheKey);
         if (cached)
             return cached;
@@ -1552,7 +1835,7 @@ export class Game {
         glyphCtx.shadowBlur = 0;
         glyphCtx.shadowOffsetX = 0;
         glyphCtx.shadowOffsetY = 0;
-        glyphCtx.fillStyle = "#ffffff";
+        glyphCtx.fillStyle = color;
         glyphCtx.font = `${size}px "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif`;
         glyphCtx.textAlign = "center";
         glyphCtx.textBaseline = "middle";
@@ -1590,8 +1873,11 @@ export class Game {
             if (sprite.rotation !== 0) {
                 ctx.rotate((sprite.rotation * Math.PI) / 180);
             }
-            if (sprite.flipX || sprite.flipY) {
-                ctx.scale(sprite.flipX ? -1 : 1, sprite.flipY ? -1 : 1);
+            const safeRenderScale = Number.isFinite(sprite.scale)
+                ? Math.max(0, sprite.scale)
+                : 1;
+            if (sprite.flipX || sprite.flipY || safeRenderScale !== 1) {
+                ctx.scale((sprite.flipX ? -1 : 1) * safeRenderScale, (sprite.flipY ? -1 : 1) * safeRenderScale);
             }
             ctx.shadowColor = "transparent";
             ctx.shadowBlur = 0;
@@ -1603,7 +1889,7 @@ export class Game {
         }
         for (const entry of this._textOverlays) {
             ctx.save();
-            ctx.font = `${entry.fontSize}px monospace`;
+            ctx.font = `${entry.fontSize}px "Press Start 2P", monospace`;
             ctx.fillStyle = entry.color;
             ctx.textAlign = entry.centered ? "center" : "left";
             ctx.textBaseline = entry.centered ? "middle" : "top";

package/package.json

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