minimojs 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/game.js

@@ -0,0 +1,1105 @@
+import { playSquareTone } from "./audio.js";
+import { scheduleAnimation, updateAnimations } from "./animations.js";
+import { bindInputEvents, collectPointers, createInputState, getPointersOverSprite, isPointerDownOverSprite, isPointerPressedOverSprite, resetTransientInput, } from "./input.js";
+import { updatePhysics } from "./physics.js";
+import { applyPageBackground, applyResponsiveCanvasLayout, renderFrame, } from "./render.js";
+import { updateTimers } from "./timers.js";
+// ---------------------------------------------------------------------------
+// Game
+// ---------------------------------------------------------------------------
+/**
+ * # MinimoJS v1 — AI Agent Integration Guide
+ *
+ * `Game` is the single entry point to the entire engine.
+ * Every feature — sprites, input, physics, sound, timers, text — is accessed
+ * directly on the `game` object. There are no sub-systems or nested namespaces.
+ *
+ * ---
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { Game, Sprite } from "minimojs";
+ *
+ * const game = new Game(800, 600);
+ *
+ * const player = new Sprite("🐢");
+ * player.x = 400;
+ * player.y = 500;
+ * player.size = 48;
+ * game.add(player);
+ *
+ * game.onUpdate = (dt) => {
+ *   if (game.isKeyDown("ArrowLeft"))  player.vx = -200;
+ *   else if (game.isKeyDown("ArrowRight")) player.vx = 200;
+ *   else player.vx = 0;
+ *
+ *   game.drawText(`x: ${Math.round(player.x)}`, 10, 10, 16);
+ * };
+ *
+ * game.start();
+ * ```
+ *
+ * ---
+ *
+ * ## Engine Philosophy
+ *
+ * MinimoJS is **flat, deterministic, and ultra-minimal**. It is intentionally
+ * designed to be easy for AI agents to reason about. The full public API is
+ * exposed through a single entrypoint. There are no plugins, no registries,
+ * no event buses.
+ *
+ * ---
+ *
+ * ## 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.
+ *
+ * ---
+ *
+ * ## Responsive Canvas
+ *
+ * The engine auto-centers the canvas on the page and responsively scales it
+ * to use as much viewport space as possible while preserving aspect ratio.
+ *
+ * ---
+ *
+ * ## 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.
+ *
+ * ---
+ *
+ * ## Degrees-Only Rotation
+ *
+ * ALL rotations are in **degrees**. Never use radians.
+ * `0` = upright, `90` = 90° clockwise, `-90` = 90° counter-clockwise.
+ * This applies to {@link Sprite.rotation} and {@link Game.animateRotation}.
+ *
+ * ---
+ *
+ * ## Milliseconds-Only Timing
+ *
+ * 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}.
+ *
+ * The `dt` parameter in {@link Game.onUpdate} is an exception — it is in
+ * **seconds** for convenient velocity math (`position += velocity * dt`).
+ *
+ * ---
+ *
+ * ## rAF-Only Loop
+ *
+ * The engine loop runs exclusively on `requestAnimationFrame`.
+ * There are **no** `setTimeout` or `setInterval` calls anywhere.
+ * All timers, animations, and physics are driven by the rAF loop.
+ * Delta time is automatically capped at 100ms to prevent spiral-of-death.
+ *
+ * ---
+ *
+ * ## Gravity Model
+ *
+ * Gravity is a constant per-frame acceleration in pixels/second².
+ * Set {@link Game.gravityX} and {@link Game.gravityY} to define the direction.
+ * For standard downward gravity: `game.gravityY = 980`.
+ *
+ * Per-sprite effect is controlled by {@link Sprite.gravityScale}:
+ * - `gravityScale = 0` (default): sprite is unaffected by gravity.
+ * - `gravityScale = 1`: full gravity applied.
+ * - `gravityScale = 0.5`: half gravity.
+ *
+ * Each frame: `vx += gravityX * gravityScale * dt`, same for Y.
+ *
+ * ---
+ *
+ * ## Timer System
+ *
+ * Timers are rAF-driven countdown callbacks — NOT `setTimeout`.
+ * They accumulate elapsed time each frame and fire when the delay is reached.
+ *
+ * - {@link Game.addTimer}`(delayMs, repeat, callback)` — schedule a callback.
+ * - {@link Game.clearTimer}`(id)` — cancel a scheduled timer.
+ * - ALL timers are cleared on {@link Game.reset}.
+ *
+ * ```ts
+ * // Fire once after 2 seconds
+ * game.addTimer(2000, false, () => { player.sprite = "💥"; });
+ *
+ * // Repeat every 1 second
+ * const id = game.addTimer(1000, true, () => { spawnEnemy(); });
+ * // Later:
+ * game.clearTimer(id);
+ * ```
+ *
+ * ---
+ *
+ * ## Scene Initialization with `onCreate`
+ *
+ * MinimoJS has NO scene system. Use {@link Game.onCreate} to build a scene.
+ * The engine calls `onCreate`:
+ * - Once before the first frame (when {@link Game.start} is called).
+ * - Again after each {@link Game.reset}.
+ *
+ * `reset()` clears:
+ * - All sprites
+ * - All timers
+ * - All running animations
+ * - All text overlays
+ * - 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.
+ *
+ * ```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);
+ * };
+ *
+ * game.onUpdate = (dt) => {
+ *   // normal per-frame update
+ * };
+ *
+ * game.start(); // calls onCreate() once before first frame
+ * // later:
+ * game.reset(); // clears + calls onCreate() again
+ * ```
+ *
+ * ---
+ *
+ * ## Sprite Lifecycle Ownership
+ *
+ * The `Game` instance owns all sprites.
+ * - Create sprites with {@link Game.add}.
+ * - Destroy sprites with {@link Game.destroySprite}.
+ * - Read the live sprite list with {@link Game.getSprites} (returns a read-only snapshot).
+ * - Do NOT hold references to destroyed sprites.
+ * - All sprites are destroyed on {@link Game.reset}.
+ *
+ * ---
+ *
+ * ## Forbidden Features
+ *
+ * The following do NOT exist in MinimoJS v1. Do NOT attempt to use them:
+ * - Scene system or scene manager
+ * - Entity Component System (ECS)
+ * - Physics engine (no Box2D, Matter.js, etc.)
+ * - Camera zoom or scale
+ * - Nested APIs or namespaces
+ * - Text input / HTML form elements
+ * - Parallax layers
+ * - Multiple cameras
+ * - Collision resolution (only detection is supported)
+ * - Image sprites (PNG, SVG, canvas, etc.)
+ * - `setTimeout` or `setInterval`
+ */
+export class Game {
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * @param width - Canvas width in pixels. Default: `800`.
+     * @param height - Canvas height in pixels. Default: `600`.
+     *
+     * @throws Error if a 2D context cannot be obtained.
+     *
+     * @example
+     * ```ts
+     * const game = new Game(800, 600);
+     * ```
+     */
+    constructor(width = 800, height = 600) {
+        /** @internal */ this._sprites = [];
+        /** @internal */ this._timers = [];
+        /** @internal */ this._animations = [];
+        /** @internal */ this._textOverlays = [];
+        /** @internal */ this._timerIdCounter = 0;
+        /** @internal */ this._input = createInputState();
+        /** @internal */ this._rafId = null;
+        /** @internal */ this._lastTimestamp = null;
+        /** @internal */ this._running = false;
+        /** @internal */ this._hasCreated = false;
+        /** @internal */ this._onResize = () => applyResponsiveCanvasLayout(this._canvas);
+        /** @internal */ this._audioCtx = null;
+        /** @internal */ this._lastAppliedPageBackground = undefined;
+        // -------------------------------------------------------------------------
+        // Public state
+        // -------------------------------------------------------------------------
+        /**
+         * Horizontal gravity acceleration in pixels per second².
+         * Applied to every sprite whose {@link Sprite.gravityScale} is non-zero.
+         * Positive = accelerates right. Typical value for sideways wind: `200`.
+         * Default: `0`.
+         *
+         * @example
+         * ```ts
+         * game.gravityX = 0;   // no horizontal gravity
+         * ```
+         */
+        this.gravityX = 0;
+        /**
+         * Vertical gravity acceleration in pixels per second².
+         * Applied to every sprite whose {@link Sprite.gravityScale} is non-zero.
+         * Positive = accelerates downward (canvas Y-axis points down).
+         * Typical value for platformers: `980` (approximately Earth gravity in px/s²).
+         * Default: `0`.
+         *
+         * @example
+         * ```ts
+         * game.gravityY = 980; // standard downward gravity
+         * ```
+         */
+        this.gravityY = 0;
+        /**
+         * Horizontal scroll offset of the world camera, in pixels.
+         * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
+         * values are revealed as `scrollX` increases.
+         * Default: `0`. Reset to `0` by {@link Game.reset}.
+         *
+         * @example
+         * ```ts
+         * game.scrollX = player.x - game.width / 2; // center camera on player
+         * ```
+         */
+        this.scrollX = 0;
+        /**
+         * Vertical scroll offset of the world camera, in pixels.
+         * The canvas viewport is shifted up by `scrollY` — sprites with higher `y`
+         * values are revealed as `scrollY` increases.
+         * Default: `0`. Reset to `0` by {@link Game.reset}.
+         */
+        this.scrollY = 0;
+        /**
+         * Solid background color for the full canvas.
+         * Set to any valid CSS color string (e.g. `"#000"`, `"skyblue"`, `"rgba(0,0,0,0.5)"`).
+         * Default: `null` (transparent canvas background).
+         *
+         * If {@link Game.backgroundGradient} is set, the gradient takes priority over
+         * this solid color.
+         *
+         * @example
+         * ```ts
+         * game.background = "#101820";
+         * ```
+         */
+        this.background = null;
+        /**
+         * Vertical gradient background for the full canvas.
+         * `from` is the top color and `to` is the bottom color.
+         * Set to `null` to disable gradient mode.
+         *
+         * @example
+         * ```ts
+         * game.backgroundGradient = { from: "#92d7ff", to: "#5ca44f" };
+         * ```
+         */
+        this.backgroundGradient = null;
+        /**
+         * Background color for the full web page (`document.body`).
+         * Set to any valid CSS color string. Default: `null` (engine leaves page background unchanged).
+         *
+         * This is independent from {@link Game.background}, which affects the canvas only.
+         *
+         * @example
+         * ```ts
+         * game.pageBackground = "#f4e4bc";
+         * ```
+         */
+        this.pageBackground = null;
+        /**
+         * 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.
+         *
+         * @example
+         * ```ts
+         * game.onCreate = () => {
+         *   const player = new Sprite("🐢");
+         *   player.x = 200;
+         *   player.y = 300;
+         *   game.add(player);
+         * };
+         * ```
+         */
+        this.onCreate = null;
+        /**
+         * Callback invoked once per frame after physics and timer updates.
+         *
+         * @param dt - Delta time in **seconds** since the last frame.
+         *   Use this for velocity-based movement: `sprite.x += speed * dt`.
+         *   Capped at `0.1` seconds (100ms) to prevent spiral-of-death.
+         *
+         * @example
+         * ```ts
+         * game.onUpdate = (dt) => {
+         *   if (game.isKeyDown("ArrowRight")) player.vx = 200;
+         *   else player.vx = 0;
+         * };
+         * ```
+         */
+        this.onUpdate = null;
+        this._canvas = document.createElement("canvas");
+        this._canvas.width = width;
+        this._canvas.height = height;
+        this._canvas.style.display = "block";
+        this._canvas.style.touchAction = "none";
+        this._canvas.style.width = `${width}px`;
+        this._canvas.style.height = `${height}px`;
+        const mountCanvas = () => {
+            if (document.body && !this._canvas.isConnected) {
+                document.body.appendChild(this._canvas);
+            }
+            applyResponsiveCanvasLayout(this._canvas);
+        };
+        if (document.body) {
+            mountCanvas();
+        }
+        else {
+            window.addEventListener("DOMContentLoaded", mountCanvas, { once: true });
+        }
+        window.addEventListener("resize", this._onResize);
+        const ctx = this._canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("MinimoJS: Could not acquire a 2D rendering context.");
+        }
+        this._ctx = ctx;
+        bindInputEvents(this._canvas, this._input);
+    }
+    // -------------------------------------------------------------------------
+    // Canvas dimensions (read-only)
+    // -------------------------------------------------------------------------
+    /**
+     * The width of the canvas in pixels. Read-only — set via constructor.
+     */
+    get width() {
+        return this._canvas.width;
+    }
+    /**
+     * The height of the canvas in pixels. Read-only — set via constructor.
+     */
+    get height() {
+        return this._canvas.height;
+    }
+    /**
+     * 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`.
+     */
+    get pointerX() {
+        return this._input.pointerX;
+    }
+    /**
+     * 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() {
+        return this._input.pointerY;
+    }
+    // -------------------------------------------------------------------------
+    // Sprite management
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * **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
+     * 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 Sprite("🪙");
+     * coin.x = 300; coin.y = 200; coin.size = 32;
+     * game.add(coin);
+     *
+     * // Custom subclass
+     * class Enemy extends Sprite {
+     *   speed = 150;
+     *   constructor(x: number, y: number) {
+     *     super("👾");
+     *     this.x = x; this.y = y; this.size = 40;
+     *   }
+     * }
+     * const enemy = game.add(new Enemy(600, 100));
+     * ```
+     */
+    add(sprite) {
+        this._sprites.push(sprite);
+        return sprite;
+    }
+    /**
+     * 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) {
+        const idx = this._sprites.indexOf(sprite);
+        if (idx !== -1)
+            this._sprites.splice(idx, 1);
+        this._animations = this._animations.filter((a) => a.sprite !== sprite);
+    }
+    /**
+     * 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() {
+        return [...this._sprites];
+    }
+    // -------------------------------------------------------------------------
+    // Collision
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * **No collision resolution is performed.** This method is detection-only.
+     * If you need bounce or push-apart behavior, implement it in `onUpdate`.
+     *
+     * @param a - First sprite.
+     * @param b - Second sprite.
+     * @returns `true` if the bounding boxes overlap; `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * if (game.overlap(player, enemy)) {
+     *   game.reset(); // restart on collision
+     * }
+     * ```
+     */
+    overlap(a, b) {
+        const halfA = a.size / 2;
+        const halfB = b.size / 2;
+        return (Math.abs(a.x - b.x) < halfA + halfB &&
+            Math.abs(a.y - b.y) < halfA + halfB);
+    }
+    /**
+     * Tests for any overlap between two groups of sprites.
+     * Performs an O(n × m) AABB check for every pair `(a, b)` where `a ∈ listA`
+     * and `b ∈ listB`. Returns the **first** overlapping pair found.
+     *
+     * Internally uses {@link Game.overlap} — same AABB rules apply.
+     * No collision resolution is performed.
+     *
+     * @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,
+     *   or `null` if no pair overlaps.
+     *
+     * @example
+     * ```ts
+     * const hit = game.overlapAny(bullets, enemies);
+     * if (hit) {
+     *   const [bullet, enemy] = hit;
+     *   game.destroySprite(bullet);
+     *   game.destroySprite(enemy);
+     * }
+     * ```
+     */
+    overlapAny(listA, listB) {
+        for (const a of listA) {
+            for (const b of listB) {
+                if (this.overlap(a, b))
+                    return [a, b];
+            }
+        }
+        return null;
+    }
+    // -------------------------------------------------------------------------
+    // Input — Keyboard
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` while the specified key is held down (every frame it is held).
+     * Use this for continuous actions like movement.
+     *
+     * Uses the `KeyboardEvent.key` string (e.g. `"ArrowLeft"`, `"a"`, `" "`, `"Enter"`).
+     * Key names are case-sensitive.
+     *
+     * **Hold behavior:** returns `true` on the first frame the key is pressed AND
+     * every subsequent frame until the key is released.
+     *
+     * @param key - The `KeyboardEvent.key` value to check.
+     * @returns `true` if the key is currently held down.
+     *
+     * @example
+     * ```ts
+     * if (game.isKeyDown("ArrowRight")) player.vx = 200;
+     * ```
+     */
+    isKeyDown(key) {
+        return this._input.keysDown.has(key);
+    }
+    /**
+     * Returns `true` only on the **single frame** the key was first pressed.
+     * Use this for one-shot actions like jumping or firing.
+     *
+     * **Edge behavior:** returns `true` exactly once per press, on the frame the
+     * key transitions from up → down. Subsequent frames while held return `false`.
+     *
+     * @param key - The `KeyboardEvent.key` value to check.
+     * @returns `true` only on the first frame of the key press.
+     *
+     * @example
+     * ```ts
+     * if (game.isKeyPressed(" ")) player.vy = -500; // jump on spacebar press
+     * ```
+     */
+    isKeyPressed(key) {
+        return this._input.keysPressed.has(key);
+    }
+    // -------------------------------------------------------------------------
+    // Input — Pointer (mouse / touch)
+    // -------------------------------------------------------------------------
+    /**
+     * Returns `true` while the pointer (mouse button or touch) is held down.
+     * Use this for continuous pointer actions.
+     *
+     * **Hold behavior:** returns `true` every frame from press until release.
+     *
+     * @returns `true` if the pointer is currently pressed.
+     *
+     * @example
+     * ```ts
+     * if (game.isPointerDown()) fireContinuously();
+     * ```
+     */
+    isPointerDown() {
+        return this._input.pointerDown;
+    }
+    /**
+     * Returns `true` only on the **single frame** the pointer was first pressed.
+     * Use this for tap/click one-shot actions.
+     *
+     * **Edge behavior:** returns `true` exactly once per press, on the frame the
+     * pointer transitions from up → down. Subsequent frames while held return `false`.
+     *
+     * @returns `true` only on the first frame of the pointer press.
+     *
+     * @example
+     * ```ts
+     * if (game.isPointerPressed()) spawnAt(game.pointerX, game.pointerY);
+     * ```
+     */
+    isPointerPressed() {
+        return this._input.pointerPressed;
+    }
+    /**
+     * 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.
+     *
+     * 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)) {
+     *   player.x -= 200 * dt;
+     * }
+     * ```
+     */
+    isPointerDownOverSprite(sprite, radiusScale = 0.5) {
+        return isPointerDownOverSprite(this._input, sprite, radiusScale, this.scrollX, this.scrollY);
+    }
+    /**
+     * 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.
+     *
+     * 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)) {
+     *   startGame();
+     * }
+     * ```
+     */
+    isPointerPressedOverSprite(sprite, radiusScale = 0.5) {
+        return isPointerPressedOverSprite(this._input, sprite, radiusScale, this.scrollX, this.scrollY);
+    }
+    /**
+     * Returns a read-only snapshot of all currently active pointers.
+     *
+     * Mouse appears in the list only while the mouse button is held down. Touches
+     * appear while they remain active on the canvas. Coordinates are returned in
+     * canvas/screen space.
+     *
+     * Use this for advanced multitouch controls such as joysticks, drag handles,
+     * or gesture-like gameplay logic.
+     *
+     * @returns A read-only array of active pointer snapshots.
+     *
+     * @example
+     * ```ts
+     * const pointers = game.getPointers();
+     * if (pointers.length > 0) {
+     *   const first = pointers[0];
+     *   game.text(`Pointer: ${first.x}, ${first.y}`, 10, 10);
+     * }
+     * ```
+     */
+    getPointers() {
+        return collectPointers(this._input);
+    }
+    /**
+     * 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.
+     *
+     * 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);
+     * if (touches.length > 0) {
+     *   const p = touches[0];
+     *   const dx = p.x - joystickBase.x;
+     * }
+     * ```
+     */
+    getPointersOverSprite(sprite, radiusScale = 0.5) {
+        return getPointersOverSprite(this._input, sprite, radiusScale, this.scrollX, this.scrollY);
+    }
+    /**
+     * Returns `true` when the current device appears to be mobile/touch-first.
+     *
+     * This is a heuristic helper intended for gameplay UI decisions (for example,
+     * showing on-screen touch controls). It checks user-agent/platform hints and
+     * coarse-pointer/touch capabilities.
+     *
+     * @returns `true` if the runtime likely corresponds to a mobile device.
+     *
+     * @example
+     * ```ts
+     * if (game.isMobileDevice()) {
+     *   // Show touch buttons
+     * } else {
+     *   // Show keyboard hints
+     * }
+     * ```
+     */
+    isMobileDevice() {
+        if (typeof navigator === "undefined")
+            return false;
+        const ua = navigator.userAgent ?? "";
+        const mobileUA = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|Mobile/i.test(ua);
+        const iPadOS = navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1;
+        const coarsePointer = typeof window !== "undefined" &&
+            typeof window.matchMedia === "function" &&
+            window.matchMedia("(pointer: coarse)").matches;
+        return mobileUA || iPadOS || coarsePointer;
+    }
+    // -------------------------------------------------------------------------
+    // Sound
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * The tone fades out exponentially over `durationMs` to avoid clicks.
+     *
+     * @param freq - Frequency in Hz. Middle C = 261.6. Typical range: 100–4000 Hz.
+     * @param durationMs - Duration of the sound in **milliseconds**.
+     *
+     * @example
+     * ```ts
+     * game.sound(440, 100);   // 440 Hz beep for 100ms
+     * game.sound(261, 500);   // middle C for 500ms
+     * game.sound(880, 50);    // high beep for 50ms (jump sound)
+     * ```
+     */
+    sound(freq, durationMs) {
+        this._audioCtx = playSquareTone(this._audioCtx, freq, durationMs);
+    }
+    // -------------------------------------------------------------------------
+    // Animations
+    // -------------------------------------------------------------------------
+    /**
+     * Animates a sprite's {@link Sprite.alpha} from its current value to `to`
+     * over `durationMs` milliseconds using **linear interpolation**.
+     *
+     * If an alpha animation is already running on this sprite, it is replaced
+     * by the new one immediately (no queuing).
+     *
+     * **Timing:** driven by the rAF loop, not `setTimeout`. Duration is in ms.
+     *
+     * @param sprite - The sprite to animate.
+     * @param to - Target alpha value (0 = transparent, 1 = opaque).
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     *
+     * @example
+     * ```ts
+     * // Fade out a sprite over 1 second, then destroy it
+     * game.animateAlpha(coin, 0, 1000, () => game.destroySprite(coin));
+     * ```
+     */
+    animateAlpha(sprite, to, durationMs, onComplete) {
+        this._animations = scheduleAnimation(this._animations, sprite, "alpha", to, durationMs, onComplete);
+    }
+    /**
+     * Animates a sprite's {@link Sprite.rotation} from its current value to `to`
+     * (in degrees) over `durationMs` milliseconds using **linear interpolation**.
+     *
+     * If a rotation animation is already running on this sprite, it is replaced
+     * immediately (no queuing).
+     *
+     * **Timing:** driven by the rAF loop, not `setTimeout`. Duration is in ms.
+     * **Units:** `to` is in **degrees**.
+     *
+     * @param sprite - The sprite to animate.
+     * @param to - Target rotation in **degrees**.
+     * @param durationMs - Duration of the animation in **milliseconds**.
+     * @param onComplete - Optional callback invoked when the animation finishes.
+     *
+     * @example
+     * ```ts
+     * // Spin a sprite 360° over 2 seconds
+     * game.animateRotation(star, 360, 2000);
+     *
+     * // Tilt on hit, then straighten
+     * game.animateRotation(player, 45, 200, () => {
+     *   game.animateRotation(player, 0, 200);
+     * });
+     * ```
+     */
+    animateRotation(sprite, to, durationMs, onComplete) {
+        this._animations = scheduleAnimation(this._animations, sprite, "rotation", to, durationMs, onComplete);
+    }
+    // -------------------------------------------------------------------------
+    // Timers
+    // -------------------------------------------------------------------------
+    /**
+     * Schedules a callback to fire after `delayMs` milliseconds, driven by the
+     * rAF loop (not `setTimeout`). Timers accumulate elapsed time each frame and
+     * fire once the threshold is reached.
+     *
+     * **Repeat behavior:**
+     * - `repeat = false`: fires once, then auto-removes.
+     * - `repeat = true`: fires every `delayMs` ms until cleared with {@link Game.clearTimer}.
+     *   The elapsed time wraps (excess time carries over), so repeat timers are
+     *   accurate over long durations.
+     *
+     * **Reset behavior:** ALL timers are cleared on {@link Game.reset}.
+     *
+     * @param delayMs - Delay (and period for repeating timers) in **milliseconds**.
+     * @param repeat - If `true`, the timer fires repeatedly every `delayMs` ms.
+     * @param callback - Function to call when the timer fires.
+     * @returns A numeric timer ID for use with {@link Game.clearTimer}.
+     *
+     * @example
+     * ```ts
+     * // One-shot: explode after 3 seconds
+     * game.addTimer(3000, false, () => { bomb.sprite = "💥"; });
+     *
+     * // Repeating: spawn enemy every 2 seconds
+     * const spawnId = game.addTimer(2000, true, spawnEnemy);
+     * // Stop spawning:
+     * game.clearTimer(spawnId);
+     * ```
+     */
+    addTimer(delayMs, repeat, callback) {
+        const id = ++this._timerIdCounter;
+        this._timers.push({ id, delayMs, elapsed: 0, repeat, callback });
+        return id;
+    }
+    /**
+     * Cancels a timer previously created with {@link Game.addTimer}.
+     * If the ID does not exist (already fired and removed, or never created),
+     * this is a safe no-op.
+     *
+     * @param id - The timer ID returned by {@link Game.addTimer}.
+     *
+     * @example
+     * ```ts
+     * const id = game.addTimer(5000, true, spawnEnemy);
+     * // Stop spawning when player reaches the end:
+     * game.clearTimer(id);
+     * ```
+     */
+    clearTimer(id) {
+        this._timers = this._timers.filter((t) => t.id !== id);
+    }
+    // -------------------------------------------------------------------------
+    // Text
+    // -------------------------------------------------------------------------
+    /**
+     * Draws text on screen as a **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.
+     *
+     * **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.
+     *
+     * @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).
+     *   Text baseline is at the top of the text.
+     * @param fontSize - Font size in pixels (e.g. `16`, `24`, `32`).
+     * @param color - CSS color string. Default: `"#ffffff"` (white).
+     * @param centered - If `true`, text is centered on `(x, y)` (both axes).
+     *   If `false`, `(x, y)` is the top-left anchor. Default: `false`.
+     *
+     * @example
+     * ```ts
+     * game.onUpdate = (dt) => {
+     *   game.drawText(`Score: ${score}`, 10, 10, 20, "#ffff00");
+     *   game.drawText(`Lives: ${"❤️".repeat(lives)}`, 10, 40, 20);
+     *   game.drawText("PAUSED", game.width / 2, game.height / 2, 28, "#ffffff", true);
+     * };
+     * ```
+     */
+    drawText(text, x, y, fontSize, color = "#ffffff", centered = false) {
+        this._textOverlays.push({ text, x, y, fontSize, color, centered });
+    }
+    // -------------------------------------------------------------------------
+    // Misc
+    // -------------------------------------------------------------------------
+    /**
+     * Returns a pseudo-random floating-point number in the range `[0, 1)`.
+     * Delegates to `Math.random()`.
+     *
+     * **Determinism note:** This method is NOT seeded and NOT deterministic across
+     * runs. The output changes every invocation. If you need reproducible randomness,
+     * implement a seeded PRNG (e.g. a simple LCG) in your game code.
+     *
+     * @returns A random number in `[0, 1)`.
+     *
+     * @example
+     * ```ts
+     * const x = game.random() * game.width;
+     * const emoji = ["⭐", "🔥", "💎"][Math.floor(game.random() * 3)];
+     * ```
+     */
+    random() {
+        return Math.random();
+    }
+    /**
+     * Performs a full engine state reset to enable scene switching.
+     *
+     * **Cleared by reset:**
+     * - All sprites (equivalent to calling {@link Game.destroySprite} on every sprite)
+     * - All timers (regardless of repeat state)
+     * - All running animations
+     * - All pending text overlays
+     * - Scroll position (`scrollX = 0`, `scrollY = 0`)
+     * - Per-frame input state (pressed keys, pressed pointer)
+     *
+     * **NOT cleared by reset:**
+     * - `gravityX` / `gravityY` (global engine setting)
+     * - `background` / `backgroundGradient` / `pageBackground`
+     * - `onCreate` callback (your handler stays registered)
+     * - `onUpdate` callback (your handler stays registered)
+     * - Canvas dimensions
+     * - AudioContext
+     *
+     * After clearing, `reset()` immediately calls `onCreate()` so your callback
+     * can rebuild the new scene synchronously.
+     *
+     * @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
+     * };
+     * ```
+     */
+    reset() {
+        this._sprites = [];
+        this._timers = [];
+        this._animations = [];
+        this._textOverlays = [];
+        resetTransientInput(this._input);
+        this.scrollX = 0;
+        this.scrollY = 0;
+        this._invokeCreate();
+    }
+    // -------------------------------------------------------------------------
+    // Loop control
+    // -------------------------------------------------------------------------
+    /**
+     * 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:
+     * 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.
+     *
+     * @example
+     * ```ts
+     * game.onUpdate = (dt) => { ... };
+     * game.start();
+     * ```
+     */
+    start() {
+        if (this._running)
+            return;
+        if (!this._hasCreated)
+            this._invokeCreate();
+        this._running = true;
+        this._lastTimestamp = null;
+        this._rafId = requestAnimationFrame(this._loop.bind(this));
+    }
+    /**
+     * Stops the game loop. The canvas retains its last rendered frame.
+     * Call {@link Game.start} to resume.
+     */
+    stop() {
+        this._running = false;
+        if (this._rafId !== null) {
+            cancelAnimationFrame(this._rafId);
+            this._rafId = null;
+        }
+        this._lastTimestamp = null;
+    }
+    // -------------------------------------------------------------------------
+    // Private — rAF loop
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _loop(timestamp) {
+        if (!this._running)
+            return;
+        if (this._lastTimestamp === null) {
+            this._lastTimestamp = timestamp;
+        }
+        let dt = (timestamp - this._lastTimestamp) / 1000;
+        this._lastTimestamp = timestamp;
+        if (dt > 0.1)
+            dt = 0.1;
+        const dtMs = dt * 1000;
+        this._timers = updateTimers(this._timers, dtMs);
+        updateAnimations(this._animations, dtMs);
+        updatePhysics(this._sprites, this.gravityX, this.gravityY, dt);
+        if (this.onUpdate)
+            this.onUpdate(dt);
+        this._lastAppliedPageBackground = applyPageBackground(this.pageBackground, this._lastAppliedPageBackground);
+        renderFrame({
+            ctx: this._ctx,
+            canvas: this._canvas,
+            sprites: this._sprites,
+            textOverlays: this._textOverlays,
+            background: this.background,
+            backgroundGradient: this.backgroundGradient,
+            scrollX: this.scrollX,
+            scrollY: this.scrollY,
+        });
+        resetTransientInput(this._input);
+        this._textOverlays = [];
+        this._rafId = requestAnimationFrame(this._loop.bind(this));
+    }
+    /** @internal */
+    _invokeCreate() {
+        this._hasCreated = true;
+        if (this.onCreate)
+            this.onCreate();
+    }
+}