minimojs 1.0.0-alpha.20 → 1.0.0-alpha.21

package/README.md

@@ -10,7 +10,7 @@ This README is intentionally high-level. It explains what the project is and how
 
 - ESM-only TypeScript-first engine
 - Single `Game` entry point
-- Emoji-based sprite rendering
+- Image-backed sprite rendering, with emoji as a zero-asset alternative
 - rAF-driven loop (timers/animations/updates)
 - Responsive auto-centered canvas
 
@@ -27,7 +27,7 @@ This README is intentionally high-level. It explains what the project is and how
 
 - Heavy scene-manager/ECS architecture
 - Heavy physics engine features
-- Image spritesheets and asset pipelines
+- Spritesheets, texture atlases, and asset pipelines
 - Nested subsystem APIs
 - `setTimeout` / `setInterval` game loops
 
@@ -40,7 +40,7 @@ npm install minimojs
 ## Quick Start
 
 ```ts
-import { DrawSprite, Game, Sprite, type IScene } from "minimojs";
+import { DrawSprite, EmojiSprite, Game, type IScene } from "minimojs";
 
 const game = new Game(720, 1280);
 game.gravityY = 980;
@@ -61,11 +61,11 @@ class MeterSprite extends DrawSprite {
 }
 
 class DemoScene implements IScene {
-  private player: Sprite | null = null;
+  private player: EmojiSprite | null = null;
   private meter: MeterSprite | null = null;
 
   onCreate() {
-    this.player = game.add(new Sprite("🐢", 360, 640, 48));
+    this.player = game.add(new EmojiSprite("🐢", 360, 640, 48));
     this.player.gravityScale = 1;
     this.meter = game.add(new MeterSprite(360, 80));
     this.meter.ignoreScroll = true;

package/dist/internal/AssetSystem.js

@@ -7,6 +7,8 @@ export class AssetSystem {
         this._loadedImages = new Map();
         /** @internal */
         this._imageSources = new Map();
+        /** @internal */
+        this._imageVersions = new Map();
     }
     queueImage(key, src) {
         const safeKey = key.trim();
@@ -24,9 +26,35 @@ export class AssetSystem {
         this._imageSources.set(safeKey, safeSrc);
         this._queuedImages.set(safeKey, safeSrc);
     }
+    createTexture(key, width, height, painter) {
+        const safeKey = key.trim();
+        if (safeKey.length === 0) {
+            throw new Error("MinimoJS: Texture keys must be non-empty strings.");
+        }
+        if (typeof painter !== "function") {
+            throw new Error("MinimoJS: createTexture() requires a painter function.");
+        }
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.max(1, Math.round(Number.isFinite(width) ? width : 1));
+        canvas.height = Math.max(1, Math.round(Number.isFinite(height) ? height : 1));
+        const ctx = canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("MinimoJS: Could not acquire a texture rendering context.");
+        }
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        painter(ctx, canvas);
+        this._queuedImages.delete(safeKey);
+        this._imageSources.delete(safeKey);
+        this._loadedImages.set(safeKey, canvas);
+        this.bumpImageVersion(safeKey);
+        return canvas;
+    }
     getImage(key) {
         return this._loadedImages.get(key);
     }
+    getImageVersion(key) {
+        return this._imageVersions.get(key) ?? 0;
+    }
     hasImage(key) {
         return this._loadedImages.has(key);
     }
@@ -49,6 +77,7 @@ export class AssetSystem {
         await Promise.all(entries.map(async ([key, src]) => {
             const image = await this.loadImage(src);
             this._loadedImages.set(key, image);
+            this.bumpImageVersion(key);
             loaded += 1;
             onProgress?.(loaded, total, key);
         }));
@@ -65,4 +94,8 @@ export class AssetSystem {
             image.src = src;
         });
     }
+    /** @internal */
+    bumpImageVersion(key) {
+        this._imageVersions.set(key, (this._imageVersions.get(key) ?? 0) + 1);
+    }
 }

package/dist/internal/RenderSystem.js

@@ -496,8 +496,8 @@ export class RenderSystem {
             throw new Error(`MinimoJS: Image '${sprite.imageKey}' is not loaded.`);
         }
         const canvas = document.createElement("canvas");
-        canvas.width = Math.max(1, image.naturalWidth || image.width);
-        canvas.height = Math.max(1, image.naturalHeight || image.height);
+        canvas.width = Math.max(1, image instanceof HTMLImageElement ? image.naturalWidth || image.width : image.width);
+        canvas.height = Math.max(1, image instanceof HTMLImageElement ? image.naturalHeight || image.height : image.height);
         const ctx = canvas.getContext("2d");
         if (!ctx) {
             throw new Error("MinimoJS: Could not acquire an image rendering context.");
@@ -774,8 +774,8 @@ export class RenderSystem {
             ctx.restore();
             return;
         }
-        const imageW = Math.max(1, image.naturalWidth || image.width);
-        const imageH = Math.max(1, image.naturalHeight || image.height);
+        const imageW = Math.max(1, image instanceof HTMLImageElement ? image.naturalWidth || image.width : image.width);
+        const imageH = Math.max(1, image instanceof HTMLImageElement ? image.naturalHeight || image.height : image.height);
         const scale = this.getBackgroundScale(layer.fit, destW, destH, imageW, imageH);
         const drawW = imageW * scale;
         const drawH = imageH * scale;

package/dist/internal/arcade-racer/ArcadeRacerCollisionSystem.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/arcade-racer/ArcadeRacerCollisionSystem.js

@@ -0,0 +1,198 @@
+const AUTO_BODY_WIDTH_VISUAL_RATIO = 0.76;
+const AUTO_BODY_LENGTH_PER_PIXEL = 1.92;
+/** @internal */
+export class ArcadeRacerCollisionSystem {
+    constructor(
+    /** @internal */ engine) {
+        this.engine = engine;
+    }
+    resolveAutoBodyFromVisual(visual, _scale) {
+        try {
+            const surface = this.engine.resolveVisualSurface(visual);
+            return {
+                width: Math.max(1, surface.width * AUTO_BODY_WIDTH_VISUAL_RATIO),
+                length: Math.max(1, surface.height),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    resolveCollisionBodyMetrics(visual, scale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY) {
+        return {
+            laneWidth: this.getBodyLaneWidthFromVisual(scale, bodyWidth),
+            distanceLength: this.getBodyLengthFromVisual(scale, bodyLength),
+            laneOffset: this.getBodyLaneOffsetFromVisual(visual, scale, bodyOffsetX),
+            distanceOffset: this.getBodyDistanceOffsetFromVisual(visual, scale, bodyOffsetY),
+        };
+    }
+    getDebugCollisionRectFromVisual(visualRect, visual, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY) {
+        const surface = this.engine.resolveVisualSurface(visual);
+        const projectedScale = Math.max(0, Math.min(visualRect.width / Math.max(1, surface.width), visualRect.height / Math.max(1, surface.height)));
+        const rectWidth = Math.max(4, bodyWidth * projectedScale);
+        const rectHeight = Math.max(8, bodyLength * projectedScale);
+        const offsetX = bodyOffsetX * projectedScale;
+        const offsetY = bodyOffsetY * projectedScale;
+        return {
+            x: visualRect.x + (visualRect.width - rectWidth) / 2 + offsetX,
+            y: visualRect.y + visualRect.height - rectHeight + offsetY,
+            width: rectWidth,
+            height: rectHeight,
+        };
+    }
+    getRealCollisionRect(current, width, height, ahead, lane, visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY, resolvedBody, anchorCenterX, anchorBottomY) {
+        const metrics = resolvedBody ??
+            this.resolveCollisionBodyMetrics(visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY);
+        const bodyLaneWidth = metrics.laneWidth;
+        const bodyDistanceLength = metrics.distanceLength;
+        const laneCenter = lane + metrics.laneOffset;
+        const bodyDistanceOffset = metrics.distanceOffset;
+        const depthCenter = this.getBodyDistanceCenterFromAnchor(ahead, bodyDistanceLength, bodyDistanceOffset);
+        const center = this.engine.projectTrafficPoint(current, depthCenter, width, height);
+        const far = this.engine.projectTrafficPoint(current, depthCenter + bodyDistanceLength * 0.5, width, height);
+        const near = this.engine.projectTrafficPoint(current, depthCenter - bodyDistanceLength * 0.5, width, height);
+        const laneUnit = center.roadWidth * 0.38;
+        const centerX = Number.isFinite(anchorCenterX)
+            ? anchorCenterX +
+                this.getBodyOffsetXInScreenPixels(visual, referenceScale, bodyOffsetX)
+            : center.x + laneCenter * laneUnit;
+        const rectWidth = Math.max(4, bodyLaneWidth * laneUnit);
+        const rawTop = Math.min(far.y, near.y);
+        const rawBottom = Math.max(far.y, near.y);
+        const rawHeight = Math.max(8, rawBottom - rawTop);
+        const bottom = Number.isFinite(anchorBottomY)
+            ? rawBottom +
+                (anchorBottomY - rawBottom) *
+                    this.engine.realCollisionVerticalShiftBlend
+            : rawBottom;
+        const top = bottom - rawHeight;
+        return {
+            x: centerX - rectWidth / 2,
+            y: top,
+            width: rectWidth,
+            height: rawHeight,
+        };
+    }
+    resolvePlayerTrafficCollisions() {
+        const nextCollisionIds = new Set();
+        const current = this.engine.trackSystem.sampleTrack(this.engine.distanceState);
+        const playerBodyWidth = this.engine.playerResolvedBodyState.laneWidth;
+        const playerBodyLength = this.engine.playerResolvedBodyState.distanceLength;
+        const playerLaneCenter = this.engine.playerLaneState + this.engine.playerResolvedBodyState.laneOffset;
+        const playerBodyDistanceOffset = this.engine.playerResolvedBodyState.distanceOffset;
+        const playerDistanceCenter = this.engine.distanceState +
+            this.getBodyDistanceCenterFromAnchor(this.engine.playerProjectionAheadDistance, playerBodyLength, playerBodyDistanceOffset);
+        const playerRect = this.getRealCollisionRect(current, this.engine.width, this.engine.height, this.engine.playerProjectionAheadDistance, this.engine.playerLaneState, this.engine.playerVisualState, this.engine.playerBaseScaleState, this.engine.playerBodyWidthState, this.engine.playerBodyLengthState, this.engine.playerBodyOffsetXState, this.engine.playerBodyOffsetYState, this.engine.playerResolvedBodyState, this.engine.getPlayerScreenX(), this.engine.playerScreenYState);
+        for (const traffic of this.engine.trafficState) {
+            const trafficBodyWidth = traffic.resolvedBody.laneWidth;
+            const trafficBodyLength = traffic.resolvedBody.distanceLength;
+            const trafficBodyDistanceOffset = traffic.resolvedBody.distanceOffset;
+            const trafficLaneCenter = traffic.lane + traffic.resolvedBody.laneOffset;
+            const trafficDistanceCenter = this.getBodyDistanceCenterFromAnchor(traffic.distance, trafficBodyLength, trafficBodyDistanceOffset);
+            const distanceDelta = trafficDistanceCenter - playerDistanceCenter;
+            const laneDelta = trafficLaneCenter - playerLaneCenter;
+            const hitDepth = Math.abs(distanceDelta) < (playerBodyLength + trafficBodyLength) * 0.5;
+            const hitLane = Math.abs(laneDelta) < (playerBodyWidth + trafficBodyWidth) * 0.5;
+            if (!hitDepth || !hitLane)
+                continue;
+            const trafficVisualBottom = this.engine.projectTrafficPoint(current, traffic.distance - this.engine.distanceState, this.engine.width, this.engine.height).y;
+            const trafficRect = this.getRealCollisionRect(current, this.engine.width, this.engine.height, traffic.distance - this.engine.distanceState, traffic.lane, traffic.visual, traffic.baseScale, traffic.bodyWidth, traffic.bodyLength, traffic.bodyOffsetX, traffic.bodyOffsetY, traffic.resolvedBody, undefined, trafficVisualBottom);
+            if (playerRect &&
+                trafficRect &&
+                !this.rectsOverlap(playerRect, trafficRect)) {
+                continue;
+            }
+            nextCollisionIds.add(traffic.id);
+            if (this.engine.activeCollisionIds.has(traffic.id))
+                continue;
+            const collision = {
+                trafficId: traffic.id,
+                distanceDelta,
+                laneDelta,
+                trafficDistance: traffic.distance,
+                trafficLane: traffic.lane,
+            };
+            for (const handler of this.engine.collisionHandlers) {
+                handler(collision);
+            }
+        }
+        this.engine.activeCollisionIds = nextCollisionIds;
+    }
+    getPlayerScreenLaneUnit() {
+        return this.engine.roadNearWidth * 0.38;
+    }
+    getBodyDistanceCenterFromAnchor(anchorDistance, bodyLength, bodyDistanceOffset) {
+        return anchorDistance + bodyLength * 0.5 - bodyDistanceOffset;
+    }
+    /** @internal */
+    getBodyOffsetXInScreenPixels(visual, scale, bodyOffsetX) {
+        if (!Number.isFinite(bodyOffsetX) || bodyOffsetX === 0)
+            return 0;
+        try {
+            const surface = this.engine.resolveVisualSurface(visual);
+            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+            const visualWidth = Math.max(1, surface.width * safeScale);
+            return Math.max(-visualWidth * 0.5, Math.min(visualWidth * 0.5, bodyOffsetX * safeScale));
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** @internal */
+    getBodyLaneWidthFromVisual(scale, bodyWidth) {
+        if (!Number.isFinite(bodyWidth) || bodyWidth <= 0)
+            return 0;
+        const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+        const projectedWidth = Math.max(1, bodyWidth * safeScale);
+        const laneUnit = Math.max(1, this.getPlayerScreenLaneUnit());
+        return Math.max(0.01, projectedWidth / laneUnit);
+    }
+    /** @internal */
+    getBodyLengthFromVisual(scale, bodyLength) {
+        if (!Number.isFinite(bodyLength) || bodyLength <= 0)
+            return 0;
+        const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+        const projectedLength = Math.max(1, bodyLength * safeScale);
+        return Math.max(1, projectedLength * AUTO_BODY_LENGTH_PER_PIXEL);
+    }
+    /** @internal */
+    getBodyLaneOffsetFromVisual(visual, scale, bodyOffsetX) {
+        if (!Number.isFinite(bodyOffsetX) || bodyOffsetX === 0)
+            return 0;
+        try {
+            const surface = this.engine.resolveVisualSurface(visual);
+            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+            const projectedOffsetX = bodyOffsetX * safeScale;
+            const laneUnit = Math.max(1, this.getPlayerScreenLaneUnit());
+            const visualWidth = Math.max(1, surface.width * safeScale);
+            const clampedOffsetX = Math.max(-visualWidth * 0.5, Math.min(visualWidth * 0.5, projectedOffsetX));
+            return clampedOffsetX / laneUnit;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** @internal */
+    getBodyDistanceOffsetFromVisual(visual, scale, bodyOffsetY) {
+        if (!Number.isFinite(bodyOffsetY) || bodyOffsetY === 0)
+            return 0;
+        try {
+            const surface = this.engine.resolveVisualSurface(visual);
+            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+            const projectedOffsetY = bodyOffsetY * safeScale;
+            const visualHeight = Math.max(1, surface.height * safeScale);
+            const clampedOffsetY = Math.max(-visualHeight * 0.5, Math.min(visualHeight * 0.5, projectedOffsetY));
+            return clampedOffsetY * AUTO_BODY_LENGTH_PER_PIXEL;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** @internal */
+    rectsOverlap(a, b) {
+        return !(a.x + a.width <= b.x ||
+            b.x + b.width <= a.x ||
+            a.y + a.height <= b.y ||
+            b.y + b.height <= a.y);
+    }
+}

package/dist/internal/arcade-racer/ArcadeRacerLaneSystem.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/arcade-racer/ArcadeRacerLaneSystem.js

@@ -0,0 +1,120 @@
+/** @internal */
+export function sanitizeLaneSpacePositions(values) {
+    if (!Array.isArray(values))
+        return null;
+    const sanitized = [];
+    for (const value of values) {
+        if (!Number.isFinite(value))
+            continue;
+        sanitized.push(Math.max(-1, Math.min(1, value)));
+    }
+    return sanitized;
+}
+/** @internal */
+export class ArcadeRacerLaneSystem {
+    constructor(requestedLaneCount, laneDirections) {
+        const highestConfiguredLaneIndex = this.getHighestConfiguredLaneIndex(laneDirections);
+        this.laneCountState = Math.max(1, Math.round(requestedLaneCount), highestConfiguredLaneIndex + 1);
+        this.lanePositionsState = this.buildLanePositions(this.laneCountState);
+        const laneDirectionGroups = this.resolveLaneDirectionIndices(laneDirections, this.laneCountState);
+        this.sameDirectionLaneIndicesState = laneDirectionGroups.same;
+        this.oncomingLaneIndicesState = laneDirectionGroups.oncoming;
+    }
+    get laneCount() {
+        return this.laneCountState;
+    }
+    getLanePosition(laneIndex) {
+        if (this.lanePositionsState.length === 0)
+            return 0;
+        const safeIndex = Number.isFinite(laneIndex)
+            ? Math.max(0, Math.min(this.laneCountState - 1, Math.round(laneIndex)))
+            : 0;
+        return this.lanePositionsState[safeIndex] ?? 0;
+    }
+    getLanePositions(direction = "all") {
+        if (direction === "all") {
+            return [...this.lanePositionsState];
+        }
+        const indices = direction === "same"
+            ? this.sameDirectionLaneIndicesState
+            : this.oncomingLaneIndicesState;
+        if (indices === null) {
+            return [...this.lanePositionsState];
+        }
+        return indices.map((index) => this.getLanePosition(index));
+    }
+    clampRoadLane(value) {
+        if (!Number.isFinite(value))
+            return 0;
+        return Math.max(-1, Math.min(1, value));
+    }
+    /** @internal */
+    buildLanePositions(laneCount) {
+        const positions = [];
+        for (let index = 0; index < laneCount; index++) {
+            positions.push(((index + 0.5) / laneCount) * 2 - 1);
+        }
+        return positions;
+    }
+    /** @internal */
+    sanitizeLaneIndexList(values, laneCount) {
+        if (!Array.isArray(values))
+            return [];
+        const result = [];
+        const seen = new Set();
+        for (const value of values) {
+            if (!Number.isFinite(value))
+                continue;
+            const index = Math.round(value);
+            if (index < 0 || index >= laneCount || seen.has(index))
+                continue;
+            seen.add(index);
+            result.push(index);
+        }
+        return result.sort((a, b) => a - b);
+    }
+    /** @internal */
+    getHighestConfiguredLaneIndex(config) {
+        let highest = -1;
+        for (const list of [config?.same, config?.oncoming]) {
+            if (!Array.isArray(list))
+                continue;
+            for (const value of list) {
+                if (!Number.isFinite(value))
+                    continue;
+                highest = Math.max(highest, Math.round(value));
+            }
+        }
+        return highest;
+    }
+    /** @internal */
+    resolveLaneDirectionIndices(config, laneCount) {
+        const hasSame = Array.isArray(config?.same);
+        const hasOncoming = Array.isArray(config?.oncoming);
+        if (!hasSame && !hasOncoming) {
+            return { same: null, oncoming: null };
+        }
+        const allLaneIndices = Array.from({ length: laneCount }, (_, index) => index);
+        const same = this.sanitizeLaneIndexList(config?.same, laneCount);
+        const oncoming = this.sanitizeLaneIndexList(config?.oncoming, laneCount);
+        if (hasSame && hasOncoming) {
+            const sameSet = new Set(same);
+            return {
+                same,
+                oncoming: oncoming.filter((index) => !sameSet.has(index)),
+            };
+        }
+        if (hasSame) {
+            const sameSet = new Set(same);
+            return {
+                same,
+                oncoming: allLaneIndices.filter((index) => !sameSet.has(index)),
+            };
+        }
+        const oncomingSet = new Set(oncoming);
+        return {
+            same: allLaneIndices.filter((index) => !oncomingSet.has(index)),
+            oncoming,
+        };
+    }
+}

package/dist/internal/arcade-racer/ArcadeRacerRenderSystem.d.ts

@@ -0,0 +1 @@
+export {};