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

package/dist/minimo.d.ts

@@ -205,7 +205,7 @@ export interface IScene {
  * shared transform, visibility, physics, and animation state required by the
  * engine.
  */
-export declare abstract class BaseSprite {
+export declare abstract class Sprite {
     protected constructor(game?: Game | null);
     /**
      * Game instance associated with this sprite, if any.
@@ -237,11 +237,11 @@ export declare abstract class BaseSprite {
      */
     scale: number;
     /**
-     * Base logical width in pixels before applying {@link BaseSprite.scale}.
+     * Base logical width in pixels before applying {@link Sprite.scale}.
      */
     abstract get width(): number;
     /**
-     * Base logical height in pixels before applying {@link BaseSprite.scale}.
+     * Base logical height in pixels before applying {@link Sprite.scale}.
      */
     abstract get height(): number;
     /**
@@ -255,16 +255,16 @@ export declare abstract 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.
      */
     bodyWidth: number | 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.
      */
     bodyHeight: number | null;
@@ -283,11 +283,11 @@ export declare abstract class BaseSprite {
      */
     bodyOffsetY: number;
     /**
-     * Effective collision-body width in pixels after applying {@link BaseSprite.scale}.
+     * Effective collision-body width in pixels after applying {@link Sprite.scale}.
      */
     get bodyDisplayWidth(): number;
     /**
-     * Effective collision-body height in pixels after applying {@link BaseSprite.scale}.
+     * Effective collision-body height in pixels after applying {@link Sprite.scale}.
      */
     get bodyDisplayHeight(): number;
     /**
@@ -406,11 +406,11 @@ export declare abstract class BaseSprite {
  *
  * @example
  * ```ts
- * const coin = new Sprite("🪙", 300, 200, 32);
+ * const coin = new EmojiSprite("🪙", 300, 200, 32);
  * game.add(coin);
  * ```
  */
-export declare class Sprite extends BaseSprite {
+export declare class EmojiSprite extends Sprite {
     /**
      * The emoji character used to render this sprite.
      * Must be a single emoji. Change this at runtime to animate between frames.
@@ -422,7 +422,7 @@ export declare class Sprite extends BaseSprite {
     get height(): number;
     get displaySize(): number;
     /**
-     * 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.
@@ -434,7 +434,7 @@ export declare class Sprite extends BaseSprite {
      *
      * @example
      * ```ts
-     * const enemy = new Sprite("👾", 200, 100, 40);
+     * const enemy = new EmojiSprite("👾", 200, 100, 40);
      * game.add(enemy);
      * ```
      */
@@ -445,9 +445,9 @@ export declare 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 declare class ImageSprite extends BaseSprite {
+export declare class ImageSprite extends Sprite {
     get imageKey(): string;
     get width(): number;
     get height(): number;
@@ -455,7 +455,7 @@ export declare class ImageSprite extends BaseSprite {
      * 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`.
      */
@@ -463,7 +463,7 @@ export declare 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: string): void;
     getRenderCacheKey(): string;
@@ -477,7 +477,7 @@ export declare 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
@@ -515,7 +515,7 @@ export declare 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 declare class DrawSprite extends BaseSprite {
+export declare class DrawSprite extends Sprite {
     /**
      * When `false` (default), MinimoJS clears this sprite's internal canvas and
      * calls {@link DrawSprite.redraw} on every render pass.
@@ -562,11 +562,11 @@ export declare class DrawSprite extends BaseSprite {
  * 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 declare class TextSprite extends BaseSprite {
+export declare class TextSprite extends Sprite {
     anchorX: "left" | "center" | "right";
     anchorY: "top" | "middle" | "bottom";
     text: string;
@@ -631,8 +631,9 @@ export type FontRequirementOptions = {
  * `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
@@ -769,21 +770,21 @@ export interface CollisionInfo {
  * 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"`.
@@ -832,12 +833,19 @@ export interface CollisionInfo {
  * ## 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;
@@ -850,6 +858,13 @@ export interface CollisionInfo {
  * 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
@@ -875,13 +890,28 @@ export interface CollisionInfo {
  *
  * ---
  *
- * ## 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.
  *
  * ---
  *
@@ -970,7 +1000,7 @@ export interface CollisionInfo {
  * ```ts
  * class SkullScene implements IScene {
  *   onCreate() {
- *     const skull = new Sprite("💀", 400, 300, 96);
+ *     const skull = new EmojiSprite("💀", 400, 300, 96);
  *     game.add(skull);
  *   }
  *
@@ -990,7 +1020,7 @@ export interface CollisionInfo {
  *
  * ---
  *
- * ## Sprite Lifecycle Ownership
+ * ## EmojiSprite Lifecycle Ownership
  *
  * The `Game` instance owns all sprites.
  * - Create sprites with {@link Game.add}.
@@ -1158,7 +1188,7 @@ export declare class Game {
      * @example
      * ```ts
      * game.onCreate = () => {
-     *   const player = new Sprite("🐢");
+     *   const player = new EmojiSprite("🐢");
      *   player.x = 200;
      *   player.y = 300;
      *   game.add(player);
@@ -1236,7 +1266,7 @@ export declare class Game {
      */
     get pointerY(): number;
     /**
-     * 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
@@ -1245,21 +1275,21 @@ export declare 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);
@@ -1268,7 +1298,7 @@ export declare class Game {
      * const enemy = game.add(new Enemy(600, 100));
      * ```
      */
-    add<T extends BaseSprite>(sprite: T): T;
+    add<T extends Sprite>(sprite: T): T;
     /**
      * Registers a {@link BackgroundLayer} with the engine.
      *
@@ -1302,7 +1332,7 @@ export declare class Game {
      * game.destroySprite(enemy); // remove enemy from game
      * ```
      */
-    destroySprite(sprite: BaseSprite): void;
+    destroySprite(sprite: Sprite): void;
     /**
      * Removes a background layer from the engine.
      *
@@ -1326,7 +1356,7 @@ export declare class Game {
      * const enemies = game.getSprites().filter(s => s.sprite === "👾");
      * ```
      */
-    getSprites(): readonly BaseSprite[];
+    getSprites(): readonly Sprite[];
     /**
      * Returns a read-only snapshot of all active background layers.
      *
@@ -1353,12 +1383,39 @@ export declare class Game {
      */
     loadImage(key: string, src: string): void;
     /**
-     * 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: string, width: number, height: number, painter: (ctx: CanvasRenderingContext2D, canvas: HTMLCanvasElement) => void): HTMLCanvasElement;
+    /**
+     * 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: string): HTMLImageElement | undefined;
+    getImage(key: string): HTMLImageElement | HTMLCanvasElement | undefined;
     /**
-     * Returns `true` if an image key has completed loading.
+     * Returns `true` if a texture key is available.
      */
     hasImage(key: string): boolean;
     /**
@@ -1382,7 +1439,7 @@ export declare class Game {
      * }
      * ```
      */
-    overlap(a: BaseSprite, b: BaseSprite): boolean;
+    overlap(a: Sprite, b: Sprite): boolean;
     /**
      * Tests for any overlap between two groups of sprites.
      * Performs an O(n × m) AABB check for every pair `(a, b)` where `a ∈ listA`
@@ -1393,7 +1450,7 @@ export declare 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
@@ -1406,7 +1463,7 @@ export declare class Game {
      * }
      * ```
      */
-    overlapAny(listA: BaseSprite[], listB: BaseSprite[]): [BaseSprite, BaseSprite] | null;
+    overlapAny(listA: Sprite[], listB: Sprite[]): [Sprite, Sprite] | null;
     /**
      * Tests and resolves a basic AABB collision between two sprites.
      *
@@ -1435,7 +1492,7 @@ export declare class Game {
      * }
      * ```
      */
-    collide(a: BaseSprite, b: BaseSprite): CollisionInfo | null;
+    collide(a: Sprite, b: Sprite): CollisionInfo | null;
     /**
      * Tests and resolves the first collision found between two groups of sprites.
      *
@@ -1445,7 +1502,7 @@ export declare 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.
      *
@@ -1457,7 +1514,7 @@ export declare class Game {
      * }
      * ```
      */
-    collideAny(listA: BaseSprite[], listB: BaseSprite[]): [BaseSprite, BaseSprite, CollisionInfo] | null;
+    collideAny(listA: Sprite[], listB: Sprite[]): [Sprite, Sprite, CollisionInfo] | null;
     /**
      * Returns `true` while the specified key is held down (every frame it is held).
      * Use this for continuous actions like movement.
@@ -1545,7 +1602,7 @@ export declare class Game {
      * }
      * ```
      */
-    isPointerDownOverSprite(sprite: BaseSprite | null | undefined): boolean;
+    isPointerDownOverSprite(sprite: Sprite | null | undefined): boolean;
     /**
      * Returns `true` only on the frame any pointer first pressed over the target
      * sprite. Works with both mouse input and multiple simultaneous touches.
@@ -1569,7 +1626,7 @@ export declare class Game {
      * }
      * ```
      */
-    isPointerPressedOverSprite(sprite: BaseSprite | null | undefined): boolean;
+    isPointerPressedOverSprite(sprite: Sprite | null | undefined): boolean;
     /**
      * Returns a read-only snapshot of all currently active pointers.
      *
@@ -1618,7 +1675,7 @@ export declare class Game {
      * }
      * ```
      */
-    getPointersOverSprite(sprite: BaseSprite | null | undefined): readonly PointerInfo[];
+    getPointersOverSprite(sprite: Sprite | null | undefined): readonly PointerInfo[];
     /**
      * Returns `true` when the current device appears to be mobile/touch-first.
      *
@@ -1698,7 +1755,7 @@ export declare class Game {
      * game.animateAlpha(coin, 0, 1000, () => game.destroySprite(coin));
      * ```
      */
-    animateAlpha(sprite: BaseSprite, to: number, durationMs: number, onComplete?: () => void): void;
+    animateAlpha(sprite: Sprite, to: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Animates a sprite's {@link Sprite.rotation} from its current value to `to`
      * (in degrees) over `durationMs` milliseconds using **linear interpolation**.
@@ -1725,13 +1782,13 @@ export declare class Game {
      * });
      * ```
      */
-    animateRotation(sprite: BaseSprite, to: number, durationMs: number, onComplete?: () => void): void;
+    animateRotation(sprite: Sprite, to: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Animates a sprite's visual deformation using non-uniform scaling around a
      * 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
@@ -1759,7 +1816,7 @@ export declare class Game {
      * });
      * ```
      */
-    animateDeform(sprite: BaseSprite, toScaleX: number, toScaleY: number, pivotX: number, pivotY: number, durationMs: number, onComplete?: () => void): void;
+    animateDeform(sprite: Sprite, toScaleX: number, toScaleY: number, pivotX: number, pivotY: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Convenience helper that squashes a sprite around its horizontal center.
      *
@@ -1771,7 +1828,7 @@ export declare class Game {
      * @param durationMs - Duration of the animation in **milliseconds**.
      * @param onComplete - Optional callback invoked when the animation finishes.
      */
-    animateSquash(sprite: BaseSprite, pivotY: number, durationMs: number, onComplete?: () => void): void;
+    animateSquash(sprite: Sprite, pivotY: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Convenience helper that stretches a sprite around its horizontal center.
      *
@@ -1783,7 +1840,7 @@ export declare class Game {
      * @param durationMs - Duration of the animation in **milliseconds**.
      * @param onComplete - Optional callback invoked when the animation finishes.
      */
-    animateStretch(sprite: BaseSprite, pivotY: number, durationMs: number, onComplete?: () => void): void;
+    animateStretch(sprite: Sprite, pivotY: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Convenience helper that applies a centered uniform scale pulse and then
      * returns the sprite to its neutral shape.
@@ -1801,7 +1858,7 @@ export declare class Game {
      * game.animatePulse(coin, 1.25, 220);
      * ```
      */
-    animatePulse(sprite: BaseSprite, scale: number, durationMs: number, onComplete?: () => void): void;
+    animatePulse(sprite: Sprite, scale: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Applies a decaying screen-space shake to a sprite without changing its
      * logical position.
@@ -1819,7 +1876,7 @@ export declare class Game {
      * game.animateShake(player, 18, 300);
      * ```
      */
-    animateShake(sprite: BaseSprite, intensity: number, durationMs: number, onComplete?: () => void): void;
+    animateShake(sprite: Sprite, intensity: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Moves a sprite upward and back down to its starting position along a simple
      * parabolic arc.
@@ -1837,7 +1894,7 @@ export declare class Game {
      * game.animateBounce(ball, 120, 600);
      * ```
      */
-    animateBounce(sprite: BaseSprite, height: number, durationMs: number, onComplete?: () => void): void;
+    animateBounce(sprite: Sprite, height: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Moves a sprite upward and back down with a smooth sine-shaped float motion.
      *
@@ -1854,7 +1911,7 @@ export declare class Game {
      * game.animateFloat(balloon, 90, 1200);
      * ```
      */
-    animateFloat(sprite: BaseSprite, distance: number, durationMs: number, onComplete?: () => void): void;
+    animateFloat(sprite: Sprite, distance: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Toggles a sprite's rendered opacity on and off a fixed number of times.
      *
@@ -1871,7 +1928,7 @@ export declare class Game {
      * game.animateBlink(player, 4, 700);
      * ```
      */
-    animateBlink(sprite: BaseSprite, times: number, durationMs: number, onComplete?: () => void): void;
+    animateBlink(sprite: Sprite, times: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Applies a rapid irregular alpha variation to create a damaged, unstable, or
      * ghost-like flicker.
@@ -1888,7 +1945,7 @@ export declare class Game {
      * game.animateFlicker(ghost, 900);
      * ```
      */
-    animateFlicker(sprite: BaseSprite, durationMs: number, onComplete?: () => void): void;
+    animateFlicker(sprite: Sprite, durationMs: number, onComplete?: () => void): void;
     /**
      * Moves a sprite from its current position to a target position along a
      * parabolic arc.
@@ -1908,7 +1965,7 @@ export declare class Game {
      * game.animateArc(coin, player.x, player.y, 80, 420);
      * ```
      */
-    animateArc(sprite: BaseSprite, toX: number, toY: number, arcHeight: number, durationMs: number, onComplete?: () => void): void;
+    animateArc(sprite: Sprite, toX: number, toY: number, arcHeight: number, durationMs: number, onComplete?: () => void): void;
     /**
      * Emits temporary afterimages from a sprite to create a motion trail.
      *
@@ -1924,7 +1981,7 @@ export declare class Game {
      * game.animateTrail(player, { durationMs: 300, spacingMs: 30, fadeMs: 180 });
      * ```
      */
-    animateTrail(sprite: BaseSprite, options?: TrailOptions, onComplete?: () => void): void;
+    animateTrail(sprite: Sprite, options?: TrailOptions, onComplete?: () => void): void;
     /**
      * Breaks a sprite into visual pieces that burst outward from its current
      * rendered appearance.
@@ -1945,7 +2002,7 @@ export declare class Game {
      * game.animateExplode(enemy, { rows: 4, cols: 4, durationMs: 650, speed: 320 });
      * ```
      */
-    animateExplode(sprite: BaseSprite, options?: ExplodeOptions, onComplete?: () => void): void;
+    animateExplode(sprite: Sprite, options?: ExplodeOptions, onComplete?: () => void): void;
     /**
      * Spawns visual pieces around a sprite and converges them back into its
      * current rendered appearance.
@@ -1960,7 +2017,7 @@ export declare class Game {
      * @param options - Optional assembly tuning values.
      * @param onComplete - Optional callback invoked when the effect finishes.
      */
-    animateAssemble(sprite: BaseSprite, options?: AssembleOptions, onComplete?: () => void): void;
+    animateAssemble(sprite: Sprite, options?: AssembleOptions, onComplete?: () => void): void;
     /**
      * Breaks a sprite apart locally inside its own bounds using a directional
      * dissolve sweep.
@@ -1975,7 +2032,7 @@ export declare class Game {
      * @param options - Optional disintegration tuning values.
      * @param onComplete - Optional callback invoked when the effect finishes.
      */
-    animateDisintegrate(sprite: BaseSprite, options?: DisintegrateOptions, onComplete?: () => void): void;
+    animateDisintegrate(sprite: Sprite, options?: DisintegrateOptions, onComplete?: () => void): void;
     /**
      * Reconstructs a sprite locally inside its own bounds using a directional
      * integration sweep.
@@ -1990,7 +2047,7 @@ export declare class Game {
      * @param options - Optional integration tuning values.
      * @param onComplete - Optional callback invoked when the effect finishes.
      */
-    animateIntegrate(sprite: BaseSprite, options?: IntegrateOptions, onComplete?: () => void): void;
+    animateIntegrate(sprite: Sprite, options?: IntegrateOptions, onComplete?: () => void): void;
     /**
      * Reveals or covers a sprite with a directional wipe mask.
      *
@@ -2008,7 +2065,7 @@ export declare class Game {
      * @param options - Optional wipe tuning values.
      * @param onComplete - Optional callback invoked when the effect finishes.
      */
-    animateWipe(sprite: BaseSprite, options?: WipeOptions, onComplete?: () => void): void;
+    animateWipe(sprite: Sprite, 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
@@ -2078,7 +2135,7 @@ export declare 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.
      *
@@ -2185,7 +2242,7 @@ export declare 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());
      *   }