minimojs 1.0.0-alpha.10 → 1.0.0-alpha.11

package/README.md

@@ -24,7 +24,7 @@ This README is intentionally high-level. It explains what the project is and how
 
 ## What It Intentionally Avoids
 
-- Scene manager/ECS architecture
+- Heavy scene-manager/ECS architecture
 - Heavy physics engine features
 - Image spritesheets and asset pipelines
 - Nested subsystem APIs
@@ -39,26 +39,32 @@ npm install minimojs
 ## Quick Start
 
 ```ts
-import { Game, Sprite } from "minimojs";
+import { Game, Sprite, type IScene } from "minimojs";
 
 const game = new Game(800, 600);
 game.gravityY = 980;
 
-const player = game.add(new Sprite("🐢", 400, 300, 48));
-player.x = 400;
-player.y = 300;
-player.gravityScale = 1;
+class DemoScene implements IScene {
+  private player: Sprite | null = null;
 
-game.onUpdate = (dt) => {
-  if (game.isKeyDown("ArrowLeft")) player.vx = -200;
-  else if (game.isKeyDown("ArrowRight")) player.vx = 200;
-  else player.vx = 0;
+  onCreate() {
+    this.player = game.add(new Sprite("🐢", 400, 300, 48));
+    this.player.gravityScale = 1;
+  }
 
-  if (game.isKeyPressed(" ")) player.vy = -600;
-  game.drawText("MinimoJS", 10, 10, 16);
-};
+  onUpdate(dt: number) {
+    if (!this.player) return;
 
-game.start();
+    if (game.isKeyDown("ArrowLeft")) this.player.vx = -200;
+    else if (game.isKeyDown("ArrowRight")) this.player.vx = 200;
+    else this.player.vx = 0;
+
+    if (game.isKeyPressed(" ")) this.player.vy = -600;
+    game.drawText("MinimoJS", 10, 10, 16);
+  }
+}
+
+game.start(new DemoScene());
 ```
 
 Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTML if you want pixel-font styling.
@@ -71,6 +77,8 @@ Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTM
 - `examples/super-minimo-bros/`
 - `examples/scale-shift/`
 - `examples/background-desert/`
+- `examples/scene-lab/`
+- `examples/image-sprite-sad-plush/`
 - `examples/animations/`
 
 Run locally from the `minimojs` directory:

package/dist/internal/RenderSystem.js

@@ -159,7 +159,9 @@ export class RenderSystem {
             return cached;
         const surface = this.isTextSprite(sprite)
             ? this.createTextSurface(sprite)
-            : this.createEmojiSurface(this.asEmojiSprite(sprite));
+            : this.isImageSprite(sprite)
+                ? this.createImageSurface(sprite)
+                : this.createEmojiSurface(this.asEmojiSprite(sprite));
         this._surfaceCache.set(cacheKey, surface);
         return surface;
     }
@@ -254,9 +256,28 @@ export class RenderSystem {
         }
         return canvas;
     }
+    createImageSurface(sprite) {
+        const image = sprite.game?.getImage(sprite.imageKey);
+        if (!image) {
+            throw new Error(`MinimoJS: Image '${sprite.imageKey}' is not loaded.`);
+        }
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.max(1, image.naturalWidth || image.width);
+        canvas.height = Math.max(1, image.naturalHeight || image.height);
+        const ctx = canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("MinimoJS: Could not acquire an image rendering context.");
+        }
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
+        return canvas;
+    }
     isTextSprite(sprite) {
         return "text" in sprite && "fontFamily" in sprite && "fontSize" in sprite;
     }
+    isImageSprite(sprite) {
+        return "imageKey" in sprite && "setTexture" in sprite;
+    }
     asEmojiSprite(sprite) {
         if ("sprite" in sprite && "size" in sprite) {
             return sprite;

package/dist/internal/SpriteSystem.js

@@ -1,10 +1,12 @@
 /** @internal */
 export class SpriteSystem {
-    constructor(animationSystem) {
+    constructor(animationSystem, game) {
         this.animationSystem = animationSystem;
+        this.game = game;
         this._sprites = [];
     }
     add(sprite) {
+        sprite._setGame(this.game);
         this._sprites.push(sprite);
         return sprite;
     }

package/dist/minimo.d.ts

@@ -56,6 +56,25 @@ export interface TrailOptions {
  * - `"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 interface IScene {
+    /**
+     * Called when the scene is created, before the first frame and again after
+     * each {@link Game.reset} that targets this scene.
+     */
+    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.
  *
@@ -64,6 +83,11 @@ export type BackgroundFit = "none" | "stretch" | "contain" | "cover";
  * engine.
  */
 export declare abstract class BaseSprite {
+    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`.
@@ -233,7 +257,7 @@ export declare class Sprite extends BaseSprite {
      * 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`.
@@ -248,9 +272,47 @@ export declare class Sprite extends BaseSprite {
     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 BaseSprite.scale}.
+ */
+export declare class ImageSprite extends BaseSprite {
+    private _imageKey;
+    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 - Preloaded image key previously registered with {@link Game.loadImage}.
+     * @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 preloaded image key to render.
+     */
+    setTexture(imageKey: string): void;
+    getRenderCacheKey(): string;
+    private getResolvedImage;
+    private assertTextureAvailable;
+}
 /**
  * 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 Sprite}. Emoji-only
+ * buttons usually behave better as sprites because they do not need text
+ * padding/layout and their bounds match the rendered emoji more directly.
  */
 export declare class TextSprite extends BaseSprite {
     private static _measurementCanvas;
@@ -491,6 +553,11 @@ export interface CollisionInfo {
  * If you use additional families, register them with {@link Game.requireFont}
  * before calling {@link Game.start}.
  *
+ * 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`.
@@ -636,10 +703,10 @@ export interface CollisionInfo {
  *
  * ---
  *
- * ## 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}.
  *
@@ -651,25 +718,30 @@ export interface CollisionInfo {
  * - 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("💀", 400, 300, 96);
- *   game.add(skull);
- * };
- *
- * game.onUpdate = (dt) => {
- *   // normal per-frame update
- * };
- *
- * game.start(); // calls onCreate() once before first frame
+ * class SkullScene implements IScene {
+ *   onCreate() {
+ *     const skull = new Sprite("💀", 400, 300, 96);
+ *     game.add(skull);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // normal per-frame update
+ *   }
+ * }
+ *
+ * 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.
+ *
  * ---
  *
  * ## Sprite Lifecycle Ownership
@@ -686,7 +758,7 @@ export interface CollisionInfo {
  * ## 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
@@ -695,7 +767,6 @@ export interface CollisionInfo {
  * - Parallax layers
  * - Multiple cameras
  * - Full physics engine (only basic explicit AABB collision helpers are provided)
- * - Image sprites (PNG, SVG, canvas, etc.) as gameplay actors
  * - `setTimeout` or `setInterval`
  */
 export declare class Game {
@@ -819,10 +890,10 @@ export declare class Game {
      */
     onPreload: (() => void) | null;
     /**
-     * Scene creation callback.
+     * 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
@@ -837,7 +908,9 @@ export declare class Game {
     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`.
@@ -852,6 +925,10 @@ export declare class Game {
      * ```
      */
     onUpdate: ((dt: number) => void) | null;
+    /**
+     * Currently active scene object, if any.
+     */
+    get currentScene(): IScene | null;
     /**
      * Creates a new MinimoJS game instance.
      *
@@ -894,7 +971,7 @@ export declare class Game {
      */
     get pointerY(): number;
     /**
-     * Registers a {@link Sprite} (or subclass instance) with the engine.
+     * Registers a {@link BaseSprite} (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
@@ -903,11 +980,11 @@ export declare class Game {
      * **Ownership:** The game instance takes ownership of the sprite from this
      * point forward. It will appear in {@link Game.getSprites} on the same frame.
      *
-     * **Subclasses:** Any class that extends {@link Sprite} can be passed here.
-     * The engine stores and processes it as a `Sprite`; your custom properties
+     * **Subclasses:** Any class that extends {@link BaseSprite} 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.
+     * @param sprite - A {@link BaseSprite} instance (or subclass) to add.
      * @returns The same sprite instance, for chaining or inline assignment.
      *
      * @example
@@ -922,7 +999,7 @@ export declare class Game {
      *   constructor(x: number, y: number) {
      *     super("👾", x, y, 40);
      *   }
-     * }
+     *   }
      * const enemy = game.add(new Enemy(600, 100));
      * ```
      */
@@ -1650,11 +1727,11 @@ 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`.
@@ -1669,6 +1746,14 @@ export declare class Game {
      * registered with {@link Game.requireFont}. If a font is unavailable, the
      * browser falls back to `monospace`.
      *
+     * 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 Sprite} 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).
      * @param y - Y position in **screen space** (pixels from canvas top edge).
@@ -1762,25 +1847,26 @@ 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.
+     *
+     * @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("💀", 400, 300, 96);
-     *   game.add(skull);
-     *   game.addTimer(3000, false, () => game.reset()); // auto-restart
-     * };
+     * class GameOverScene {
+     *   onCreate() {
+     *     const skull = new Sprite("💀", 400, 300, 96);
+     *     game.add(skull);
+     *     game.addTimer(3000, false, () => game.reset());
+     *   }
+   * }
+   *
+     * game.reset(new GameOverScene());
      * ```
      */
-    reset(): void;
+    reset(scene?: IScene): void;
     /**
      * Starts the `requestAnimationFrame` game loop.
      * Safe to call multiple times — does nothing if already running.
@@ -1788,10 +1874,12 @@ export declare class Game {
      * asset registration, loads queued images, waits for all fonts registered via
      * {@link Game.requireFont}, and only then, if images were queued, shows a
      * default loading screen while those image assets are still loading.
-     * After preload completes, `onCreate()` is called before the first frame.
+     * After preload completes, the active scene's `onCreate()` is called before
+     * the first frame.
      *
-     * The loop calls `onUpdate` once per frame, then renders all sprites and
-     * text overlays. Order per 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. Advance active explosion effects.
@@ -1805,11 +1893,15 @@ export declare class Game {
      *
      * @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.

package/dist/minimo.js

@@ -32,7 +32,7 @@ import { TimerSystem } from "./internal/TimerSystem.js";
  * engine.
  */
 export class BaseSprite {
-    constructor() {
+    constructor(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`.
@@ -137,6 +137,20 @@ export class BaseSprite {
          * Values > 1 amplify gravity; negative values invert it.
          */
         this.gravityScale = 0;
+        this._game = game;
+    }
+    /**
+     * Game instance associated with this sprite, if any.
+     */
+    get game() {
+        return this._game;
+    }
+    /** @internal */
+    _setGame(game) {
+        if (this._game !== null && this._game !== game) {
+            throw new Error("MinimoJS: A sprite cannot be attached to multiple Game instances.");
+        }
+        this._game = game;
     }
     /**
      * Resolved center X used internally by rendering, hit testing, and collisions.
@@ -207,7 +221,7 @@ export class Sprite extends BaseSprite {
      * 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`.
@@ -231,9 +245,86 @@ export class Sprite extends BaseSprite {
         return `emoji:${this.sprite}|size:${this._size}|color:${this.color}`;
     }
 }
+/**
+ * A renderable sprite backed by a preloaded image asset.
+ *
+ * Width and height are always resolved from the current texture. To resize the
+ * sprite visually, use {@link BaseSprite.scale}.
+ */
+export class ImageSprite extends BaseSprite {
+    get imageKey() {
+        return this._imageKey;
+    }
+    get width() {
+        const image = this.getResolvedImage();
+        return image.naturalWidth || image.width;
+    }
+    get height() {
+        const image = this.getResolvedImage();
+        return image.naturalHeight || image.height;
+    }
+    /**
+     * Creates a new image-backed sprite.
+     *
+     * @param game - Game instance used to resolve the texture key.
+     * @param imageKey - Preloaded image key previously registered with {@link Game.loadImage}.
+     * @param 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, imageKey, x = 0, y = 0) {
+        super(game);
+        this._imageKey = imageKey;
+        this.x = x;
+        this.y = y;
+    }
+    /**
+     * Replaces the current texture with another preloaded image.
+     *
+     * @param imageKey - New preloaded image key to render.
+     */
+    setTexture(imageKey) {
+        if (imageKey === this._imageKey)
+            return;
+        this.assertTextureAvailable(imageKey);
+        this._imageKey = imageKey;
+    }
+    getRenderCacheKey() {
+        const image = this.getResolvedImage();
+        return [
+            "image",
+            this._imageKey,
+            image.naturalWidth || image.width,
+            image.naturalHeight || image.height,
+        ].join("|");
+    }
+    getResolvedImage() {
+        this.assertTextureAvailable(this._imageKey);
+        const image = this.game?.getImage(this._imageKey);
+        if (!image) {
+            throw new Error(`MinimoJS: Image '${this._imageKey}' is not loaded.`);
+        }
+        return image;
+    }
+    assertTextureAvailable(imageKey) {
+        if (!this.game) {
+            throw new Error("MinimoJS: ImageSprite requires an associated Game instance.");
+        }
+        if (!this.game.hasImage(imageKey)) {
+            throw new Error(`MinimoJS: Image '${imageKey}' is not loaded.`);
+        }
+    }
+}
 /**
  * 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 Sprite}. Emoji-only
+ * buttons usually behave better as sprites because they do not need text
+ * padding/layout and their bounds match the rendered emoji more directly.
  */
 export class TextSprite extends BaseSprite {
     get width() {
@@ -254,8 +345,8 @@ export class TextSprite extends BaseSprite {
         this.maxWidth = 0;
         this.fixedWidth = 0;
         this.fixedHeight = 0;
-        this.paddingX = 0;
-        this.paddingY = 0;
+        this.paddingX = 2;
+        this.paddingY = 2;
         this.backgroundColor = null;
         this.borderColor = null;
         this.borderWidth = 0;
@@ -579,6 +670,11 @@ export class BackgroundLayer {
  * If you use additional families, register them with {@link Game.requireFont}
  * before calling {@link Game.start}.
  *
+ * 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`.
@@ -724,10 +820,10 @@ export class BackgroundLayer {
  *
  * ---
  *
- * ## 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}.
  *
@@ -739,25 +835,30 @@ export class BackgroundLayer {
  * - 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("💀", 400, 300, 96);
- *   game.add(skull);
- * };
- *
- * game.onUpdate = (dt) => {
- *   // normal per-frame update
- * };
- *
- * game.start(); // calls onCreate() once before first frame
+ * class SkullScene implements IScene {
+ *   onCreate() {
+ *     const skull = new Sprite("💀", 400, 300, 96);
+ *     game.add(skull);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // normal per-frame update
+ *   }
+ * }
+ *
+ * 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.
+ *
  * ---
  *
  * ## Sprite Lifecycle Ownership
@@ -774,7 +875,7 @@ export class BackgroundLayer {
  * ## 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
@@ -783,7 +884,6 @@ export class BackgroundLayer {
  * - Parallax layers
  * - Multiple cameras
  * - Full physics engine (only basic explicit AABB collision helpers are provided)
- * - Image sprites (PNG, SVG, canvas, etc.) as gameplay actors
  * - `setTimeout` or `setInterval`
  */
 export class Game {
@@ -845,10 +945,10 @@ export class Game {
         this._physicsSystem.enabled = value;
     }
     /**
-     * Scene creation callback.
+     * 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
@@ -861,10 +961,16 @@ export class Game {
      * ```
      */
     get onCreate() {
-        return this._loopSystem.onCreate;
+        return this._onCreate;
     }
     set onCreate(callback) {
-        this._loopSystem.onCreate = callback;
+        this._onCreate = callback;
+    }
+    /**
+     * Currently active scene object, if any.
+     */
+    get currentScene() {
+        return this._currentScene;
     }
     // -------------------------------------------------------------------------
     // Constructor
@@ -893,6 +999,8 @@ export class Game {
         /** @internal */ this._isRegisteringPreloadAssets = false;
         /** @internal */ this._hasCompletedPreload = false;
         /** @internal */ this._preloadPromise = null;
+        /** @internal */ this._onCreate = null;
+        /** @internal */ this._currentScene = null;
         /**
          * Horizontal scroll offset of the world camera, in pixels.
          * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -968,7 +1076,9 @@ export class Game {
          */
         this.onPreload = 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`.
@@ -1000,7 +1110,7 @@ export class Game {
         this._timerSystem = new TimerSystem();
         this._animationSystem = new AnimationSystem();
         this._physicsSystem = new PhysicsSystem();
-        this._spriteSystem = new SpriteSystem(this._animationSystem);
+        this._spriteSystem = new SpriteSystem(this._animationSystem, this);
         this._backgroundSystem = new BackgroundSystem();
         this._assetSystem = new AssetSystem();
         this._inputSystem = new InputSystem(this, this._canvas);
@@ -1010,6 +1120,7 @@ export class Game {
         this._explosionSystem = new ExplosionSystem();
         this._trailSystem = new TrailSystem();
         this._loopSystem = new LoopSystem(this._onLoopFrameCallback.bind(this));
+        this._loopSystem.onCreate = this._invokeCreate.bind(this);
         this._inputSystem.bindInputEvents();
         this.requireFont('"Press Start 2P"', {
             sampleText: "Loading... SCORE LIVES GAME OVER YOU WIN",
@@ -1053,7 +1164,7 @@ export class Game {
     // Sprite management
     // -------------------------------------------------------------------------
     /**
-     * Registers a {@link Sprite} (or subclass instance) with the engine.
+     * Registers a {@link BaseSprite} (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
@@ -1062,11 +1173,11 @@ export class Game {
      * **Ownership:** The game instance takes ownership of the sprite from this
      * point forward. It will appear in {@link Game.getSprites} on the same frame.
      *
-     * **Subclasses:** Any class that extends {@link Sprite} can be passed here.
-     * The engine stores and processes it as a `Sprite`; your custom properties
+     * **Subclasses:** Any class that extends {@link BaseSprite} 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.
+     * @param sprite - A {@link BaseSprite} instance (or subclass) to add.
      * @returns The same sprite instance, for chaining or inline assignment.
      *
      * @example
@@ -1081,7 +1192,7 @@ export class Game {
      *   constructor(x: number, y: number) {
      *     super("👾", x, y, 40);
      *   }
-     * }
+     *   }
      * const enemy = game.add(new Enemy(600, 100));
      * ```
      */
@@ -1926,11 +2037,11 @@ export class Game {
     // Text
     // -------------------------------------------------------------------------
     /**
-     * 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`.
@@ -1945,6 +2056,14 @@ export class Game {
      * registered with {@link Game.requireFont}. If a font is unavailable, the
      * browser falls back to `monospace`.
      *
+     * 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 Sprite} 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).
      * @param y - Y position in **screen space** (pixels from canvas top edge).
@@ -2067,25 +2186,29 @@ export 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.
+     *
+     * @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("💀", 400, 300, 96);
-     *   game.add(skull);
-     *   game.addTimer(3000, false, () => game.reset()); // auto-restart
-     * };
+     * class GameOverScene {
+     *   onCreate() {
+     *     const skull = new Sprite("💀", 400, 300, 96);
+     *     game.add(skull);
+     *     game.addTimer(3000, false, () => game.reset());
+     *   }
+   * }
+   *
+     * game.reset(new GameOverScene());
      * ```
      */
-    reset() {
+    reset(scene) {
+        if (scene !== undefined) {
+            this._currentScene = scene;
+        }
         this._backgroundSystem.clearAll();
         this._spriteSystem.clearAll();
         this._timerSystem.clearAll();
@@ -2108,10 +2231,12 @@ export class Game {
      * asset registration, loads queued images, waits for all fonts registered via
      * {@link Game.requireFont}, and only then, if images were queued, shows a
      * default loading screen while those image assets are still loading.
-     * After preload completes, `onCreate()` is called before the first frame.
+     * After preload completes, the active scene's `onCreate()` is called before
+     * the first frame.
      *
-     * The loop calls `onUpdate` once per frame, then renders all sprites and
-     * text overlays. Order per 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. Advance active explosion effects.
@@ -2125,11 +2250,18 @@ export class Game {
      *
      * @example
      * ```ts
-     * game.onUpdate = (dt) => { ... };
-     * game.start();
+     * class DemoScene {
+     *   onCreate() {}
+     *   onUpdate(dt: number) {}
+     * }
+     *
+     * game.start(new DemoScene());
      * ```
      */
-    start() {
+    start(scene) {
+        if (scene !== undefined) {
+            this._currentScene = scene;
+        }
         this.applyGlobalFontRequirements();
         if (this._hasCompletedPreload) {
             this._loopSystem.start();
@@ -2207,7 +2339,9 @@ export class Game {
         this._animationSystem.update(dtMs);
         this._explosionSystem.update(dt, dtMs);
         this._physicsSystem.update(this._spriteSystem.getMutableSprites(), dt);
-        if (this.onUpdate)
+        if (this._currentScene?.onUpdate)
+            this._currentScene.onUpdate(dt);
+        else if (this.onUpdate)
             this.onUpdate(dt);
         this._trailSystem.update(dtMs, this._renderSystem.getSpriteRenderSnapshot.bind(this._renderSystem));
         this._render();
@@ -2215,6 +2349,13 @@ export class Game {
         this._textSystem.clear();
     }
     /** @internal */
+    _invokeCreate() {
+        if (this._currentScene?.onCreate)
+            this._currentScene.onCreate();
+        else
+            this._onCreate?.();
+    }
+    /** @internal */
     waitForDocumentFonts() {
         if (typeof document === "undefined") {
             return Promise.resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Emoji-only sprites, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",