minimojs 1.0.0-alpha.18 → 1.0.0-alpha.19

package/dist/minimo-arcaderacer.d.ts

@@ -216,6 +216,25 @@ export interface ArcadeRacerMinimapOptions {
     /** Player marker radius in pixels. Default: `4`. */
     playerRadius: number;
 }
+/**
+ * Debug overlay settings for inspecting projected car bounds and collisions.
+ */
+export interface ArcadeRacerDebugOptions {
+    /** Whether the debug overlay is rendered. Default: `false`. */
+    enabled: boolean;
+    /** Draws the actual screen-space image/emoji rectangle. Default: `true`. */
+    visualBounds: boolean;
+    /** Draws the approximate road-space collision body rectangle. Default: `true`. */
+    collisionBounds: boolean;
+    /** Stroke color for the rendered visual rectangle. Default: `rgba(80, 220, 255, 0.9)`. */
+    visualBoundsColor: string;
+    /** Stroke color for the player collision body. Default: `rgba(255, 238, 88, 0.95)`. */
+    playerCollisionBoundsColor: string;
+    /** Stroke color for traffic collision bodies. Default: `rgba(255, 82, 82, 0.95)`. */
+    trafficCollisionBoundsColor: string;
+    /** Debug stroke width in screen pixels. Default: `2`. */
+    lineWidth: number;
+}
 /**
  * Construction options for {@link ArcadeRacerEngine}.
  */
@@ -258,9 +277,9 @@ export interface ArcadeRacerEngineOptions {
     playerBaseScale?: number;
     /** Player visual source. Default: `🏎️`. */
     playerVisual?: ArcadeRacerVisualSource;
-    /** Player collision width in lane units. Default: `0.26`. */
+    /** Player collision width in lane units. Defaults to a value derived from the player visual size. */
     playerBodyWidth?: number;
-    /** Player collision length in world distance units. Default: `120`. */
+    /** Player collision length in world distance units. Defaults to a value derived from the player visual size. */
     playerBodyLength?: number;
     /** Steering speed in lane units per second. Default: `1.85`. */
     steeringRate?: number;
@@ -304,6 +323,8 @@ export interface ArcadeRacerEngineOptions {
     horizon?: Partial<ArcadeRacerHorizonOptions>;
     /** Optional partial minimap overlay override. */
     minimap?: Partial<ArcadeRacerMinimapOptions>;
+    /** Optional debug overlay for car visual and collision bounds. */
+    debug?: boolean | Partial<ArcadeRacerDebugOptions>;
     /** Optional partial theme override. */
     theme?: Partial<ArcadeRacerTheme>;
 }
@@ -343,9 +364,9 @@ export interface ArcadeRacerTrafficConfig {
     speed?: number;
     /** Optional multiplier applied to the projected scale. Default: `1`. */
     baseScale?: number;
-    /** Collision width in lane units. Default: `0.26`. */
+    /** Collision width in lane units. Defaults to a value derived from the traffic visual size. */
     bodyWidth?: number;
-    /** Collision length in world distance units. Default: `120`. */
+    /** Collision length in world distance units. Defaults to a value derived from the traffic visual size. */
     bodyLength?: number;
     /** Whether the car should be recycled one lap ahead when it falls behind. Default: `true`. */
     loop?: boolean;
@@ -465,6 +486,8 @@ export interface ArcadeRacerTrafficCollision {
  *   certain headings.
  * - Use {@link setPlayerBody} when you need to tune collisions without changing
  *   the player artwork.
+ * - Use {@link setDebug} when you need to visualize car image bounds and
+ *   collision bodies while tuning traffic hits.
  *
  * This interface is the canonical public surface of the module. Its JSDoc is
  * intended to be consumed directly by AI agents and tooling that generate code
@@ -683,6 +706,14 @@ export interface ArcadeRacerEngine {
      * Merges minimap settings into the current minimap config.
      */
     setMinimap(options: Partial<ArcadeRacerMinimapOptions>): void;
+    /**
+     * Enables, disables, or updates the debug overlay for car bounds.
+     *
+     * Pass `true` to enable defaults, `false` to disable, or a partial options
+     * object to customize colors and which rectangles are shown. The overlay draws
+     * visual rectangles and collision-body rectangles for the player and traffic.
+     */
+    setDebug(options: boolean | Partial<ArcadeRacerDebugOptions>): void;
     /**
      * Shows the minimap and optionally applies a partial minimap config update.
      */

package/dist/minimo-arcaderacer.js

@@ -45,6 +45,17 @@ const DEFAULT_MINIMAP = {
     playerStrokeColor: "#fff7dd",
     playerRadius: 4,
 };
+const AUTO_BODY_WIDTH_VISUAL_RATIO = 0.76;
+const AUTO_BODY_LENGTH_PER_PIXEL = 1.92;
+const DEFAULT_DEBUG = {
+    enabled: false,
+    visualBounds: true,
+    collisionBounds: true,
+    visualBoundsColor: "rgba(80, 220, 255, 0.9)",
+    playerCollisionBoundsColor: "rgba(255, 238, 88, 0.95)",
+    trafficCollisionBoundsColor: "rgba(255, 82, 82, 0.95)",
+    lineWidth: 2,
+};
 const MPH_PER_SPEED_UNIT = 0.22;
 const DEFAULT_GROUND_FILL = {
     enabled: true,
@@ -104,6 +115,10 @@ class ArcadeRacerEngineImpl {
         /** @internal */
         this.backgroundLayersState = [];
         /** @internal */
+        this.playerBodyWidthManual = false;
+        /** @internal */
+        this.playerBodyLengthManual = false;
+        /** @internal */
         this.distanceState = 0;
         /** @internal */
         this.nextId = 1;
@@ -180,16 +195,24 @@ class ArcadeRacerEngineImpl {
             playerStrokeColor: options.minimap?.playerStrokeColor ?? DEFAULT_MINIMAP.playerStrokeColor,
             playerRadius: options.minimap?.playerRadius ?? DEFAULT_MINIMAP.playerRadius,
         });
+        this.debugState = this.sanitizeDebugOptions(options.debug ?? false);
         this.playerVisualState =
             options.playerVisual ?? { type: "emoji", value: "🏎️", size: 48 };
         this.playerScreenYState =
             options.playerScreenY ?? Math.round(this.height * 0.86);
         this.playerBaseScaleState =
             options.playerBaseScale ?? DEFAULT_OPTIONS.playerBaseScale;
+        this.playerBodyWidthManual = Number.isFinite(options.playerBodyWidth);
+        this.playerBodyLengthManual = Number.isFinite(options.playerBodyLength);
+        const autoPlayerBody = this.resolveAutoBodyFromVisual(this.playerVisualState, this.playerBaseScaleState);
         this.playerBodyWidthState =
-            options.playerBodyWidth ?? DEFAULT_OPTIONS.playerBodyWidth;
+            options.playerBodyWidth ??
+                autoPlayerBody?.width ??
+                DEFAULT_OPTIONS.playerBodyWidth;
         this.playerBodyLengthState =
-            options.playerBodyLength ?? DEFAULT_OPTIONS.playerBodyLength;
+            options.playerBodyLength ??
+                autoPlayerBody?.length ??
+                DEFAULT_OPTIONS.playerBodyLength;
         this.speedState = options.speed ?? DEFAULT_OPTIONS.speed;
         this.playerLaneState = this.clampPlayerLane(options.playerLane ?? DEFAULT_OPTIONS.playerLane);
         this.resetTrack();
@@ -468,21 +491,23 @@ class ArcadeRacerEngineImpl {
      */
     addTraffic(visual, config) {
         const id = this.makeId("car");
+        const baseScale = Number.isFinite(config.baseScale)
+            ? Math.max(0, config.baseScale)
+            : 1;
+        const autoBody = this.resolveAutoBodyFromVisual(visual, baseScale);
         this.trafficState.push({
             id,
             visual,
             distance: Math.max(0, config.distance),
             lane: this.clampRoadLane(config.lane),
             speed: Number.isFinite(config.speed) ? config.speed : 140,
-            baseScale: Number.isFinite(config.baseScale)
-                ? Math.max(0, config.baseScale)
-                : 1,
+            baseScale,
             bodyWidth: Number.isFinite(config.bodyWidth)
                 ? Math.max(0.01, config.bodyWidth)
-                : 0.26,
+                : autoBody?.width ?? 0.26,
             bodyLength: Number.isFinite(config.bodyLength)
                 ? Math.max(1, config.bodyLength)
-                : 120,
+                : autoBody?.length ?? 120,
             loop: config.loop ?? true,
             alpha: this.clamp01(config.alpha ?? 1),
         });
@@ -598,6 +623,12 @@ class ArcadeRacerEngineImpl {
             ...options,
         });
     }
+    /**
+     * Enables, disables, or updates car bounds debug rendering.
+     */
+    setDebug(options) {
+        this.debugState = this.sanitizeDebugOptions(typeof options === "boolean" ? options : { ...this.debugState, ...options });
+    }
     /**
      * Shows the minimap and optionally applies overrides.
      */
@@ -615,6 +646,7 @@ class ArcadeRacerEngineImpl {
      */
     setPlayerVisual(source) {
         this.playerVisualState = source;
+        this.refreshAutoPlayerBodyFromVisual();
     }
     /**
      * Updates the player screen-space Y position.
@@ -630,9 +662,11 @@ class ArcadeRacerEngineImpl {
     setPlayerBody(width, length) {
         if (Number.isFinite(width)) {
             this.playerBodyWidthState = Math.max(0.01, width);
+            this.playerBodyWidthManual = true;
         }
         if (Number.isFinite(length)) {
             this.playerBodyLengthState = Math.max(1, length);
+            this.playerBodyLengthManual = true;
         }
     }
     /**
@@ -642,6 +676,7 @@ class ArcadeRacerEngineImpl {
         if (!Number.isFinite(value))
             return;
         this.playerBaseScaleState = Math.max(0, value);
+        this.refreshAutoPlayerBodyFromVisual();
     }
     /**
      * Updates the player lane position.
@@ -1076,6 +1111,7 @@ class ArcadeRacerEngineImpl {
                 scale: projection.scale * billboard.baseScale,
                 alpha: billboard.alpha,
                 visual: billboard.visual,
+                kind: "billboard",
             });
         }
         for (const traffic of this.trafficState) {
@@ -1093,34 +1129,135 @@ class ArcadeRacerEngineImpl {
                 scale: projection.scale * traffic.baseScale,
                 alpha: traffic.alpha,
                 visual: traffic.visual,
+                kind: "traffic",
+                bodyWidth: traffic.bodyWidth,
+                bodyLength: traffic.bodyLength,
+                bodyReferenceScale: traffic.baseScale,
             });
         }
         const playerProjection = this.projectTrafficPoint(current, this.playerProjectionAheadDistance, width, height);
-        const playerLaneWidth = this.roadNearWidth * 0.52;
+        const playerCenterX = this.getPlayerScreenX();
         visible.push({
             depth: this.playerProjectionAheadDistance,
-            x: width / 2 + this.playerLaneState * playerLaneWidth,
+            x: playerCenterX,
             y: this.playerScreenYState,
             scale: playerProjection.scale * this.playerBaseScaleState,
             alpha: 1,
             visual: this.playerVisualState,
+            kind: "player",
+            bodyWidth: this.playerBodyWidthState,
+            bodyLength: this.playerBodyLengthState,
+            bodyReferenceScale: this.playerBaseScaleState,
         });
         visible.sort((a, b) => b.depth - a.depth);
         for (const entry of visible) {
-            this.drawVisual(ctx, entry.visual, entry.x, entry.y, entry.scale, entry.alpha);
+            const visualRect = this.drawVisual(ctx, entry.visual, entry.x, entry.y, entry.scale, entry.alpha);
+            if (entry.kind !== "billboard") {
+                this.drawCarDebugBounds(ctx, entry.kind, visualRect, entry.visual, entry.bodyReferenceScale, entry.bodyWidth, entry.bodyLength);
+            }
         }
     }
     /** @internal */
     drawVisual(ctx, visual, x, y, scale, alpha) {
         const surface = this.resolveVisualSurface(visual);
+        const rect = this.getVisualRect(surface, x, y, scale);
+        ctx.save();
+        ctx.globalAlpha = this.clamp01(alpha);
+        ctx.drawImage(surface.source, rect.x, rect.y, rect.width, rect.height);
+        ctx.restore();
+        return rect;
+    }
+    /** @internal */
+    getVisualRect(surface, x, y, scale) {
         const drawWidth = Math.max(1, surface.width * Math.max(0, scale));
         const drawHeight = Math.max(1, surface.height * Math.max(0, scale));
+        return {
+            x: Math.round(x - drawWidth / 2),
+            y: Math.round(y - drawHeight),
+            width: drawWidth,
+            height: drawHeight,
+        };
+    }
+    /** @internal */
+    drawCarDebugBounds(ctx, kind, visualRect, visual, bodyReferenceScale, bodyWidth, bodyLength) {
+        if (!this.debugState.enabled)
+            return;
         ctx.save();
-        ctx.globalAlpha = this.clamp01(alpha);
-        ctx.drawImage(surface.source, Math.round(x - drawWidth / 2), Math.round(y - drawHeight), drawWidth, drawHeight);
+        ctx.lineWidth = this.debugState.lineWidth;
+        ctx.setLineDash([]);
+        if (this.debugState.visualBounds) {
+            ctx.strokeStyle = this.debugState.visualBoundsColor;
+            ctx.strokeRect(visualRect.x, visualRect.y, visualRect.width, visualRect.height);
+        }
+        const collisionRect = this.debugState.collisionBounds &&
+            Number.isFinite(bodyWidth) &&
+            Number.isFinite(bodyLength)
+            ? this.getDebugCollisionRectFromVisual(visualRect, visual, bodyReferenceScale ?? 1, bodyWidth, bodyLength)
+            : null;
+        if (this.debugState.collisionBounds && collisionRect) {
+            ctx.strokeStyle =
+                kind === "player"
+                    ? this.debugState.playerCollisionBoundsColor
+                    : this.debugState.trafficCollisionBoundsColor;
+            ctx.setLineDash([6, 4]);
+            ctx.strokeRect(collisionRect.x, collisionRect.y, collisionRect.width, collisionRect.height);
+        }
         ctx.restore();
     }
     /** @internal */
+    getDebugCollisionRectFromVisual(visualRect, visual, referenceScale, bodyWidth, bodyLength) {
+        const autoBody = this.resolveAutoBodyFromVisual(visual, referenceScale);
+        if (!autoBody)
+            return null;
+        const widthRatio = Math.max(0.05, bodyWidth / autoBody.width);
+        const heightRatio = Math.max(0.05, bodyLength / autoBody.length);
+        const rectWidth = Math.max(4, visualRect.width * AUTO_BODY_WIDTH_VISUAL_RATIO * widthRatio);
+        const rectHeight = Math.max(8, visualRect.height * heightRatio);
+        return {
+            x: visualRect.x + (visualRect.width - rectWidth) / 2,
+            y: visualRect.y + visualRect.height - rectHeight,
+            width: rectWidth,
+            height: rectHeight,
+        };
+    }
+    /** @internal */
+    getPlayerScreenLaneUnit() {
+        return this.roadNearWidth * 0.38;
+    }
+    /** @internal */
+    resolveAutoBodyFromVisual(visual, scale) {
+        try {
+            const surface = this.resolveVisualSurface(visual);
+            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
+            const visualWidth = Math.max(1, surface.width * safeScale);
+            const visualHeight = Math.max(1, surface.height * safeScale);
+            const laneUnit = Math.max(1, this.getPlayerScreenLaneUnit());
+            return {
+                width: Math.max(0.01, (visualWidth * AUTO_BODY_WIDTH_VISUAL_RATIO) / laneUnit),
+                length: Math.max(1, visualHeight * AUTO_BODY_LENGTH_PER_PIXEL),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** @internal */
+    refreshAutoPlayerBodyFromVisual() {
+        const autoBody = this.resolveAutoBodyFromVisual(this.playerVisualState, this.playerBaseScaleState);
+        if (!autoBody)
+            return;
+        if (!this.playerBodyWidthManual) {
+            this.playerBodyWidthState = autoBody.width;
+        }
+        if (!this.playerBodyLengthManual) {
+            this.playerBodyLengthState = autoBody.length;
+        }
+    }
+    /** @internal */
+    getPlayerScreenX() {
+        return this.width / 2 + this.playerLaneState * this.getPlayerScreenLaneUnit();
+    }
+    /** @internal */
     resolveVisualSurface(visual) {
         if (visual.type === "image") {
             const image = this.game.getImage(visual.key);
@@ -1824,6 +1961,25 @@ class ArcadeRacerEngineImpl {
         };
     }
     /** @internal */
+    sanitizeDebugOptions(options) {
+        if (typeof options === "boolean") {
+            return { ...DEFAULT_DEBUG, enabled: options };
+        }
+        return {
+            enabled: options.enabled ?? DEFAULT_DEBUG.enabled,
+            visualBounds: options.visualBounds ?? DEFAULT_DEBUG.visualBounds,
+            collisionBounds: options.collisionBounds ?? DEFAULT_DEBUG.collisionBounds,
+            visualBoundsColor: options.visualBoundsColor || DEFAULT_DEBUG.visualBoundsColor,
+            playerCollisionBoundsColor: options.playerCollisionBoundsColor ||
+                DEFAULT_DEBUG.playerCollisionBoundsColor,
+            trafficCollisionBoundsColor: options.trafficCollisionBoundsColor ||
+                DEFAULT_DEBUG.trafficCollisionBoundsColor,
+            lineWidth: Number.isFinite(options.lineWidth)
+                ? Math.max(1, options.lineWidth)
+                : DEFAULT_DEBUG.lineWidth,
+        };
+    }
+    /** @internal */
     normalizeAngle(angle) {
         if (!Number.isFinite(angle))
             return 0;

package/package.json

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