minimojs 1.0.0-alpha.15 → 1.0.0-alpha.17

package/README.md

@@ -40,17 +40,35 @@ npm install minimojs
 ## Quick Start
 
 ```ts
-import { Game, Sprite, type IScene } from "minimojs";
+import { DrawSprite, Game, Sprite, type IScene } from "minimojs";
 
 const game = new Game(720, 1280);
 game.gravityY = 980;
 
+class MeterSprite extends DrawSprite {
+  public value = 0.5;
+
+  constructor(x: number, y: number) {
+    super(160, 28, x, y);
+  }
+
+  redraw(ctx: CanvasRenderingContext2D) {
+    ctx.fillStyle = "#1a2236";
+    ctx.fillRect(0, 0, this.width, this.height);
+    ctx.fillStyle = "#7ce7ff";
+    ctx.fillRect(0, 0, this.width * this.value, this.height);
+  }
+}
+
 class DemoScene implements IScene {
   private player: Sprite | null = null;
+  private meter: MeterSprite | null = null;
 
   onCreate() {
     this.player = game.add(new Sprite("🐢", 360, 640, 48));
     this.player.gravityScale = 1;
+    this.meter = game.add(new MeterSprite(360, 80));
+    this.meter.ignoreScroll = true;
   }
 
   onUpdate(dt: number) {
@@ -61,6 +79,7 @@ class DemoScene implements IScene {
     else this.player.vx = 0;
 
     if (game.isKeyPressed(" ")) this.player.vy = -600;
+    if (this.meter) this.meter.value = Math.abs(this.player.vx) / 200;
     game.drawText("MinimoJS", 10, 10, 16);
   }
 }
@@ -80,6 +99,8 @@ Note: `drawText()` uses `"Press Start 2P", monospace`. Load the font in your HTM
 - `examples/background-desert/`
 - `examples/scene-lab/`
 - `examples/image-sprite-sad-plush/`
+- `examples/draw-sprite/`
+- `examples/pseudo-3d-racer/`
 - `examples/animations/`
 
 Run locally from the `minimojs` directory:

package/dist/internal/PhysicsSystem.js

@@ -37,12 +37,12 @@ export class PhysicsSystem {
         }
     }
     overlap(a, b) {
-        const halfWidthA = a.displayWidth / 2;
-        const halfHeightA = a.displayHeight / 2;
-        const halfWidthB = b.displayWidth / 2;
-        const halfHeightB = b.displayHeight / 2;
-        return (Math.abs(a.renderX - b.renderX) < halfWidthA + halfWidthB &&
-            Math.abs(a.renderY - b.renderY) < halfHeightA + halfHeightB);
+        const halfWidthA = a.bodyDisplayWidth / 2;
+        const halfHeightA = a.bodyDisplayHeight / 2;
+        const halfWidthB = b.bodyDisplayWidth / 2;
+        const halfHeightB = b.bodyDisplayHeight / 2;
+        return (Math.abs(a.bodyCenterX - b.bodyCenterX) < halfWidthA + halfWidthB &&
+            Math.abs(a.bodyCenterY - b.bodyCenterY) < halfHeightA + halfHeightB);
     }
     overlapAny(listA, listB) {
         for (const a of listA) {
@@ -100,12 +100,12 @@ export class PhysicsSystem {
         }
     }
     getCollisionResolution(a, b) {
-        const halfWidthA = a.displayWidth / 2;
-        const halfHeightA = a.displayHeight / 2;
-        const halfWidthB = b.displayWidth / 2;
-        const halfHeightB = b.displayHeight / 2;
-        const dx = b.renderX - a.renderX;
-        const dy = b.renderY - a.renderY;
+        const halfWidthA = a.bodyDisplayWidth / 2;
+        const halfHeightA = a.bodyDisplayHeight / 2;
+        const halfWidthB = b.bodyDisplayWidth / 2;
+        const halfHeightB = b.bodyDisplayHeight / 2;
+        const dx = b.bodyCenterX - a.bodyCenterX;
+        const dy = b.bodyCenterY - a.bodyCenterY;
         const overlapX = halfWidthA + halfWidthB - Math.abs(dx);
         const overlapY = halfHeightA + halfHeightB - Math.abs(dy);
         if (overlapX <= 0 || overlapY <= 0) {

package/dist/internal/RenderSystem.js

@@ -5,10 +5,14 @@ export class RenderSystem {
         this._lastAppliedPageBackground = undefined;
         this._transitionScratchCanvas = null;
         this._transitionScratchContext = null;
+        this._dynamicSurfacePassId = 0;
     }
     clearSpriteCache() {
         this._surfaceCache.clear();
     }
+    beginDynamicSurfacePass() {
+        this._dynamicSurfacePassId += 1;
+    }
     getSpriteGlyphCanvasForEffects(sprite) {
         return this.getRenderSurface(sprite);
     }
@@ -196,6 +200,60 @@ export class RenderSystem {
             ctx.fillText(entry.text, entry.x, entry.y);
             ctx.restore();
         }
+        if (options.debugBodies) {
+            this.drawBodyDebugOverlay(ctx, sorted, options.scrollX, options.scrollY);
+        }
+        if (options.debugInputAreas) {
+            this.drawInputDebugOverlay(ctx, sorted, options.scrollX, options.scrollY);
+        }
+    }
+    drawBodyDebugOverlay(ctx, sprites, scrollX, scrollY) {
+        ctx.save();
+        ctx.setLineDash([6, 4]);
+        ctx.lineWidth = 2;
+        for (const sprite of sprites) {
+            const halfWidth = sprite.bodyDisplayWidth / 2;
+            const halfHeight = sprite.bodyDisplayHeight / 2;
+            const centerX = sprite.ignoreScroll ? sprite.bodyCenterX : sprite.bodyCenterX - scrollX;
+            const centerY = sprite.ignoreScroll ? sprite.bodyCenterY : sprite.bodyCenterY - scrollY;
+            const left = Math.round(centerX - halfWidth) + 0.5;
+            const top = Math.round(centerY - halfHeight) + 0.5;
+            const width = Math.max(1, Math.round(sprite.bodyDisplayWidth) - 1);
+            const height = Math.max(1, Math.round(sprite.bodyDisplayHeight) - 1);
+            const stroke = sprite.isStatic
+                ? 'rgba(0, 217, 255, 0.95)'
+                : 'rgba(255, 77, 109, 0.95)';
+            const fill = sprite.isStatic
+                ? 'rgba(0, 217, 255, 0.12)'
+                : 'rgba(255, 77, 109, 0.12)';
+            ctx.strokeStyle = stroke;
+            ctx.fillStyle = fill;
+            ctx.fillRect(left, top, width, height);
+            ctx.strokeRect(left, top, width, height);
+        }
+        ctx.restore();
+    }
+    drawInputDebugOverlay(ctx, sprites, scrollX, scrollY) {
+        ctx.save();
+        ctx.setLineDash([3, 5]);
+        ctx.lineWidth = 2;
+        for (const sprite of sprites) {
+            const halfWidth = sprite.displayWidth / 2;
+            const halfHeight = sprite.displayHeight / 2;
+            const centerX = sprite.ignoreScroll ? sprite.renderX : sprite.renderX - scrollX;
+            const centerY = sprite.ignoreScroll ? sprite.renderY : sprite.renderY - scrollY;
+            const left = Math.round(centerX - halfWidth) + 0.5;
+            const top = Math.round(centerY - halfHeight) + 0.5;
+            const width = Math.max(1, Math.round(sprite.displayWidth) - 1);
+            const height = Math.max(1, Math.round(sprite.displayHeight) - 1);
+            const stroke = "rgba(255, 196, 0, 0.98)";
+            const fill = "rgba(255, 196, 0, 0.10)";
+            ctx.strokeStyle = stroke;
+            ctx.fillStyle = fill;
+            ctx.fillRect(left, top, width, height);
+            ctx.strokeRect(left, top, width, height);
+        }
+        ctx.restore();
     }
     renderLoadingScreen(options) {
         const ctx = options.context;
@@ -294,6 +352,9 @@ export class RenderSystem {
         ctx.restore();
     }
     getRenderSurface(sprite) {
+        if (this.isDrawSprite(sprite)) {
+            return this.getDrawSurface(sprite);
+        }
         const cacheKey = sprite.getRenderCacheKey();
         const cached = this._surfaceCache.get(cacheKey);
         if (cached)
@@ -413,9 +474,47 @@ export class RenderSystem {
         ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
         return canvas;
     }
+    getDrawSurface(sprite) {
+        const width = Math.max(1, Math.round(sprite.width));
+        const height = Math.max(1, Math.round(sprite.height));
+        let surface = sprite._surface;
+        if (!surface) {
+            surface = document.createElement("canvas");
+            sprite._surface = surface;
+        }
+        const sizeChanged = surface.width !== width || surface.height !== height;
+        if (sprite.frozen && !sizeChanged && surface.width > 0 && surface.height > 0) {
+            return surface;
+        }
+        if (!sprite.frozen &&
+            sprite._lastRedrawPassId === this._dynamicSurfacePassId &&
+            surface.width === width &&
+            surface.height === height) {
+            return surface;
+        }
+        if (sizeChanged) {
+            surface.width = width;
+            surface.height = height;
+        }
+        else {
+            // Resetting width clears pixels and restores the default 2D context state.
+            surface.width = width;
+        }
+        const ctx = surface.getContext("2d");
+        if (!ctx) {
+            throw new Error("MinimoJS: Could not acquire a DrawSprite rendering context.");
+        }
+        sprite._surfaceCtx = ctx;
+        sprite.redraw(ctx);
+        sprite._lastRedrawPassId = this._dynamicSurfacePassId;
+        return surface;
+    }
     isTextSprite(sprite) {
         return "text" in sprite && "fontFamily" in sprite && "fontSize" in sprite;
     }
+    isDrawSprite(sprite) {
+        return "redraw" in sprite && "_surface" in sprite && "_surfaceCtx" in sprite;
+    }
     isImageSprite(sprite) {
         return "imageKey" in sprite && "setTexture" in sprite;
     }

package/dist/minimo.d.ts

@@ -252,6 +252,52 @@ export declare abstract class BaseSprite {
      * Effective rendered/collision height in pixels.
      */
     get displayHeight(): number;
+    /**
+     * Optional logical body width used by physics helpers and collision checks.
+     *
+     * When `null` (default), MinimoJS uses the sprite's visual {@link BaseSprite.width}.
+     * When set, this value is scaled by {@link BaseSprite.scale} the same way as the
+     * visual sprite size.
+     */
+    bodyWidth: number | null;
+    /**
+     * Optional logical body height used by physics helpers and collision checks.
+     *
+     * When `null` (default), MinimoJS uses the sprite's visual {@link BaseSprite.height}.
+     * When set, this value is scaled by {@link BaseSprite.scale} the same way as the
+     * visual sprite size.
+     */
+    bodyHeight: number | null;
+    /**
+     * Horizontal body offset, in local sprite pixels before scale is applied.
+     *
+     * Positive values move the collision body to the right of the sprite's rendered center.
+     * Negative values move it to the left.
+     */
+    bodyOffsetX: number;
+    /**
+     * Vertical body offset, in local sprite pixels before scale is applied.
+     *
+     * Positive values move the collision body downward relative to the sprite's
+     * rendered center. Negative values move it upward.
+     */
+    bodyOffsetY: number;
+    /**
+     * Effective collision-body width in pixels after applying {@link BaseSprite.scale}.
+     */
+    get bodyDisplayWidth(): number;
+    /**
+     * Effective collision-body height in pixels after applying {@link BaseSprite.scale}.
+     */
+    get bodyDisplayHeight(): number;
+    /**
+     * Resolved body center X used internally by physics helpers and collision checks.
+     */
+    get bodyCenterX(): number;
+    /**
+     * Resolved body center Y used internally by physics helpers and collision checks.
+     */
+    get bodyCenterY(): number;
     /**
      * CSS text color used when rendering this sprite.
      *
@@ -425,6 +471,96 @@ export declare class ImageSprite extends BaseSprite {
     private getResolvedImage;
     private assertTextureAvailable;
 }
+/**
+ * A renderable sprite backed by a per-instance canvas that is repainted on demand.
+ *
+ * `DrawSprite` is useful for procedural shapes, gauges, charts, minimaps, and
+ * HUD widgets whose appearance changes often and is easier to express with
+ * Canvas 2D drawing commands than with emoji, text, or image swaps.
+ *
+ * Treat `DrawSprite` as a specialized tool, not the default sprite type.
+ * Because it may execute custom Canvas 2D drawing code repeatedly, overusing it
+ * can affect game performance much more than regular {@link Sprite},
+ * {@link ImageSprite}, or {@link TextSprite} instances.
+ *
+ * Prefer the other sprite types whenever they can express the same result more
+ * simply. Reach for `DrawSprite` only when you truly need procedural drawing or
+ * custom per-sprite canvas rendering that the built-in sprite types cannot
+ * provide cleanly.
+ *
+ * MinimoJS creates and owns an internal canvas for each `DrawSprite` instance.
+ * Before every engine render that needs this sprite's surface, the engine:
+ *
+ * 1. Resolves the sprite's internal canvas size
+ * 2. Optionally clears and repaints that internal canvas
+ * 3. Draws the resulting canvas like any other sprite surface
+ *
+ * By default, `DrawSprite` is live-rendered: the engine clears the internal
+ * canvas and calls {@link DrawSprite.redraw} every frame.
+ *
+ * Set {@link DrawSprite.frozen} to `true` if you want to keep and reuse the
+ * last rendered canvas contents without repainting on each frame. This is
+ * useful for shapes or procedural art that you only want to draw once.
+ *
+ * While `frozen` is `true`, MinimoJS reuses the existing surface exactly as-is:
+ * it does not clear the canvas and does not call {@link DrawSprite.redraw}
+ * again, unless the surface does not exist yet or its size had to be rebuilt.
+ *
+ * This means freezing is a rendering optimization and content-preservation
+ * flag, not a separate caching system. You can switch `frozen` on or off at
+ * runtime whenever it makes sense for your sprite.
+ *
+ * The local drawing coordinate system uses the sprite surface itself:
+ * - `(0, 0)` is the top-left corner of the internal canvas
+ * - `width` / `height` match the sprite's logical size before `scale`
+ * - draw centered content yourself if you want the visual origin in the middle
+ *
+ * Override {@link DrawSprite.redraw} in a subclass, or assign your own method
+ * on an instance if you prefer an inline style in JavaScript.
+ */
+export declare class DrawSprite extends BaseSprite {
+    private static _nextSurfaceId;
+    /**
+     * When `false` (default), MinimoJS clears this sprite's internal canvas and
+     * calls {@link DrawSprite.redraw} on every render pass.
+     *
+     * When `true`, MinimoJS keeps and reuses the existing canvas contents without
+     * clearing or repainting them again, unless the internal surface does not yet
+     * exist or had to be resized.
+     *
+     * Use this when your procedural drawing becomes static after its first paint,
+     * or when you want explicit manual control over when the sprite is redrawn by
+     * toggling `frozen` at runtime.
+     */
+    frozen: boolean;
+    private readonly _surfaceId;
+    private readonly _width;
+    private readonly _height;
+    get width(): number;
+    get height(): number;
+    /**
+     * Creates a new dynamic canvas-backed sprite.
+     *
+     * @param width - Internal canvas width in pixels. Minimum `1`.
+     * @param height - Internal canvas height in pixels. Minimum `1`.
+     * @param x - Initial X position in world space (center), in pixels. Default: `0`.
+     * @param y - Initial Y position in world space (center), in pixels. Default: `0`.
+     */
+    constructor(width: number, height: number, x?: number, y?: number);
+    /**
+     * Called by the engine whenever the sprite's internal surface must be repainted.
+     *
+     * The provided context is already cleared and reset to the default 2D canvas
+     * state for the current surface size. MinimoJS repaints each `DrawSprite` at
+     * most once per render pass while it is not {@link DrawSprite.frozen}, so
+     * repeated snapshot reads during the same frame reuse the already-redrawn
+     * surface.
+     *
+     * @param ctx - The sprite's internal 2D drawing context.
+     */
+    redraw(_ctx: CanvasRenderingContext2D): void;
+    getRenderCacheKey(): string;
+}
 /**
  * A renderable text actor that participates in the same animation/effects
  * pipeline as regular sprites.
@@ -982,6 +1118,20 @@ export declare class Game {
         from: string;
         to: string;
     } | null;
+    /**
+     * When `true`, MinimoJS draws every sprite's collision body as an overlay.
+     *
+     * This is a runtime debugging aid only. It does not change collisions,
+     * input, rendering order, or physics behavior.
+     */
+    debugBodies: boolean;
+    /**
+     * When `true`, MinimoJS draws every sprite's input area as an overlay.
+     *
+     * This is a runtime debugging aid only. It does not change input behavior,
+     * physics, or rendering.
+     */
+    debugInputAreas: boolean;
     /**
      * Background color for the full web page (`document.body`).
      * Set to any valid CSS color string. Default: `null` (engine leaves page background unchanged).

package/dist/minimo.js

@@ -53,6 +53,36 @@ export class BaseSprite {
         this.scale = 1;
         /** @internal */
         this._renderData = null;
+        /**
+         * Optional logical body width used by physics helpers and collision checks.
+         *
+         * When `null` (default), MinimoJS uses the sprite's visual {@link BaseSprite.width}.
+         * When set, this value is scaled by {@link BaseSprite.scale} the same way as the
+         * visual sprite size.
+         */
+        this.bodyWidth = null;
+        /**
+         * Optional logical body height used by physics helpers and collision checks.
+         *
+         * When `null` (default), MinimoJS uses the sprite's visual {@link BaseSprite.height}.
+         * When set, this value is scaled by {@link BaseSprite.scale} the same way as the
+         * visual sprite size.
+         */
+        this.bodyHeight = null;
+        /**
+         * Horizontal body offset, in local sprite pixels before scale is applied.
+         *
+         * Positive values move the collision body to the right of the sprite's rendered center.
+         * Negative values move it to the left.
+         */
+        this.bodyOffsetX = 0;
+        /**
+         * Vertical body offset, in local sprite pixels before scale is applied.
+         *
+         * Positive values move the collision body downward relative to the sprite's
+         * rendered center. Negative values move it upward.
+         */
+        this.bodyOffsetY = 0;
         /**
          * CSS text color used when rendering this sprite.
          *
@@ -179,6 +209,44 @@ export class BaseSprite {
         const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
         return this.height * Math.max(0, safeScale);
     }
+    /**
+     * Effective collision-body width in pixels after applying {@link BaseSprite.scale}.
+     */
+    get bodyDisplayWidth() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        const baseWidth = typeof this.bodyWidth === "number" &&
+            Number.isFinite(this.bodyWidth) &&
+            this.bodyWidth > 0
+            ? this.bodyWidth
+            : this.width;
+        return baseWidth * Math.max(0, safeScale);
+    }
+    /**
+     * Effective collision-body height in pixels after applying {@link BaseSprite.scale}.
+     */
+    get bodyDisplayHeight() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        const baseHeight = typeof this.bodyHeight === "number" &&
+            Number.isFinite(this.bodyHeight) &&
+            this.bodyHeight > 0
+            ? this.bodyHeight
+            : this.height;
+        return baseHeight * Math.max(0, safeScale);
+    }
+    /**
+     * Resolved body center X used internally by physics helpers and collision checks.
+     */
+    get bodyCenterX() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this.renderX + this.bodyOffsetX * Math.max(0, safeScale);
+    }
+    /**
+     * Resolved body center Y used internally by physics helpers and collision checks.
+     */
+    get bodyCenterY() {
+        const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
+        return this.renderY + this.bodyOffsetY * Math.max(0, safeScale);
+    }
     getAnchorOffsetX() {
         return 0;
     }
@@ -315,6 +383,112 @@ export class ImageSprite extends BaseSprite {
         }
     }
 }
+/**
+ * A renderable sprite backed by a per-instance canvas that is repainted on demand.
+ *
+ * `DrawSprite` is useful for procedural shapes, gauges, charts, minimaps, and
+ * HUD widgets whose appearance changes often and is easier to express with
+ * Canvas 2D drawing commands than with emoji, text, or image swaps.
+ *
+ * Treat `DrawSprite` as a specialized tool, not the default sprite type.
+ * Because it may execute custom Canvas 2D drawing code repeatedly, overusing it
+ * can affect game performance much more than regular {@link Sprite},
+ * {@link ImageSprite}, or {@link TextSprite} instances.
+ *
+ * Prefer the other sprite types whenever they can express the same result more
+ * simply. Reach for `DrawSprite` only when you truly need procedural drawing or
+ * custom per-sprite canvas rendering that the built-in sprite types cannot
+ * provide cleanly.
+ *
+ * MinimoJS creates and owns an internal canvas for each `DrawSprite` instance.
+ * Before every engine render that needs this sprite's surface, the engine:
+ *
+ * 1. Resolves the sprite's internal canvas size
+ * 2. Optionally clears and repaints that internal canvas
+ * 3. Draws the resulting canvas like any other sprite surface
+ *
+ * By default, `DrawSprite` is live-rendered: the engine clears the internal
+ * canvas and calls {@link DrawSprite.redraw} every frame.
+ *
+ * Set {@link DrawSprite.frozen} to `true` if you want to keep and reuse the
+ * last rendered canvas contents without repainting on each frame. This is
+ * useful for shapes or procedural art that you only want to draw once.
+ *
+ * While `frozen` is `true`, MinimoJS reuses the existing surface exactly as-is:
+ * it does not clear the canvas and does not call {@link DrawSprite.redraw}
+ * again, unless the surface does not exist yet or its size had to be rebuilt.
+ *
+ * This means freezing is a rendering optimization and content-preservation
+ * flag, not a separate caching system. You can switch `frozen` on or off at
+ * runtime whenever it makes sense for your sprite.
+ *
+ * The local drawing coordinate system uses the sprite surface itself:
+ * - `(0, 0)` is the top-left corner of the internal canvas
+ * - `width` / `height` match the sprite's logical size before `scale`
+ * - draw centered content yourself if you want the visual origin in the middle
+ *
+ * Override {@link DrawSprite.redraw} in a subclass, or assign your own method
+ * on an instance if you prefer an inline style in JavaScript.
+ */
+export class DrawSprite extends BaseSprite {
+    get width() {
+        return this._width;
+    }
+    get height() {
+        return this._height;
+    }
+    /**
+     * Creates a new dynamic canvas-backed sprite.
+     *
+     * @param width - Internal canvas width in pixels. Minimum `1`.
+     * @param height - Internal canvas height in pixels. Minimum `1`.
+     * @param x - Initial X position in world space (center), in pixels. Default: `0`.
+     * @param y - Initial Y position in world space (center), in pixels. Default: `0`.
+     */
+    constructor(width, height, x = 0, y = 0) {
+        super();
+        /** @internal */
+        this._surface = null;
+        /** @internal */
+        this._surfaceCtx = null;
+        /** @internal */
+        this._lastRedrawPassId = -1;
+        /**
+         * When `false` (default), MinimoJS clears this sprite's internal canvas and
+         * calls {@link DrawSprite.redraw} on every render pass.
+         *
+         * When `true`, MinimoJS keeps and reuses the existing canvas contents without
+         * clearing or repainting them again, unless the internal surface does not yet
+         * exist or had to be resized.
+         *
+         * Use this when your procedural drawing becomes static after its first paint,
+         * or when you want explicit manual control over when the sprite is redrawn by
+         * toggling `frozen` at runtime.
+         */
+        this.frozen = false;
+        this._surfaceId = DrawSprite._nextSurfaceId++;
+        this._width = Math.max(1, Math.round(Number.isFinite(width) ? width : 1));
+        this._height = Math.max(1, Math.round(Number.isFinite(height) ? height : 1));
+        this.x = x;
+        this.y = y;
+    }
+    /**
+     * Called by the engine whenever the sprite's internal surface must be repainted.
+     *
+     * The provided context is already cleared and reset to the default 2D canvas
+     * state for the current surface size. MinimoJS repaints each `DrawSprite` at
+     * most once per render pass while it is not {@link DrawSprite.frozen}, so
+     * repeated snapshot reads during the same frame reuse the already-redrawn
+     * surface.
+     *
+     * @param ctx - The sprite's internal 2D drawing context.
+     */
+    redraw(_ctx) { }
+    getRenderCacheKey() {
+        return `draw:${this._surfaceId}`;
+    }
+}
+DrawSprite._nextSurfaceId = 1;
 /**
  * A renderable text actor that participates in the same animation/effects
  * pipeline as regular sprites.
@@ -1053,6 +1227,20 @@ export class Game {
          * ```
          */
         this.backgroundGradient = null;
+        /**
+         * When `true`, MinimoJS draws every sprite's collision body as an overlay.
+         *
+         * This is a runtime debugging aid only. It does not change collisions,
+         * input, rendering order, or physics behavior.
+         */
+        this.debugBodies = false;
+        /**
+         * When `true`, MinimoJS draws every sprite's input area as an overlay.
+         *
+         * This is a runtime debugging aid only. It does not change input behavior,
+         * physics, or rendering.
+         */
+        this.debugInputAreas = false;
         /**
          * Background color for the full web page (`document.body`).
          * Set to any valid CSS color string. Default: `null` (engine leaves page background unchanged).
@@ -2458,6 +2646,7 @@ export class Game {
     // Private — rendering
     // -------------------------------------------------------------------------
     /** @internal */ _onLoopFrameCallback(dt, dtMs) {
+        this._renderSystem.beginDynamicSurfacePass();
         if (this._transitionSystem.isActive) {
             this._transitionSystem.update(dtMs);
             if (this._transitionSystem.isActive) {
@@ -2584,6 +2773,8 @@ export class Game {
             background: this.background,
             backgroundGradient: this.backgroundGradient,
             pageBackground: this.pageBackground,
+            debugBodies: this.debugBodies,
+            debugInputAreas: this.debugInputAreas,
         });
     }
     /** @internal */ _renderTransition() {
@@ -2600,6 +2791,7 @@ export class Game {
         });
     }
     /** @internal */ _captureFrameSnapshot() {
+        this._renderSystem.beginDynamicSurfacePass();
         return this._renderSystem.captureFrame({
             canvas: this._canvas,
             context: this._ctx,
@@ -2615,6 +2807,8 @@ export class Game {
             background: this.background,
             backgroundGradient: this.backgroundGradient,
             pageBackground: this.pageBackground,
+            debugBodies: this.debugBodies,
+            debugInputAreas: this.debugInputAreas,
         });
     }
     /** @internal */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.17",
   "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",