minimojs 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/minimo-arcaderacer.js

@@ -0,0 +1,2060 @@
+import { ArcadeRacerLaneSystem, sanitizeLaneSpacePositions, } from "./internal/arcade-racer/ArcadeRacerLaneSystem.js";
+import { ArcadeRacerCollisionSystem } from "./internal/arcade-racer/ArcadeRacerCollisionSystem.js";
+import { ArcadeRacerRenderSystem } from "./internal/arcade-racer/ArcadeRacerRenderSystem.js";
+import { ArcadeRacerRoadSprite } from "./internal/arcade-racer/ArcadeRacerRoadSprite.js";
+import { ArcadeRacerTrackSystem } from "./internal/arcade-racer/ArcadeRacerTrackSystem.js";
+/**
+ * Default road drawer used by {@link ArcadeRacerEngine}.
+ *
+ * Extend this class when you want to keep the built-in pseudo-3D road geometry
+ * and only customize colors, lane markings, textures, or strip-level effects.
+ */
+export class DefaultArcadeRacerRoadDrawer {
+    /** Paints the full default strip in four stages: ground, shoulders, road, and lane markers. */
+    drawStrip(ctx, frame, strip) {
+        this.drawGround(ctx, frame, strip);
+        this.drawShoulders(ctx, frame, strip);
+        this.drawRoadSurface(ctx, frame, strip);
+        this.drawLaneMarkers(ctx, frame, strip);
+    }
+    /** Draws the default post-road vignette overlay. */
+    drawOverlay(ctx, frame) {
+        const vignette = ctx.createLinearGradient(0, frame.horizonY, 0, frame.height);
+        vignette.addColorStop(0, "rgba(0, 0, 0, 0)");
+        vignette.addColorStop(1, "rgba(0, 0, 0, 0.18)");
+        ctx.fillStyle = vignette;
+        ctx.fillRect(0, frame.horizonY, frame.width, frame.height - frame.horizonY);
+    }
+    /** Draws the off-road ground area for one strip. */
+    drawGround(ctx, frame, strip) {
+        this.drawQuad(ctx, 0, strip.farY, frame.width, strip.farY, frame.width, strip.nearY, 0, strip.nearY, this.getGrassColor(frame, strip));
+    }
+    /** Draws the shoulder band for one strip. */
+    drawShoulders(ctx, frame, strip) {
+        this.drawQuad(ctx, strip.leftOuterFar, strip.farY, strip.rightOuterFar, strip.farY, strip.rightOuterNear, strip.nearY, strip.leftOuterNear, strip.nearY, this.getShoulderColor(frame, strip));
+    }
+    /** Draws the paved road surface for one strip. */
+    drawRoadSurface(ctx, frame, strip) {
+        this.drawQuad(ctx, strip.leftRoadFar, strip.farY, strip.rightRoadFar, strip.farY, strip.rightRoadNear, strip.nearY, strip.leftRoadNear, strip.nearY, this.getRoadColor(frame, strip));
+    }
+    /** Draws all lane markers for one strip when enabled. */
+    drawLaneMarkers(ctx, frame, strip) {
+        if (!this.shouldDrawLaneMarkers(frame, strip)) {
+            return;
+        }
+        const color = this.getLaneMarkerColor(frame, strip);
+        for (const marker of strip.laneMarkers) {
+            this.drawQuad(ctx, marker.farX - marker.farWidth / 2, strip.farY, marker.farX + marker.farWidth / 2, strip.farY, marker.nearX + marker.nearWidth / 2, strip.nearY, marker.nearX - marker.nearWidth / 2, strip.nearY, color);
+        }
+    }
+    /** Returns the fill color used for the ground area of a strip. */
+    getGrassColor(frame, strip) {
+        return strip.grassBandIndex % 2 === 0
+            ? frame.theme.grassA
+            : frame.theme.grassB;
+    }
+    /** Returns the fill color used for the shoulder area of a strip. */
+    getShoulderColor(frame, strip) {
+        return strip.shoulderBandIndex % 2 === 0
+            ? frame.theme.shoulderA
+            : frame.theme.shoulderB;
+    }
+    /** Returns the fill color used for the paved road of a strip. */
+    getRoadColor(frame, strip) {
+        return strip.roadBandIndex % 2 === 0
+            ? frame.theme.roadA
+            : frame.theme.roadB;
+    }
+    /** Returns the color used for lane-marker quads. */
+    getLaneMarkerColor(frame, _strip) {
+        return frame.theme.laneMarker;
+    }
+    /** Controls whether lane markers should be painted for the strip. */
+    shouldDrawLaneMarkers(_frame, strip) {
+        return strip.laneMarkers.length > 0;
+    }
+    /** Helper that fills a four-point polygon, useful for custom subclasses. */
+    drawQuad(ctx, x1, y1, x2, y2, x3, y3, x4, y4, color) {
+        ctx.fillStyle = color;
+        ctx.beginPath();
+        ctx.moveTo(x1, y1);
+        ctx.lineTo(x2, y2);
+        ctx.lineTo(x3, y3);
+        ctx.lineTo(x4, y4);
+        ctx.closePath();
+        ctx.fill();
+    }
+}
+/**
+ * Road drawer that forwards each paint call to multiple child drawers.
+ *
+ * Drawers are executed in array order, which makes this useful for layering a
+ * base road style with extra passes such as crops, palm fields, rocks, or
+ * tunnel accents.
+ */
+export class CompositeRoadDrawer {
+    /**
+     * Creates a composite drawer from the provided children.
+     *
+     * The order matters: earlier drawers paint first and later drawers paint on top.
+     */
+    constructor(drawers = []) {
+        this.drawers = [...drawers];
+    }
+    /** Paints the strip by forwarding the call to each child drawer in order. */
+    drawStrip(ctx, frame, strip) {
+        for (const drawer of this.drawers) {
+            drawer.drawStrip(ctx, frame, strip);
+        }
+    }
+    /** Forwards the optional overlay pass to each child drawer that implements it. */
+    drawOverlay(ctx, frame) {
+        for (const drawer of this.drawers) {
+            drawer.drawOverlay?.(ctx, frame);
+        }
+    }
+    /** Appends another child drawer to the composite. */
+    addDrawer(drawer) {
+        this.drawers.push(drawer);
+    }
+    /** Removes all child drawers from the composite. */
+    clearDrawers() {
+        this.drawers.length = 0;
+    }
+}
+/**
+ * Configurable roadside crop drawer.
+ *
+ * This drawer paints repeated crop sprites across the left and/or right grass
+ * bands. Use it inside {@link CompositeRoadDrawer} together with
+ * {@link DefaultArcadeRacerRoadDrawer} when you want the built-in road style
+ * plus crop layouts on top.
+ */
+export class CropRoadDrawer extends DefaultArcadeRacerRoadDrawer {
+    /** Creates a crop drawer with configurable density, spacing, and height variation. */
+    constructor(options) {
+        super();
+        /** @internal */
+        this.emojiSurfaceCache = null;
+        this.game = options.game;
+        this.visual = options.visual;
+        this.sides = options.sides?.length
+            ? [...options.sides]
+            : ["left", "right"];
+        this.paintGround = options.paintGround ?? false;
+        this.groundColor = options.groundColor ?? "#7b5a32";
+        this.rowSpacing = Math.max(1, options.rowSpacing ?? 82);
+        this.columnSpacing = Math.max(1, options.columnSpacing ?? 34);
+        this.columnSpacingJitter = Math.max(0, options.columnSpacingJitter ?? 0);
+        this.columnInset = Math.max(0, options.columnInset ?? 42);
+        this.rowShift =
+            options.rowShift ?? Math.max(0, this.columnSpacing * 0.5);
+        this.minHeightRatio = Math.max(0.1, options.minHeightRatio ?? 0.85);
+        this.maxHeightRatio = Math.max(this.minHeightRatio, options.maxHeightRatio ?? 1.35);
+        this.baseHeightScale = Math.max(0.001, options.baseHeightScale ?? 0.12);
+        this.minDrawHeight = Math.max(1, options.minDrawHeight ?? 16);
+        this.alpha = Math.max(0, Math.min(1, options.alpha ?? 0.9));
+        this.drawBaseShadow = options.drawBaseShadow ?? true;
+        this.baseShadowColor = options.baseShadowColor ?? "rgba(68, 38, 18, 1)";
+        this.baseShadowAlpha = Math.max(0, Math.min(1, options.baseShadowAlpha ?? 0.28));
+        this.baseShadowRadiusScale = Math.max(0, options.baseShadowRadiusScale ?? 0.3);
+        this.baseShadowHeightScale = Math.max(0, options.baseShadowHeightScale ?? 0.42);
+    }
+    /** Paints crop ground and crop instances for the configured roadside bands. */
+    drawStrip(ctx, frame, strip) {
+        if (strip.nearProjection.roadWidth < 8) {
+            return;
+        }
+        if (this.paintGround) {
+            for (const side of this.sides) {
+                this.drawCropGroundOnSide(ctx, frame, strip, side);
+            }
+        }
+        const metrics = this.resolveVisualMetrics();
+        if (!metrics) {
+            return;
+        }
+        for (const side of this.sides) {
+            this.drawCropRowsOnSide(ctx, frame, strip, side, metrics);
+        }
+    }
+    /** @internal */
+    drawCropGroundOnSide(ctx, frame, strip, side) {
+        if (side === "left") {
+            this.drawQuad(ctx, 0, strip.farY, strip.leftOuterFar, strip.farY, strip.leftOuterNear, strip.nearY, 0, strip.nearY, this.groundColor);
+            return;
+        }
+        this.drawQuad(ctx, strip.rightOuterFar, strip.farY, frame.width, strip.farY, frame.width, strip.nearY, strip.rightOuterNear, strip.nearY, this.groundColor);
+    }
+    /** @internal */
+    drawCropRowsOnSide(ctx, frame, strip, side, metrics) {
+        const minDistance = Math.min(strip.farDistance, strip.nearDistance);
+        const maxDistance = Math.max(strip.farDistance, strip.nearDistance);
+        const startRow = Math.floor(minDistance / this.rowSpacing);
+        const endRow = Math.floor(maxDistance / this.rowSpacing);
+        for (let row = startRow; row <= endRow; row++) {
+            const worldDistance = (row + 0.5) * this.rowSpacing;
+            if (worldDistance < minDistance || worldDistance > maxDistance) {
+                continue;
+            }
+            const surface = frame.projectDistance(worldDistance);
+            const baseY = surface.projection.y;
+            const edgeOuterX = side === "left" ? surface.leftOuterX : surface.rightOuterX;
+            const scale = surface.projection.scale;
+            const roadWidth = surface.projection.roadWidth;
+            const placements = this.getPlantPlacementsForSurface(surface, frame.width, side, row);
+            for (const placement of placements) {
+                const x = side === "left"
+                    ? edgeOuterX - placement.offset * scale
+                    : edgeOuterX + placement.offset * scale;
+                const drawHeight = Math.max(this.minDrawHeight, roadWidth * this.baseHeightScale * placement.heightScale);
+                const drawWidth = drawHeight * metrics.aspect;
+                if (this.drawBaseShadow) {
+                    this.drawCropShadow(ctx, x, baseY, drawWidth);
+                }
+                ctx.save();
+                ctx.globalAlpha = this.alpha;
+                ctx.drawImage(metrics.surface, Math.round(x - drawWidth * 0.5), Math.round(baseY - drawHeight), drawWidth, drawHeight);
+                ctx.restore();
+            }
+        }
+    }
+    /** @internal */
+    drawCropShadow(ctx, x, baseY, drawWidth) {
+        const shadowRadius = Math.max(2, drawWidth * this.baseShadowRadiusScale);
+        ctx.save();
+        ctx.globalAlpha = this.baseShadowAlpha;
+        ctx.fillStyle = this.baseShadowColor;
+        ctx.beginPath();
+        ctx.ellipse(Math.round(x), Math.round(baseY - shadowRadius * 0.12), shadowRadius, Math.max(1.5, shadowRadius * this.baseShadowHeightScale), 0, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.restore();
+    }
+    /** @internal */
+    getPlantPlacementsForSurface(surface, frameWidth, side, row) {
+        const spanPixels = side === "left" ? surface.leftOuterX : frameWidth - surface.rightOuterX;
+        const scale = Math.max(surface.projection.scale, 0.0001);
+        const maxWorldOffset = Math.max(this.columnInset, spanPixels / scale + this.columnSpacing);
+        const sideSeed = side === "left" ? 0 : 1000;
+        const placements = [];
+        let offset = this.columnInset +
+            (row % 2 === 0 ? 0 : this.rowShift) +
+            this.hashValue(row * 17 + sideSeed + 1) * this.columnSpacingJitter;
+        let index = 0;
+        while (offset <= maxWorldOffset) {
+            const spacingJitter = this.hashValue(row * 43 + sideSeed + index * 7 + 3);
+            const heightJitter = this.hashValue(row * 61 + sideSeed + index * 11 + 9);
+            placements.push({
+                offset,
+                heightScale: this.minHeightRatio +
+                    heightJitter * (this.maxHeightRatio - this.minHeightRatio),
+            });
+            offset +=
+                this.columnSpacing +
+                    (spacingJitter - 0.5) * 2 * this.columnSpacingJitter;
+            index += 1;
+        }
+        return placements;
+    }
+    /** @internal */
+    resolveVisualMetrics() {
+        const source = this.visual;
+        if (source.type === "image") {
+            const image = this.game.getImage(source.key);
+            if (!image) {
+                return null;
+            }
+            const width = source.width ??
+                (image instanceof HTMLImageElement
+                    ? image.naturalWidth || image.width
+                    : image.width);
+            const height = source.height ??
+                (image instanceof HTMLImageElement
+                    ? image.naturalHeight || image.height
+                    : image.height);
+            return {
+                surface: image,
+                aspect: width / Math.max(1, height),
+            };
+        }
+        const canvas = this.emojiSurfaceCache ?? this.createEmojiSurface(source);
+        this.emojiSurfaceCache = canvas;
+        return {
+            surface: canvas,
+            aspect: canvas.width / Math.max(1, canvas.height),
+        };
+    }
+    /** @internal */
+    createEmojiSurface(source) {
+        const size = Math.max(8, source.size ?? 64);
+        const canvas = document.createElement("canvas");
+        canvas.width = size;
+        canvas.height = size;
+        const ctx = canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("Unable to create crop drawer emoji surface");
+        }
+        ctx.clearRect(0, 0, size, size);
+        ctx.textAlign = "center";
+        ctx.textBaseline = "middle";
+        ctx.font = `${Math.round(size * 0.82)}px system-ui`;
+        if (source.color) {
+            ctx.fillStyle = source.color;
+        }
+        ctx.fillText(source.value, size * 0.5, size * 0.56);
+        return canvas;
+    }
+    /** @internal */
+    hashValue(value) {
+        const s = Math.sin(value * 127.1 + 311.7) * 43758.5453123;
+        return s - Math.floor(s);
+    }
+}
+const DEFAULT_THEME = {
+    skyTop: "#6ab7ff",
+    skyBottom: "#10203d",
+    mountainBack: "#21395f",
+    mountainFront: "#152744",
+    grassA: "#2f5f33",
+    grassB: "#356c3a",
+    roadA: "#555761",
+    roadB: "#62646f",
+    shoulderA: "#d85b63",
+    shoulderB: "#f4dfcf",
+    laneMarker: "#fff9da",
+    horizonGlow: "rgba(255, 214, 122, 0.24)",
+    sunInner: "rgba(255, 250, 205, 0.98)",
+    sunOuter: "rgba(255, 205, 113, 0)",
+};
+const DEFAULT_PERFORMANCE = {
+    zeroToSixtySeconds: 6.2,
+    sixtyToZeroSeconds: 3.6,
+    topSpeedMph: 145,
+    steeringLowSpeedScale: 0.9,
+    steeringHighSpeedScale: 0.34,
+    steeringSpeedCurvePower: 1.8,
+    lateralDamping: 6.8,
+};
+const DEFAULT_HORIZON = {
+    influenceAngle: 120,
+    parallaxFactor: 0.26,
+    baseYOffset: 26,
+    maxVisibleMarkers: 3,
+    headingResponse: 0.24,
+};
+const DEFAULT_MINIMAP = {
+    visible: false,
+    width: 148,
+    height: 148,
+    padding: 10,
+    alpha: 1,
+    backgroundColor: "rgba(6, 10, 18, 0.72)",
+    borderColor: "rgba(126, 224, 255, 0.45)",
+    borderWidth: 2,
+    trackColor: "rgba(245, 248, 255, 0.9)",
+    trackLineWidth: 3,
+    playerColor: "#ff6a6e",
+    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,
+    realCollisionBounds: true,
+    visualBoundsColor: "rgba(80, 220, 255, 0.9)",
+    playerCollisionBoundsColor: "rgba(255, 238, 88, 0.95)",
+    trafficCollisionBoundsColor: "rgba(255, 82, 82, 0.95)",
+    playerRealCollisionBoundsColor: "rgba(255, 170, 0, 0.95)",
+    trafficRealCollisionBoundsColor: "rgba(255, 0, 170, 0.95)",
+    lineWidth: 2,
+};
+const MPH_PER_SPEED_UNIT = 0.22;
+const DEFAULT_GROUND_FILL = {
+    enabled: true,
+    color: null,
+};
+const DEFAULT_OPTIONS = {
+    stripCount: 78,
+    drawDistance: 1200,
+    laneCount: 3,
+    playerLane: 0,
+    speed: 0,
+    playerBaseScale: 1,
+    playerBodyWidth: 36,
+    playerBodyLength: 48,
+    steeringRate: 1.85,
+    curveScale: 0.9,
+    hillScale: 0.22,
+    playerRoadInfluence: 0.46,
+    playerLaneLimit: 1.8,
+    offRoadThreshold: 0.82,
+    offRoadTargetSpeedMph: 18,
+    offRoadBrakeRate: 3.2,
+    offRoadAccelerationScale: 0.28,
+    realCollisionVerticalShiftBlend: 0.5,
+};
+const DEFAULT_TRAFFIC_MANAGER_OPTIONS = {
+    maxActive: 14,
+    initialActive: 6,
+    spawnInterval: 0.45,
+    spawnAheadMin: 900,
+    spawnAheadMax: 2200,
+    spawnBehindMin: 320,
+    spawnBehindMax: 760,
+    despawnBehindDistance: 260,
+    despawnAheadDistance: 2800,
+    minGapDistance: 220,
+    oncomingChance: 0.35,
+    fasterTrafficSpawnsBehind: true,
+};
+/**
+ * Main public API for the MinimoJS arcade racing module.
+ *
+ * `ArcadeRacerEngine` is a pseudo-3D road renderer and gameplay helper built
+ * on top of MinimoJS. It is designed for highway racers, Out Run style arcade
+ * games, looping circuits, and simple traffic-heavy road scenes where the
+ * player remains screen-anchored while the road, traffic, roadside objects, and
+ * heading-based background move around them.
+ *
+ * Instead of building the scene out of many ordinary MinimoJS sprites, the
+ * engine owns one internal {@link DrawSprite} and composes most of the frame
+ * inside that surface. That design keeps the API compact while still supporting:
+ *
+ * - straight roads and curved roads using path primitives
+ * - optional elevation changes on straights and arcs
+ * - roadside billboards and traffic vehicles
+ * - heading-based horizon markers
+ * - layered image backgrounds with parallax
+ * - minimap rendering
+ * - off-road detection and optional automatic slowdown
+ * - player speed control in engine units or mph
+ *
+ * Typical usage follows this flow:
+ *
+ * ```ts
+ * const racer = new ArcadeRacerEngine(game, {
+ *   width: game.width,
+ *   height: game.height,
+ *   horizonY: 180,
+ * });
+ *
+ * racer.clearTrack();
+ * racer.straight(2600, { elevationDelta: 40 });
+ * racer.arcRight(1200, 24);
+ * racer.straight(1800);
+ *
+ * racer.addTraffic({ type: "image", key: "truck" }, {
+ *   lane: 0.4,
+ *   distance: 800,
+ *   speed: 120,
+ * });
+ *
+ * const roadSprite = racer.build();
+ * game.add(roadSprite);
+ *
+ * game.onUpdate = (dt) => {
+ *   racer.accelerateToMph(110, dt);
+ *   if (game.isKeyDown("ArrowLeft")) racer.steerLeft(dt);
+ *   if (game.isKeyDown("ArrowRight")) racer.steerRight(dt);
+ *   racer.update(dt);
+ * };
+ * ```
+ *
+ * Conceptually, the engine is split into five parts:
+ *
+ * 1. Track definition:
+ *    Use {@link clearTrack}, {@link straight}, {@link arcLeft}, and
+ *    {@link arcRight} to build the center path of the road. These methods are
+ *    the primary geometry API.
+ * 2. Player state:
+ *    The player is controlled through properties like {@link speedMph},
+ *    {@link playerLane}, and helper methods such as {@link steerLeft},
+ *    {@link steerRight}, {@link accelerateToMph}, and {@link brakeToMph}.
+ * 3. Scene objects:
+ *    Use {@link addTraffic} and {@link addBillboard} to place vehicles,
+ *    roadside decoration, and wide anchored structures such as bridges,
+ *    arches, or fences that extend into the road.
+ * 4. Background and atmosphere:
+ *    Configure atmosphere in the constructor, then use
+ *    {@link addBackgroundLayer} and {@link addHorizonMarker} to place skies,
+ *    mountains, distant landmarks, and horizon visuals.
+ * 5. Presentation and HUD helpers:
+ *    Use constructor options such as `theme`, `minimap`, `horizon`,
+ *    `performance`, and `debug` to set the look and HUD overlays up front.
+ *
+ * Important behavioral notes:
+ *
+ * - The player is screen-anchored. They do not move through MinimoJS world
+ *   coordinates like a regular sprite; instead, the engine projects the road
+ *   and scene around the player.
+ * - `distance` keeps increasing even on looping tracks. The renderer wraps
+ *   internally when sampling road geometry.
+ * - `playerLane` is the main lateral control value. Around `-1..1` the player
+ *   is on the paved road; beyond that they enter shoulders and off-road space
+ *   depending on `playerLaneLimit`.
+ * - `laneCount` controls how many visible lane bands the road renders. When
+ *   you also provide `laneDirections`, the engine can tell which zero-based
+ *   lanes belong to same-direction versus oncoming traffic, and helpers such as
+ *   {@link getLanePositions} can return those subsets for you.
+ * - Traffic collisions are resolved in road space, not by 2D sprite overlap.
+ * - If no image background layers are configured, the engine falls back to a
+ *   built-in procedural sky and mountain backdrop.
+ *
+ * Visual source model:
+ *
+ * Most methods that draw objects accept {@link ArcadeRacerVisualSource}. That
+ * means you can mix emoji-backed visuals and preloaded MinimoJS images in the
+ * same scene. This is especially useful for quick prototypes that later evolve
+ * into art-driven scenes without changing the rest of the engine API.
+ *
+ * Choosing the right APIs:
+ *
+ * - Use {@link speed} / {@link accelerateTo} when working in engine units.
+ * - Use {@link speedMph} / {@link accelerateToMph} for player-facing gameplay.
+ * - Use {@link addBackgroundLayer} for wide, repeating, parallax image bands.
+ * - Use {@link addHorizonMarker} for directional landmarks that appear only at
+ *   certain headings.
+ * - Prefer {@link ArcadeRacerTrafficManager} as the first solution for dynamic
+ *   gameplay traffic. It is the recommended default before building a custom
+ *   spawning system with direct {@link addTraffic} and {@link removeTrafficById}
+ *   calls.
+ * - Use constructor options such as `playerBodyWidth`, `playerBodyLength`,
+ *   `playerBodyOffsetX`, and `playerBodyOffsetY` when you need to tune
+ *   collisions in local image pixels without changing the player artwork.
+ * - Use {@link getLanePosition} and {@link getLanePositions} when you want to
+ *   place traffic, race competitors, or billboards directly on lane centers
+ *   instead of guessing lane-space numbers by hand.
+ * - Use constructor `debug` options when you need to visualize car image
+ *   bounds and collision bodies while tuning traffic hits.
+ * - Use `roadDrawer`, {@link addRoadDrawerRange}, and
+ *   {@link DefaultArcadeRacerRoadDrawer} when you want to restyle the road
+ *   globally or switch to custom road painting on specific track spans.
+ *
+ * This class is the canonical public surface of the module. Its JSDoc is
+ * intended to be consumed directly by AI agents and tooling that generate code
+ * against `minimo-arcaderacer.js`.
+ */
+export class ArcadeRacerEngine {
+    /** @internal */
+    constructor(game, options = {}) {
+        /** @internal */
+        this.collisionHandlers = [];
+        /** @internal */
+        this.emojiSurfaceCache = new Map();
+        /** @internal */
+        this.trafficBehindVisibilityDistance = 220;
+        /** @internal */
+        this.playerProjectionAheadDistance = 210;
+        /** @internal */
+        this.roadBandSpan = 4;
+        /** @internal */
+        this.shoulderBandSpan = 4;
+        /** @internal */
+        this.grassBandSpan = 3;
+        /** @internal */
+        this.roadDrawerRangesState = [];
+        /** @internal */
+        this.billboardsState = [];
+        /** @internal */
+        this.trafficState = [];
+        /** @internal */
+        this.horizonMarkersState = [];
+        /** @internal */
+        this.backgroundLayersState = [];
+        /** @internal */
+        this.playerBodyWidthManual = false;
+        /** @internal */
+        this.playerBodyLengthManual = false;
+        /** @internal */
+        this.distanceState = 0;
+        /** @internal */
+        this.playerSteeringInputState = 0;
+        /** @internal */
+        this.playerLateralVelocityState = 0;
+        /** @internal */
+        this.nextId = 1;
+        /** @internal */
+        this.roadSprite = null;
+        /** @internal */
+        this.activeCollisionIds = new Set();
+        /** @internal */
+        this.headingState = 0;
+        this.game = game;
+        this.width = Math.max(1, Math.round(options.width ?? game.width));
+        this.height = Math.max(1, Math.round(options.height ?? game.height));
+        this.x = options.x ?? this.width / 2;
+        this.y = options.y ?? this.height / 2;
+        this.layer = options.layer ?? 0;
+        this.horizonY =
+            options.horizonY ?? Math.round(this.height * 0.27);
+        this.stripCount = Math.max(12, Math.round(options.stripCount ?? DEFAULT_OPTIONS.stripCount));
+        this.drawDistance = Math.max(100, options.drawDistance ?? DEFAULT_OPTIONS.drawDistance);
+        this.roadNearWidth = Math.max(16, options.roadNearWidth ?? this.width * 0.98);
+        this.roadFarWidth = Math.max(4, options.roadFarWidth ?? this.width * 0.1);
+        const explicitLaneCount = Math.max(1, Math.round(options.laneCount ?? DEFAULT_OPTIONS.laneCount));
+        this.laneSystem = new ArcadeRacerLaneSystem(explicitLaneCount, options.laneDirections);
+        this.trackSystem = new ArcadeRacerTrackSystem();
+        this.collisionSystem = new ArcadeRacerCollisionSystem(this);
+        this.renderSystem = new ArcadeRacerRenderSystem(this);
+        this.defaultRoadDrawer = new DefaultArcadeRacerRoadDrawer();
+        this.roadDrawerState = options.roadDrawer ?? this.defaultRoadDrawer;
+        this.roadDrawerRangesState = [...(options.roadDrawerRanges ?? [])];
+        this.steeringRate = Math.max(0, options.steeringRate ?? DEFAULT_OPTIONS.steeringRate);
+        this.curveScale = Math.max(0, options.curveScale ?? DEFAULT_OPTIONS.curveScale);
+        this.hillScale = Math.max(0, options.hillScale ?? DEFAULT_OPTIONS.hillScale);
+        this.playerRoadInfluence = Math.max(0, options.playerRoadInfluence ?? DEFAULT_OPTIONS.playerRoadInfluence);
+        this.playerLaneLimit = Math.max(1, options.playerLaneLimit ?? DEFAULT_OPTIONS.playerLaneLimit);
+        this.offRoadThreshold = this.clamp01(Math.min(options.offRoadThreshold ?? DEFAULT_OPTIONS.offRoadThreshold, this.playerLaneLimit));
+        this.offRoadSlowdownEnabled = options.offRoadSlowdownEnabled ?? false;
+        this.offRoadTargetSpeedMph = Math.max(0, options.offRoadTargetSpeedMph ?? DEFAULT_OPTIONS.offRoadTargetSpeedMph);
+        this.offRoadBrakeRate = Math.max(0, options.offRoadBrakeRate ?? DEFAULT_OPTIONS.offRoadBrakeRate);
+        this.offRoadAccelerationScale = this.clamp01(options.offRoadAccelerationScale ??
+            DEFAULT_OPTIONS.offRoadAccelerationScale);
+        this.realCollisionVerticalShiftBlend = this.clamp01(options.realCollisionVerticalShiftBlend ??
+            DEFAULT_OPTIONS.realCollisionVerticalShiftBlend);
+        this.themeState = {
+            ...DEFAULT_THEME,
+            ...(options.theme ?? {}),
+        };
+        this.groundFillState = this.sanitizeGroundFillOptions({
+            ...DEFAULT_GROUND_FILL,
+            ...(options.groundFill ?? {}),
+        });
+        this.performanceState = this.sanitizePerformanceOptions({
+            ...DEFAULT_PERFORMANCE,
+            ...(options.performance ?? {}),
+        });
+        this.horizonState = this.sanitizeHorizonOptions({
+            ...DEFAULT_HORIZON,
+            ...(options.horizon ?? {}),
+        });
+        this.minimapState = this.sanitizeMinimapOptions({
+            visible: options.minimap?.visible ?? DEFAULT_MINIMAP.visible,
+            x: options.minimap?.x ?? this.width - 164,
+            y: options.minimap?.y ?? 16,
+            width: options.minimap?.width ?? DEFAULT_MINIMAP.width,
+            height: options.minimap?.height ?? DEFAULT_MINIMAP.height,
+            padding: options.minimap?.padding ?? DEFAULT_MINIMAP.padding,
+            alpha: options.minimap?.alpha ?? DEFAULT_MINIMAP.alpha,
+            backgroundColor: options.minimap?.backgroundColor ?? DEFAULT_MINIMAP.backgroundColor,
+            borderColor: options.minimap?.borderColor ?? DEFAULT_MINIMAP.borderColor,
+            borderWidth: options.minimap?.borderWidth ?? DEFAULT_MINIMAP.borderWidth,
+            trackColor: options.minimap?.trackColor ?? DEFAULT_MINIMAP.trackColor,
+            trackLineWidth: options.minimap?.trackLineWidth ?? DEFAULT_MINIMAP.trackLineWidth,
+            playerColor: options.minimap?.playerColor ?? DEFAULT_MINIMAP.playerColor,
+            playerStrokeColor: options.minimap?.playerStrokeColor ?? DEFAULT_MINIMAP.playerStrokeColor,
+            playerRadius: options.minimap?.playerRadius ?? DEFAULT_MINIMAP.playerRadius,
+        });
+        this.debugState = this.sanitizeDebugOptions(options.debug ?? false);
+        this.playerVisualState =
+            // Falls back to an emoji because the module cannot assume any image key is
+            // loaded. Pass `playerVisual: { type: "image", key }` to use the game's art.
+            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 ??
+                autoPlayerBody?.width ??
+                DEFAULT_OPTIONS.playerBodyWidth;
+        this.playerBodyLengthState =
+            options.playerBodyLength ??
+                autoPlayerBody?.length ??
+                DEFAULT_OPTIONS.playerBodyLength;
+        this.playerBodyOffsetXState = Number.isFinite(options.playerBodyOffsetX)
+            ? options.playerBodyOffsetX
+            : 0;
+        this.playerBodyOffsetYState = Number.isFinite(options.playerBodyOffsetY)
+            ? options.playerBodyOffsetY
+            : 0;
+        this.playerResolvedBodyState = this.resolveCollisionBodyMetrics(this.playerVisualState, this.playerBaseScaleState, this.playerBodyWidthState, this.playerBodyLengthState, this.playerBodyOffsetXState, this.playerBodyOffsetYState);
+        this.speedState = options.speed ?? DEFAULT_OPTIONS.speed;
+        this.playerLaneState = this.clampPlayerLane(options.playerLane ?? DEFAULT_OPTIONS.playerLane);
+    }
+    /**
+     * Number of visible driving lanes configured for the road.
+     */
+    get laneCount() {
+        return this.laneSystem.laneCount;
+    }
+    /**
+     * Returns the lane-space center position for a zero-based lane index.
+     *
+     * The returned value is expressed in the same `[-1, 1]` road-space used by
+     * `playerLane`, `addTraffic({ lane })`, and billboard lane placement.
+     * Out-of-range indices are clamped to the nearest valid lane.
+     */
+    getLanePosition(laneIndex) {
+        return this.laneSystem.getLanePosition(laneIndex);
+    }
+    /**
+     * Returns lane-space center positions for all lanes or a directional subset.
+     *
+     * When `laneDirections` was not configured, `"same"` and `"oncoming"` both
+     * fall back to all lanes.
+     */
+    getLanePositions(direction = "all") {
+        return this.laneSystem.getLanePositions(direction);
+    }
+    /**
+     * Current player speed in world units per second.
+     */
+    get speed() {
+        return this.speedState;
+    }
+    set speed(value) {
+        this.speedState = Number.isFinite(value) ? value : 0;
+    }
+    /**
+     * Current player speed in miles per hour.
+     */
+    get speedMph() {
+        return this.speedToMph(this.speedState);
+    }
+    set speedMph(value) {
+        this.speedState = this.mphToSpeed(value);
+    }
+    /**
+     * Current heading in degrees in range `[0, 360)`.
+     */
+    get headingDegrees() {
+        return this.headingState;
+    }
+    set headingDegrees(value) {
+        this.headingState = this.normalizeAngle(value);
+    }
+    /**
+     * Total forward distance traveled by the player.
+     */
+    get distance() {
+        return this.distanceState;
+    }
+    set distance(value) {
+        this.distanceState = Number.isFinite(value) ? value : 0;
+    }
+    /**
+     * Player lane position.
+     */
+    get playerLane() {
+        return this.playerLaneState;
+    }
+    set playerLane(value) {
+        this.playerLaneState = this.clampPlayerLane(value);
+        this.playerLateralVelocityState = 0;
+    }
+    /**
+     * Whether the player is currently outside the configured road threshold.
+     */
+    get isOffRoad() {
+        return this.getOffRoadAmount() > 0;
+    }
+    /**
+     * Normalized amount of how far the player has gone off-road in range `[0, 1]`.
+     */
+    get offRoadAmount() {
+        return this.getOffRoadAmount();
+    }
+    /**
+     * Removes all existing track primitives and legacy segments.
+     */
+    clearTrack() {
+        this.trackSystem.clearTrack();
+    }
+    /**
+     * Appends a straight path section.
+     */
+    straight(length, options = {}) {
+        this.trackSystem.appendPathLine(length, options);
+    }
+    /**
+     * Replaces the track with a naturally closed rounded rectangle circuit.
+     */
+    roundedRect(width, height, cornerRadius) {
+        this.trackSystem.setRoundedRectTrack(width, height, cornerRadius);
+    }
+    /**
+     * Appends a path arc that bends left by the given number of degrees.
+     */
+    arcLeft(radius, degrees, options = {}) {
+        this.trackSystem.appendPathArc(radius, degrees, -1, options);
+    }
+    /**
+     * Appends a path arc that bends right by the given number of degrees.
+     */
+    arcRight(radius, degrees, options = {}) {
+        this.trackSystem.appendPathArc(radius, degrees, 1, options);
+    }
+    /**
+     * Creates the internal road sprite if it does not yet exist and returns it.
+     *
+     * The sprite is not added to the scene automatically. Add the returned
+     * `DrawSprite` yourself so the display-list order stays explicit.
+     */
+    build() {
+        if (this.roadSprite)
+            return this.roadSprite;
+        const sprite = new ArcadeRacerRoadSprite(this.width, this.height, (ctx, width, height) => this.render(ctx, width, height));
+        sprite.x = this.x;
+        sprite.y = this.y;
+        sprite.ignoreScroll = true;
+        sprite.layer = this.layer;
+        this.roadSprite = sprite;
+        return this.roadSprite;
+    }
+    /**
+     * Returns the internal road render sprite, or `null` if `build()` has not run yet.
+     */
+    getRoadSprite() {
+        return this.roadSprite;
+    }
+    /**
+     * Advances the racer simulation and redraws on the next MinimoJS render pass.
+     */
+    update(dt) {
+        this.build();
+        const safeDt = Number.isFinite(dt) && dt > 0 ? Math.min(dt, 0.1) : 0;
+        this.distanceState += this.speedState * safeDt;
+        const current = this.trackSystem.sampleTrack(this.distanceState);
+        if (this.trackSystem.hasPathPrimitives) {
+            const targetHeading = this.normalizeAngle((current.heading * 180) / Math.PI);
+            const headingDelta = this.getShortestAngleDelta(this.headingState, targetHeading);
+            const followStrength = Math.min(1, this.horizonState.headingResponse * 2.5);
+            this.headingState = this.normalizeAngle(this.headingState + headingDelta * followStrength);
+        }
+        else {
+            this.headingState = this.normalizeAngle(this.headingState +
+                current.curve *
+                    this.speedToMph(Math.abs(this.speedState)) *
+                    this.horizonState.headingResponse *
+                    safeDt);
+        }
+        const forwardSpeed = Math.abs(this.speedState);
+        this.updatePlayerLateralDynamics(current, forwardSpeed, safeDt);
+        if (this.offRoadSlowdownEnabled && this.isOffRoad) {
+            this.brakeToMph(this.offRoadTargetSpeedMph, safeDt, this.offRoadBrakeRate);
+        }
+        for (const traffic of this.trafficState) {
+            traffic.distance += traffic.speed * safeDt;
+            if (traffic.loop && this.trackSystem.totalTrackLength > 0) {
+                while (traffic.distance <
+                    this.distanceState - this.trafficBehindVisibilityDistance) {
+                    traffic.distance += this.trackSystem.totalTrackLength;
+                }
+            }
+        }
+        this.resolvePlayerTrafficCollisions();
+        this.playerSteeringInputState = 0;
+    }
+    /**
+     * Moves the player left using the configured steering rate.
+     */
+    steerLeft(dt, strength = 1) {
+        void dt;
+        const safeStrength = Number.isFinite(strength) ? Math.max(0, strength) : 1;
+        this.playerSteeringInputState = Math.max(-1, Math.min(1, this.playerSteeringInputState - safeStrength));
+    }
+    /**
+     * Moves the player right using the configured steering rate.
+     */
+    steerRight(dt, strength = 1) {
+        void dt;
+        const safeStrength = Number.isFinite(strength) ? Math.max(0, strength) : 1;
+        this.playerSteeringInputState = Math.max(-1, Math.min(1, this.playerSteeringInputState + safeStrength));
+    }
+    /**
+     * Smoothly accelerates the player speed toward a target value.
+     */
+    accelerateTo(targetSpeed, dt, rate = 2.8) {
+        const cappedTarget = Math.min(Math.max(0, targetSpeed), this.mphToSpeed(this.performanceState.topSpeedMph));
+        const accelerationScale = this.getOffRoadAccelerationScale();
+        if (arguments.length >= 3) {
+            this.speedState = this.approach(this.speedState, cappedTarget, rate * accelerationScale, dt);
+            return;
+        }
+        const accelerationPerSecond = this.mphToSpeed(60) / this.performanceState.zeroToSixtySeconds;
+        this.speedState = this.approachLinear(this.speedState, cappedTarget, accelerationPerSecond * accelerationScale, dt);
+    }
+    /**
+     * Smoothly brakes the player speed toward a target value.
+     */
+    brakeTo(targetSpeed, dt, rate = 4) {
+        const cappedTarget = Math.max(0, targetSpeed);
+        if (arguments.length >= 3) {
+            this.speedState = this.approach(this.speedState, cappedTarget, rate, dt);
+            return;
+        }
+        const brakingPerSecond = this.mphToSpeed(60) / this.performanceState.sixtyToZeroSeconds;
+        this.speedState = this.approachLinear(this.speedState, cappedTarget, brakingPerSecond, dt);
+    }
+    /**
+     * Smoothly accelerates the player toward a target speed expressed in mph.
+     */
+    accelerateToMph(targetMph, dt, rate) {
+        if (Number.isFinite(rate)) {
+            this.accelerateTo(this.mphToSpeed(targetMph), dt, rate);
+            return;
+        }
+        this.accelerateTo(this.mphToSpeed(targetMph), dt);
+    }
+    /**
+     * Smoothly brakes the player toward a target speed expressed in mph.
+     */
+    brakeToMph(targetMph, dt, rate) {
+        if (Number.isFinite(rate)) {
+            this.brakeTo(this.mphToSpeed(targetMph), dt, rate);
+            return;
+        }
+        this.brakeTo(this.mphToSpeed(targetMph), dt);
+    }
+    /**
+     * Registers a collision callback without using the builder API.
+     */
+    onPlayerTrafficHit(handler) {
+        this.collisionHandlers.push(handler);
+    }
+    /**
+     * Removes all registered player-traffic collision handlers.
+     */
+    clearPlayerTrafficHitHandlers() {
+        this.collisionHandlers.length = 0;
+    }
+    /**
+     * Adds a billboard directly and returns its generated id.
+     */
+    addBillboard(visual, config) {
+        const ids = [];
+        const repeat = Math.max(1, Math.round(config.repeat ?? 1));
+        const spacing = Math.max(1, config.spacing ?? 240);
+        for (let i = 0; i < repeat; i++) {
+            const id = this.makeId("bb");
+            ids.push(id);
+            this.billboardsState.push({
+                id,
+                visual,
+                distance: Math.max(0, config.distance + i * spacing),
+                lane: Number.isFinite(config.lane)
+                    ? this.laneSystem.clampRoadLane(config.lane)
+                    : null,
+                side: config.side ?? "right",
+                offset: Number.isFinite(config.offset) ? Math.max(0, config.offset) : 48,
+                anchorX: this.clamp01(config.anchorX ?? 0.5),
+                anchorY: this.clamp01(config.anchorY ?? 1),
+                baseScale: Number.isFinite(config.baseScale)
+                    ? Math.max(0, config.baseScale)
+                    : 1,
+                alpha: this.clamp01(config.alpha ?? 1),
+            });
+        }
+        return ids[0];
+    }
+    /**
+     * Adds a traffic vehicle directly and returns its generated id.
+     */
+    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);
+        const bodyWidth = Number.isFinite(config.bodyWidth)
+            ? Math.max(1, config.bodyWidth)
+            : autoBody?.width ?? 36;
+        const bodyLength = Number.isFinite(config.bodyLength)
+            ? Math.max(1, config.bodyLength)
+            : autoBody?.length ?? 48;
+        const bodyOffsetX = Number.isFinite(config.bodyOffsetX)
+            ? config.bodyOffsetX
+            : 0;
+        const bodyOffsetY = Number.isFinite(config.bodyOffsetY)
+            ? config.bodyOffsetY
+            : 0;
+        this.trafficState.push({
+            id,
+            visual,
+            distance: Number.isFinite(config.distance) ? config.distance : 0,
+            lane: this.laneSystem.clampRoadLane(config.lane),
+            speed: Number.isFinite(config.speed) ? config.speed : 140,
+            baseScale,
+            bodyWidth,
+            bodyLength,
+            bodyOffsetX,
+            bodyOffsetY,
+            resolvedBody: this.resolveCollisionBodyMetrics(visual, baseScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY),
+            loop: config.loop ?? true,
+            alpha: this.clamp01(config.alpha ?? 1),
+        });
+        return id;
+    }
+    /**
+     * Removes a traffic vehicle by id.
+     *
+     * Returns `true` when a vehicle was found and removed.
+     */
+    removeTrafficById(id) {
+        const index = this.trafficState.findIndex((entry) => entry.id === id);
+        if (index < 0)
+            return false;
+        this.trafficState.splice(index, 1);
+        this.activeCollisionIds.delete(id);
+        return true;
+    }
+    /**
+     * Updates an existing traffic vehicle by id.
+     *
+     * This is intended for higher-level systems such as race managers that need
+     * to drive opponent state explicitly over time.
+     */
+    updateTrafficById(id, config) {
+        const entry = this.trafficState.find((item) => item.id === id);
+        if (!entry)
+            return false;
+        if (Number.isFinite(config.distance)) {
+            entry.distance = config.distance;
+        }
+        if (Number.isFinite(config.lane)) {
+            entry.lane = this.laneSystem.clampRoadLane(config.lane);
+        }
+        if (Number.isFinite(config.speed)) {
+            entry.speed = config.speed;
+        }
+        if (Number.isFinite(config.baseScale)) {
+            entry.baseScale = Math.max(0, config.baseScale);
+        }
+        if (Number.isFinite(config.bodyWidth)) {
+            entry.bodyWidth = Math.max(1, config.bodyWidth);
+        }
+        if (Number.isFinite(config.bodyLength)) {
+            entry.bodyLength = Math.max(1, config.bodyLength);
+        }
+        if (Number.isFinite(config.bodyOffsetX)) {
+            entry.bodyOffsetX = config.bodyOffsetX;
+        }
+        if (Number.isFinite(config.bodyOffsetY)) {
+            entry.bodyOffsetY = config.bodyOffsetY;
+        }
+        if (typeof config.loop === "boolean") {
+            entry.loop = config.loop;
+        }
+        if (Number.isFinite(config.alpha)) {
+            entry.alpha = this.clamp01(config.alpha);
+        }
+        entry.resolvedBody = this.resolveCollisionBodyMetrics(entry.visual, entry.baseScale, entry.bodyWidth, entry.bodyLength, entry.bodyOffsetX, entry.bodyOffsetY);
+        return true;
+    }
+    /**
+     * Clears all configured traffic vehicles.
+     */
+    clearTraffic() {
+        this.trafficState.length = 0;
+        this.activeCollisionIds.clear();
+    }
+    /**
+     * Clears all configured billboards.
+     */
+    clearBillboards() {
+        this.billboardsState.length = 0;
+    }
+    /**
+     * Adds a wrapped track-distance range that swaps the active road drawer.
+     *
+     * When multiple ranges overlap, the most recently added range wins.
+     */
+    addRoadDrawerRange(range) {
+        this.roadDrawerRangesState.push(range);
+    }
+    /**
+     * Clears all per-range road drawer overrides.
+     */
+    clearRoadDrawerRanges() {
+        this.roadDrawerRangesState.length = 0;
+    }
+    /**
+     * Adds a heading-based horizon marker directly and returns its generated id.
+     */
+    addHorizonMarker(visual, config) {
+        const id = this.makeId("hz");
+        this.horizonMarkersState.push({
+            id,
+            visual,
+            angle: this.normalizeAngle(config.angle),
+            baseScale: Number.isFinite(config.baseScale)
+                ? Math.max(0, config.baseScale)
+                : 1,
+            alpha: this.clamp01(config.alpha ?? 1),
+            yOffset: Number.isFinite(config.yOffset)
+                ? config.yOffset
+                : 0,
+            influenceAngle: Number.isFinite(config.influenceAngle)
+                ? Math.max(1, Math.abs(config.influenceAngle))
+                : null,
+            parallaxFactor: Number.isFinite(config.parallaxFactor)
+                ? Math.max(0, Math.abs(config.parallaxFactor))
+                : null,
+        });
+        return id;
+    }
+    /**
+     * Clears all configured horizon markers.
+     */
+    clearHorizonMarkers() {
+        this.horizonMarkersState.length = 0;
+    }
+    /**
+     * Adds a parallax background image layer and returns its generated id.
+     */
+    addBackgroundLayer(visual, config = {}) {
+        const id = this.makeId("bg");
+        this.backgroundLayersState.push({
+            id,
+            visual,
+            y: Number.isFinite(config.y) ? config.y : 0,
+            xOffset: Number.isFinite(config.xOffset) ? config.xOffset : 0,
+            baseScale: Number.isFinite(config.baseScale)
+                ? Math.max(0, config.baseScale)
+                : 1,
+            alpha: this.clamp01(config.alpha ?? 1),
+            repeat: config.repeat ?? true,
+            spacing: Number.isFinite(config.spacing) ? Math.max(0, config.spacing) : 0,
+            parallaxDistance: Number.isFinite(config.parallaxDistance)
+                ? config.parallaxDistance
+                : 0,
+            parallaxHeading: Number.isFinite(config.parallaxHeading)
+                ? Math.max(0, Math.abs(config.parallaxHeading))
+                : 0,
+        });
+        return id;
+    }
+    /**
+     * Clears all configured background image layers.
+     */
+    clearBackgroundLayers() {
+        this.backgroundLayersState.length = 0;
+    }
+    /** @internal */
+    render(ctx, width, height) {
+        this.renderSystem.renderFrame(ctx, width, height);
+    }
+    /** @internal */
+    getDebugCollisionRectFromVisual(visualRect, visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY) {
+        return this.collisionSystem.getDebugCollisionRectFromVisual(visualRect, visual, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY);
+    }
+    /** @internal */
+    getRealCollisionRect(current, width, height, ahead, lane, visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY, resolvedBody, anchorCenterX, anchorBottomY) {
+        return this.collisionSystem.getRealCollisionRect(current, width, height, ahead, lane, visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY, resolvedBody, anchorCenterX, anchorBottomY);
+    }
+    /** @internal */
+    resolveAutoBodyFromVisual(visual, scale) {
+        return this.collisionSystem.resolveAutoBodyFromVisual(visual, scale);
+    }
+    /** @internal */
+    resolveCollisionBodyMetrics(visual, scale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY) {
+        return this.collisionSystem.resolveCollisionBodyMetrics(visual, scale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY);
+    }
+    /** @internal */
+    getBodyDistanceCenterFromAnchor(anchorDistance, bodyLength, bodyDistanceOffset) {
+        return this.collisionSystem.getBodyDistanceCenterFromAnchor(anchorDistance, bodyLength, bodyDistanceOffset);
+    }
+    /** @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;
+        }
+        this.playerResolvedBodyState = this.resolveCollisionBodyMetrics(this.playerVisualState, this.playerBaseScaleState, this.playerBodyWidthState, this.playerBodyLengthState, this.playerBodyOffsetXState, this.playerBodyOffsetYState);
+    }
+    /** @internal */
+    getPlayerScreenX() {
+        return (this.width / 2 +
+            this.playerLaneState * this.collisionSystem.getPlayerScreenLaneUnit());
+    }
+    /** @internal */
+    resolveVisualSurface(visual) {
+        if (visual.type === "image") {
+            const image = this.game.getImage(visual.key);
+            if (!image) {
+                throw new Error(`MinimoJS Arcade Racer: Image '${visual.key}' is not loaded.`);
+            }
+            const naturalWidth = Math.max(1, image instanceof HTMLImageElement ? image.naturalWidth || image.width : image.width);
+            const naturalHeight = Math.max(1, image instanceof HTMLImageElement ? image.naturalHeight || image.height : image.height);
+            if (visual.width && visual.height) {
+                return {
+                    source: image,
+                    width: Math.max(1, visual.width),
+                    height: Math.max(1, visual.height),
+                };
+            }
+            if (visual.width) {
+                return {
+                    source: image,
+                    width: Math.max(1, visual.width),
+                    height: Math.max(1, (visual.width / naturalWidth) * naturalHeight),
+                };
+            }
+            if (visual.height) {
+                return {
+                    source: image,
+                    width: Math.max(1, (visual.height / naturalHeight) * naturalWidth),
+                    height: Math.max(1, visual.height),
+                };
+            }
+            return {
+                source: image,
+                width: naturalWidth,
+                height: naturalHeight,
+            };
+        }
+        const size = Math.max(1, Math.round(visual.size ?? 64));
+        const color = visual.color ?? "#ffffff";
+        const cacheKey = [visual.value, size, color].join("|");
+        let surface = this.emojiSurfaceCache.get(cacheKey);
+        if (!surface) {
+            surface = document.createElement("canvas");
+            const boxSize = Math.max(2, Math.ceil(size * 2));
+            surface.width = boxSize;
+            surface.height = boxSize;
+            const glyphCtx = surface.getContext("2d");
+            if (!glyphCtx) {
+                throw new Error("MinimoJS Arcade Racer: Could not acquire an emoji rendering context.");
+            }
+            glyphCtx.clearRect(0, 0, boxSize, boxSize);
+            glyphCtx.shadowColor = "transparent";
+            glyphCtx.shadowBlur = 0;
+            glyphCtx.shadowOffsetX = 0;
+            glyphCtx.shadowOffsetY = 0;
+            glyphCtx.fillStyle = color;
+            glyphCtx.font = `${size}px "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif`;
+            glyphCtx.textAlign = "center";
+            glyphCtx.textBaseline = "middle";
+            glyphCtx.fillText(visual.value, boxSize / 2, boxSize / 2);
+            this.emojiSurfaceCache.set(cacheKey, surface);
+        }
+        return {
+            source: surface,
+            width: size,
+            height: size,
+        };
+    }
+    /** @internal */
+    projectObject(current, ahead, billboard, width, height) {
+        const projection = this.projectRoadPoint(current, ahead, width, height);
+        const roadsideX = billboard.lane !== null
+            ? projection.x + billboard.lane * projection.roadWidth * 0.38
+            : projection.x +
+                (billboard.side === "left" ? -1 : 1) *
+                    (projection.roadWidth * 0.56 + billboard.offset * projection.scale);
+        if (roadsideX < -200 || roadsideX > width + 200) {
+            return null;
+        }
+        return {
+            ...projection,
+            x: roadsideX,
+        };
+    }
+    /** @internal */
+    projectTrafficPoint(current, ahead, width, height) {
+        if (ahead >= 0) {
+            return this.projectRoadPoint(current, Math.max(1, ahead), width, height);
+        }
+        const near = this.projectRoadPoint(current, 1, width, height);
+        const behindT = Math.min(1, Math.max(0, -ahead / this.trafficBehindVisibilityDistance));
+        return {
+            x: near.x,
+            y: near.y + behindT * Math.max(90, height * 0.32),
+            roadWidth: near.roadWidth,
+            scale: near.scale * (1 + behindT * 0.18),
+            t: near.t,
+        };
+    }
+    /** @internal */
+    projectRoadPoint(current, ahead, width, height) {
+        if (this.trackSystem.hasPathPrimitives) {
+            const distanceAhead = Math.max(0, Math.min(ahead, this.drawDistance));
+            const t = 1 - distanceAhead / this.drawDistance;
+            const p = t * t;
+            const sample = this.trackSystem.sampleTrack(this.distanceState + distanceAhead);
+            const dx = sample.worldX - current.worldX;
+            const dy = sample.worldY - current.worldY;
+            const rightX = -Math.sin(current.heading);
+            const rightY = Math.cos(current.heading);
+            const lateral = dx * rightX + dy * rightY;
+            const relElevation = sample.elevation - current.elevation;
+            const roadWidth = this.lerp(this.roadFarWidth, this.roadNearWidth, p);
+            const scale = roadWidth / this.roadNearWidth;
+            const hillPerspective = 0.32 + p * 0.68;
+            return {
+                x: width / 2 + lateral * this.curveScale,
+                y: this.horizonY +
+                    p * (height - this.horizonY) -
+                    relElevation * this.hillScale * hillPerspective,
+                roadWidth,
+                scale,
+                t: p,
+            };
+        }
+        const distanceAhead = Math.max(0, Math.min(ahead, this.drawDistance));
+        const t = 1 - distanceAhead / this.drawDistance;
+        const p = t * t;
+        const sample = this.trackSystem.sampleTrack(this.distanceState + distanceAhead);
+        const relOffset = sample.lateralOffset - current.lateralOffset;
+        const relElevation = sample.elevation - current.elevation;
+        const roadWidth = this.lerp(this.roadFarWidth, this.roadNearWidth, p);
+        const scale = roadWidth / this.roadNearWidth;
+        const x = width / 2 + relOffset * this.curveScale;
+        const hillPerspective = 0.32 + p * 0.68;
+        const y = this.horizonY +
+            p * (height - this.horizonY) -
+            relElevation * this.hillScale * hillPerspective;
+        return { x, y, roadWidth, scale, t: p };
+    }
+    /** @internal */
+    sampleMinimapPoint(points, distance) {
+        if (points.length === 0 || this.trackSystem.totalTrackLength <= 0) {
+            return { x: 0, y: 0, distance: 0 };
+        }
+        const wrapped = this.trackSystem.wrapDistance(distance);
+        const sampleT = (wrapped / this.trackSystem.totalTrackLength) * (points.length - 1);
+        const index = Math.max(0, Math.min(points.length - 1, Math.floor(sampleT)));
+        const nextIndex = Math.min(points.length - 1, index + 1);
+        const t = sampleT - index;
+        const from = points[index];
+        const to = points[nextIndex];
+        return {
+            x: this.lerp(from.x, to.x, t),
+            y: this.lerp(from.y, to.y, t),
+            distance: wrapped,
+        };
+    }
+    /** @internal */
+    resolveRoadDrawer(trackDistance) {
+        for (let i = this.roadDrawerRangesState.length - 1; i >= 0; i--) {
+            const range = this.roadDrawerRangesState[i];
+            if (this.matchesRoadDrawerRange(trackDistance, range)) {
+                return range.drawer;
+            }
+        }
+        return this.roadDrawerState;
+    }
+    /** @internal */
+    matchesRoadDrawerRange(trackDistance, range) {
+        const total = this.trackSystem.totalTrackLength;
+        const wrappedTrackDistance = total > 0
+            ? this.trackSystem.wrapDistance(trackDistance)
+            : trackDistance;
+        const from = total > 0 ? this.trackSystem.wrapDistance(range.from) : range.from;
+        const to = total > 0 ? this.trackSystem.wrapDistance(range.to) : range.to;
+        if (from === to) {
+            return true;
+        }
+        if (from < to) {
+            return wrappedTrackDistance >= from && wrappedTrackDistance < to;
+        }
+        return wrappedTrackDistance >= from || wrappedTrackDistance < to;
+    }
+    /** @internal */
+    resolvePlayerTrafficCollisions() {
+        this.collisionSystem.resolvePlayerTrafficCollisions();
+    }
+    /** @internal */
+    makeId(prefix) {
+        return `${prefix}-${this.nextId++}`;
+    }
+    /** @internal */
+    clampPlayerLane(value) {
+        if (!Number.isFinite(value))
+            return 0;
+        return Math.max(-this.playerLaneLimit, Math.min(this.playerLaneLimit, value));
+    }
+    /** @internal */
+    clamp01(value) {
+        if (!Number.isFinite(value))
+            return 0;
+        return Math.max(0, Math.min(1, value));
+    }
+    /** @internal */
+    getOffRoadAmount() {
+        const absLane = Math.abs(this.playerLaneState);
+        if (absLane <= this.offRoadThreshold) {
+            return 0;
+        }
+        const maxOffRoadSpan = Math.max(0.0001, this.playerLaneLimit - this.offRoadThreshold);
+        const normalized = (absLane - this.offRoadThreshold) / maxOffRoadSpan;
+        return this.clamp01(normalized);
+    }
+    /** @internal */
+    getOffRoadAccelerationScale() {
+        if (!this.isOffRoad) {
+            return 1;
+        }
+        return this.lerp(1, this.offRoadAccelerationScale, this.getOffRoadAmount());
+    }
+    /** @internal */
+    getOffRoadLateralGripScale() {
+        if (!this.isOffRoad) {
+            return 1;
+        }
+        return this.lerp(1, 0.58, this.getOffRoadAmount());
+    }
+    /** @internal */
+    getSteeringScale() {
+        const speedRatio = this.clamp01(this.speedToMph(Math.abs(this.speedState)) / this.performanceState.topSpeedMph);
+        const eased = Math.pow(speedRatio, this.performanceState.steeringSpeedCurvePower);
+        return this.lerp(this.performanceState.steeringLowSpeedScale, this.performanceState.steeringHighSpeedScale, eased);
+    }
+    /** @internal */
+    updatePlayerLateralDynamics(current, forwardSpeed, dt) {
+        if (dt <= 0) {
+            return;
+        }
+        const forwardMph = this.speedToMph(forwardSpeed);
+        const topSpeedMph = Math.max(1, this.performanceState.topSpeedMph);
+        const speedRatio = this.clamp01(forwardMph / topSpeedMph);
+        const steeringAuthority = this.getSteeringScale();
+        const offRoadGripScale = this.getOffRoadLateralGripScale();
+        const lowSpeedLateralScale = 0.06 + Math.pow(speedRatio, 0.72) * 0.94;
+        const steeringAcceleration = this.playerSteeringInputState *
+            this.steeringRate *
+            steeringAuthority *
+            offRoadGripScale *
+            lowSpeedLateralScale *
+            7.5;
+        const curvePush = current.curve *
+            forwardSpeed *
+            this.playerRoadInfluence *
+            (0.28 + speedRatio * 1.42) *
+            (1 + Math.abs(current.curve) * 900) *
+            (1.05 + (1 - offRoadGripScale) * 0.9);
+        this.playerLateralVelocityState +=
+            (steeringAcceleration - curvePush) * dt;
+        const maxLateralVelocity = (0.18 + speedRatio * 1.65) * offRoadGripScale;
+        this.playerLateralVelocityState = Math.max(-maxLateralVelocity, Math.min(maxLateralVelocity, this.playerLateralVelocityState));
+        const damping = this.performanceState.lateralDamping *
+            (0.85 + (1 - offRoadGripScale) * 0.9);
+        this.playerLateralVelocityState = this.approach(this.playerLateralVelocityState, 0, damping, dt);
+        const nextLane = this.clampPlayerLane(this.playerLaneState + this.playerLateralVelocityState * dt);
+        if (nextLane === -this.playerLaneLimit || nextLane === this.playerLaneLimit) {
+            this.playerLateralVelocityState = 0;
+        }
+        this.playerLaneState = nextLane;
+    }
+    /** @internal */
+    mphToSpeed(mph) {
+        if (!Number.isFinite(mph))
+            return 0;
+        return Math.max(0, mph / MPH_PER_SPEED_UNIT);
+    }
+    /** @internal */
+    speedToMph(speed) {
+        if (!Number.isFinite(speed))
+            return 0;
+        return Math.max(0, speed * MPH_PER_SPEED_UNIT);
+    }
+    /** @internal */
+    approach(current, target, rate, dt) {
+        const safeRate = Number.isFinite(rate) ? Math.max(0, rate) : 0;
+        const safeDt = Number.isFinite(dt) ? Math.max(0, dt) : 0;
+        return current + (target - current) * Math.min(1, safeRate * safeDt);
+    }
+    /** @internal */
+    approachLinear(current, target, unitsPerSecond, dt) {
+        const safeUnits = Number.isFinite(unitsPerSecond)
+            ? Math.max(0, unitsPerSecond)
+            : 0;
+        const safeDt = Number.isFinite(dt) ? Math.max(0, dt) : 0;
+        const step = safeUnits * safeDt;
+        if (current < target)
+            return Math.min(target, current + step);
+        if (current > target)
+            return Math.max(target, current - step);
+        return current;
+    }
+    /** @internal */
+    sanitizePerformanceOptions(options) {
+        return {
+            zeroToSixtySeconds: Number.isFinite(options.zeroToSixtySeconds)
+                ? Math.max(0.1, options.zeroToSixtySeconds)
+                : DEFAULT_PERFORMANCE.zeroToSixtySeconds,
+            sixtyToZeroSeconds: Number.isFinite(options.sixtyToZeroSeconds)
+                ? Math.max(0.1, options.sixtyToZeroSeconds)
+                : DEFAULT_PERFORMANCE.sixtyToZeroSeconds,
+            topSpeedMph: Number.isFinite(options.topSpeedMph)
+                ? Math.max(1, options.topSpeedMph)
+                : DEFAULT_PERFORMANCE.topSpeedMph,
+            steeringLowSpeedScale: Number.isFinite(options.steeringLowSpeedScale)
+                ? Math.max(0, options.steeringLowSpeedScale)
+                : DEFAULT_PERFORMANCE.steeringLowSpeedScale,
+            steeringHighSpeedScale: Number.isFinite(options.steeringHighSpeedScale)
+                ? Math.max(0, options.steeringHighSpeedScale)
+                : DEFAULT_PERFORMANCE.steeringHighSpeedScale,
+            steeringSpeedCurvePower: Number.isFinite(options.steeringSpeedCurvePower)
+                ? Math.max(0.1, options.steeringSpeedCurvePower)
+                : DEFAULT_PERFORMANCE.steeringSpeedCurvePower,
+            lateralDamping: Number.isFinite(options.lateralDamping)
+                ? Math.max(0, options.lateralDamping)
+                : DEFAULT_PERFORMANCE.lateralDamping,
+        };
+    }
+    /** @internal */
+    sanitizeHorizonOptions(options) {
+        return {
+            influenceAngle: Number.isFinite(options.influenceAngle)
+                ? Math.max(1, Math.abs(options.influenceAngle))
+                : DEFAULT_HORIZON.influenceAngle,
+            parallaxFactor: Number.isFinite(options.parallaxFactor)
+                ? Math.max(0, Math.abs(options.parallaxFactor))
+                : DEFAULT_HORIZON.parallaxFactor,
+            baseYOffset: Number.isFinite(options.baseYOffset)
+                ? options.baseYOffset
+                : DEFAULT_HORIZON.baseYOffset,
+            maxVisibleMarkers: Number.isFinite(options.maxVisibleMarkers)
+                ? Math.max(1, Math.round(options.maxVisibleMarkers))
+                : DEFAULT_HORIZON.maxVisibleMarkers,
+            headingResponse: Number.isFinite(options.headingResponse)
+                ? Math.max(0, Math.abs(options.headingResponse))
+                : DEFAULT_HORIZON.headingResponse,
+        };
+    }
+    /** @internal */
+    sanitizeMinimapOptions(options) {
+        return {
+            visible: options.visible !== false,
+            x: Number.isFinite(options.x) ? options.x : this.width - 164,
+            y: Number.isFinite(options.y) ? options.y : 16,
+            width: Number.isFinite(options.width) ? Math.max(48, options.width) : 148,
+            height: Number.isFinite(options.height) ? Math.max(48, options.height) : 148,
+            padding: Number.isFinite(options.padding) ? Math.max(0, options.padding) : 10,
+            alpha: this.clamp01(options.alpha),
+            backgroundColor: options.backgroundColor || DEFAULT_MINIMAP.backgroundColor,
+            borderColor: options.borderColor || DEFAULT_MINIMAP.borderColor,
+            borderWidth: Number.isFinite(options.borderWidth)
+                ? Math.max(0, options.borderWidth)
+                : DEFAULT_MINIMAP.borderWidth,
+            trackColor: options.trackColor || DEFAULT_MINIMAP.trackColor,
+            trackLineWidth: Number.isFinite(options.trackLineWidth)
+                ? Math.max(1, options.trackLineWidth)
+                : DEFAULT_MINIMAP.trackLineWidth,
+            playerColor: options.playerColor || DEFAULT_MINIMAP.playerColor,
+            playerStrokeColor: options.playerStrokeColor || DEFAULT_MINIMAP.playerStrokeColor,
+            playerRadius: Number.isFinite(options.playerRadius)
+                ? Math.max(1, options.playerRadius)
+                : DEFAULT_MINIMAP.playerRadius,
+        };
+    }
+    /** @internal */
+    sanitizeGroundFillOptions(options) {
+        return {
+            enabled: options.enabled !== false,
+            color: options.color === null || options.color === undefined || options.color === ""
+                ? null
+                : options.color,
+        };
+    }
+    /** @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,
+            realCollisionBounds: options.realCollisionBounds ?? DEFAULT_DEBUG.realCollisionBounds,
+            visualBoundsColor: options.visualBoundsColor || DEFAULT_DEBUG.visualBoundsColor,
+            playerCollisionBoundsColor: options.playerCollisionBoundsColor ||
+                DEFAULT_DEBUG.playerCollisionBoundsColor,
+            trafficCollisionBoundsColor: options.trafficCollisionBoundsColor ||
+                DEFAULT_DEBUG.trafficCollisionBoundsColor,
+            playerRealCollisionBoundsColor: options.playerRealCollisionBoundsColor ||
+                DEFAULT_DEBUG.playerRealCollisionBoundsColor,
+            trafficRealCollisionBoundsColor: options.trafficRealCollisionBoundsColor ||
+                DEFAULT_DEBUG.trafficRealCollisionBoundsColor,
+            lineWidth: Number.isFinite(options.lineWidth)
+                ? Math.max(1, options.lineWidth)
+                : DEFAULT_DEBUG.lineWidth,
+        };
+    }
+    /** @internal */
+    normalizeAngle(angle) {
+        if (!Number.isFinite(angle))
+            return 0;
+        const wrapped = angle % 360;
+        return wrapped < 0 ? wrapped + 360 : wrapped;
+    }
+    /** @internal */
+    getShortestAngleDelta(fromAngle, toAngle) {
+        const from = this.normalizeAngle(fromAngle);
+        const to = this.normalizeAngle(toAngle);
+        let delta = to - from;
+        if (delta > 180)
+            delta -= 360;
+        if (delta < -180)
+            delta += 360;
+        return delta;
+    }
+    /** @internal */
+    easeInOut(value) {
+        return value * value * (3 - 2 * value);
+    }
+    /** @internal */
+    lerp(a, b, t) {
+        return a + (b - a) * t;
+    }
+}
+/**
+ * Automatic traffic orchestration for {@link ArcadeRacerEngine}.
+ *
+ * `ArcadeRacerTrafficManager` owns a pool of manager-spawned vehicles and keeps
+ * that pool populated by:
+ *
+ * - choosing weighted traffic profiles
+ * - selecting lanes and spawn distances ahead of the player
+ * - removing vehicles that have fallen sufficiently behind
+ * - respecting a simple same-lane minimum gap
+ *
+ * The manager is intentionally separate from {@link ArcadeRacerEngine} so AI
+ * agents and game code can opt into dynamic traffic only when they need it.
+ * You construct it explicitly with `new ArcadeRacerTrafficManager(racer, ...)`
+ * and call {@link update} each frame.
+ *
+ * Recommended usage:
+ *
+ * Start with `ArcadeRacerTrafficManager` as the default solution for gameplay
+ * traffic. It covers the common arcade-racer needs of weighted vehicle mixes,
+ * lane-aware spacing, spawn windows, and cleanup with a small API surface.
+ * If your game later needs more specialized behavior such as scripted events,
+ * convoy logic, mission traffic, branching-road orchestration, or highly custom
+ * spawning rules, you can replace it with your own traffic strategy while still
+ * using {@link ArcadeRacerEngine.addTraffic} and
+ * {@link ArcadeRacerEngine.removeTrafficById} directly.
+ *
+ * The manager only tracks vehicles that it spawned itself. Vehicles added
+ * manually with {@link ArcadeRacerEngine.addTraffic} remain untouched.
+ */
+export class ArcadeRacerTrafficManager {
+    constructor(racer, options) {
+        /** @internal */
+        this.entries = [];
+        /** @internal */
+        this.spawnCooldown = 0;
+        this.racer = racer;
+        this.profiles = options.profiles.filter(Boolean);
+        this.lanePositions = sanitizeLaneSpacePositions(options.lanePositions);
+        this.onSpawn = options.onSpawn;
+        this.onDespawn = options.onDespawn;
+        this.maxActive = Math.max(1, Math.round(options.maxActive ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.maxActive));
+        this.spawnAheadMin = Math.max(1, options.spawnAheadMin ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.spawnAheadMin);
+        this.spawnAheadMax = Math.max(this.spawnAheadMin, options.spawnAheadMax ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.spawnAheadMax);
+        this.spawnBehindMin = Math.max(1, options.spawnBehindMin ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.spawnBehindMin);
+        this.spawnBehindMax = Math.max(this.spawnBehindMin, options.spawnBehindMax ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.spawnBehindMax);
+        this.despawnBehindDistance = Math.max(1, options.despawnBehindDistance ??
+            DEFAULT_TRAFFIC_MANAGER_OPTIONS.despawnBehindDistance);
+        this.despawnAheadDistance = Math.max(this.spawnAheadMax, options.despawnAheadDistance ??
+            DEFAULT_TRAFFIC_MANAGER_OPTIONS.despawnAheadDistance);
+        this.minGapDistance = Math.max(1, options.minGapDistance ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.minGapDistance);
+        this.spawnInterval = Math.max(0.05, options.spawnInterval ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.spawnInterval);
+        this.oncomingChance = Math.max(0, Math.min(1, options.oncomingChance ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.oncomingChance));
+        this.fasterTrafficSpawnsBehind =
+            options.fasterTrafficSpawnsBehind ??
+                DEFAULT_TRAFFIC_MANAGER_OPTIONS.fasterTrafficSpawnsBehind;
+        this.enabledState = options.enabled ?? true;
+        const initialActive = Math.max(0, Math.min(this.maxActive, Math.round(options.initialActive ?? DEFAULT_TRAFFIC_MANAGER_OPTIONS.initialActive)));
+        if (initialActive > 0) {
+            this.spawnNow(initialActive);
+        }
+    }
+    /**
+     * Whether the manager is allowed to spawn new vehicles.
+     *
+     * Disabling the manager does not remove existing managed traffic; it only
+     * pauses new spawn attempts. Existing entries continue to be tracked and
+     * despawned when they fall behind the player.
+     */
+    get enabled() {
+        return this.enabledState;
+    }
+    set enabled(value) {
+        this.enabledState = Boolean(value);
+    }
+    /**
+     * Number of currently active manager-owned traffic vehicles.
+     */
+    get activeCount() {
+        return this.entries.length;
+    }
+    /**
+     * Updates manager-owned traffic bookkeeping and performs spawn/despawn work.
+     */
+    update(dt) {
+        const safeDt = Number.isFinite(dt) && dt > 0 ? Math.min(dt, 0.1) : 0;
+        if (safeDt > 0) {
+            for (const entry of this.entries) {
+                entry.distance += entry.speed * safeDt;
+            }
+        }
+        this.pruneBehindPlayer();
+        if (!this.enabledState || this.profiles.length === 0) {
+            return;
+        }
+        this.spawnCooldown -= safeDt;
+        while (this.spawnCooldown <= 0 &&
+            this.entries.length < this.maxActive) {
+            this.spawnCooldown += this.spawnInterval;
+            if (!this.spawnOne()) {
+                break;
+            }
+        }
+    }
+    /**
+     * Immediately spawns up to `count` new traffic vehicles if valid slots exist.
+     */
+    spawnNow(count = 1) {
+        const target = Math.max(0, Math.round(count));
+        let spawned = 0;
+        for (let i = 0; i < target && this.entries.length < this.maxActive; i++) {
+            if (!this.spawnOne())
+                break;
+            spawned += 1;
+        }
+        return spawned;
+    }
+    /**
+     * Removes all manager-owned vehicles from the racer.
+     */
+    clear() {
+        while (this.entries.length > 0) {
+            const entry = this.entries.pop();
+            this.racer.removeTrafficById(entry.id);
+            this.onDespawn?.({
+                id: entry.id,
+                reason: "cleared",
+                profile: entry.profile,
+            });
+        }
+    }
+    /** @internal */
+    spawnOne() {
+        if (this.profiles.length === 0)
+            return false;
+        const maxAttempts = Math.max(4, this.profiles.length * 3);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const profile = this.pickProfile();
+            if (!profile)
+                return false;
+            const oncoming = this.resolveOncoming(profile);
+            const lane = this.pickLane(profile, oncoming);
+            if (!Number.isFinite(lane))
+                continue;
+            const speedMph = this.pickSpeedMph(profile, oncoming);
+            const speed = (oncoming ? -1 : 1) * Math.max(0, speedMph / MPH_PER_SPEED_UNIT);
+            const distance = this.pickSpawnDistance(speed, oncoming);
+            if (!this.isGapSafe(lane, distance))
+                continue;
+            const baseScale = this.pickBaseScale(profile);
+            const trafficId = this.racer.addTraffic(profile.visual, {
+                lane,
+                distance,
+                speed,
+                baseScale,
+                bodyWidth: profile.bodyWidth,
+                bodyLength: profile.bodyLength,
+                bodyOffsetX: profile.bodyOffsetX,
+                bodyOffsetY: profile.bodyOffsetY,
+            });
+            this.entries.push({
+                id: trafficId,
+                lane,
+                distance,
+                speed,
+                oncoming,
+                profile,
+            });
+            this.onSpawn?.({
+                id: trafficId,
+                lane,
+                distance,
+                speed,
+                speedMph,
+                oncoming,
+                profile,
+            });
+            return true;
+        }
+        return false;
+    }
+    /** @internal */
+    pruneBehindPlayer() {
+        const cutoff = this.racer.distance -
+            Math.max(this.despawnBehindDistance, this.spawnBehindMax + this.minGapDistance * 0.5);
+        const aheadCutoff = this.racer.distance + this.despawnAheadDistance;
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const entry = this.entries[i];
+            if (entry.distance <= cutoff) {
+                this.entries.splice(i, 1);
+                this.racer.removeTrafficById(entry.id);
+                this.onDespawn?.({
+                    id: entry.id,
+                    reason: "behind",
+                    profile: entry.profile,
+                });
+                continue;
+            }
+            if (entry.distance < aheadCutoff)
+                continue;
+            this.entries.splice(i, 1);
+            this.racer.removeTrafficById(entry.id);
+            this.onDespawn?.({
+                id: entry.id,
+                reason: "ahead",
+                profile: entry.profile,
+            });
+        }
+    }
+    /** @internal */
+    pickProfile() {
+        let totalWeight = 0;
+        for (const profile of this.profiles) {
+            totalWeight += Math.max(0.0001, profile.weight ?? 1);
+        }
+        if (totalWeight <= 0)
+            return null;
+        let cursor = Math.random() * totalWeight;
+        for (const profile of this.profiles) {
+            cursor -= Math.max(0.0001, profile.weight ?? 1);
+            if (cursor <= 0)
+                return profile;
+        }
+        return this.profiles[this.profiles.length - 1] ?? null;
+    }
+    /** @internal */
+    pickLane(profile, oncoming) {
+        if (Number.isFinite(profile.lane)) {
+            return profile.lane;
+        }
+        const lanes = sanitizeLaneSpacePositions(profile.lanes) ??
+            this.lanePositions ??
+            this.racer.getLanePositions(oncoming ? "oncoming" : "same");
+        if (lanes.length === 0)
+            return Number.NaN;
+        return lanes[Math.floor(Math.random() * lanes.length)] ?? 0;
+    }
+    /** @internal */
+    resolveOncoming(profile) {
+        if (profile.direction === "oncoming")
+            return true;
+        if (profile.direction === "either")
+            return Math.random() < this.oncomingChance;
+        return false;
+    }
+    /** @internal */
+    pickSpeedMph(profile, oncoming) {
+        if (Number.isFinite(profile.speedMph)) {
+            return Math.max(1, Math.abs(profile.speedMph));
+        }
+        const defaultMin = oncoming ? 135 : 92;
+        const defaultMax = oncoming ? 185 : 145;
+        const min = Math.max(1, profile.speedMphMin ?? defaultMin);
+        const max = Math.max(min, profile.speedMphMax ?? defaultMax);
+        return min + Math.random() * (max - min);
+    }
+    /** @internal */
+    pickBaseScale(profile) {
+        if (Number.isFinite(profile.baseScale)) {
+            return Math.max(0, profile.baseScale);
+        }
+        const min = Math.max(0, profile.baseScaleMin ?? 1);
+        const max = Math.max(min, profile.baseScaleMax ?? min);
+        return min + Math.random() * (max - min);
+    }
+    /** @internal */
+    pickSpawnDistance(speed, oncoming) {
+        const playerSpeed = Math.max(0, this.racer.speed);
+        if (!oncoming &&
+            this.fasterTrafficSpawnsBehind &&
+            speed > playerSpeed + 0.001) {
+            return (this.racer.distance -
+                (this.spawnBehindMin +
+                    Math.random() * (this.spawnBehindMax - this.spawnBehindMin)));
+        }
+        return (this.racer.distance +
+            this.spawnAheadMin +
+            Math.random() * (this.spawnAheadMax - this.spawnAheadMin));
+    }
+    /** @internal */
+    isGapSafe(lane, distance) {
+        return this.entries.every((entry) => {
+            if (Math.abs(entry.lane - lane) > 0.08)
+                return true;
+            return Math.abs(entry.distance - distance) >= this.minGapDistance;
+        });
+    }
+}
+/**
+ * Fixed-field race competitor orchestration for {@link ArcadeRacerEngine}.
+ *
+ * Use `ArcadeRacerRaceManager` when the player is competing against a known set
+ * of opponents instead of ambient road traffic. The manager creates one traffic
+ * vehicle per competitor, advances each competitor explicitly every frame, and
+ * exposes simple race standings based on forward progress toward a finish
+ * distance.
+ *
+ * This manager is best suited to classic arcade races where:
+ *
+ * - the roster is fixed at race start
+ * - opponents have defined names and pacing
+ * - finishing place matters more than ambient traffic density
+ *
+ * For world-traffic scenarios or open-road cruising, prefer
+ * {@link ArcadeRacerTrafficManager} instead.
+ */
+export class ArcadeRacerRaceManager {
+    constructor(racer, options) {
+        /** @internal */
+        this.entries = [];
+        this.racer = racer;
+        this.finishDistance = Math.max(1, options.finishDistance);
+        this.lanePositions =
+            sanitizeLaneSpacePositions(options.lanePositions) ??
+                (() => {
+                    const sameDirectionLanes = this.racer.getLanePositions("same");
+                    return sameDirectionLanes.length > 0
+                        ? sameDirectionLanes
+                        : this.racer.getLanePositions();
+                })();
+        for (const competitor of options.competitors) {
+            const lane = this.pickCompetitorLane(competitor);
+            const startDistance = Number.isFinite(competitor.startDistance)
+                ? competitor.startDistance
+                : 0;
+            const speedMph = this.pickCompetitorSpeedMph(competitor);
+            const speed = Math.max(0, speedMph / MPH_PER_SPEED_UNIT);
+            const trafficId = this.racer.addTraffic(competitor.visual, {
+                lane,
+                distance: startDistance,
+                speed: 0,
+                baseScale: competitor.baseScale,
+                bodyWidth: competitor.bodyWidth,
+                bodyLength: competitor.bodyLength,
+                bodyOffsetX: competitor.bodyOffsetX,
+                bodyOffsetY: competitor.bodyOffsetY,
+                loop: false,
+            });
+            this.entries.push({
+                id: trafficId,
+                name: competitor.name,
+                distance: startDistance,
+                lane,
+                speed,
+                finished: startDistance >= this.finishDistance,
+                profile: competitor,
+            });
+        }
+    }
+    /**
+     * Number of AI competitors currently managed by the race.
+     */
+    get competitorCount() {
+        return this.entries.length;
+    }
+    /**
+     * Advances competitor progress and synchronizes their traffic vehicles.
+     */
+    update(dt) {
+        const safeDt = Number.isFinite(dt) && dt > 0 ? Math.min(dt, 0.1) : 0;
+        if (safeDt <= 0)
+            return;
+        for (const entry of this.entries) {
+            if (!entry.finished) {
+                entry.distance += entry.speed * safeDt;
+                if (entry.distance >= this.finishDistance) {
+                    entry.distance = this.finishDistance;
+                    entry.finished = true;
+                }
+            }
+            this.racer.updateTrafficById(entry.id, {
+                distance: entry.distance,
+                lane: entry.lane,
+                speed: 0,
+                loop: false,
+            });
+        }
+    }
+    /**
+     * Returns race standings including the player.
+     */
+    getStandings() {
+        const standings = [
+            {
+                id: "player",
+                name: "PLAYER",
+                distance: Math.min(this.racer.distance, this.finishDistance),
+                finished: this.racer.distance >= this.finishDistance,
+                isPlayer: true,
+                position: 0,
+            },
+            ...this.entries.map((entry) => ({
+                id: entry.id,
+                name: entry.name,
+                distance: Math.min(entry.distance, this.finishDistance),
+                finished: entry.finished,
+                isPlayer: false,
+                position: 0,
+            })),
+        ];
+        standings.sort((a, b) => {
+            if (a.distance !== b.distance)
+                return b.distance - a.distance;
+            if (a.finished !== b.finished)
+                return Number(b.finished) - Number(a.finished);
+            return a.name.localeCompare(b.name);
+        });
+        standings.forEach((entry, index) => {
+            entry.position = index + 1;
+        });
+        return standings;
+    }
+    /**
+     * Returns the player's current race position.
+     */
+    getPlayerPosition() {
+        return this.getStandings().find((entry) => entry.isPlayer)?.position ?? 1;
+    }
+    /**
+     * Removes all race competitors from the racer.
+     */
+    clear() {
+        while (this.entries.length > 0) {
+            const entry = this.entries.pop();
+            this.racer.removeTrafficById(entry.id);
+        }
+    }
+    /** @internal */
+    pickCompetitorLane(competitor) {
+        if (Number.isFinite(competitor.lane)) {
+            return competitor.lane;
+        }
+        const lanes = competitor.lanes?.length
+            ? competitor.lanes
+            : this.lanePositions;
+        return lanes[Math.floor(Math.random() * lanes.length)] ?? 0;
+    }
+    /** @internal */
+    pickCompetitorSpeedMph(competitor) {
+        if (Number.isFinite(competitor.speedMph)) {
+            return Math.max(1, competitor.speedMph);
+        }
+        const min = Math.max(1, competitor.speedMphMin ?? 112);
+        const max = Math.max(min, competitor.speedMphMax ?? 136);
+        return min + Math.random() * (max - min);
+    }
+}