minimojs 1.0.0-alpha.16 → 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/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);
     }
@@ -348,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)
@@ -467,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

@@ -471,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.

package/dist/minimo.js

@@ -383,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.
@@ -2540,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) {
@@ -2684,6 +2791,7 @@ export class Game {
         });
     }
     /** @internal */ _captureFrameSnapshot() {
+        this._renderSystem.beginDynamicSurfacePass();
         return this._renderSystem.captureFrame({
             canvas: this._canvas,
             context: this._ctx,

package/package.json

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