minimojs 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/minimo.d.ts

@@ -22,10 +22,7 @@
  * @example
  * ```ts
  * // Direct instantiation
- * const coin = new Sprite("🪙");
- * coin.x = 300;
- * coin.y = 200;
- * coin.size = 32;
+ * const coin = new Sprite("🪙", 300, 200, 32);
  * game.add(coin);
  * ```
  *
@@ -36,10 +33,7 @@
  *   health = 3;
  *
  *   constructor(x: number, y: number) {
- *     super("🐢");
- *     this.x = x;
- *     this.y = y;
- *     this.size = 48;
+ *     super("🐢", x, y, 48);
  *     this.gravityScale = 1;
  *   }
  * }
@@ -68,10 +62,47 @@ 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.
+     * Base width and height of this sprite in pixels.
+     *
+     * This value is read-only after construction and defines the glyph-cache
+     * render size. The visible and collision size during gameplay is exposed by
+     * {@link Sprite.displaySize}.
+     */
+    get size(): number;
+    /**
+     * Visual scale multiplier applied to {@link Sprite.size}.
+     * Default: `1`.
+     *
+     * Set this at runtime to resize a sprite without changing its base cached
+     * glyph size.
+     */
+    scale: number;
+    /**
+     * Effective rendered/collision size in pixels.
+     * Computed as `size * scale` with non-negative clamping.
      */
-    size: number;
+    get displaySize(): number;
+    /**
+     * CSS text color used when rendering this sprite.
+     *
+     * This mainly affects monochrome glyphs and symbol-style sprites.
+     * Full-color emoji may ignore this and render with their native colors,
+     * 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.
@@ -137,7 +168,7 @@ export declare class Sprite {
      */
     gravityScale: number;
     /**
-     * Creates a new Sprite with the given emoji and optional position.
+     * Creates a new Sprite 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.
@@ -145,15 +176,15 @@ export declare class Sprite {
      *   @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 Sprite("👾", 200, 100, 40);
      * game.add(enemy);
      * ```
      */
-    constructor(sprite: string, x?: number, y?: number);
+    constructor(sprite: string, x?: number, y?: number, size?: number);
 }
 /**
  * Snapshot of an active pointer tracked by the engine.
@@ -181,6 +212,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
  *
@@ -190,17 +251,63 @@ export interface PointerInfo {
  *
  * ---
  *
- * ## Quick Start
+ * ## ES Module Only
+ *
+ * MinimoJS is an **ES module only** package.
+ * You must import it with standard ESM syntax such as:
  *
  * ```ts
  * import { Game, Sprite } from "minimojs";
+ * ```
+ *
+ * In the browser, use it from a module script:
+ *
+ * ```html
+ * <script type="module">
+ *   import { Game, Sprite } from "./dist/minimo.js";
+ * </script>
+ * ```
+ *
+ * Or from a CDN:
+ *
+ * ```ts
+ * import { Game, Sprite } 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).
+ *
+ * ---
+ *
+ * ## Required Font Setup
+ *
+ * `drawText()` renders with `"Press Start 2P", monospace`.
+ * You MUST load `Press Start 2P` yourself in your `index.html` before starting
+ * the game. MinimoJS does NOT download, inject, or manage web fonts for you.
+ * If the 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"
+ * />
+ * ```
+ *
+ * ---
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { Game, Sprite } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo.js";
  *
  * const game = new Game(800, 600);
  *
- * const player = new Sprite("🐢");
- * player.x = 400;
- * player.y = 500;
- * player.size = 48;
+ * const player = new Sprite("🐢", 400, 500, 48);
  * game.add(player);
  *
  * game.onUpdate = (dt) => {
@@ -227,7 +334,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.
  *
  * ---
  *
@@ -333,8 +441,7 @@ export interface PointerInfo {
  * ```ts
  * game.onCreate = () => {
  *   // scene init: add sprites, setup timers
- *   const skull = new Sprite("💀");
- *   skull.x = 400; skull.y = 300; skull.size = 96;
+ *   const skull = new Sprite("💀", 400, 300, 96);
  *   game.add(skull);
  * };
  *
@@ -371,7 +478,7 @@ export interface PointerInfo {
  * - Text input / HTML form elements
  * - Parallax layers
  * - Multiple cameras
- * - Collision resolution (only detection is supported)
+ * - Full physics engine (only basic explicit AABB collision helpers are provided)
  * - Image sprites (PNG, SVG, canvas, etc.)
  * - `setTimeout` or `setInterval`
  */
@@ -401,6 +508,20 @@ export declare class Game {
      * ```
      */
     gravityY: 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;
+     * ```
+     */
+    physics: boolean;
     /**
      * Horizontal scroll offset of the world camera, in pixels.
      * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -508,6 +629,7 @@ export declare class Game {
      * @example
      * ```ts
      * const game = new Game(800, 600);
+     * game.physics = true;
      * ```
      */
     constructor(width?: number, height?: number);
@@ -535,8 +657,9 @@ export declare class Game {
     get pointerY(): number;
     /**
      * 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.
+     * 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.
@@ -551,16 +674,14 @@ export declare class Game {
      * @example
      * ```ts
      * // Plain sprite
-     * const coin = new Sprite("🪙");
-     * coin.x = 300; coin.y = 200; coin.size = 32;
+     * const coin = new Sprite("🪙", 300, 200, 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;
+     *     super("👾", x, y, 40);
      *   }
      * }
      * const enemy = game.add(new Enemy(600, 100));
@@ -606,10 +727,10 @@ export declare class Game {
      * 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.
@@ -647,6 +768,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 `[Sprite, Sprite, 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.
@@ -716,14 +888,14 @@ export declare class Game {
      * 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
+     * is `sprite.displaySize * 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.
+     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
      *   Default: `0.5`.
      * @returns `true` if any currently held pointer overlaps the sprite hit area.
      *
@@ -740,14 +912,14 @@ export declare class Game {
      * 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
+     * is `sprite.displaySize * 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.
+     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
      *   Default: `0.5`.
      * @returns `true` if any pointer began pressing this frame over the sprite hit area.
      *
@@ -776,7 +948,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);
      * }
      * ```
      */
@@ -786,7 +958,7 @@ export declare class Game {
      * 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
+     * is `sprite.displaySize * radiusScale`. World-space sprites are tested against the
      * current camera scroll. HUD sprites with `ignoreScroll = true` are tested in
      * screen space.
      *
@@ -794,7 +966,7 @@ export declare class Game {
      * 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.
+     * @param radiusScale - Multiplier applied to `sprite.displaySize` to define the hit radius.
      *   Default: `0.5`.
      * @returns A read-only array of active pointer snapshots currently over the sprite.
      *
@@ -954,8 +1126,11 @@ export declare class Game {
      * 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 uses `"Press Start 2P", monospace`.
+     * You MUST load `Press Start 2P` yourself in `index.html` (for example via
+     * Google Fonts) before calling {@link Game.start}. MinimoJS does NOT load
+     * external fonts for you. If the font is unavailable, the browser falls back
+     * to `monospace`. 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).
@@ -976,6 +1151,22 @@ export declare class Game {
      * ```
      */
     drawText(text: string, x: number, y: number, fontSize: number, color?: string, centered?: boolean): void;
+    /**
+     * Clears the internal sprite glyph cache.
+     *
+     * MinimoJS prerenders sprite glyphs into offscreen canvases for more stable
+     * emoji rendering and better performance. In long-running sessions, you can
+     * call this to release cached glyph variants and force them to be rebuilt on
+     * the next render.
+     *
+     * This does not change any sprite state. It only clears cached render data.
+     *
+     * @example
+     * ```ts
+     * game.clearSpriteCache();
+     * ```
+     */
+    clearSpriteCache(): void;
     /**
      * Returns a pseudo-random floating-point number in the range `[0, 1)`.
      * Delegates to `Math.random()`.
@@ -1024,8 +1215,7 @@ export declare class Game {
      *
      * game.onCreate = () => {
      *   // Scene init
-     *   const skull = new Sprite("💀");
-     *   skull.x = 400; skull.y = 300; skull.size = 96;
+     *   const skull = new Sprite("💀", 400, 300, 96);
      *   game.add(skull);
      *   game.addTimer(3000, false, () => game.reset()); // auto-restart
      * };