minimojs 1.0.0-alpha.3 → 1.0.0-alpha.31

package/dist/minimo.d.ts

@@ -7,54 +7,253 @@
  * ALL ROTATIONS ARE IN DEGREES.
  * THE ENGINE LOOP USES requestAnimationFrame ONLY.
  */
+import { SoundPlayback } from "./internal/SoundSystem.js";
+import type { PlaySoundOptions } from "./internal/SoundSystem.js";
+import type { DesignObject } from "./minimo-format.js";
+export { Design, parseAssetFile } from "./minimo-format.js";
+export { SoundPlayback } from "./internal/SoundSystem.js";
+export type { PlaySoundOptions, SoundPlaybackState } from "./internal/SoundSystem.js";
+export type { AssetFile, DesignBackground, DesignEmoji, DesignFile, DesignImage, DesignObject, DesignObjectBase, DesignObjectType, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
 /**
- * A 2D game object rendered as an emoji on the canvas.
+ * Optional tuning values for {@link Game.animateExplode}.
  *
- * Instantiate directly or extend to create custom sprite types.
- * Register with the engine by passing the instance to {@link Game.add}.
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface ExplodeOptions {
+    /** Number of vertical slices used to break the sprite apart. */
+    rows?: number;
+    /** Number of horizontal slices used to break the sprite apart. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Initial outward velocity magnitude in pixels per second. */
+    speed?: number;
+    /** Downward acceleration applied to pieces in pixels per second squared. */
+    gravityY?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade out as the effect approaches completion. */
+    fade?: boolean;
+    /** Whether the original sprite is destroyed instead of restored after the effect. */
+    destroySprite?: boolean;
+}
+/**
+ * Cardinal flow direction used by directional visual effects.
+ */
+export type FlowDirection = "left-to-right" | "right-to-left" | "top-to-bottom" | "bottom-to-top";
+/**
+ * Direction used by piece-based local integration and disintegration effects.
  *
- * **Coordinate system:** center-based world space. `(x, y)` is the center of
- * the sprite. Positive X = right, positive Y = down.
+ * - Cardinal values apply a directional sweep across the sprite.
+ * - `"in-place"` keeps pieces in their final positions and only randomizes
+ *   when each piece appears or disappears.
+ */
+export type PieceFlowDirection = FlowDirection | "in-place";
+/**
+ * Optional tuning values for {@link Game.animateAssemble}.
  *
- * **Lifecycle:** A sprite exists until {@link Game.destroySprite} is called or
- * {@link Game.reset} is invoked. After destruction, do not read or write its fields.
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface AssembleOptions {
+    /** Number of vertical slices used to reconstruct the sprite. */
+    rows?: number;
+    /** Number of horizontal slices used to reconstruct the sprite. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Initial outward distance magnitude in pixels per second equivalent. */
+    speed?: number;
+    /** Downward pull applied while pieces converge, in pixels per second squared. */
+    gravityY?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade in while assembling. */
+    fade?: boolean;
+}
+/**
+ * Optional tuning values for {@link Game.animateDisintegrate}.
  *
- * @example
- * ```ts
- * // Direct instantiation
- * const coin = new Sprite("🪙");
- * coin.x = 300;
- * coin.y = 200;
- * coin.size = 32;
- * game.add(coin);
- * ```
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface DisintegrateOptions {
+    /** Number of vertical slices used to dissolve the sprite. */
+    rows?: number;
+    /** Number of horizontal slices used to dissolve the sprite. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Primary sweep direction across the sprite. */
+    direction?: PieceFlowDirection;
+    /** Maximum local travel distance in pixels for each piece. */
+    distance?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade out as they disintegrate. */
+    fade?: boolean;
+    /** Whether the original sprite is destroyed instead of left hidden after the effect. */
+    destroySprite?: boolean;
+}
+/**
+ * Optional tuning values for {@link Game.animateIntegrate}.
  *
- * @example
- * ```ts
- * // Subclassing for custom game objects
- * class Player extends Sprite {
- *   health = 3;
- *
- *   constructor(x: number, y: number) {
- *     super("🐢");
- *     this.x = x;
- *     this.y = y;
- *     this.size = 48;
- *     this.gravityScale = 1;
- *   }
- * }
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface IntegrateOptions {
+    /** Number of vertical slices used to reconstruct the sprite. */
+    rows?: number;
+    /** Number of horizontal slices used to reconstruct the sprite. */
+    cols?: number;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Primary sweep direction across the sprite. */
+    direction?: PieceFlowDirection;
+    /** Maximum local travel distance in pixels for each piece. */
+    distance?: number;
+    /** Maximum angular speed applied to pieces, in degrees per second. */
+    spin?: number;
+    /** Whether pieces fade in while integrating. */
+    fade?: boolean;
+}
+/**
+ * Wipe mode used by {@link Game.animateWipe}.
+ */
+export type WipeMode = "reveal" | "cover";
+/**
+ * Full-screen transition type used by {@link Game.transitionTo}.
+ */
+export type ScreenTransitionType = "fade" | "wipe" | "slide" | "iris" | "pixelate" | "flash";
+/**
+ * Optional tuning values for {@link Game.animateWipe}.
  *
- * const player = new Player(400, 300);
- * game.add(player);
- * ```
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface WipeOptions {
+    /** Whether the wipe reveals the sprite or covers it away. */
+    mode?: WipeMode;
+    /** Primary wipe direction. */
+    direction?: FlowDirection;
+    /** Total effect duration in **milliseconds**. */
+    durationMs?: number;
+    /** Whether the original sprite is destroyed for `mode: "cover"`. */
+    destroySprite?: boolean;
+}
+/**
+ * Optional tuning values for {@link Game.transitionTo}.
+ *
+ * MinimoJS scene transitions operate on frozen snapshots of the outgoing and
+ * incoming scenes. The target scene is created immediately, then both
+ * snapshots are composited for the duration of the effect.
+ */
+export interface SceneTransitionOptions {
+    /** Required transition style. */
+    type: ScreenTransitionType;
+    /** Total transition duration in **milliseconds**. */
+    durationMs?: number;
+    /** Optional color used by `fade` and `flash`. */
+    color?: string;
+    /** Direction used by `wipe` and `slide`. */
+    direction?: FlowDirection;
+    /** Optional iris center X position in canvas pixels. */
+    centerX?: number;
+    /** Optional iris center Y position in canvas pixels. */
+    centerY?: number;
+    /** Maximum pixel block size used by `pixelate`. */
+    pixelSize?: number;
+}
+/**
+ * Optional tuning values for {@link Game.animateTrail}.
+ *
+ * All fields are optional. Omitted fields use the engine defaults.
+ */
+export interface TrailOptions {
+    /** How long the emitter spawns afterimages, in **milliseconds**. */
+    durationMs?: number;
+    /** Time between emitted afterimages, in **milliseconds**. */
+    spacingMs?: number;
+    /** Lifetime of each afterimage before it disappears, in **milliseconds**. */
+    fadeMs?: number;
+    /** Starting opacity multiplier for each emitted afterimage, in range `[0, 1]`. */
+    alpha?: number;
+    /** Final scale multiplier reached by each afterimage before it vanishes. */
+    scaleTo?: number;
+}
+/**
+ * How a {@link BackgroundLayer} image is fit inside its destination rectangle.
+ *
+ * - `"none"`: draws the image at its original size with no scaling.
+ * - `"stretch"`: fills the destination exactly, ignoring aspect ratio.
+ * - `"contain"`: preserves aspect ratio and keeps the entire image visible.
+ * - `"cover"`: preserves aspect ratio and fully covers the destination, cropping if needed.
+ */
+export type BackgroundFit = "none" | "stretch" | "contain" | "cover";
+/**
+ * Minimal scene contract understood by {@link Game.start} and {@link Game.reset}.
+ *
+ * Scene methods are invoked directly on the scene instance, so class-based
+ * scenes keep their expected `this` value.
  */
-export declare class Sprite {
+export interface IScene {
     /**
-     * The emoji character used to render this sprite.
-     * Must be a single emoji. Change this at runtime to animate between frames.
-     * @example "🔥", "⭐", "🐢"
+     * Registers images this scene needs that the rest of the game does not.
+     *
+     * **Only for games with many scenes that each carry many assets of their
+     * own**, such as a game with many levels, where a player does not reach
+     * every scene in a session and loading all of them at boot would make the
+     * first wait needlessly long. Every other game should load its images in
+     * {@link Game.onPreload}, once, at boot.
+     *
+     * Called whenever the scene is entered — by {@link Game.start},
+     * {@link Game.reset}, or {@link Game.transitionTo} — before
+     * {@link IScene.onCreate}. Call {@link Game.loadAssets},
+     * {@link Game.loadImage}, or {@link Game.loadSound} inside it, as inside `game.onPreload`. Images that
+     * are already loaded are skipped, so replaying a scene loads nothing.
+     *
+     * When images are pending, the scene being left freezes, dimmed, under a
+     * progress ring until they load, and only then is this scene created.
+     * Because of that, `reset()` and `transitionTo()` may return before this
+     * scene exists: continue in `onCreate()`, not in the code after the call.
+     *
+     * @example
+     * ```ts
+     * class Level {
+     *   constructor(n) { this.n = n; }
+     *   onPreload() {
+     *     game.loadImage(`level-${this.n}-bg`, `assets/level-${this.n}-bg.png`);
+     *   }
+     *   onCreate() {
+     *     game.addBackground(new BackgroundLayer(`level-${this.n}-bg`));
+     *   }
+     * }
+     * ```
      */
-    sprite: string;
+    onPreload?(): void;
+    /**
+     * Called when the scene is created, before the first frame and again after
+     * each {@link Game.reset} that targets this scene. When the scene has an
+     * {@link IScene.onPreload} with images still loading, it is called once they
+     * have loaded.
+     */
+    onCreate?(): void;
+    /**
+     * Called once per frame after timers, animation, and physics updates.
+     *
+     * @param dt - Delta time in seconds since the previous frame.
+     */
+    onUpdate?(dt: number): void;
+}
+/**
+ * Base class for all renderable MinimoJS actors.
+ *
+ * Concrete subclasses provide their own visual content while inheriting the
+ * shared transform, visibility, physics, and animation state required by the
+ * engine.
+ */
+export declare abstract class Sprite {
+    protected constructor(game?: Game | null);
+    /**
+     * Game instance associated with this sprite, if any.
+     */
+    get game(): Game | null;
     /**
      * X position in world space (horizontal center of the sprite), in pixels.
      * Positive X points right. Updated each frame by: `x += vx * dt`.
@@ -68,10 +267,80 @@ export declare class Sprite {
      */
     y: number;
     /**
-     * Width and height of the sprite's bounding square, in pixels.
-     * Used for both canvas rendering (font size) and AABB collision detection.
+     * Resolved center X used internally by rendering, hit testing, and collisions.
      */
-    size: number;
+    get renderX(): number;
+    /**
+     * Resolved center Y used internally by rendering, hit testing, and collisions.
+     */
+    get renderY(): number;
+    /**
+     * Visual scale multiplier applied to this sprite's logical width/height.
+     * Default: `1`.
+     */
+    scale: number;
+    /**
+     * Base logical width in pixels before applying {@link Sprite.scale}.
+     */
+    abstract get width(): number;
+    /**
+     * Base logical height in pixels before applying {@link Sprite.scale}.
+     */
+    abstract get height(): number;
+    /**
+     * Effective rendered/collision width in pixels.
+     */
+    get displayWidth(): number;
+    /**
+     * Effective rendered/collision height in pixels.
+     */
+    get displayHeight(): number;
+    /**
+     * Optional logical body width used by physics helpers and collision checks.
+     *
+     * 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 Sprite.height}.
+     * When set, this value is scaled by {@link Sprite.scale} the same way as the
+     * visual sprite size.
+     */
+    bodyHeight: number | null;
+    /**
+     * Horizontal body offset, in local sprite pixels before scale is applied.
+     *
+     * Positive values move the collision body to the right of the sprite's rendered center.
+     * Negative values move it to the left.
+     */
+    bodyOffsetX: number;
+    /**
+     * Vertical body offset, in local sprite pixels before scale is applied.
+     *
+     * Positive values move the collision body downward relative to the sprite's
+     * rendered center. Negative values move it upward.
+     */
+    bodyOffsetY: number;
+    /**
+     * Effective collision-body width in pixels after applying {@link Sprite.scale}.
+     */
+    get bodyDisplayWidth(): number;
+    /**
+     * Effective collision-body height in pixels after applying {@link Sprite.scale}.
+     */
+    get bodyDisplayHeight(): number;
+    /**
+     * Resolved body center X used internally by physics helpers and collision checks.
+     */
+    get bodyCenterX(): number;
+    /**
+     * Resolved body center Y used internally by physics helpers and collision checks.
+     */
+    get bodyCenterY(): number;
     /**
      * CSS text color used when rendering this sprite.
      *
@@ -80,6 +349,19 @@ export declare class Sprite {
      * depending on browser behavior.
      */
     color: string;
+    /**
+     * 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.
+     */
+    isStatic: boolean;
     /**
      * Visual rotation of the sprite in degrees.
      * `0` = upright. Positive values rotate clockwise.
@@ -145,24 +427,415 @@ export declare class Sprite {
      */
     gravityScale: number;
     /**
-     * Creates a new Sprite with the given emoji and optional position.
+     * Optional name, so code can ask an object what it is. Names may repeat,
+     * like a `name` attribute in the DOM. The engine never reads it.
+     * A sprite created from a design file takes the object's `name`.
+     *
+     * @example
+     * ```ts
+     * if (other.name === "door") openDoor();
+     * ```
+     */
+    name: string | undefined;
+    /**
+     * Tags for grouping, like CSS classes in the DOM. Empty by default. The
+     * engine never reads them. A sprite created from a design file takes the
+     * object's `tags`, which {@link Game.registerBuilderByTag} also matches.
+     *
+     * @example
+     * ```ts
+     * if (other.tags.includes("coin")) collect(other);
+     * ```
+     */
+    tags: string[];
+    /**
+     * The game's own values for this object, such as a button's action or an
+     * enemy's speed. An empty object by default, so `sprite.data.hp = 3` needs
+     * no check. The engine never reads it. A sprite created from a design file
+     * takes a copy of the object's `data`.
+     */
+    data: Record<string, unknown>;
+    /**
+     * Stable cache key describing the sprite's rendered appearance.
+     *
+     * The renderer uses this to reuse prerendered canvases across frames.
+     */
+    abstract getRenderCacheKey(): string;
+    protected getAnchorOffsetX(): number;
+    protected getAnchorOffsetY(): number;
+}
+/**
+ * A 2D game object rendered as an emoji on the canvas.
+ *
+ * Instantiate directly or extend to create custom sprite types.
+ * Register with the engine by passing the instance to {@link Game.add}.
+ *
+ * **Coordinate system:** center-based world space. `(x, y)` is the center of
+ * the sprite. Positive X = right, positive Y = down.
+ *
+ * **Lifecycle:** A sprite exists until {@link Game.destroySprite} is called or
+ * {@link Game.reset} is invoked. After destruction, do not read or write its fields.
+ *
+ * @example
+ * ```ts
+ * const coin = new EmojiSprite("🪙", 300, 200, 32);
+ * game.add(coin);
+ * ```
+ */
+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.
+     * @example "🔥", "⭐", "🐢"
+     */
+    sprite: string;
+    get size(): number;
+    get width(): number;
+    get height(): number;
+    get displaySize(): number;
+    /**
+     * 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.
-     *   Image sprites are NOT supported — emoji only.
+     *   Use {@link ImageSprite} for preloaded bitmap textures.
      *   @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 EmojiSprite("👾", 200, 100, 40);
      * game.add(enemy);
      * ```
      */
-    constructor(sprite: string, x?: number, y?: number);
+    constructor(sprite: string, x?: number, y?: number, size?: number);
+    getRenderCacheKey(): string;
+}
+/**
+ * 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 Sprite.scale}.
+ */
+export declare class ImageSprite extends Sprite {
+    get imageKey(): string;
+    get width(): number;
+    get height(): number;
+    /**
+     * Creates a new image-backed sprite.
+     *
+     * @param game - Game instance used to resolve the texture key.
+     * @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`.
+     */
+    constructor(game: Game, imageKey: string, x?: number, y?: number);
+    /**
+     * Replaces the current texture with another preloaded image.
+     *
+     * @param imageKey - New texture key to render.
+     */
+    setTexture(imageKey: string): void;
+    getRenderCacheKey(): string;
+}
+/**
+ * A renderable sprite backed by a per-instance canvas that is repainted on demand.
+ *
+ * `DrawSprite` is useful for procedural shapes, gauges, charts, minimaps, and
+ * HUD widgets whose appearance changes often and is easier to express with
+ * Canvas 2D drawing commands than with emoji, text, or image swaps.
+ *
+ * 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 EmojiSprite},
+ * {@link ImageSprite}, or {@link TextSprite} instances.
+ *
+ * Prefer the other sprite types whenever they can express the same result more
+ * simply. Reach for `DrawSprite` only when you truly need procedural drawing or
+ * custom per-sprite canvas rendering that the built-in sprite types cannot
+ * provide cleanly.
+ *
+ * MinimoJS creates and owns an internal canvas for each `DrawSprite` instance.
+ * Before every engine render that needs this sprite's surface, the engine:
+ *
+ * 1. Resolves the sprite's internal canvas size
+ * 2. Optionally clears and repaints that internal canvas
+ * 3. Draws the resulting canvas like any other sprite surface
+ *
+ * By default, `DrawSprite` is live-rendered: the engine clears the internal
+ * canvas and calls {@link DrawSprite.redraw} every frame.
+ *
+ * Set {@link DrawSprite.frozen} to `true` if you want to keep and reuse the
+ * last rendered canvas contents without repainting on each frame. This is
+ * useful for shapes or procedural art that you only want to draw once.
+ *
+ * While `frozen` is `true`, MinimoJS reuses the existing surface exactly as-is:
+ * it does not clear the canvas and does not call {@link DrawSprite.redraw}
+ * again, unless the surface does not exist yet or its size had to be rebuilt.
+ *
+ * This means freezing is a rendering optimization and content-preservation
+ * flag, not a separate caching system. You can switch `frozen` on or off at
+ * runtime whenever it makes sense for your sprite.
+ *
+ * The local drawing coordinate system uses the sprite surface itself:
+ * - `(0, 0)` is the top-left corner of the internal canvas
+ * - `width` / `height` match the sprite's logical size before `scale`
+ * - draw centered content yourself if you want the visual origin in the middle
+ *
+ * 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 Sprite {
+    /**
+     * When `false` (default), MinimoJS clears this sprite's internal canvas and
+     * calls {@link DrawSprite.redraw} on every render pass.
+     *
+     * When `true`, MinimoJS keeps and reuses the existing canvas contents without
+     * clearing or repainting them again, unless the internal surface does not yet
+     * exist or had to be resized.
+     *
+     * Use this when your procedural drawing becomes static after its first paint,
+     * or when you want explicit manual control over when the sprite is redrawn by
+     * toggling `frozen` at runtime.
+     */
+    frozen: boolean;
+    get width(): number;
+    get height(): number;
+    /**
+     * Creates a new dynamic canvas-backed sprite.
+     *
+     * @param width - Internal canvas width in pixels. Minimum `1`.
+     * @param height - Internal canvas height in pixels. Minimum `1`.
+     * @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`.
+     */
+    constructor(width: number, height: number, x?: number, y?: number);
+    /**
+     * Called by the engine whenever the sprite's internal surface must be repainted.
+     *
+     * The provided context is already cleared and reset to the default 2D canvas
+     * state for the current surface size. MinimoJS repaints each `DrawSprite` at
+     * most once per render pass while it is not {@link DrawSprite.frozen}, so
+     * repeated snapshot reads during the same frame reuse the already-redrawn
+     * surface.
+     *
+     * @param ctx - The sprite's internal 2D drawing context.
+     */
+    redraw(_ctx: CanvasRenderingContext2D): void;
+    getRenderCacheKey(): string;
 }
+/**
+ * A renderable text actor that participates in the same animation/effects
+ * pipeline as regular sprites.
+ *
+ * Use `TextSprite` when the content is primarily text, or when you need text
+ * layout features such as wrapping, fixed button sizes, background/border, or
+ * text stroke.
+ *
+ * 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 Sprite {
+    anchorX: "left" | "center" | "right";
+    anchorY: "top" | "middle" | "bottom";
+    text: string;
+    /**
+     * CSS font family. Default: `monospace`, which needs no download. Name a web
+     * font here, and register it with {@link Game.requireFont}, to use one.
+     */
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: string;
+    lineHeight: number;
+    maxWidth: number;
+    fixedWidth: number;
+    fixedHeight: number;
+    paddingX: number;
+    paddingY: number;
+    backgroundColor: string | null;
+    borderColor: string | null;
+    borderWidth: number;
+    cornerRadius: number;
+    strokeColor: string | null;
+    strokeWidth: number;
+    textAlign: CanvasTextAlign;
+    get width(): number;
+    get height(): number;
+    constructor(text: string, x?: number, y?: number, fontSizeOrConfig?: number | TextSpriteConfig, config?: TextSpriteConfig);
+    getRenderCacheKey(): string;
+    get align(): CanvasTextAlign;
+    set align(value: CanvasTextAlign);
+    protected getAnchorOffsetX(): number;
+    protected getAnchorOffsetY(): number;
+}
+export type TextSpriteConfig = {
+    anchorX?: "left" | "center" | "right";
+    anchorY?: "top" | "middle" | "bottom";
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    lineHeight?: number;
+    maxWidth?: number;
+    fixedWidth?: number;
+    fixedHeight?: number;
+    paddingX?: number;
+    paddingY?: number;
+    backgroundColor?: string | null;
+    borderColor?: string | null;
+    borderWidth?: number;
+    cornerRadius?: number;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    textAlign?: CanvasTextAlign;
+    align?: CanvasTextAlign;
+};
+export type FontRequirementOptions = {
+    weight?: string;
+    style?: "normal" | "italic" | "oblique";
+    size?: number;
+    sampleText?: string;
+};
+/**
+ * A static image-based background layer rendered behind all sprites.
+ *
+ * Background layers are visual-only: they do not participate in physics,
+ * collisions, input hit-testing, or sprite queries.
+ *
+ * `x` / `y` use **top-left screen-space coordinates**, unlike {@link Sprite},
+ * which uses center-based world space.
+ *
+ * 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
+ * game.onPreload = () => {
+ *   game.loadImage("sky", "assets/sky.png");
+ * };
+ *
+ * game.onCreate = () => {
+ *   const bg = game.addBackground(new BackgroundLayer("sky"));
+ *   bg.fit = "cover";
+ * };
+ * ```
+ */
+export declare class BackgroundLayer {
+    /**
+     * Key of the preloaded image to render.
+     */
+    imageKey: string;
+    /**
+     * Left edge of the destination rectangle in screen space, in pixels.
+     */
+    x: number;
+    /**
+     * Top edge of the destination rectangle in screen space, in pixels.
+     */
+    y: number;
+    /**
+     * Width of the destination rectangle in pixels.
+     * If `0` (default), the canvas width is used.
+     */
+    width: number;
+    /**
+     * Height of the destination rectangle in pixels.
+     * If `0` (default), the canvas height is used.
+     */
+    height: number;
+    /**
+     * Opacity of the layer in range `[0, 1]`.
+     */
+    alpha: number;
+    /**
+     * Controls whether the layer is drawn.
+     */
+    visible: boolean;
+    /**
+     * Orders background layers relative to each other.
+     * Higher values render on top of lower background layers, but still behind sprites.
+     */
+    layer: number;
+    /**
+     * How the image is fit inside the destination rectangle.
+     * Default: `"cover"`.
+     */
+    fit: BackgroundFit;
+    /**
+     * Optional name, so code can ask a layer what it is. Names may repeat. The
+     * engine never reads it. See {@link Sprite.name}.
+     */
+    name: string | undefined;
+    /**
+     * Tags for grouping. Empty by default. The engine never reads them. See
+     * {@link Sprite.tags}.
+     */
+    tags: string[];
+    /**
+     * The game's own values for this layer. An empty object by default. The
+     * engine never reads it. See {@link Sprite.data}.
+     */
+    data: Record<string, unknown>;
+    /**
+     * Creates a new background layer.
+     *
+     * @param imageKey - Preloaded image key previously registered with {@link Game.loadImage}.
+     * @param x - Destination rectangle left edge in screen space. Default: `0`.
+     * @param y - Destination rectangle top edge in screen space. Default: `0`.
+     * @param width - Destination rectangle width. `0` means canvas width. Default: `0`.
+     * @param height - Destination rectangle height. `0` means canvas height. Default: `0`.
+     */
+    constructor(imageKey: string, x?: number, y?: number, width?: number, height?: number);
+}
+/**
+ * The objects {@link Game.createObjectList} created, in the order of their
+ * data, and searches on them.
+ *
+ * An `ObjectList` only holds and finds its objects; it never changes them.
+ * Remove them through the game, as any other object:
+ *
+ * ```ts
+ * for (const obj of ui.objects) {
+ *   if (obj instanceof BackgroundLayer) game.destroyBackgroundLayer(obj);
+ *   else game.destroySprite(obj);
+ * }
+ * ```
+ *
+ * Searches read each object's current {@link Sprite.name} and
+ * {@link Sprite.tags}. In TypeScript, name the type you expect:
+ * `ui.findByName<ImageSprite>("play")`.
+ */
+export declare class ObjectList {
+    /** Every object created, in the order of the data. */
+    readonly objects: readonly (Sprite | BackgroundLayer)[];
+    /**
+     * Returns the first object whose `name` is `name`, in order.
+     * Throws an error naming `name` when there is none.
+     *
+     * @example
+     * ```ts
+     * const play = ui.findByName("play");
+     * ```
+     */
+    findByName<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(name: string): T;
+    /** Returns every object whose `name` is `name`, in order; an empty list when there is none. */
+    findAllByName<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(name: string): T[];
+    /**
+     * Returns the first object whose `tags` include `tag`, in order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(tag: string): T;
+    /** Returns every object whose `tags` include `tag`, in order; an empty list when there is none. */
+    findAllByTag<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(tag: string): T[];
+}
+/**
+ * Builds the object for a design object whose tags include the tag it was
+ * registered for. See {@link Game.registerBuilderByTag}.
+ */
+export type ObjectBuilder = (obj: DesignObject, game: Game) => Sprite | BackgroundLayer;
 /**
  * Snapshot of an active pointer tracked by the engine.
  *
@@ -189,6 +862,36 @@ export interface PointerInfo {
      */
     pressed: boolean;
 }
+/**
+ * Information about a resolved AABB collision.
+ *
+ * Flags are reported relative to the **first** sprite passed to
+ * {@link Game.collide}. For example, `bottom = true` means the bottom side of
+ * the first sprite contacted the top side of the second sprite.
+ */
+export interface CollisionInfo {
+    /**
+     * `true` when the first sprite's left side hit the second sprite.
+     */
+    left: boolean;
+    /**
+     * `true` when the first sprite's right side hit the second sprite.
+     */
+    right: boolean;
+    /**
+     * `true` when the first sprite's top side hit the second sprite from below.
+     */
+    top: boolean;
+    /**
+     * `true` when the first sprite's bottom side landed on the second sprite.
+     */
+    bottom: boolean;
+    /**
+     * Convenience flag for platformers.
+     * Equivalent to `bottom = true`.
+     */
+    grounded: boolean;
+}
 /**
  * # MinimoJS v1 — AI Agent Integration Guide
  *
@@ -198,18 +901,88 @@ export interface PointerInfo {
  *
  * ---
  *
+ * ## ES Module Only
+ *
+ * MinimoJS is an **ES module only** package.
+ * You must import it with standard ESM syntax such as:
+ *
+ * ```ts
+ * import { Game, EmojiSprite } from "minimojs";
+ * ```
+ *
+ * In the browser, use it from a module script:
+ *
+ * ```html
+ * <script type="module">
+ *   import { Game, EmojiSprite } from "./dist/minimo.js";
+ * </script>
+ * ```
+ *
+ * Or from a CDN:
+ *
+ * ```ts
+ * import { Game, EmojiSprite } 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).
+ *
+ * ---
+ *
+ * ## Font Setup
+ *
+ * `drawText()` and `TextSprite` default to `monospace`, which every device
+ * has, so a game that names no font downloads none and waits for none. To use
+ * a web font, declare it in your page, register it with {@link Game.requireFont}
+ * before calling {@link Game.start}, and name it in {@link TextSprite.fontFamily}.
+ *
+ * Prefer {@link TextSprite} for persistent UI text, interactive labels,
+ * buttons, fixed-size text boxes, and styled text elements. Keep
+ * `drawText()` for simple screen-space overlays such as HUD counters, debug
+ * text, or other text that is redrawn every frame.
+ *
+ * You MUST still declare the fonts yourself in your `index.html`. MinimoJS
+ * does NOT download, inject, or manage web fonts for you. If a 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"
+ * />
+ * ```
+ *
+ * Example custom font registration:
+ *
+ * ```ts
+ * const game = new Game(720, 1280);
+ * game.requireFont('"Bangers"', { weight: "400" });
+ * game.start();
+ * ```
+ *
+ * ---
+ *
  * ## 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);
+ *
+ * game.onPreload = () => {
+ *   game.loadImage("player", "assets/player.png");
+ * };
  *
- * const game = new Game(800, 600);
+ * let player: ImageSprite;
  *
- * const player = new Sprite("🐢");
- * player.x = 400;
- * player.y = 500;
- * player.size = 48;
- * game.add(player);
+ * game.onCreate = () => {
+ *   player = game.add(new ImageSprite(game, "player", 400, 500));
+ * };
  *
  * game.onUpdate = (dt) => {
  *   if (game.isKeyDown("ArrowLeft"))  player.vx = -200;
@@ -222,6 +995,13 @@ export interface PointerInfo {
  * 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
@@ -235,7 +1015,8 @@ export interface PointerInfo {
  * ## 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.
  *
  * ---
  *
@@ -246,13 +1027,28 @@ export interface PointerInfo {
  *
  * ---
  *
- * ## 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.
  *
  * ---
  *
@@ -268,7 +1064,7 @@ export interface PointerInfo {
  *
  * ALL time parameters to engine methods are in **milliseconds (ms)**.
  * This includes: {@link Game.addTimer}, {@link Game.animateAlpha},
- * {@link Game.animateRotation}, and {@link Game.sound}.
+ * {@link Game.animateRotation}, {@link Game.animateDeform}, and {@link Game.sound}.
  *
  * The `dt` parameter in {@link Game.onUpdate} is an exception — it is in
  * **seconds** for convenient velocity math (`position += velocity * dt`).
@@ -320,10 +1116,10 @@ export interface PointerInfo {
  *
  * ---
  *
- * ## Scene Initialization with `onCreate`
+ * ## Scene Initialization with `IScene`
  *
- * MinimoJS has NO scene system. Use {@link Game.onCreate} to build a scene.
- * The engine calls `onCreate`:
+ * MinimoJS supports simple scene objects via {@link IScene}. The engine calls
+ * a scene's `onCreate()`:
  * - Once before the first frame (when {@link Game.start} is called).
  * - Again after each {@link Game.reset}.
  *
@@ -335,29 +1131,42 @@ export interface PointerInfo {
  * - Scroll position (scrollX and scrollY reset to 0)
  * - Per-frame input state (pressed keys/pointer)
  *
- * After clearing, `reset()` calls `onCreate()` so your callback can rebuild the
- * new scene immediately. Simply re-add sprites and re-register timers.
+ * After clearing, `reset()` calls the active scene's `onCreate()` so it can
+ * rebuild immediately. Simply re-add sprites and re-register timers.
  *
  * ```ts
- * game.onCreate = () => {
- *   // scene init: add sprites, setup timers
- *   const skull = new Sprite("💀");
- *   skull.x = 400; skull.y = 300; skull.size = 96;
- *   game.add(skull);
- * };
+ * class SkullScene implements IScene {
+ *   onCreate() {
+ *     const skull = new EmojiSprite("💀", 400, 300, 96);
+ *     game.add(skull);
+ *   }
  *
- * game.onUpdate = (dt) => {
- *   // normal per-frame update
- * };
+ *   onUpdate(dt: number) {
+ *     // normal per-frame update
+ *   }
+ * }
  *
- * game.start(); // calls onCreate() once before first frame
+ * const scene = new SkullScene();
+ * game.start(scene); // calls onCreate() once before first frame
  * // later:
  * game.reset(); // clears + calls onCreate() again
  * ```
  *
+ * Legacy `game.onCreate` / `game.onUpdate` callbacks still work when no active
+ * {@link IScene} is set.
+ *
+ * ### Loading a Scene's Own Images
+ *
+ * Load images in {@link Game.onPreload}: once, at boot. Only a game with many
+ * scenes that each carry many assets of their own — typically a game with many
+ * levels, whose player does not reach every level in a session — should give
+ * scenes an {@link IScene.onPreload}. Entering such a scene loads its images
+ * first, with the scene being left frozen and dimmed under a progress ring, so `reset()`
+ * and `transitionTo()` may return before the new scene's `onCreate()` runs.
+ *
  * ---
  *
- * ## Sprite Lifecycle Ownership
+ * ## EmojiSprite Lifecycle Ownership
  *
  * The `Game` instance owns all sprites.
  * - Create sprites with {@link Game.add}.
@@ -371,7 +1180,7 @@ export interface PointerInfo {
  * ## Forbidden Features
  *
  * The following do NOT exist in MinimoJS v1. Do NOT attempt to use them:
- * - Scene system or scene manager
+ * - Full scene manager architecture (scene stacks, transitions, loaders, etc.)
  * - Entity Component System (ECS)
  * - Physics engine (no Box2D, Matter.js, etc.)
  * - Camera zoom or scale
@@ -379,8 +1188,7 @@ export interface PointerInfo {
  * - Text input / HTML form elements
  * - Parallax layers
  * - Multiple cameras
- * - Collision resolution (only detection is supported)
- * - Image sprites (PNG, SVG, canvas, etc.)
+ * - Full physics engine (only basic explicit AABB collision helpers are provided)
  * - `setTimeout` or `setInterval`
  */
 export declare class Game {
@@ -395,7 +1203,8 @@ export declare class Game {
      * game.gravityX = 0;   // no horizontal gravity
      * ```
      */
-    gravityX: number;
+    get gravityX(): number;
+    set gravityX(value: number);
     /**
      * Vertical gravity acceleration in pixels per second².
      * Applied to every sprite whose {@link Sprite.gravityScale} is non-zero.
@@ -408,7 +1217,23 @@ export declare class Game {
      * game.gravityY = 980; // standard downward gravity
      * ```
      */
-    gravityY: number;
+    get gravityY(): number;
+    set gravityY(value: number);
+    /**
+     * 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;
+     * ```
+     */
+    get physics(): boolean;
+    set physics(value: boolean);
     /**
      * Horizontal scroll offset of the world camera, in pixels.
      * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -456,6 +1281,20 @@ export declare class Game {
         from: string;
         to: string;
     } | null;
+    /**
+     * When `true`, MinimoJS draws every sprite's collision body as an overlay.
+     *
+     * This is a runtime debugging aid only. It does not change collisions,
+     * input, rendering order, or physics behavior.
+     */
+    debugBodies: boolean;
+    /**
+     * When `true`, MinimoJS draws every sprite's input area as an overlay.
+     *
+     * This is a runtime debugging aid only. It does not change input behavior,
+     * physics, or rendering.
+     */
+    debugInputAreas: boolean;
     /**
      * Background color for the full web page (`document.body`).
      * Set to any valid CSS color string. Default: `null` (engine leaves page background unchanged).
@@ -469,24 +1308,49 @@ export declare class Game {
      */
     pageBackground: string | null;
     /**
-     * Scene creation callback.
+     * Asset registration callback invoked once before the first scene is created.
+     *
+     * This is the normal place to load a game's images and sounds. Use it to register them
+     * with {@link Game.loadAssets}, {@link Game.loadImage}, or {@link Game.loadSound}. The callback is synchronous: it should only
+     * queue assets, not await network work.
+     *
+     * After `onPreload` returns, MinimoJS loads the queued images and sounds, together with
+     * those of the first scene's {@link IScene.onPreload} if it has one, and
+     * shows a loading line until they are ready. If any file fails, it asks the
+     * player with `window.confirm` whether to retry them; declining leaves the
+     * game on the loading screen and reports the failed files on the console.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadImage("sky", "assets/sky.png");
+     *   game.loadImage("land", "assets/land.png");
+     * };
+     * ```
+     */
+    onPreload: (() => void) | null;
+    /**
+     * Legacy scene creation callback.
      *
      * Called once before the first frame on {@link Game.start}, and again after
-     * each {@link Game.reset}. Use this to create sprites and timers for a scene.
+     * each {@link Game.reset} when no active {@link IScene} is set.
      *
      * @example
      * ```ts
      * game.onCreate = () => {
-     *   const player = new Sprite("🐢");
+     *   const player = new EmojiSprite("🐢");
      *   player.x = 200;
      *   player.y = 300;
      *   game.add(player);
      * };
      * ```
      */
-    onCreate: (() => void) | null;
+    get onCreate(): (() => void) | null;
+    set onCreate(callback: (() => void) | null);
     /**
-     * Callback invoked once per frame after physics and timer updates.
+     * Legacy per-frame callback invoked after physics and timer updates.
+     *
+     * This is used only when no active {@link IScene} is set.
      *
      * @param dt - Delta time in **seconds** since the last frame.
      *   Use this for velocity-based movement: `sprite.x += speed * dt`.
@@ -501,21 +1365,38 @@ export declare class Game {
      * ```
      */
     onUpdate: ((dt: number) => void) | null;
+    /**
+     * Currently active scene object, if any.
+     */
+    get currentScene(): IScene | null;
+    /**
+     * Returns `true` while a full-screen scene transition is playing.
+     */
+    get isTransitioning(): boolean;
+    /**
+     * Returns `true` while images are loading: at boot, or while a scene with
+     * pending images in its {@link IScene.onPreload} is being entered. While a
+     * scene loads, the scene being left is frozen and `reset()` and
+     * `transitionTo()` are ignored.
+     */
+    get isLoading(): boolean;
     /**
      * Creates a new MinimoJS game instance.
      *
      * The engine creates its own `<canvas>`, sets its dimensions, and appends it
      * to `document.body`. The canvas is automatically centered and responsively
      * scaled to use the maximum available viewport space while preserving aspect ratio.
+     * For new mobile-first Minimo Games, prefer a portrait canvas such as `720x1280`.
      *
-     * @param width - Canvas width in pixels. Default: `800`.
-     * @param height - Canvas height in pixels. Default: `600`.
+     * @param width - Canvas width in pixels. Default: `720`.
+     * @param height - Canvas height in pixels. Default: `1280`.
      *
      * @throws Error if a 2D context cannot be obtained.
      *
      * @example
      * ```ts
-     * const game = new Game(800, 600);
+     * const game = new Game(720, 1280);
+     * game.physics = true;
      * ```
      */
     constructor(width?: number, height?: number);
@@ -526,98 +1407,350 @@ export declare class Game {
     /**
      * The height of the canvas in pixels. Read-only — set via constructor.
      */
-    get height(): number;
+    get height(): number;
+    /**
+     * Current pointer (mouse or touch) X position in **canvas/screen space**,
+     * in pixels. Updated every `mousemove` / `touchmove` event.
+     * `(0, 0)` is the top-left corner of the canvas.
+     * To convert to world space: `worldX = game.pointerX + game.scrollX`.
+     *
+     * On a touch screen the pointer is one finger: the first to touch while no
+     * finger is followed. Other fingers never move it, and when the followed
+     * finger lifts, the pointer stays where it left the screen even if others
+     * are still down. Use {@link Game.getPointers} to follow several fingers.
+     */
+    get pointerX(): number;
+    /**
+     * Current pointer (mouse or touch) Y position in **canvas/screen space**,
+     * in pixels. Updated every `mousemove` / `touchmove` event.
+     * `(0, 0)` is the top-left corner of the canvas.
+     * To convert to world space: `worldY = game.pointerY + game.scrollY`.
+     */
+    get pointerY(): number;
+    /**
+     * 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
+     * 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.
+     *
+     * **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 Sprite} instance (or subclass) to add.
+     * @returns The same sprite instance, for chaining or inline assignment.
+     *
+     * @example
+     * ```ts
+     * // Plain sprite
+     * const coin = new EmojiSprite("🪙", 300, 200, 32);
+     * game.add(coin);
+     *
+     * // Custom subclass
+     * class Enemy extends EmojiSprite {
+     *   speed = 150;
+     *   constructor(x: number, y: number) {
+     *     super("👾", x, y, 40);
+     *   }
+     *   }
+     * const enemy = game.add(new Enemy(600, 100));
+     * ```
+     */
+    add<T extends Sprite>(sprite: T): T;
+    /**
+     * Registers a {@link BackgroundLayer} with the engine.
+     *
+     * Background layers are rendered behind all sprites and are not affected by
+     * physics, collisions, or sprite queries.
+     *
+     * @param layer - The background layer to add.
+     * @returns The same background layer instance.
+     *
+     * @example
+     * ```ts
+     * const sky = game.addBackground(new BackgroundLayer("sky"));
+     * sky.fit = "cover";
+     * ```
+     */
+    addBackground(layer: BackgroundLayer): BackgroundLayer;
+    /**
+     * Removes a sprite from the engine, stopping its rendering and physics updates.
+     * Also cancels any running animations targeting this sprite.
+     *
+     * **Side effects:** The sprite is removed immediately. Accessing the sprite's
+     * fields after destruction has no effect on the engine, but reading them
+     * returns stale values. Do not keep references to destroyed sprites.
+     *
+     * If `sprite` is not found (already destroyed or never added), this is a no-op.
+     *
+     * @param sprite - The sprite instance to destroy, as passed to {@link Game.add}.
+     *
+     * @example
+     * ```ts
+     * game.destroySprite(enemy); // remove enemy from game
+     * ```
+     */
+    destroySprite(sprite: Sprite): void;
+    /**
+     * Removes a background layer from the engine.
+     *
+     * If the layer is not currently registered, this is a safe no-op.
+     *
+     * @param layer - The background layer to remove.
+     */
+    destroyBackgroundLayer(layer: BackgroundLayer): void;
+    /**
+     * Returns a **read-only snapshot** of all currently active sprites.
+     * The array is a shallow copy — mutating it has no effect on the engine.
+     * Individual sprite objects in the array are the live instances.
+     *
+     * **Deterministic guarantee:** Sprites appear in creation order within each
+     * layer. The order matches the render order (lower layer = earlier in array).
+     *
+     * @returns A read-only array of active {@link Sprite} instances.
+     *
+     * @example
+     * ```ts
+     * const enemies = game.getSprites().filter(s => s.sprite === "👾");
+     * ```
+     */
+    getSprites(): readonly Sprite[];
+    /**
+     * Returns a read-only snapshot of all active background layers.
+     *
+     * Background layers are returned in creation order within each layer value.
+     */
+    getBackgroundLayers(): readonly BackgroundLayer[];
+    /**
+     * Queues an image to be loaded during {@link Game.onPreload}.
+     *
+     * This method registers the asset only. The actual network/image fetch begins
+     * after `onPreload` returns and is managed automatically by the engine.
+     *
+     * `loadImage` may only be called from within {@link Game.onPreload} or a
+     * scene's {@link IScene.onPreload}.
+     *
+     * @param key - Stable key used later by {@link BackgroundLayer.imageKey} or {@link Game.getImage}.
+     * @param src - Image URL or relative path.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadImage("sky", "assets/sky.png");
+     * };
+     * ```
+     */
+    loadImage(key: string, src: string): void;
+    /**
+     * Queues an audio file to be loaded during {@link Game.onPreload}, to play
+     * later with {@link Game.playSound}.
+     *
+     * Like {@link Game.loadImage}, it only registers the sound, and may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@link IScene.onPreload}. The file loads and decodes with the images,
+     * under the same loading line, and a file that fails is retried with them.
+     * Keys are unique in the whole game: a sound cannot share its key with an
+     * image. Prefer declaring sounds in an asset file, as `sound` entries
+     * loaded with {@link Game.loadAssets}.
+     *
+     * MP3 plays in every browser; WAV does too, but its files are large. OGG
+     * does not play in every Safari.
+     *
+     * @param key - Stable key used later by {@link Game.playSound}.
+     * @param src - Audio file URL or relative path.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadSound("jump", "assets/jump.mp3");
+     *   game.loadSound("theme", "assets/theme.mp3");
+     * };
+     * ```
+     */
+    loadSound(key: string, src: string): void;
+    /**
+     * Queues every asset an asset file declares, as one {@link Game.loadImage}
+     * call per `image` entry and one {@link Game.loadSound} call per `sound`
+     * entry would.
+     *
+     * Pass the content of a `*.assets.json` file, obtained by JSON import. The
+     * file is checked with {@link parseAssetFile}, and an invalid one throws an
+     * error naming what is wrong. Like `loadImage`, `loadAssets` may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@link IScene.onPreload}.
+     *
+     * - Keys are unique in the whole game. A key that another asset file
+     *   declares, or that {@link Game.loadImage}, {@link Game.loadSound}, or
+     *   {@link Game.createTexture} registered, throws an error naming it, and so does a later
+     *   `loadImage` or `createTexture` of a key an asset file declares.
+     * - Loading the same file again, as a scene's `onPreload()` does each time
+     *   the scene is entered, queues only its files that are not loaded.
+     * - An entry of a type this engine does not support is skipped, with a
+     *   console warning naming it, so the game still loads every asset it can.
+     *
+     * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
+     *
+     * @example
+     * ```ts
+     * import common from "./common.assets.json" with { type: "json" };
+     *
+     * game.onPreload = () => game.loadAssets(common);
+     * ```
+     */
+    loadAssets(assets: unknown): void;
+    /**
+     * 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;
     /**
-     * Current pointer (mouse or touch) X position in **canvas/screen space**,
-     * in pixels. Updated every `mousemove` / `touchmove` event.
-     * `(0, 0)` is the top-left corner of the canvas.
-     * To convert to world space: `worldX = game.pointerX + game.scrollX`.
+     * Returns a loaded image or created texture previously registered with
+     * {@link Game.loadImage} or {@link Game.createTexture}, or `undefined` if it
+     * is not available.
      */
-    get pointerX(): number;
+    getImage(key: string): HTMLImageElement | HTMLCanvasElement | undefined;
     /**
-     * Current pointer (mouse or touch) Y position in **canvas/screen space**,
-     * in pixels. Updated every `mousemove` / `touchmove` event.
-     * `(0, 0)` is the top-left corner of the canvas.
-     * To convert to world space: `worldY = game.pointerY + game.scrollY`.
+     * Returns `true` if a texture key is available.
      */
-    get pointerY(): number;
+    hasImage(key: string): boolean;
     /**
-     * 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.
+     * Creates one runtime object from object data, such as a template found in
+     * a {@link Design}, and adds it to the 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.
+     * The object is built through the same public constructors and
+     * {@link Game.add} or {@link Game.addBackground} that code uses, so it
+     * behaves as the equivalent code. Its type picks its class: `image` builds
+     * an {@link ImageSprite}, `emoji` an {@link EmojiSprite}, `text` a
+     * {@link TextSprite}, and `background` a {@link BackgroundLayer}, unless a
+     * builder registered with {@link Game.registerBuilderByTag} matches one of
+     * its tags. Then every property the data holds is applied, including
+     * `name`, `tags`, and a copy of `data`.
      *
-     * **Subclasses:** Any class that extends {@link Sprite} can be passed here.
-     * The engine stores and processes it as a `Sprite`; your custom properties
-     * are preserved on the instance.
+     * Each call creates a new object, so one template can be created any number
+     * of times. Set its position afterwards to place it; the object is never
+     * drawn at the template's position.
      *
-     * @param sprite - A {@link Sprite} instance (or subclass) to add.
-     * @returns The same sprite instance, for chaining or inline assignment.
+     * Throws an error naming what is wrong when the data is not a valid design
+     * object, or naming the key when it uses an image key that is not loaded.
+     *
+     * @param data - One design object, such as `design.findByName("player")`. Not a `Design`.
+     * @param options - `add: false` creates the object without adding it to the game. Default: added.
+     * @returns The created object. In TypeScript, name its type: `game.createObject<ImageSprite>(data)`.
      *
      * @example
      * ```ts
-     * // Plain sprite
-     * const coin = new Sprite("🪙");
-     * coin.x = 300; coin.y = 200; coin.size = 32;
-     * game.add(coin);
+     * import charactersJson from "./characters.design.json" with { type: "json" };
+     * const characters = new Design(charactersJson);
      *
-     * // Custom subclass
-     * class Enemy extends Sprite {
-     *   speed = 150;
-     *   constructor(x: number, y: number) {
-     *     super("👾");
-     *     this.x = x; this.y = y; this.size = 40;
-     *   }
-     * }
-     * const enemy = game.add(new Enemy(600, 100));
+     * const bat = game.createObject(characters.findByName("bat"));
+     * bat.x = spawn.x;
+     * bat.y = spawn.y;
      * ```
      */
-    add(sprite: Sprite): Sprite;
+    createObject<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(data: DesignObject, options?: {
+        add?: boolean;
+    }): T;
     /**
-     * Removes a sprite from the engine, stopping its rendering and physics updates.
-     * Also cancels any running animations targeting this sprite.
-     *
-     * **Side effects:** The sprite is removed immediately. Accessing the sprite's
-     * fields after destruction has no effect on the engine, but reading them
-     * returns stale values. Do not keep references to destroyed sprites.
+     * Creates a runtime object from each object data, in order, and adds them
+     * to the game, as {@link Game.createObject} does for one. Objects in the
+     * same layer draw in the order of the data.
      *
-     * If `sprite` is not found (already destroyed or never added), this is a no-op.
+     * Every object is checked before any is created, so invalid data or an
+     * image key that is not loaded creates nothing.
      *
-     * @param sprite - The sprite instance to destroy, as passed to {@link Game.add}.
+     * @param objects - Object data, such as `design.objects` or `design.findAllByTag("enemy")`. Not a `Design`.
+     * @param options - `add: false` creates the objects without adding them to the game. Default: added.
+     * @returns An {@link ObjectList} of the created objects, to find them by name or tag.
      *
      * @example
      * ```ts
-     * game.destroySprite(enemy); // remove enemy from game
+     * import menuJson from "./menu.design.json" with { type: "json" };
+     * const menu = new Design(menuJson);
+     *
+     * class MenuScene {
+     *   onCreate() {
+     *     const ui = game.createObjectList(menu.objects);
+     *     this.play = ui.findByName("play");
+     *   }
+     *   onUpdate() {
+     *     if (game.isPointerPressedOverSprite(this.play)) start(this.play.data.action);
+     *   }
+     * }
      * ```
      */
-    destroySprite(sprite: Sprite): void;
+    createObjectList(objects: readonly DesignObject[], options?: {
+        add?: boolean;
+    }): ObjectList;
     /**
-     * Returns a **read-only snapshot** of all currently active sprites.
-     * The array is a shallow copy — mutating it has no effect on the engine.
-     * Individual sprite objects in the array are the live instances.
-     *
-     * **Deterministic guarantee:** Sprites appear in creation order within each
-     * layer. The order matches the render order (lower layer = earlier in array).
-     *
-     * @returns A read-only array of active {@link Sprite} instances.
+     * Makes {@link Game.createObject} and {@link Game.createObjectList} build
+     * the design objects tagged `tag` with `builder`, such as an `Enemy` class
+     * of the game's own.
+     *
+     * - The builder returns an instance of the object's type class or a
+     *   subclass of it: {@link ImageSprite} for `image`, {@link EmojiSprite} for
+     *   `emoji`, {@link TextSprite} for `text`, and {@link BackgroundLayer} for
+     *   `background`. Anything else throws an error naming the object.
+     * - The engine then applies every property the data holds, so the file wins
+     *   over the constructor. Properties the data omits keep what the builder set.
+     *   An `emoji` object's `size` cannot be changed after construction, so a
+     *   builder must pass it on, or the creation throws.
+     * - An object matching the builders of two of its tags throws an error
+     *   naming the object and both tags.
+     * - Builders are scene state: {@link Game.reset} clears them, as it clears
+     *   timers, so each scene registers its own in `onCreate()`.
+     *
+     * @param tag - The tag whose objects the builder builds.
+     * @param builder - Receives the object's data and the game, and returns the object, not yet added.
      *
      * @example
      * ```ts
-     * const enemies = game.getSprites().filter(s => s.sprite === "👾");
+     * class Enemy extends ImageSprite {
+     *   update(dt) { this.x += this.data.speed * dt; }
+     * }
+     *
+     * class Level1Scene {
+     *   onCreate() {
+     *     game.registerBuilderByTag("enemy", (obj, game) => new Enemy(game, obj.imageKey));
+     *     this.enemies = game.createObjectList(level1.findAllByTag("enemy")).objects;
+     *   }
+     * }
      * ```
      */
-    getSprites(): readonly Sprite[];
+    registerBuilderByTag(tag: string, builder: ObjectBuilder): void;
     /**
      * Tests whether two sprites overlap using **Axis-Aligned Bounding Box (AABB)**
      * 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.
@@ -641,7 +1774,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
@@ -655,6 +1788,57 @@ export declare class Game {
      * ```
      */
     overlapAny(listA: Sprite[], listB: Sprite[]): [Sprite, Sprite] | 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: Sprite, b: Sprite): CollisionInfo | null;
+    /**
+     * 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 `[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.
+     *
+     * @example
+     * ```ts
+     * const hit = game.collideAny([player], floorTiles);
+     * if (hit?.[2].grounded) {
+     *   canJump = true;
+     * }
+     * ```
+     */
+    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.
@@ -695,6 +1879,8 @@ export declare class Game {
      * Use this for continuous pointer actions.
      *
      * **Hold behavior:** returns `true` every frame from press until release.
+     * On a touch screen it follows one finger, as {@link Game.pointerX} does,
+     * so it turns `false` when that finger lifts, even if another is down.
      *
      * @returns `true` if the pointer is currently pressed.
      *
@@ -723,50 +1909,50 @@ export declare class Game {
      * Returns `true` while any active pointer is held down over the target 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
-     * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
-     * screen space.
+     * Pointer hit testing uses the sprite's exact displayed rectangular bounds.
+     * World-space sprites are tested against the current camera scroll. HUD
+     * sprites with `ignoreScroll = true` are tested in screen space. For
+     * anchored {@link TextSprite} instances, the engine first resolves
+     * `anchorX` / `anchorY` into the final rendered center, then tests against
+     * that rectangle.
      *
      * 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.
-     *   Default: `0.5`.
      * @returns `true` if any currently held pointer overlaps the sprite hit area.
      *
      * @example
      * ```ts
-     * if (game.isPointerDownOverSprite(leftButton, 0.72)) {
+     * if (game.isPointerDownOverSprite(leftButton)) {
      *   player.x -= 200 * dt;
      * }
      * ```
      */
-    isPointerDownOverSprite(sprite: Sprite | null | undefined, radiusScale?: number): 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.
      *
-     * Pointer hit testing uses a circular area centered on the sprite. The radius
-     * is `sprite.size * radiusScale`. World-space sprites are tested against the
-     * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
-     * screen space.
+     * Pointer hit testing uses the sprite's exact displayed rectangular bounds.
+     * World-space sprites are tested against the current camera scroll. HUD
+     * sprites with `ignoreScroll = true` are tested in screen space. For
+     * anchored {@link TextSprite} instances, the engine first resolves
+     * `anchorX` / `anchorY` into the final rendered center, then tests against
+     * that rectangle.
      *
      * 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.
-     *   Default: `0.5`.
      * @returns `true` if any pointer began pressing this frame over the sprite hit area.
      *
      * @example
      * ```ts
-     * if (game.isPointerPressedOverSprite(startButton, 0.8)) {
+     * if (game.isPointerPressedOverSprite(startButton)) {
      *   startGame();
      * }
      * ```
      */
-    isPointerPressedOverSprite(sprite: Sprite | null | undefined, radiusScale?: number): boolean;
+    isPointerPressedOverSprite(sprite: Sprite | null | undefined): boolean;
     /**
      * Returns a read-only snapshot of all currently active pointers.
      *
@@ -784,7 +1970,7 @@ export declare 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);
      * }
      * ```
      */
@@ -793,29 +1979,29 @@ export declare class Game {
      * Returns a read-only snapshot of all active pointers currently overlapping
      * 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
-     * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
-     * screen space.
+     * Pointer hit testing uses the sprite's exact displayed rectangular bounds.
+     * World-space sprites are tested against the current camera scroll. HUD
+     * sprites with `ignoreScroll = true` are tested in screen space. For
+     * anchored {@link TextSprite} instances, the engine first resolves
+     * `anchorX` / `anchorY` into the final rendered center, then tests against
+     * that rectangle.
      *
      * Use this when you need more than a boolean result, such as reading the exact
      * 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.
-     *   Default: `0.5`.
      * @returns A read-only array of active pointer snapshots currently over the sprite.
      *
      * @example
      * ```ts
-     * const touches = game.getPointersOverSprite(joystickBase, 1.0);
+     * const touches = game.getPointersOverSprite(joystickBase);
      * if (touches.length > 0) {
      *   const p = touches[0];
      *   const dx = p.x - joystickBase.x;
      * }
      * ```
      */
-    getPointersOverSprite(sprite: Sprite | null | undefined, radiusScale?: number): readonly PointerInfo[];
+    getPointersOverSprite(sprite: Sprite | null | undefined): readonly PointerInfo[];
     /**
      * Returns `true` when the current device appears to be mobile/touch-first.
      *
@@ -835,16 +2021,64 @@ export declare class Game {
      * ```
      */
     isMobileDevice(): boolean;
+    /**
+     * Plays a sound loaded with {@link Game.loadSound} or an asset file's
+     * `sound` entry, and returns its {@link SoundPlayback}.
+     *
+     * Plays overlap: playing a sound that is already playing starts another
+     * play of it. Keep the returned playback to pause, resume, or stop it, such
+     * as the game's music. A one-shot play stops by itself when it ends; a
+     * looping one plays until stopped.
+     *
+     * - **Before the first tap.** Browsers keep a page silent until the player
+     *   taps, clicks, or presses a key. A looping sound started earlier, such as
+     *   music started in a scene's `onCreate()`, waits and begins with that
+     *   first gesture. A one-shot sound played earlier is dropped, and its
+     *   playback is returned already stopped.
+     * - **Scenes.** {@link Game.reset} and {@link Game.transitionTo} do not stop
+     *   sounds. Stop the music yourself when a scene should change it.
+     * - **Hidden page.** Every sound pauses while the page is hidden, and
+     *   continues when it is shown again.
+     *
+     * Throws an error naming the key when no sound is loaded under it.
+     *
+     * @param key - A key loaded with {@link Game.loadSound} or an asset file.
+     * @param options - `loop` to repeat until stopped, and `volume` from `0` to `1`.
+     *
+     * @example
+     * ```ts
+     * game.playSound("jump");
+     * const music = game.playSound("theme", { loop: true, volume: 0.6 });
+     * music.pause();
+     * music.resume();
+     * music.stop();
+     * ```
+     */
+    playSound(key: string, options?: PlaySoundOptions): SoundPlayback;
+    /**
+     * Stops every sound playing from a file, such as music and effects started
+     * with {@link Game.playSound}. Synthesized tones are not affected.
+     *
+     * @example
+     * ```ts
+     * game.stopAllSounds();
+     * ```
+     */
+    stopAllSounds(): void;
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **Square wave only.** MinimoJS does not support audio files, samples,
-     * or other waveforms. Only procedural square-wave tones.
+     * **Square wave only.** This synthesizes a tone and needs no file. To play
+     * a recorded sound, load it with {@link Game.loadSound} and play it with
+     * {@link Game.playSound}.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in
      * response to user input or a game event triggered by input.
      *
+     * If you need a melody/sequence, use {@link Game.soundSequence} instead of
+     * multiple `sound()` calls in the same frame.
+     *
      * The tone fades out exponentially over `durationMs` to avoid clicks.
      *
      * @param freq - Frequency in Hz. Middle C = 261.6. Typical range: 100–4000 Hz.
@@ -858,6 +2092,20 @@ export declare class Game {
      * ```
      */
     sound(freq: number, durationMs: number): void;
+    /**
+     * Plays multiple square-wave tones in strict sequence.
+     *
+     * Each tuple is `[frequencyHz, durationMs]`. The next tone starts when the
+     * previous one ends.
+     *
+     * @param tones - Tone tuples in playback order.
+     *
+     * @example
+     * ```ts
+     * game.soundSequence([660, 80], [820, 90], [980, 110], [1180, 150]);
+     * ```
+     */
+    soundSequence(...tones: Array<readonly [number, number]>): void;
     /**
      * Animates a sprite's {@link Sprite.alpha} from its current value to `to`
      * over `durationMs` milliseconds using **linear interpolation**.
@@ -906,6 +2154,289 @@ export declare class Game {
      * ```
      */
     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 EmojiSprite.displaySize} and ignore the deform result.
+     *
+     * `pivotX` / `pivotY` are normalized anchors in the sprite's square display box:
+     * - `0` = left/top
+     * - `0.5` = center
+     * - `1` = right/bottom
+     *
+     * For example, `pivotY = 1` keeps the bottom visually pinned while squashing
+     * or stretching, which is useful for floor-contact animation.
+     *
+     * Like other MinimoJS animations, this animates from the sprite's current
+     * deform state to the requested target and leaves the final result applied.
+     *
+     * @param sprite - The sprite to deform.
+     * @param toScaleX - Target horizontal deform scale. `1` = unchanged.
+     * @param toScaleY - Target vertical deform scale. `1` = unchanged.
+     * @param pivotX - Horizontal pivot in normalized `[0, 1]` sprite space.
+     * @param pivotY - Vertical pivot in normalized `[0, 1]` sprite space.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     *
+     * @example
+     * ```ts
+     * game.animateDeform(player, 1.18, 0.85, 0.5, 1, 90, () => {
+     *   game.animateDeform(player, 1, 1, 0.5, 1, 120);
+     * });
+     * ```
+     */
+    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.
+     *
+     * This is equivalent to animating toward a wider, shorter visual pose using
+     * {@link Game.animateDeform}. `pivotY = 1` is the common floor-anchored case.
+     *
+     * @param sprite - The sprite to squash.
+     * @param pivotY - Vertical pivot in normalized `[0, 1]` sprite space.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     */
+    animateSquash(sprite: Sprite, pivotY: number, durationMs: number, onComplete?: () => void): void;
+    /**
+     * Convenience helper that stretches a sprite around its horizontal center.
+     *
+     * This is equivalent to animating toward a narrower, taller visual pose using
+     * {@link Game.animateDeform}. `pivotY = 1` is the common floor-anchored case.
+     *
+     * @param sprite - The sprite to stretch.
+     * @param pivotY - Vertical pivot in normalized `[0, 1]` sprite space.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     */
+    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.
+     *
+     * Internally this runs two deform animations back-to-back using
+     * {@link Game.animateDeform}.
+     *
+     * @param sprite - The sprite to pulse.
+     * @param scale - Peak uniform scale reached midway through the pulse. `1` leaves the sprite unchanged.
+     * @param durationMs - Total pulse duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked after the sprite returns to neutral.
+     *
+     * @example
+     * ```ts
+     * game.animatePulse(coin, 1.25, 220);
+     * ```
+     */
+    animatePulse(sprite: Sprite, scale: number, durationMs: number, onComplete?: () => void): void;
+    /**
+     * Applies a decaying screen-space shake to a sprite without changing its
+     * logical position.
+     *
+     * This is a render-only effect. Physics, collisions, and the sprite's
+     * `x` / `y` values are not modified.
+     *
+     * @param sprite - The sprite to shake.
+     * @param intensity - Maximum shake offset in pixels.
+     * @param durationMs - Duration of the shake in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the shake ends.
+     *
+     * @example
+     * ```ts
+     * game.animateShake(player, 18, 300);
+     * ```
+     */
+    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.
+     *
+     * This animation writes directly to {@link Sprite.x} / {@link Sprite.y} while
+     * it is active.
+     *
+     * @param sprite - The sprite to bounce.
+     * @param height - Peak bounce height in pixels.
+     * @param durationMs - Total bounce duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the bounce ends.
+     *
+     * @example
+     * ```ts
+     * game.animateBounce(ball, 120, 600);
+     * ```
+     */
+    animateBounce(sprite: Sprite, height: number, durationMs: number, onComplete?: () => void): void;
+    /**
+     * Moves a sprite upward and back down with a smooth sine-shaped float motion.
+     *
+     * This animation writes directly to {@link Sprite.x} / {@link Sprite.y} while
+     * it is active.
+     *
+     * @param sprite - The sprite to float.
+     * @param distance - Maximum upward travel in pixels.
+     * @param durationMs - Total float duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the float ends.
+     *
+     * @example
+     * ```ts
+     * game.animateFloat(balloon, 90, 1200);
+     * ```
+     */
+    animateFloat(sprite: Sprite, distance: number, durationMs: number, onComplete?: () => void): void;
+    /**
+     * Toggles a sprite's rendered opacity on and off a fixed number of times.
+     *
+     * This is a render-only effect. The sprite remains present in the world and
+     * keeps receiving physics updates while blinking.
+     *
+     * @param sprite - The sprite to blink.
+     * @param times - Number of visible/invisible toggle cycles.
+     * @param durationMs - Total blink duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when blinking ends.
+     *
+     * @example
+     * ```ts
+     * game.animateBlink(player, 4, 700);
+     * ```
+     */
+    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.
+     *
+     * This is a render-only effect and does not change the sprite's logical
+     * position or collision state.
+     *
+     * @param sprite - The sprite to flicker.
+     * @param durationMs - Total flicker duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the flicker ends.
+     *
+     * @example
+     * ```ts
+     * game.animateFlicker(ghost, 900);
+     * ```
+     */
+    animateFlicker(sprite: Sprite, durationMs: number, onComplete?: () => void): void;
+    /**
+     * Moves a sprite from its current position to a target position along a
+     * parabolic arc.
+     *
+     * This animation writes directly to {@link Sprite.x} / {@link Sprite.y} while
+     * it is active.
+     *
+     * @param sprite - The sprite to move.
+     * @param toX - Destination X position in world space.
+     * @param toY - Destination Y position in world space.
+     * @param arcHeight - Maximum height of the arc above the linear path, in pixels.
+     * @param durationMs - Total arc duration in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the arc ends.
+     *
+     * @example
+     * ```ts
+     * game.animateArc(coin, player.x, player.y, 80, 420);
+     * ```
+     */
+    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.
+     *
+     * This is a render-only effect. Trail ghosts are not real sprites and do not
+     * appear in {@link Game.getSprites}, collide, or receive physics.
+     *
+     * @param sprite - The sprite to sample for trail ghosts.
+     * @param options - Optional trail tuning values.
+     * @param onComplete - Optional callback invoked when the emitter stops spawning ghosts.
+     *
+     * @example
+     * ```ts
+     * game.animateTrail(player, { durationMs: 300, spacingMs: 30, fadeMs: 180 });
+     * ```
+     */
+    animateTrail(sprite: Sprite, options?: TrailOptions, onComplete?: () => void): void;
+    /**
+     * Breaks a sprite into visual pieces that burst outward from its current
+     * rendered appearance.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and do
+     * not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * By default, the original sprite is destroyed immediately after the explosion
+     * effect is spawned. Set `destroySprite: false` to hide the sprite during the
+     * effect and restore it when the explosion ends.
+     *
+     * @param sprite - The sprite to explode.
+     * @param options - Optional explosion tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     *
+     * @example
+     * ```ts
+     * game.animateExplode(enemy, { rows: 4, cols: 4, durationMs: 650, speed: 320 });
+     * ```
+     */
+    animateExplode(sprite: Sprite, options?: ExplodeOptions, onComplete?: () => void): void;
+    /**
+     * Spawns visual pieces around a sprite and converges them back into its
+     * current rendered appearance.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * The original sprite is hidden while the assembly plays and is restored when
+     * the effect finishes.
+     *
+     * @param sprite - The sprite to assemble.
+     * @param options - Optional assembly tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateAssemble(sprite: Sprite, options?: AssembleOptions, onComplete?: () => void): void;
+    /**
+     * Breaks a sprite apart locally inside its own bounds using a directional
+     * dissolve sweep.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * By default, the original sprite is destroyed immediately after the effect
+     * is spawned. Set `destroySprite: false` to leave the sprite hidden instead.
+     *
+     * @param sprite - The sprite to disintegrate.
+     * @param options - Optional disintegration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateDisintegrate(sprite: Sprite, options?: DisintegrateOptions, onComplete?: () => void): void;
+    /**
+     * Reconstructs a sprite locally inside its own bounds using a directional
+     * integration sweep.
+     *
+     * This is a render-only effect. The spawned pieces are not real sprites and
+     * do not appear in {@link Game.getSprites}, receive physics, or collide.
+     *
+     * The original sprite is hidden while the integration plays and is restored
+     * when the effect finishes.
+     *
+     * @param sprite - The sprite to integrate.
+     * @param options - Optional integration tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateIntegrate(sprite: Sprite, options?: IntegrateOptions, onComplete?: () => void): void;
+    /**
+     * Reveals or covers a sprite with a directional wipe mask.
+     *
+     * This is a render-only effect that captures the sprite's current appearance
+     * and animates a clipping region over that snapshot.
+     *
+     * For `mode: "reveal"`, the original sprite is hidden during the wipe and is
+     * restored when the effect finishes.
+     *
+     * For `mode: "cover"`, the effect hides the sprite over time. If
+     * `destroySprite` is omitted or `true`, the sprite is destroyed immediately
+     * after the wipe starts and only the wipe snapshot remains visible.
+     *
+     * @param sprite - The sprite to wipe.
+     * @param options - Optional wipe tuning values.
+     * @param onComplete - Optional callback invoked when the effect finishes.
+     */
+    animateWipe(sprite: 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
@@ -952,18 +2483,26 @@ export declare class Game {
      */
     clearTimer(id: number): void;
     /**
-     * Draws text on screen as a **screen-space overlay** this frame.
+     * Draws text on screen as a **simple screen-space overlay** this frame.
      *
      * **Overlay behavior:** Text is drawn in canvas/screen space — it ignores
      * `scrollX` / `scrollY`. Position `(0, 0)` is always the top-left of the canvas.
-     * Use this for HUD elements: score, lives, timer, debug info.
+     * Use this for lightweight HUD elements: score, lives, timer, debug info.
      *
      * **Per-frame:** `drawText` must be called every frame to keep text visible.
      * 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 always uses `monospace`. Use {@link TextSprite} for any
+     * other family.
+     *
+     * Prefer {@link TextSprite} for UI buttons or labels that need persistent
+     * 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 EmojiSprite} over
+     * {@link TextSprite}. Emoji-only buttons do not benefit from text padding and
+     * usually fit more naturally in the sprite pipeline.
      *
      * @param text - The string to render. Supports emoji and Unicode.
      * @param x - X position in **screen space** (pixels from canvas left edge).
@@ -1000,6 +2539,25 @@ export declare class Game {
      * ```
      */
     clearSpriteCache(): void;
+    /**
+     * Registers a web font family that must be loaded before the first frame.
+     *
+     * Call this before {@link Game.start}, typically right after constructing the
+     * game or inside {@link Game.onPreload}. MinimoJS waits for every registered
+     * font via `document.fonts.load(...)` before rendering anything. Host
+     * environments may also pre-register fonts by setting
+     * `globalThis.__MINIMO_WEB_FONT_REQUIREMENTS__` before your game code runs.
+     *
+     * The font itself must still be declared by your page (for example with a
+     * `<link rel="stylesheet">` in `index.html`). MinimoJS only waits for it.
+     *
+     * @example
+     * ```ts
+     * game.requireFont('"Press Start 2P"');
+     * game.requireFont('"Bangers"', { weight: "700" });
+     * ```
+     */
+    requireFont(family: string, options?: FontRequirementOptions): void;
     /**
      * Returns a pseudo-random floating-point number in the range `[0, 1)`.
      * Delegates to `Math.random()`.
@@ -1021,9 +2579,12 @@ export declare class Game {
      * Performs a full engine state reset to enable scene switching.
      *
      * **Cleared by reset:**
+     * - All background layers
      * - All sprites (equivalent to calling {@link Game.destroySprite} on every sprite)
      * - All timers (regardless of repeat state)
      * - All running animations
+     * - All active explosion effects
+     * - All active trail effects
      * - All pending text overlays
      * - Scroll position (`scrollX = 0`, `scrollY = 0`)
      * - Per-frame input state (pressed keys, pressed pointer)
@@ -1036,50 +2597,95 @@ export declare class Game {
      * - Canvas dimensions
      * - AudioContext
      *
-     * After clearing, `reset()` immediately calls `onCreate()` so your callback
-     * can rebuild the new scene synchronously.
+     * After clearing, `reset()` immediately calls the active scene's
+     * `onCreate()` (or legacy {@link Game.onCreate} if no scene is active) so it
+     * can rebuild synchronously.
+     *
+     * The exception is a scene whose {@link IScene.onPreload} registers images
+     * that are not loaded yet. Then the current scene freezes and dims under a progress
+     * ring, nothing is cleared until the images load, and `reset()` returns
+     * before the scene is rebuilt; its `onCreate()` runs once they have loaded.
+     * A `reset()` called while a scene is loading is ignored.
+     *
+     * @param scene - Optional new scene to make active before rebuilding.
      *
      * @example
      * ```ts
-     * // Switch from gameplay to game-over screen
-     * function gameOver() {
-     *   game.reset(); // onCreate() is called here, rebuild inside it
-     * }
-     *
-     * game.onCreate = () => {
-     *   // Scene init
-     *   const skull = new Sprite("💀");
-     *   skull.x = 400; skull.y = 300; skull.size = 96;
-     *   game.add(skull);
-     *   game.addTimer(3000, false, () => game.reset()); // auto-restart
-     * };
+     * class GameOverScene {
+     *   onCreate() {
+     *     const skull = new EmojiSprite("💀", 400, 300, 96);
+     *     game.add(skull);
+     *     game.addTimer(3000, false, () => game.reset());
+     *   }
+   * }
+   *
+     * game.reset(new GameOverScene());
      * ```
      */
-    reset(): void;
+    reset(scene?: IScene): void;
+    /**
+     * Changes to a new scene using a full-screen transition between frozen scene
+     * snapshots.
+     *
+     * `transitionTo()` does not change the behavior of {@link Game.reset}. It
+     * captures the current scene as a snapshot, rebuilds the target scene
+     * immediately, captures the new scene as another snapshot, and then animates
+     * between those two images for the requested duration.
+     *
+     * While the transition is active, gameplay updates are paused.
+     *
+     * If the target scene's {@link IScene.onPreload} registers images that are
+     * not loaded yet, the current scene first freezes and dims under a progress ring
+     * until they load, and the transition plays after that. `transitionTo()`
+     * then returns before the target scene exists; continue in its
+     * `onCreate()` or in `onComplete`. If the player declines to retry failed
+     * images, the game stays on the current scene and `onComplete` is not
+     * called.
+     *
+     * A call made while a transition plays or a scene loads is ignored.
+     *
+     * If the game loop is not running yet, this falls back to
+     * {@link Game.reset}.
+     *
+     * @param scene - Target scene to make active.
+     * @param options - Transition style and optional tuning values.
+     * @param onComplete - Optional callback invoked when the transition finishes.
+     */
+    transitionTo(scene: IScene, options: SceneTransitionOptions, onComplete?: () => void): void;
     /**
      * Starts the `requestAnimationFrame` game loop.
      * Safe to call multiple times — does nothing if already running.
-     * If this is the first start (or after a reset), `onCreate()` is called
-     * before the first frame.
-     *
-     * The loop calls `onUpdate` once per frame, then renders all sprites and
-     * text overlays. Order per frame:
+     * On the first start, MinimoJS runs {@link Game.onPreload} and the active
+     * scene's {@link IScene.onPreload}, loads the images they queued while
+     * showing a thin loading line, and waits for all fonts registered via
+     * {@link Game.requireFont}. After that, the active scene's `onCreate()` is
+     * called before the first frame.
+     *
+     * The loop calls the active scene's `onUpdate(dt)` (or legacy
+     * {@link Game.onUpdate}) once per frame, then renders all sprites and text
+     * overlays. Order per frame:
      * 1. Accumulate timer elapsed time; fire ready callbacks.
      * 2. Advance animations (linear interpolation).
-     * 3. Apply gravity to sprite velocities.
-     * 4. Apply velocities to sprite positions.
-     * 5. Call `onUpdate(dt)`.
-     * 6. Render sprites (sorted by layer) with scroll offset.
-     * 7. Render text overlays (screen space, on top of sprites).
-     * 8. Clear per-frame input state.
+     * 3. Advance active piece and wipe effects.
+     * 4. Apply gravity to sprite velocities.
+     * 5. Apply velocities to sprite positions.
+     * 6. Call `onUpdate(dt)`.
+     * 7. Advance active trail effects.
+     * 8. Render sprites/effects (with scroll offset).
+     * 9. Render text overlays (screen space, on top of sprites).
+     * 10. Clear per-frame input state.
      *
      * @example
      * ```ts
-     * game.onUpdate = (dt) => { ... };
-     * game.start();
+     * class DemoScene {
+     *   onCreate() {}
+     *   onUpdate(dt: number) {}
+     * }
+     *
+     * game.start(new DemoScene());
      * ```
      */
-    start(): void;
+    start(scene?: IScene): void;
     /**
      * Stops the game loop. The canvas retains its last rendered frame.
      * Call {@link Game.start} to resume.