minimojs 1.0.0-alpha.20 → 1.0.0-alpha.21

package/dist/minimo.js

@@ -23,7 +23,7 @@ import { TrailSystem } from "./internal/TrailSystem.js";
 import { TransitionSystem } from "./internal/TransitionSystem.js";
 import { TimerSystem } from "./internal/TimerSystem.js";
 // ---------------------------------------------------------------------------
-// Sprite
+// EmojiSprite
 // ---------------------------------------------------------------------------
 /**
  * Base class for all renderable MinimoJS actors.
@@ -32,7 +32,7 @@ import { TimerSystem } from "./internal/TimerSystem.js";
  * shared transform, visibility, physics, and animation state required by the
  * engine.
  */
-export class BaseSprite {
+export class Sprite {
     constructor(game = null) {
         /**
          * X position in world space (horizontal center of the sprite), in pixels.
@@ -56,16 +56,16 @@ export class BaseSprite {
         /**
          * Optional logical body width used by physics helpers and collision checks.
          *
-         * When `null` (default), MinimoJS uses the sprite's visual {@link BaseSprite.width}.
-         * When set, this value is scaled by {@link BaseSprite.scale} the same way as the
+         * When `null` (default), MinimoJS uses the sprite's visual {@link Sprite.width}.
+         * When set, this value is scaled by {@link Sprite.scale} the same way as the
          * visual sprite size.
          */
         this.bodyWidth = null;
         /**
          * Optional logical body height used by physics helpers and collision checks.
          *
-         * When `null` (default), MinimoJS uses the sprite's visual {@link BaseSprite.height}.
-         * When set, this value is scaled by {@link BaseSprite.scale} the same way as the
+         * When `null` (default), MinimoJS uses the sprite's visual {@link Sprite.height}.
+         * When set, this value is scaled by {@link Sprite.scale} the same way as the
          * visual sprite size.
          */
         this.bodyHeight = null;
@@ -168,6 +168,17 @@ export class BaseSprite {
          * Values > 1 amplify gravity; negative values invert it.
          */
         this.gravityScale = 0;
+        // `abstract` and `protected` are erased by the TypeScript compiler, and games
+        // are written in JavaScript, so nothing but this check stops old code from
+        // calling `new Sprite(glyph, x, y, size)`. Without it the glyph would be
+        // stored as this sprite's game reference, the position and size would be
+        // discarded, and the failure would surface one call later inside `Game.add`
+        // as an unrelated "attached to multiple Game instances" error.
+        if (new.target === Sprite) {
+            throw new Error("MinimoJS: Sprite is an abstract type and cannot be constructed directly. " +
+                "Use EmojiSprite for an emoji, ImageSprite for a preloaded image, " +
+                "TextSprite for text, or DrawSprite for procedural drawing.");
+        }
         this._game = game;
     }
     /**
@@ -210,7 +221,7 @@ export class BaseSprite {
         return this.height * Math.max(0, safeScale);
     }
     /**
-     * Effective collision-body width in pixels after applying {@link BaseSprite.scale}.
+     * Effective collision-body width in pixels after applying {@link Sprite.scale}.
      */
     get bodyDisplayWidth() {
         const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
@@ -222,7 +233,7 @@ export class BaseSprite {
         return baseWidth * Math.max(0, safeScale);
     }
     /**
-     * Effective collision-body height in pixels after applying {@link BaseSprite.scale}.
+     * Effective collision-body height in pixels after applying {@link Sprite.scale}.
      */
     get bodyDisplayHeight() {
         const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
@@ -268,11 +279,11 @@ export class BaseSprite {
  *
  * @example
  * ```ts
- * const coin = new Sprite("🪙", 300, 200, 32);
+ * const coin = new EmojiSprite("🪙", 300, 200, 32);
  * game.add(coin);
  * ```
  */
-export class Sprite extends BaseSprite {
+export class EmojiSprite extends Sprite {
     get size() {
         return this._size;
     }
@@ -286,7 +297,7 @@ export class Sprite extends BaseSprite {
         return this.displayWidth;
     }
     /**
-     * Creates a new Sprite with the given emoji, optional position, and base size.
+     * Creates a new EmojiSprite 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.
@@ -298,7 +309,7 @@ export class Sprite extends BaseSprite {
      *
      * @example
      * ```ts
-     * const enemy = new Sprite("👾", 200, 100, 40);
+     * const enemy = new EmojiSprite("👾", 200, 100, 40);
      * game.add(enemy);
      * ```
      */
@@ -318,25 +329,29 @@ export class Sprite extends BaseSprite {
  * A renderable sprite backed by a preloaded image asset.
  *
  * Width and height are always resolved from the current texture. To resize the
- * sprite visually, use {@link BaseSprite.scale}.
+ * sprite visually, use {@link Sprite.scale}.
  */
-export class ImageSprite extends BaseSprite {
+export class ImageSprite extends Sprite {
     get imageKey() {
         return this._imageKey;
     }
     get width() {
         const image = this.getResolvedImage();
-        return image.naturalWidth || image.width;
+        return image instanceof HTMLImageElement
+            ? image.naturalWidth || image.width
+            : image.width;
     }
     get height() {
         const image = this.getResolvedImage();
-        return image.naturalHeight || image.height;
+        return image instanceof HTMLImageElement
+            ? image.naturalHeight || image.height
+            : image.height;
     }
     /**
      * Creates a new image-backed sprite.
      *
      * @param game - Game instance used to resolve the texture key.
-     * @param imageKey - Preloaded image key previously registered with {@link Game.loadImage}.
+     * @param imageKey - Texture key previously registered with {@link Game.loadImage} or {@link Game.createTexture}.
      * @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`.
      */
@@ -349,7 +364,7 @@ export class ImageSprite extends BaseSprite {
     /**
      * Replaces the current texture with another preloaded image.
      *
-     * @param imageKey - New preloaded image key to render.
+     * @param imageKey - New texture key to render.
      */
     setTexture(imageKey) {
         if (imageKey === this._imageKey)
@@ -359,11 +374,14 @@ export class ImageSprite extends BaseSprite {
     }
     getRenderCacheKey() {
         const image = this.getResolvedImage();
+        const width = image instanceof HTMLImageElement ? image.naturalWidth || image.width : image.width;
+        const height = image instanceof HTMLImageElement ? image.naturalHeight || image.height : image.height;
         return [
             "image",
             this._imageKey,
-            image.naturalWidth || image.width,
-            image.naturalHeight || image.height,
+            this.game?.getImageVersion(this._imageKey) ?? 0,
+            width,
+            height,
         ].join("|");
     }
     /** @internal */
@@ -394,7 +412,7 @@ export class ImageSprite extends BaseSprite {
  *
  * Treat `DrawSprite` as a specialized tool, not the default sprite type.
  * Because it may execute custom Canvas 2D drawing code repeatedly, overusing it
- * can affect game performance much more than regular {@link Sprite},
+ * can affect game performance much more than regular {@link EmojiSprite},
  * {@link ImageSprite}, or {@link TextSprite} instances.
  *
  * Prefer the other sprite types whenever they can express the same result more
@@ -432,7 +450,7 @@ export class ImageSprite extends BaseSprite {
  * Override {@link DrawSprite.redraw} in a subclass, or assign your own method
  * on an instance if you prefer an inline style in JavaScript.
  */
-export class DrawSprite extends BaseSprite {
+export class DrawSprite extends Sprite {
     get width() {
         return this._width;
     }
@@ -500,11 +518,11 @@ DrawSprite._nextSurfaceId = 1;
  * layout features such as wrapping, fixed button sizes, background/border, or
  * text stroke.
  *
- * For controls that are only a single emoji, prefer {@link Sprite}. Emoji-only
+ * For controls that are only a single emoji, prefer {@link EmojiSprite}. Emoji-only
  * buttons usually behave better as sprites because they do not need text
  * padding/layout and their bounds match the rendered emoji more directly.
  */
-export class TextSprite extends BaseSprite {
+export class TextSprite extends Sprite {
     get width() {
         this.ensureMeasured();
         return this._measuredWidth;
@@ -752,8 +770,9 @@ TextSprite._measurementContext = null;
  * `x` / `y` use **top-left screen-space coordinates**, unlike {@link Sprite},
  * which uses center-based world space.
  *
- * The image referenced by {@link BackgroundLayer.imageKey} must be registered
- * with {@link Game.loadImage} during {@link Game.onPreload}.
+ * The texture referenced by {@link BackgroundLayer.imageKey} must be registered
+ * with {@link Game.loadImage} during {@link Game.onPreload}, or created
+ * dynamically with {@link Game.createTexture}.
  *
  * @example
  * ```ts
@@ -824,21 +843,21 @@ export class BackgroundLayer {
  * You must import it with standard ESM syntax such as:
  *
  * ```ts
- * import { Game, Sprite } from "minimojs";
+ * import { Game, EmojiSprite } from "minimojs";
  * ```
  *
  * In the browser, use it from a module script:
  *
  * ```html
  * <script type="module">
- *   import { Game, Sprite } from "./dist/minimo.js";
+ *   import { Game, EmojiSprite } from "./dist/minimo.js";
  * </script>
  * ```
  *
  * Or from a CDN:
  *
  * ```ts
- * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
+ * import { Game, EmojiSprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  * ```
  *
  * Do NOT use a classic `<script>` tag without `type="module"`.
@@ -887,12 +906,19 @@ export class BackgroundLayer {
  * ## Quick Start
  *
  * ```ts
- * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
+ * import { Game, ImageSprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  *
  * const game = new Game(720, 1280);
  *
- * const player = new Sprite("🐢", 400, 500, 48);
- * game.add(player);
+ * game.onPreload = () => {
+ *   game.loadImage("player", "assets/player.png");
+ * };
+ *
+ * let player: ImageSprite;
+ *
+ * game.onCreate = () => {
+ *   player = game.add(new ImageSprite(game, "player", 400, 500));
+ * };
  *
  * game.onUpdate = (dt) => {
  *   if (game.isKeyDown("ArrowLeft"))  player.vx = -200;
@@ -905,6 +931,13 @@ export class BackgroundLayer {
  * game.start();
  * ```
  *
+ * Prototyping, and have no art yet? Swap the texture for an emoji and drop the
+ * preload entirely — everything else stays the same:
+ *
+ * ```ts
+ * const player = game.add(new EmojiSprite("🐢", 400, 500, 48));
+ * ```
+ *
  * ---
  *
  * ## Engine Philosophy
@@ -930,13 +963,28 @@ export class BackgroundLayer {
  *
  * ---
  *
- * ## Emoji-Only Sprites
- *
- * Every sprite MUST use a single emoji character as its visual representation.
- * PNG, SVG, spritesheet, and image sprites are NOT supported.
- * Use Unicode emoji: `"🔥"`, `"⭐"`, `"💣"`, `"🐢"`, `"👾"`, `"🧱"`, etc.
- * AI agents can also use text-like emojis (regional indicators, symbols, letters)
- * to build fun title art, HUD labels, and expressive in-game text.
+ * ## Choosing a Visual Source
+ *
+ * A sprite's look comes from one of four concrete types, all of which extend the
+ * shared abstract {@link Sprite} type. Use `Sprite` as the type in your own
+ * signatures; never construct it directly.
+ *
+ * 1. {@link ImageSprite} — the game's own images, and the first option to reach
+ *    for. Register a texture with {@link Game.loadImage} inside
+ *    {@link Game.onPreload}, or build one at runtime with
+ *    {@link Game.createTexture}, then render it with
+ *    `new ImageSprite(game, key, x, y)`. An image looks identical on every
+ *    device and belongs to the game.
+ * 2. {@link EmojiSprite} — a single Unicode emoji, and the shortest path to a
+ *    first prototype: `new EmojiSprite("🐢", x, y, size)`. Note that an
+ *    emoji is drawn with the player's own system emoji font, so the same game
+ *    looks different across iOS, Android, and Windows, and a glyph the platform
+ *    lacks renders as an empty box. Prefer an image whenever the look matters.
+ * 3. {@link TextSprite} — text, labels, and buttons.
+ * 4. {@link DrawSprite} — procedural Canvas 2D drawing, for shapes and gauges
+ *    the other three cannot express cleanly.
+ *
+ * Emoji and images mix freely in one game.
  *
  * ---
  *
@@ -1025,7 +1073,7 @@ export class BackgroundLayer {
  * ```ts
  * class SkullScene implements IScene {
  *   onCreate() {
- *     const skull = new Sprite("💀", 400, 300, 96);
+ *     const skull = new EmojiSprite("💀", 400, 300, 96);
  *     game.add(skull);
  *   }
  *
@@ -1045,7 +1093,7 @@ export class BackgroundLayer {
  *
  * ---
  *
- * ## Sprite Lifecycle Ownership
+ * ## EmojiSprite Lifecycle Ownership
  *
  * The `Game` instance owns all sprites.
  * - Create sprites with {@link Game.add}.
@@ -1137,7 +1185,7 @@ export class Game {
      * @example
      * ```ts
      * game.onCreate = () => {
-     *   const player = new Sprite("🐢");
+     *   const player = new EmojiSprite("🐢");
      *   player.x = 200;
      *   player.y = 300;
      *   game.add(player);
@@ -1367,10 +1415,10 @@ export class Game {
         return this._inputSystem.pointerY;
     }
     // -------------------------------------------------------------------------
-    // Sprite management
+    // EmojiSprite management
     // -------------------------------------------------------------------------
     /**
-     * Registers a {@link BaseSprite} (or subclass instance) with the engine.
+     * Registers a {@link Sprite} (or subclass instance) with the engine.
      *
      * After calling `add`, the sprite is rendered and, if dynamic
      * (`isStatic = false`), receives built-in velocity/gravity integration every
@@ -1379,21 +1427,21 @@ export class Game {
      * **Ownership:** The game instance takes ownership of the sprite from this
      * point forward. It will appear in {@link Game.getSprites} on the same frame.
      *
-     * **Subclasses:** Any class that extends {@link BaseSprite} can be passed here.
+     * **Subclasses:** Any class that extends {@link Sprite} can be passed here.
      * The engine stores and processes it as a live sprite; your custom properties
      * are preserved on the instance.
      *
-     * @param sprite - A {@link BaseSprite} instance (or subclass) to add.
+     * @param sprite - A {@link Sprite} instance (or subclass) to add.
      * @returns The same sprite instance, for chaining or inline assignment.
      *
      * @example
      * ```ts
      * // Plain sprite
-     * const coin = new Sprite("🪙", 300, 200, 32);
+     * const coin = new EmojiSprite("🪙", 300, 200, 32);
      * game.add(coin);
      *
      * // Custom subclass
-     * class Enemy extends Sprite {
+     * class Enemy extends EmojiSprite {
      *   speed = 150;
      *   constructor(x: number, y: number) {
      *     super("👾", x, y, 40);
@@ -1508,14 +1556,47 @@ export class Game {
         this._assetSystem.queueImage(key, src);
     }
     /**
-     * Returns a loaded image previously registered with {@link Game.loadImage},
-     * or `undefined` if it is not available.
+     * Creates a dynamic texture immediately and registers it under a stable key.
+     *
+     * Unlike {@link Game.loadImage}, this does not require {@link Game.onPreload}.
+     * The `painter` callback receives a fresh offscreen canvas and should draw the
+     * full texture contents into it.
+     *
+     * The resulting texture can be used anywhere a normal image key is accepted,
+     * including {@link ImageSprite}, background layers, and optional modules.
+     *
+     * @param key - Stable texture key used later by sprites and render helpers.
+     * @param width - Texture width in pixels. Minimum `1`.
+     * @param height - Texture height in pixels. Minimum `1`.
+     * @param painter - Function that paints into the offscreen texture canvas.
+     *
+     * @example
+     * ```ts
+     * game.createTexture("checkpoint", 128, 64, (ctx, canvas) => {
+     *   ctx.fillStyle = "#101820";
+     *   ctx.fillRect(0, 0, canvas.width, canvas.height);
+     *   ctx.fillStyle = "#ffd54f";
+     *   ctx.fillRect(8, 8, canvas.width - 16, canvas.height - 16);
+     * });
+     * ```
+     */
+    createTexture(key, width, height, painter) {
+        return this._assetSystem.createTexture(key, width, height, painter);
+    }
+    /**
+     * Returns a loaded image or created texture previously registered with
+     * {@link Game.loadImage} or {@link Game.createTexture}, or `undefined` if it
+     * is not available.
      */
     getImage(key) {
         return this._assetSystem.getImage(key);
     }
+    /** @internal */
+    getImageVersion(key) {
+        return this._assetSystem.getImageVersion(key);
+    }
     /**
-     * Returns `true` if an image key has completed loading.
+     * Returns `true` if a texture key is available.
      */
     hasImage(key) {
         return this._assetSystem.hasImage(key);
@@ -1557,7 +1638,7 @@ export class Game {
      *
      * @param listA - First group of sprites.
      * @param listB - Second group of sprites. May share sprites with `listA`.
-     * @returns A `[Sprite, Sprite]` tuple of the first overlapping pair,
+     * @returns A `[EmojiSprite, EmojiSprite]` tuple of the first overlapping pair,
      *   or `null` if no pair overlaps.
      *
      * @example
@@ -1613,7 +1694,7 @@ export class Game {
      *
      * @param listA - First group of sprites.
      * @param listB - Second group of sprites.
-     * @returns A `[Sprite, Sprite, CollisionInfo]` tuple for the first collision found,
+     * @returns A `[EmojiSprite, EmojiSprite, CollisionInfo]` tuple for the first collision found,
      *   or `null` if no pair overlaps.
      * @throws Error if the game's physics helpers are not enabled.
      *
@@ -1939,7 +2020,7 @@ export class Game {
      * normalized pivot point.
      *
      * This affects rendering only. Physics and collision bounds continue to use
-     * {@link Sprite.displaySize} and ignore the deform result.
+     * {@link EmojiSprite.displaySize} and ignore the deform result.
      *
      * `pivotX` / `pivotY` are normalized anchors in the sprite's square display box:
      * - `0` = left/top
@@ -2347,7 +2428,7 @@ export class Game {
      * bounds, hit testing, fixed sizes, backgrounds, borders, or text stroke.
      * `drawText()` is the lightweight overlay API, not the primary UI API.
      *
-     * For controls that are only a single emoji, prefer {@link Sprite} over
+     * For controls that are only a single emoji, prefer {@link EmojiSprite} over
      * {@link TextSprite}. Emoji-only buttons do not benefit from text padding and
      * usually fit more naturally in the sprite pipeline.
      *
@@ -2483,7 +2564,7 @@ export class Game {
      * ```ts
      * class GameOverScene {
      *   onCreate() {
-     *     const skull = new Sprite("💀", 400, 300, 96);
+     *     const skull = new EmojiSprite("💀", 400, 300, 96);
      *     game.add(skull);
      *     game.addTimer(3000, false, () => game.reset());
      *   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.20",
-  "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Emoji-only sprites, rAF loop, TypeScript-first, LLM-friendly.",
+  "version": "1.0.0-alpha.21",
+  "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",
   "types": "dist/minimo.d.ts",
@@ -28,6 +28,7 @@
     "engine",
     "2d",
     "canvas",
+    "sprites",
     "emoji",
     "minimal",
     "typescript"