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

package/dist/minimo-arcaderacer.js

@@ -1,4 +1,315 @@
-import { DrawSprite } from "./minimo.js";
+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",
@@ -19,9 +330,10 @@ const DEFAULT_PERFORMANCE = {
     zeroToSixtySeconds: 6.2,
     sixtyToZeroSeconds: 3.6,
     topSpeedMph: 145,
-    steeringLowSpeedScale: 0.18,
-    steeringHighSpeedScale: 0.78,
-    steeringSpeedCurvePower: 1.5,
+    steeringLowSpeedScale: 0.9,
+    steeringHighSpeedScale: 0.34,
+    steeringSpeedCurvePower: 1.8,
+    lateralDamping: 6.8,
 };
 const DEFAULT_HORIZON = {
     influenceAngle: 120,
@@ -81,6 +393,22 @@ const DEFAULT_OPTIONS = {
     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.
@@ -124,7 +452,8 @@ const DEFAULT_OPTIONS = {
  *   speed: 120,
  * });
  *
- * racer.build();
+ * const roadSprite = racer.build();
+ * game.add(roadSprite);
  *
  * game.onUpdate = (dt) => {
  *   racer.accelerateToMph(110, dt);
@@ -145,8 +474,9 @@ const DEFAULT_OPTIONS = {
  *    {@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 and
- *    roadside decoration along the road.
+ *    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,
@@ -165,6 +495,10 @@ const DEFAULT_OPTIONS = {
  * - `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.
@@ -183,17 +517,28 @@ const DEFAULT_OPTIONS = {
  * - 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 = [];
@@ -210,15 +555,7 @@ export class ArcadeRacerEngine {
         /** @internal */
         this.grassBandSpan = 3;
         /** @internal */
-        this.segments = [];
-        /** @internal */
-        this.pathPrimitives = [];
-        /** @internal */
-        this.pathPointsCacheVersion = -1;
-        /** @internal */
-        this.pathPointsCache = [];
-        /** @internal */
-        this.totalTrackLength = 0;
+        this.roadDrawerRangesState = [];
         /** @internal */
         this.billboardsState = [];
         /** @internal */
@@ -234,6 +571,10 @@ export class ArcadeRacerEngine {
         /** @internal */
         this.distanceState = 0;
         /** @internal */
+        this.playerSteeringInputState = 0;
+        /** @internal */
+        this.playerLateralVelocityState = 0;
+        /** @internal */
         this.nextId = 1;
         /** @internal */
         this.roadSprite = null;
@@ -241,18 +582,6 @@ export class ArcadeRacerEngine {
         this.activeCollisionIds = new Set();
         /** @internal */
         this.headingState = 0;
-        /** @internal */
-        this.trackVersion = 0;
-        /** @internal */
-        this.trackExplicitlyClosed = false;
-        /** @internal */
-        this.trackClosureMetricsVersion = -1;
-        /** @internal */
-        this.trackClosureMetrics = null;
-        /** @internal */
-        this.minimapPathCacheVersion = -1;
-        /** @internal */
-        this.minimapPathCache = [];
         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));
@@ -265,7 +594,14 @@ export class ArcadeRacerEngine {
         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);
-        this.laneCount = Math.max(1, Math.round(options.laneCount ?? DEFAULT_OPTIONS.laneCount));
+        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);
@@ -275,6 +611,10 @@ export class ArcadeRacerEngine {
         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 ?? {}),
@@ -310,6 +650,8 @@ export class ArcadeRacerEngine {
         });
         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);
@@ -335,8 +677,31 @@ export class ArcadeRacerEngine {
         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);
-        this.resetTrack();
-        this.addTrackSegment({ length: 4000, curve: 0, hill: 0 });
+    }
+    /**
+     * 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.
@@ -382,6 +747,7 @@ export class ArcadeRacerEngine {
     }
     set playerLane(value) {
         this.playerLaneState = this.clampPlayerLane(value);
+        this.playerLateralVelocityState = 0;
     }
     /**
      * Whether the player is currently outside the configured road threshold.
@@ -399,34 +765,37 @@ export class ArcadeRacerEngine {
      * Removes all existing track primitives and legacy segments.
      */
     clearTrack() {
-        this.resetTrack();
+        this.trackSystem.clearTrack();
     }
     /**
      * Appends a straight path section.
      */
     straight(length, options = {}) {
-        this.appendPathLine(length, options);
+        this.trackSystem.appendPathLine(length, options);
     }
     /**
      * Replaces the track with a naturally closed rounded rectangle circuit.
      */
     roundedRect(width, height, cornerRadius) {
-        this.setRoundedRectTrack(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.appendPathArc(radius, degrees, -1, 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.appendPathArc(radius, degrees, 1, options);
+        this.trackSystem.appendPathArc(radius, degrees, 1, options);
     }
     /**
-     * Creates and registers the internal road sprite if it does not yet exist.
+     * 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)
@@ -436,7 +805,7 @@ export class ArcadeRacerEngine {
         sprite.y = this.y;
         sprite.ignoreScroll = true;
         sprite.layer = this.layer;
-        this.roadSprite = this.game.add(sprite);
+        this.roadSprite = sprite;
         return this.roadSprite;
     }
     /**
@@ -452,8 +821,8 @@ export class ArcadeRacerEngine {
         this.build();
         const safeDt = Number.isFinite(dt) && dt > 0 ? Math.min(dt, 0.1) : 0;
         this.distanceState += this.speedState * safeDt;
-        const current = this.sampleTrack(this.distanceState);
-        if (this.pathPrimitives.length > 0) {
+        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);
@@ -467,60 +836,50 @@ export class ArcadeRacerEngine {
                     safeDt);
         }
         const forwardSpeed = Math.abs(this.speedState);
-        const speedRatio = this.clamp01(forwardSpeed / 420);
-        const roadInfluenceScale = 0.18 + speedRatio * 0.82;
-        if (!this.isOffRoad) {
-            this.playerLaneState = this.clampPlayerLane(this.playerLaneState -
-                current.curve *
-                    forwardSpeed *
-                    this.playerRoadInfluence *
-                    roadInfluenceScale *
-                    safeDt *
-                    0.32);
-        }
+        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.totalTrackLength > 0) {
+            if (traffic.loop && this.trackSystem.totalTrackLength > 0) {
                 while (traffic.distance <
                     this.distanceState - this.trafficBehindVisibilityDistance) {
-                    traffic.distance += this.totalTrackLength;
+                    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;
-        const steeringScale = this.getSteeringScale();
-        this.playerLaneState = this.clampPlayerLane(this.playerLaneState -
-            this.steeringRate * steeringScale * safeStrength * Math.max(0, dt));
+        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;
-        const steeringScale = this.getSteeringScale();
-        this.playerLaneState = this.clampPlayerLane(this.playerLaneState +
-            this.steeringRate * steeringScale * safeStrength * Math.max(0, dt));
+        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, dt);
+            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, dt);
+        this.speedState = this.approachLinear(this.speedState, cappedTarget, accelerationPerSecond * accelerationScale, dt);
     }
     /**
      * Smoothly brakes the player speed toward a target value.
@@ -580,9 +939,13 @@ export class ArcadeRacerEngine {
                 id,
                 visual,
                 distance: Math.max(0, config.distance + i * spacing),
-                lane: Number.isFinite(config.lane) ? this.clampRoadLane(config.lane) : null,
+                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,
@@ -615,8 +978,8 @@ export class ArcadeRacerEngine {
         this.trafficState.push({
             id,
             visual,
-            distance: Math.max(0, config.distance),
-            lane: this.clampRoadLane(config.lane),
+            distance: Number.isFinite(config.distance) ? config.distance : 0,
+            lane: this.laneSystem.clampRoadLane(config.lane),
             speed: Number.isFinite(config.speed) ? config.speed : 140,
             baseScale,
             bodyWidth,
@@ -629,6 +992,62 @@ export class ArcadeRacerEngine {
         });
         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.
      */
@@ -642,6 +1061,20 @@ export class ArcadeRacerEngine {
     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.
      */
@@ -705,637 +1138,28 @@ export class ArcadeRacerEngine {
         this.backgroundLayersState.length = 0;
     }
     /** @internal */
-    setRoundedRectTrack(circuitWidth, circuitHeight, cornerRadius) {
-        const safeWidth = Math.max(48, Math.abs(circuitWidth));
-        const safeHeight = Math.max(48, Math.abs(circuitHeight));
-        const radius = Math.max(12, Math.min(Math.abs(cornerRadius), safeWidth / 2 - 1, safeHeight / 2 - 1));
-        const horizontal = Math.max(1, safeWidth - radius * 2);
-        const vertical = Math.max(1, safeHeight - radius * 2);
-        const arcAngle = Math.PI / 2;
-        this.resetTrack();
-        this.pathPrimitives = [
-            { type: "line", length: horizontal, elevationDelta: 0 },
-            { type: "arc", radius, angleRad: arcAngle, elevationDelta: 0 },
-            { type: "line", length: vertical, elevationDelta: 0 },
-            { type: "arc", radius, angleRad: arcAngle, elevationDelta: 0 },
-            { type: "line", length: horizontal, elevationDelta: 0 },
-            { type: "arc", radius, angleRad: arcAngle, elevationDelta: 0 },
-            { type: "line", length: vertical, elevationDelta: 0 },
-            { type: "arc", radius, angleRad: arcAngle, elevationDelta: 0 },
-        ];
-        this.totalTrackLength =
-            horizontal * 2 + vertical * 2 + radius * Math.PI * 2;
-        this.trackExplicitlyClosed = true;
-        this.trackVersion += 1;
-        this.pathPointsCache = [];
-        this.pathPointsCacheVersion = -1;
-    }
-    /** @internal */
-    appendPathLine(length, options = {}) {
-        const safeLength = Math.max(1, Math.abs(length));
-        if (this.pathPrimitives.length === 0 && this.segments.length > 0) {
-            this.resetTrack();
-        }
-        this.pathPrimitives.push({
-            type: "line",
-            length: safeLength,
-            elevationDelta: Number.isFinite(options.elevationDelta)
-                ? options.elevationDelta
-                : 0,
-        });
-        this.totalTrackLength += safeLength;
-        this.trackVersion += 1;
-        this.pathPointsCache = [];
-        this.pathPointsCacheVersion = -1;
-        this.trackExplicitlyClosed = false;
-    }
-    /** @internal */
-    appendPathArc(radius, degrees, direction, options = {}) {
-        const safeRadius = Math.max(1, Math.abs(radius));
-        const safeDegrees = Math.max(0.1, Math.abs(degrees));
-        if (this.pathPrimitives.length === 0 && this.segments.length > 0) {
-            this.resetTrack();
-        }
-        const angleRad = ((safeDegrees * Math.PI) / 180) * direction;
-        this.pathPrimitives.push({
-            type: "arc",
-            radius: safeRadius,
-            angleRad,
-            elevationDelta: Number.isFinite(options.elevationDelta)
-                ? options.elevationDelta
-                : 0,
-        });
-        this.totalTrackLength += Math.abs(safeRadius * angleRad);
-        this.trackVersion += 1;
-        this.pathPointsCache = [];
-        this.pathPointsCacheVersion = -1;
-        this.trackExplicitlyClosed = false;
-    }
-    /** @internal */
     render(ctx, width, height) {
-        const current = this.sampleTrack(this.distanceState);
-        this.drawBackground(ctx, width, height);
-        this.drawRoad(ctx, width, height, current);
-        this.drawSceneObjects(ctx, width, height, current);
-        this.drawMinimap(ctx);
-    }
-    /** @internal */
-    drawBackground(ctx, width, height) {
-        if (this.backgroundLayersState.length > 0) {
-            this.drawImageBackground(ctx, width, height);
-            return;
-        }
-        this.drawFallbackBackground(ctx, width, height);
-    }
-    /** @internal */
-    drawFallbackBackground(ctx, width, height) {
-        const sky = ctx.createLinearGradient(0, 0, 0, this.horizonY + 80);
-        sky.addColorStop(0, this.themeState.skyTop);
-        sky.addColorStop(0.55, this.themeState.skyBottom);
-        sky.addColorStop(1, this.themeState.skyBottom);
-        ctx.fillStyle = sky;
-        ctx.fillRect(0, 0, width, this.horizonY + 80);
-        ctx.fillStyle = this.themeState.horizonGlow;
-        ctx.fillRect(0, this.horizonY - 8, width, 18);
-        const sunX = width * 0.74;
-        const sunY = Math.max(40, this.horizonY * 0.54);
-        const sun = ctx.createRadialGradient(sunX, sunY, 8, sunX, sunY, 56);
-        sun.addColorStop(0, this.themeState.sunInner);
-        sun.addColorStop(0.45, "rgba(255, 205, 113, 0.75)");
-        sun.addColorStop(1, this.themeState.sunOuter);
-        ctx.fillStyle = sun;
-        ctx.beginPath();
-        ctx.arc(sunX, sunY, 56, 0, Math.PI * 2);
-        ctx.fill();
-        ctx.fillStyle = this.themeState.mountainBack;
-        ctx.beginPath();
-        ctx.moveTo(0, this.horizonY + 18);
-        for (let x = 0; x <= width; x += 8) {
-            const y = this.horizonY +
-                24 +
-                Math.sin(x * 0.012 + this.distanceState * 0.00015) * 22 +
-                Math.sin(x * 0.021 - this.distanceState * 0.00008) * 11;
-            ctx.lineTo(x, y);
-        }
-        ctx.lineTo(width, this.horizonY + 90);
-        ctx.lineTo(0, this.horizonY + 90);
-        ctx.closePath();
-        ctx.fill();
-        ctx.fillStyle = this.themeState.mountainFront;
-        ctx.beginPath();
-        ctx.moveTo(0, this.horizonY + 34);
-        for (let x = 0; x <= width; x += 7) {
-            const y = this.horizonY +
-                42 +
-                Math.sin(x * 0.01 + this.distanceState * 0.00019 + 1.1) * 30 +
-                Math.sin(x * 0.018 - this.distanceState * 0.0001 - 0.7) * 16;
-            ctx.lineTo(x, y);
-        }
-        ctx.lineTo(width, this.horizonY + 115);
-        ctx.lineTo(0, this.horizonY + 115);
-        ctx.closePath();
-        ctx.fill();
-        this.drawDirectionalHorizon(ctx, width);
-        if (this.groundFillState.enabled) {
-            ctx.fillStyle = this.groundFillState.color ?? this.themeState.grassA;
-            ctx.fillRect(0, this.horizonY, width, height - this.horizonY);
-        }
-    }
-    /** @internal */
-    drawImageBackground(ctx, width, height) {
-        ctx.fillStyle = this.themeState.skyBottom;
-        ctx.fillRect(0, 0, width, this.horizonY + 80);
-        for (const layer of this.backgroundLayersState) {
-            const surface = this.resolveVisualSurface(layer.visual);
-            const drawWidth = Math.max(1, surface.width * layer.baseScale);
-            const drawHeight = Math.max(1, surface.height * layer.baseScale);
-            const distanceOffset = this.distanceState * layer.parallaxDistance;
-            const headingOffset = (this.headingState / 90) * width * layer.parallaxHeading;
-            const stride = drawWidth + layer.spacing;
-            const y = layer.y;
-            ctx.save();
-            ctx.globalAlpha = layer.alpha;
-            if (layer.repeat) {
-                let startX = layer.xOffset - distanceOffset - headingOffset;
-                startX = ((startX % stride) + stride) % stride - stride;
-                for (let x = startX; x < width + stride; x += stride) {
-                    ctx.drawImage(surface.source, Math.round(x), Math.round(y), drawWidth, drawHeight);
-                }
-            }
-            else {
-                const x = width / 2 -
-                    drawWidth / 2 +
-                    layer.xOffset -
-                    distanceOffset -
-                    headingOffset;
-                ctx.drawImage(surface.source, Math.round(x), Math.round(y), drawWidth, drawHeight);
-            }
-            ctx.restore();
-        }
-        this.drawDirectionalHorizon(ctx, width);
-        if (this.groundFillState.enabled) {
-            ctx.fillStyle = this.groundFillState.color ?? this.themeState.grassA;
-            ctx.fillRect(0, this.horizonY, width, height - this.horizonY);
-        }
-    }
-    /** @internal */
-    drawDirectionalHorizon(ctx, width) {
-        if (this.horizonMarkersState.length === 0) {
-            return;
-        }
-        const visible = this.horizonMarkersState
-            .map((marker) => {
-            const influenceAngle = marker.influenceAngle ?? this.horizonState.influenceAngle;
-            const signedDelta = this.getShortestAngleDelta(this.headingState, marker.angle);
-            const absDelta = Math.abs(signedDelta);
-            if (absDelta > influenceAngle) {
-                return null;
-            }
-            const weight = 1 - absDelta / influenceAngle;
-            const easedWeight = this.easeInOut(weight);
-            const parallaxFactor = marker.parallaxFactor ?? this.horizonState.parallaxFactor;
-            const x = width / 2 + (signedDelta / 90) * width * parallaxFactor;
-            return {
-                marker,
-                absDelta,
-                alpha: marker.alpha * easedWeight,
-                x,
-                y: this.horizonY + this.horizonState.baseYOffset + marker.yOffset,
-            };
-        })
-            .filter((entry) => entry !== null && entry.alpha > 0.001)
-            .sort((a, b) => a.absDelta - b.absDelta)
-            .slice(0, this.horizonState.maxVisibleMarkers)
-            .sort((a, b) => a.alpha - b.alpha);
-        for (const entry of visible) {
-            this.drawVisual(ctx, entry.marker.visual, entry.x, entry.y, entry.marker.baseScale, entry.alpha);
-        }
-    }
-    /** @internal */
-    drawMinimap(ctx) {
-        if (!this.minimapState.visible || this.totalTrackLength <= 0) {
-            return;
-        }
-        const points = this.getMinimapPathPoints();
-        if (points.length < 2) {
-            return;
-        }
-        const x = this.minimapState.x;
-        const y = this.minimapState.y;
-        const width = this.minimapState.width;
-        const height = this.minimapState.height;
-        const padding = this.minimapState.padding;
-        let minX = Number.POSITIVE_INFINITY;
-        let maxX = Number.NEGATIVE_INFINITY;
-        let minY = Number.POSITIVE_INFINITY;
-        let maxY = Number.NEGATIVE_INFINITY;
-        for (const point of points) {
-            if (point.x < minX)
-                minX = point.x;
-            if (point.x > maxX)
-                maxX = point.x;
-            if (point.y < minY)
-                minY = point.y;
-            if (point.y > maxY)
-                maxY = point.y;
-        }
-        const innerWidth = Math.max(1, width - padding * 2);
-        const innerHeight = Math.max(1, height - padding * 2);
-        const boundsWidth = Math.max(1, maxX - minX);
-        const boundsHeight = Math.max(1, maxY - minY);
-        const scale = Math.min(innerWidth / boundsWidth, innerHeight / boundsHeight);
-        const offsetX = x + padding + (innerWidth - boundsWidth * scale) / 2 - minX * scale;
-        const offsetY = y + padding + (innerHeight - boundsHeight * scale) / 2 - minY * scale;
-        ctx.save();
-        ctx.globalAlpha = this.clamp01(this.minimapState.alpha);
-        ctx.fillStyle = this.minimapState.backgroundColor;
-        this.fillRoundedRect(ctx, x, y, width, height, 12);
-        if (this.minimapState.borderWidth > 0) {
-            ctx.strokeStyle = this.minimapState.borderColor;
-            ctx.lineWidth = this.minimapState.borderWidth;
-            this.strokeRoundedRect(ctx, x, y, width, height, 12);
-        }
-        ctx.beginPath();
-        ctx.lineJoin = "round";
-        ctx.lineCap = "round";
-        ctx.lineWidth = this.minimapState.trackLineWidth;
-        ctx.strokeStyle = this.minimapState.trackColor;
-        ctx.moveTo(offsetX + points[0].x * scale, offsetY + points[0].y * scale);
-        for (let i = 1; i < points.length; i++) {
-            ctx.lineTo(offsetX + points[i].x * scale, offsetY + points[i].y * scale);
-        }
-        const startPoint = points[0];
-        const endPoint = points[points.length - 1];
-        const closureDistance = Math.hypot(endPoint.x - startPoint.x, endPoint.y - startPoint.y);
-        const closureTolerance = Math.max(boundsWidth, boundsHeight) * 0.08;
-        if (closureDistance <= closureTolerance) {
-            ctx.closePath();
-        }
-        ctx.stroke();
-        const wrappedDistance = this.wrapDistance(this.distanceState);
-        const playerPoint = this.sampleMinimapPoint(points, wrappedDistance);
-        const playerX = offsetX + playerPoint.x * scale;
-        const playerY = offsetY + playerPoint.y * scale;
-        const radius = this.minimapState.playerRadius;
-        ctx.beginPath();
-        ctx.arc(playerX, playerY, radius, 0, Math.PI * 2);
-        ctx.fillStyle = this.minimapState.playerColor;
-        ctx.fill();
-        ctx.lineWidth = Math.max(1, this.minimapState.borderWidth * 0.75);
-        ctx.strokeStyle = this.minimapState.playerStrokeColor;
-        ctx.stroke();
-        ctx.restore();
-    }
-    /** @internal */
-    drawRoad(ctx, width, height, current) {
-        for (let i = 0; i < this.stripCount; i++) {
-            const tFar = i / this.stripCount;
-            const tNear = (i + 1) / this.stripCount;
-            const aheadFar = (1 - tFar) * this.drawDistance;
-            const aheadNear = (1 - tNear) * this.drawDistance;
-            const far = this.projectRoadPoint(current, aheadFar, width, height);
-            const near = this.projectRoadPoint(current, aheadNear, width, height);
-            const stripeIndex = Math.floor(this.distanceState * 0.05 + i);
-            const grassBandIndex = Math.floor(stripeIndex / this.grassBandSpan);
-            const shoulderBandIndex = Math.floor(stripeIndex / this.shoulderBandSpan);
-            const roadBandIndex = Math.floor(stripeIndex / this.roadBandSpan);
-            const farY = Math.floor(far.y);
-            const nearY = Math.ceil(near.y) + 1;
-            if (nearY <= farY) {
-                continue;
-            }
-            this.drawQuad(ctx, 0, farY, width, farY, width, nearY, 0, nearY, grassBandIndex % 2 === 0 ? this.themeState.grassA : this.themeState.grassB);
-            const shoulderFar = far.roadWidth * 0.12;
-            const shoulderNear = near.roadWidth * 0.12;
-            const leftOuterFar = far.x - far.roadWidth / 2 - shoulderFar;
-            const rightOuterFar = far.x + far.roadWidth / 2 + shoulderFar;
-            const leftOuterNear = near.x - near.roadWidth / 2 - shoulderNear;
-            const rightOuterNear = near.x + near.roadWidth / 2 + shoulderNear;
-            const leftRoadFar = far.x - far.roadWidth / 2;
-            const rightRoadFar = far.x + far.roadWidth / 2;
-            const leftRoadNear = near.x - near.roadWidth / 2;
-            const rightRoadNear = near.x + near.roadWidth / 2;
-            this.drawQuad(ctx, leftOuterFar, farY, rightOuterFar, farY, rightOuterNear, nearY, leftOuterNear, nearY, shoulderBandIndex % 2 === 0
-                ? this.themeState.shoulderA
-                : this.themeState.shoulderB);
-            this.drawQuad(ctx, leftRoadFar, farY, rightRoadFar, farY, rightRoadNear, nearY, leftRoadNear, nearY, roadBandIndex % 2 === 0 ? this.themeState.roadA : this.themeState.roadB);
-            const laneSeparators = Math.max(0, this.laneCount - 1);
-            if (laneSeparators > 0 && near.roadWidth > 90 && stripeIndex % 7 < 3) {
-                for (let laneIndex = 1; laneIndex < this.laneCount; laneIndex++) {
-                    const laneT = laneIndex / this.laneCount;
-                    const markerFarX = leftRoadFar + laneT * (rightRoadFar - leftRoadFar);
-                    const markerNearX = leftRoadNear + laneT * (rightRoadNear - leftRoadNear);
-                    const markerFarWidth = Math.max(2, far.roadWidth * 0.028);
-                    const markerNearWidth = Math.max(2, near.roadWidth * 0.028);
-                    this.drawQuad(ctx, markerFarX - markerFarWidth / 2, farY, markerFarX + markerFarWidth / 2, farY, markerNearX + markerNearWidth / 2, nearY, markerNearX - markerNearWidth / 2, nearY, this.themeState.laneMarker);
-                }
-            }
-        }
-        const vignette = ctx.createLinearGradient(0, this.horizonY, 0, height);
-        vignette.addColorStop(0, "rgba(0, 0, 0, 0)");
-        vignette.addColorStop(1, "rgba(0, 0, 0, 0.18)");
-        ctx.fillStyle = vignette;
-        ctx.fillRect(0, this.horizonY, width, height - this.horizonY);
-    }
-    /** @internal */
-    drawSceneObjects(ctx, width, height, current) {
-        const visible = [];
-        for (const billboard of this.billboardsState) {
-            const ahead = this.getLoopingAheadDistance(billboard.distance);
-            if (ahead <= 0 || ahead > this.drawDistance)
-                continue;
-            const projection = this.projectObject(current, ahead, billboard, width, height);
-            if (!projection)
-                continue;
-            visible.push({
-                depth: ahead,
-                x: projection.x,
-                y: projection.y,
-                bottom: this.getVisualBottom(billboard.visual, projection.x, projection.y, projection.scale * billboard.baseScale),
-                scale: projection.scale * billboard.baseScale,
-                alpha: billboard.alpha,
-                visual: billboard.visual,
-                kind: "billboard",
-            });
-        }
-        for (const traffic of this.trafficState) {
-            const ahead = traffic.distance - this.distanceState;
-            if (ahead <= -this.trafficBehindVisibilityDistance ||
-                ahead > this.drawDistance) {
-                continue;
-            }
-            const projection = this.projectTrafficPoint(current, ahead, width, height);
-            const x = projection.x + traffic.lane * projection.roadWidth * 0.38;
-            visible.push({
-                depth: ahead,
-                x,
-                y: projection.y,
-                bottom: this.getVisualBottom(traffic.visual, x, projection.y, projection.scale * traffic.baseScale),
-                scale: projection.scale * traffic.baseScale,
-                alpha: traffic.alpha,
-                visual: traffic.visual,
-                kind: "traffic",
-                bodyWidth: traffic.bodyWidth,
-                bodyLength: traffic.bodyLength,
-                bodyReferenceScale: traffic.baseScale,
-                bodyOffsetX: traffic.bodyOffsetX,
-                bodyOffsetY: traffic.bodyOffsetY,
-                resolvedBody: traffic.resolvedBody,
-                collisionAhead: ahead,
-                collisionLane: traffic.lane,
-                collisionCenterX: x,
-            });
-        }
-        const playerProjection = this.projectTrafficPoint(current, this.playerProjectionAheadDistance, width, height);
-        const playerCenterX = this.getPlayerScreenX();
-        visible.push({
-            depth: this.playerProjectionAheadDistance,
-            x: playerCenterX,
-            y: this.playerScreenYState,
-            bottom: this.getVisualBottom(this.playerVisualState, playerCenterX, this.playerScreenYState, playerProjection.scale * this.playerBaseScaleState),
-            scale: playerProjection.scale * this.playerBaseScaleState,
-            alpha: 1,
-            visual: this.playerVisualState,
-            kind: "player",
-            bodyWidth: this.playerBodyWidthState,
-            bodyLength: this.playerBodyLengthState,
-            bodyReferenceScale: this.playerBaseScaleState,
-            bodyOffsetX: this.playerBodyOffsetXState,
-            bodyOffsetY: this.playerBodyOffsetYState,
-            resolvedBody: this.playerResolvedBodyState,
-            collisionAhead: this.playerProjectionAheadDistance,
-            collisionLane: this.playerLaneState,
-            collisionCenterX: playerCenterX,
-        });
-        visible.sort((a, b) => {
-            if (a.bottom !== b.bottom) {
-                return a.bottom - b.bottom;
-            }
-            return b.depth - a.depth;
-        });
-        for (const entry of visible) {
-            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, entry.bodyOffsetX, entry.bodyOffsetY, entry.resolvedBody, current, width, height, entry.collisionAhead, entry.collisionLane, entry.collisionCenterX);
-            }
-        }
-    }
-    /** @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 */
-    getVisualBottom(visual, x, y, scale) {
-        const surface = this.resolveVisualSurface(visual);
-        const rect = this.getVisualRect(surface, x, y, scale);
-        return rect.y + rect.height;
-    }
-    /** @internal */
-    drawCarDebugBounds(ctx, kind, visualRect, visual, bodyReferenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY, resolvedBody, current, width, height, collisionAhead, collisionLane, collisionCenterX) {
-        if (!this.debugState.enabled)
-            return;
-        ctx.save();
-        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, bodyOffsetX ?? 0, bodyOffsetY ?? 0)
-            : 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);
-        }
-        const realCollisionRect = this.debugState.realCollisionBounds &&
-            current &&
-            Number.isFinite(width) &&
-            Number.isFinite(height) &&
-            Number.isFinite(bodyWidth) &&
-            Number.isFinite(bodyLength) &&
-            Number.isFinite(collisionAhead) &&
-            Number.isFinite(collisionLane)
-            ? this.getRealCollisionRect(current, width, height, collisionAhead, collisionLane, visual, bodyReferenceScale ?? 1, bodyWidth, bodyLength, bodyOffsetX ?? 0, bodyOffsetY ?? 0, resolvedBody, visualRect.x + visualRect.width / 2)
-            : null;
-        if (this.debugState.realCollisionBounds && realCollisionRect) {
-            ctx.strokeStyle =
-                kind === "player"
-                    ? this.debugState.playerRealCollisionBoundsColor
-                    : this.debugState.trafficRealCollisionBoundsColor;
-            ctx.setLineDash([2, 4]);
-            ctx.strokeRect(realCollisionRect.x, realCollisionRect.y, realCollisionRect.width, realCollisionRect.height);
-        }
-        ctx.restore();
+        this.renderSystem.renderFrame(ctx, width, height);
     }
     /** @internal */
     getDebugCollisionRectFromVisual(visualRect, visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY) {
-        const surface = this.resolveVisualSurface(visual);
-        const projectedScale = Math.max(0, Math.min(visualRect.width / Math.max(1, surface.width), visualRect.height / Math.max(1, surface.height)));
-        const rectWidth = Math.max(4, bodyWidth * projectedScale);
-        const rectHeight = Math.max(8, bodyLength * projectedScale);
-        const offsetX = bodyOffsetX * projectedScale;
-        const offsetY = bodyOffsetY * projectedScale;
-        return {
-            x: visualRect.x + (visualRect.width - rectWidth) / 2 + offsetX,
-            y: visualRect.y + visualRect.height - rectHeight + offsetY,
-            width: rectWidth,
-            height: rectHeight,
-        };
-    }
-    /** @internal */
-    getRealCollisionRect(current, width, height, ahead, lane, visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY, resolvedBody, anchorCenterX) {
-        const metrics = resolvedBody ??
-            this.resolveCollisionBodyMetrics(visual, referenceScale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY);
-        const bodyLaneWidth = metrics.laneWidth;
-        const bodyDistanceLength = metrics.distanceLength;
-        const laneCenter = lane + metrics.laneOffset;
-        const bodyDistanceOffset = metrics.distanceOffset;
-        const depthCenter = this.getBodyDistanceCenterFromAnchor(ahead, bodyDistanceLength, bodyDistanceOffset);
-        const center = this.projectTrafficPoint(current, depthCenter, width, height);
-        const far = this.projectTrafficPoint(current, depthCenter + bodyDistanceLength * 0.5, width, height);
-        const near = this.projectTrafficPoint(current, depthCenter - bodyDistanceLength * 0.5, width, height);
-        const laneUnit = center.roadWidth * 0.38;
-        const centerX = Number.isFinite(anchorCenterX)
-            ? anchorCenterX +
-                this.getBodyOffsetXInScreenPixels(visual, referenceScale, bodyOffsetX)
-            : center.x + laneCenter * laneUnit;
-        const rectWidth = Math.max(4, bodyLaneWidth * laneUnit);
-        const top = Math.min(far.y, near.y);
-        const bottom = Math.max(far.y, near.y);
-        return {
-            x: centerX - rectWidth / 2,
-            y: top,
-            width: rectWidth,
-            height: Math.max(8, bottom - top),
-        };
-    }
-    /** @internal */
-    getPlayerScreenLaneUnit() {
-        return this.roadNearWidth * 0.38;
+        return this.collisionSystem.getDebugCollisionRectFromVisual(visualRect, visual, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY);
     }
     /** @internal */
-    getBodyOffsetXInScreenPixels(visual, scale, bodyOffsetX) {
-        if (!Number.isFinite(bodyOffsetX) || bodyOffsetX === 0)
-            return 0;
-        try {
-            const surface = this.resolveVisualSurface(visual);
-            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
-            const visualWidth = Math.max(1, surface.width * safeScale);
-            return Math.max(-visualWidth * 0.5, Math.min(visualWidth * 0.5, bodyOffsetX * safeScale));
-        }
-        catch {
-            return 0;
-        }
+    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) {
-        try {
-            const surface = this.resolveVisualSurface(visual);
-            return {
-                width: Math.max(1, surface.width * AUTO_BODY_WIDTH_VISUAL_RATIO),
-                length: Math.max(1, surface.height),
-            };
-        }
-        catch {
-            return null;
-        }
-    }
-    /** @internal */
-    getBodyLaneWidthFromVisual(_visual, scale, bodyWidth) {
-        if (!Number.isFinite(bodyWidth) || bodyWidth <= 0)
-            return 0;
-        try {
-            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
-            const projectedWidth = Math.max(1, bodyWidth * safeScale);
-            const laneUnit = Math.max(1, this.getPlayerScreenLaneUnit());
-            return Math.max(0.01, projectedWidth / laneUnit);
-        }
-        catch {
-            return 0;
-        }
-    }
-    /** @internal */
-    getBodyLengthFromVisual(_visual, scale, bodyLength) {
-        if (!Number.isFinite(bodyLength) || bodyLength <= 0)
-            return 0;
-        try {
-            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
-            const projectedLength = Math.max(1, bodyLength * safeScale);
-            return Math.max(1, projectedLength * AUTO_BODY_LENGTH_PER_PIXEL);
-        }
-        catch {
-            return 0;
-        }
-    }
-    /** @internal */
-    getBodyLaneOffsetFromVisual(visual, scale, bodyOffsetX) {
-        if (!Number.isFinite(bodyOffsetX) || bodyOffsetX === 0)
-            return 0;
-        try {
-            const surface = this.resolveVisualSurface(visual);
-            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
-            const projectedOffsetX = bodyOffsetX * safeScale;
-            const laneUnit = Math.max(1, this.getPlayerScreenLaneUnit());
-            const visualWidth = Math.max(1, surface.width * safeScale);
-            const clampedOffsetX = Math.max(-visualWidth * 0.5, Math.min(visualWidth * 0.5, projectedOffsetX));
-            return clampedOffsetX / laneUnit;
-        }
-        catch {
-            return 0;
-        }
-    }
-    /** @internal */
-    getBodyDistanceOffsetFromVisual(visual, scale, bodyOffsetY) {
-        if (!Number.isFinite(bodyOffsetY) || bodyOffsetY === 0)
-            return 0;
-        try {
-            const surface = this.resolveVisualSurface(visual);
-            const safeScale = Number.isFinite(scale) ? Math.max(0, scale) : 1;
-            const projectedOffsetY = bodyOffsetY * safeScale;
-            const visualHeight = Math.max(1, surface.height * safeScale);
-            const clampedOffsetY = Math.max(-visualHeight * 0.5, Math.min(visualHeight * 0.5, projectedOffsetY));
-            return clampedOffsetY * AUTO_BODY_LENGTH_PER_PIXEL;
-        }
-        catch {
-            return 0;
-        }
+    resolveAutoBodyFromVisual(visual, scale) {
+        return this.collisionSystem.resolveAutoBodyFromVisual(visual, scale);
     }
     /** @internal */
     resolveCollisionBodyMetrics(visual, scale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY) {
-        return {
-            laneWidth: this.getBodyLaneWidthFromVisual(visual, scale, bodyWidth),
-            distanceLength: this.getBodyLengthFromVisual(visual, scale, bodyLength),
-            laneOffset: this.getBodyLaneOffsetFromVisual(visual, scale, bodyOffsetX),
-            distanceOffset: this.getBodyDistanceOffsetFromVisual(visual, scale, bodyOffsetY),
-        };
+        return this.collisionSystem.resolveCollisionBodyMetrics(visual, scale, bodyWidth, bodyLength, bodyOffsetX, bodyOffsetY);
     }
     /** @internal */
     getBodyDistanceCenterFromAnchor(anchorDistance, bodyLength, bodyDistanceOffset) {
-        return anchorDistance + bodyLength * 0.5 - bodyDistanceOffset;
+        return this.collisionSystem.getBodyDistanceCenterFromAnchor(anchorDistance, bodyLength, bodyDistanceOffset);
     }
     /** @internal */
     refreshAutoPlayerBodyFromVisual() {
@@ -1352,7 +1176,8 @@ export class ArcadeRacerEngine {
     }
     /** @internal */
     getPlayerScreenX() {
-        return this.width / 2 + this.playerLaneState * this.getPlayerScreenLaneUnit();
+        return (this.width / 2 +
+            this.playerLaneState * this.collisionSystem.getPlayerScreenLaneUnit());
     }
     /** @internal */
     resolveVisualSurface(visual) {
@@ -1361,8 +1186,8 @@ export class ArcadeRacerEngine {
             if (!image) {
                 throw new Error(`MinimoJS Arcade Racer: Image '${visual.key}' is not loaded.`);
             }
-            const naturalWidth = Math.max(1, image.naturalWidth || image.width);
-            const naturalHeight = Math.max(1, image.naturalHeight || image.height);
+            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,
@@ -1454,11 +1279,11 @@ export class ArcadeRacerEngine {
     }
     /** @internal */
     projectRoadPoint(current, ahead, width, height) {
-        if (this.pathPrimitives.length > 0) {
+        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.sampleTrack(this.distanceState + distanceAhead);
+            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);
@@ -1481,7 +1306,7 @@ export class ArcadeRacerEngine {
         const distanceAhead = Math.max(0, Math.min(ahead, this.drawDistance));
         const t = 1 - distanceAhead / this.drawDistance;
         const p = t * t;
-        const sample = this.sampleTrack(this.distanceState + distanceAhead);
+        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);
@@ -1494,62 +1319,12 @@ export class ArcadeRacerEngine {
         return { x, y, roadWidth, scale, t: p };
     }
     /** @internal */
-    getMinimapPathPoints() {
-        if (this.pathPrimitives.length > 0) {
-            const pathPoints = this.getPathTrackPoints();
-            let visiblePathPoints = pathPoints;
-            if (pathPoints.length >= 3) {
-                const first = pathPoints[0];
-                const last = pathPoints[pathPoints.length - 1];
-                const previous = pathPoints[pathPoints.length - 2];
-                const lastMatchesStart = Math.hypot(last.x - first.x, last.y - first.y) <= 0.001;
-                const previousStillOpen = Math.hypot(previous.x - first.x, previous.y - first.y) > 0.001;
-                if (lastMatchesStart && previousStillOpen) {
-                    visiblePathPoints = pathPoints.slice(0, -1);
-                }
-            }
-            return visiblePathPoints.map((point) => ({
-                x: point.x,
-                y: point.y,
-                distance: point.distance,
-            }));
-        }
-        if (this.minimapPathCacheVersion === this.trackVersion) {
-            return this.minimapPathCache;
-        }
-        if (this.totalTrackLength <= 0) {
-            this.minimapPathCache = [];
-            this.minimapPathCacheVersion = this.trackVersion;
-            return this.minimapPathCache;
-        }
-        const sampleCount = Math.max(64, Math.round(this.totalTrackLength / 80));
-        const points = [{ x: 0, y: 0, distance: 0 }];
-        let x = 0;
-        let y = 0;
-        let heading = -Math.PI / 2;
-        let previousDistance = 0;
-        const turnFactor = 0.0034;
-        for (let i = 1; i <= sampleCount; i++) {
-            const distance = (i / sampleCount) * this.totalTrackLength;
-            const delta = distance - previousDistance;
-            const sample = this.sampleTrack(previousDistance + delta * 0.5);
-            heading += sample.curve * delta * turnFactor;
-            x += Math.cos(heading) * delta;
-            y += Math.sin(heading) * delta;
-            points.push({ x, y, distance });
-            previousDistance = distance;
-        }
-        this.minimapPathCache = points;
-        this.minimapPathCacheVersion = this.trackVersion;
-        return this.minimapPathCache;
-    }
-    /** @internal */
     sampleMinimapPoint(points, distance) {
-        if (points.length === 0 || this.totalTrackLength <= 0) {
+        if (points.length === 0 || this.trackSystem.totalTrackLength <= 0) {
             return { x: 0, y: 0, distance: 0 };
         }
-        const wrapped = this.wrapDistance(distance);
-        const sampleT = (wrapped / this.totalTrackLength) * (points.length - 1);
+        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;
@@ -1562,361 +1337,40 @@ export class ArcadeRacerEngine {
         };
     }
     /** @internal */
-    resolvePlayerTrafficCollisions() {
-        const nextCollisionIds = new Set();
-        const playerBodyWidth = this.playerResolvedBodyState.laneWidth;
-        const playerBodyLength = this.playerResolvedBodyState.distanceLength;
-        const playerLaneCenter = this.playerLaneState + this.playerResolvedBodyState.laneOffset;
-        const playerBodyDistanceOffset = this.playerResolvedBodyState.distanceOffset;
-        const playerDistanceCenter = this.distanceState +
-            this.getBodyDistanceCenterFromAnchor(this.playerProjectionAheadDistance, playerBodyLength, playerBodyDistanceOffset);
-        for (const traffic of this.trafficState) {
-            const trafficBodyWidth = traffic.resolvedBody.laneWidth;
-            const trafficBodyLength = traffic.resolvedBody.distanceLength;
-            const trafficBodyDistanceOffset = traffic.resolvedBody.distanceOffset;
-            const trafficLaneCenter = traffic.lane + traffic.resolvedBody.laneOffset;
-            const trafficDistanceCenter = this.getBodyDistanceCenterFromAnchor(traffic.distance, trafficBodyLength, trafficBodyDistanceOffset);
-            const distanceDelta = trafficDistanceCenter - playerDistanceCenter;
-            const laneDelta = trafficLaneCenter - playerLaneCenter;
-            const hitDepth = Math.abs(distanceDelta) <
-                (playerBodyLength + trafficBodyLength) * 0.5;
-            const hitLane = Math.abs(laneDelta) <
-                (playerBodyWidth + trafficBodyWidth) * 0.5;
-            if (!hitDepth || !hitLane)
-                continue;
-            nextCollisionIds.add(traffic.id);
-            if (this.activeCollisionIds.has(traffic.id)) {
-                continue;
-            }
-            const collision = {
-                trafficId: traffic.id,
-                distanceDelta,
-                laneDelta,
-                trafficDistance: traffic.distance,
-                trafficLane: traffic.lane,
-            };
-            for (const handler of this.collisionHandlers) {
-                handler(collision);
-            }
-        }
-        this.activeCollisionIds = nextCollisionIds;
-    }
-    /** @internal */
-    getLoopingAheadDistance(targetDistance) {
-        if (this.totalTrackLength <= 0) {
-            return targetDistance - this.distanceState;
-        }
-        const currentWrapped = this.wrapDistance(this.distanceState);
-        const targetWrapped = this.wrapDistance(targetDistance);
-        let delta = targetWrapped - currentWrapped;
-        if (delta < 0) {
-            delta += this.totalTrackLength;
-        }
-        return delta;
-    }
-    /** @internal */
-    sampleTrack(distance) {
-        if (this.pathPrimitives.length > 0) {
-            return this.samplePathTrack(distance);
-        }
-        if (this.segments.length === 0 || this.totalTrackLength <= 0) {
-            return {
-                lateralOffset: 0,
-                elevation: 0,
-                curve: 0,
-                hill: 0,
-                worldX: 0,
-                worldY: 0,
-                heading: 0,
-            };
-        }
-        const raw = this.sampleRawTrack(distance);
-        const metrics = this.getTrackClosureMetrics();
-        const wrapped = this.wrapDistance(distance);
-        const t = this.totalTrackLength <= 0 ? 0 : Math.max(0, Math.min(1, wrapped / this.totalTrackLength));
-        return {
-            lateralOffset: raw.lateralOffset - metrics.offsetDrift * t,
-            elevation: raw.elevation - metrics.elevationDrift * t,
-            curve: raw.curve - metrics.curveDrift * t,
-            hill: raw.hill - metrics.hillDrift * t,
-            worldX: raw.lateralOffset - metrics.offsetDrift * t,
-            worldY: wrapped,
-            heading: 0,
-        };
-    }
-    /** @internal */
-    sampleRawTrack(distance) {
-        if (this.segments.length === 0 || this.totalTrackLength <= 0) {
-            return {
-                lateralOffset: 0,
-                elevation: 0,
-                curve: 0,
-                hill: 0,
-                worldX: 0,
-                worldY: 0,
-                heading: 0,
-            };
-        }
-        const wrapped = this.wrapDistance(distance);
-        let segment = this.segments[this.segments.length - 1];
-        for (const candidate of this.segments) {
-            if (wrapped >= candidate.start && wrapped <= candidate.end) {
-                segment = candidate;
-                break;
+    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;
             }
         }
-        const local = wrapped - segment.start;
-        const t = segment.length <= 0 ? 0 : Math.max(0, Math.min(1, local / segment.length));
-        const eased = this.easeInOut(t);
-        const curve = this.lerp(segment.curveFrom, segment.curveTo, eased);
-        const hill = this.lerp(segment.hillFrom, segment.hillTo, eased);
-        const localOffset = ((segment.curveFrom + curve) * 0.5) * local;
-        const localElevation = ((segment.hillFrom + hill) * 0.5) * local;
-        return {
-            lateralOffset: segment.offsetAtStart + localOffset,
-            elevation: segment.elevationAtStart + localElevation,
-            curve,
-            hill,
-            worldX: segment.offsetAtStart + localOffset,
-            worldY: wrapped,
-            heading: 0,
-        };
+        return this.roadDrawerState;
     }
     /** @internal */
-    samplePathTrack(distance) {
-        const points = this.getPathTrackPoints();
-        if (points.length === 0 || this.totalTrackLength <= 0) {
-            return {
-                lateralOffset: 0,
-                elevation: 0,
-                curve: 0,
-                hill: 0,
-                worldX: 0,
-                worldY: 0,
-                heading: 0,
-            };
+    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;
         }
-        const wrapped = this.wrapDistance(distance);
-        for (let i = 1; i < points.length; i++) {
-            const from = points[i - 1];
-            const to = points[i];
-            if (wrapped > to.distance)
-                continue;
-            const span = Math.max(0.0001, to.distance - from.distance);
-            const t = Math.max(0, Math.min(1, (wrapped - from.distance) / span));
-            const heading = this.lerp(from.heading, to.heading, t);
-            const elevation = this.lerp(from.elevation, to.elevation, t);
-            const curve = this.lerp(from.curve, to.curve, t);
-            const hill = this.lerp(from.hill, to.hill, t);
-            const worldX = this.lerp(from.x, to.x, t);
-            const worldY = this.lerp(from.y, to.y, t);
-            return {
-                lateralOffset: worldX,
-                elevation,
-                curve,
-                hill,
-                worldX,
-                worldY,
-                heading,
-            };
+        if (from < to) {
+            return wrappedTrackDistance >= from && wrappedTrackDistance < to;
         }
-        const last = points[points.length - 1];
-        return {
-            lateralOffset: last.x,
-            elevation: last.elevation,
-            curve: last.curve,
-            hill: last.hill,
-            worldX: last.x,
-            worldY: last.y,
-            heading: last.heading,
-        };
-    }
-    /** @internal */
-    getPathTrackPoints() {
-        if (this.pathPointsCacheVersion === this.trackVersion) {
-            return this.pathPointsCache;
-        }
-        const points = [];
-        if (this.pathPrimitives.length === 0) {
-            this.pathPointsCache = points;
-            this.pathPointsCacheVersion = this.trackVersion;
-            return points;
-        }
-        let x = 0;
-        let y = 0;
-        let heading = 0;
-        let distance = 0;
-        let elevation = 0;
-        points.push({
-            distance,
-            x,
-            y,
-            heading,
-            elevation,
-            curve: 0,
-            hill: 0,
-        });
-        for (const primitive of this.pathPrimitives) {
-            if (primitive.type === "line") {
-                const steps = Math.max(1, Math.ceil(primitive.length / 40));
-                const stepLength = primitive.length / steps;
-                const stepElevation = primitive.elevationDelta / steps;
-                const hill = primitive.elevationDelta / Math.max(1, primitive.length);
-                for (let i = 0; i < steps; i++) {
-                    x += Math.cos(heading) * stepLength;
-                    y += Math.sin(heading) * stepLength;
-                    distance += stepLength;
-                    elevation += stepElevation;
-                    points.push({
-                        distance,
-                        x,
-                        y,
-                        heading,
-                        elevation,
-                        curve: 0,
-                        hill,
-                    });
-                }
-                continue;
-            }
-            const arcLength = Math.abs(primitive.radius * primitive.angleRad);
-            const steps = Math.max(4, Math.ceil(arcLength / 32));
-            const stepAngle = primitive.angleRad / steps;
-            const stepLength = arcLength / steps;
-            const curve = primitive.angleRad >= 0 ? 1 / primitive.radius : -1 / primitive.radius;
-            const stepElevation = primitive.elevationDelta / steps;
-            const hill = primitive.elevationDelta / Math.max(1, arcLength);
-            for (let i = 0; i < steps; i++) {
-                const headingMid = heading + stepAngle * 0.5;
-                x += Math.cos(headingMid) * stepLength;
-                y += Math.sin(headingMid) * stepLength;
-                heading += stepAngle;
-                distance += stepLength;
-                elevation += stepElevation;
-                points.push({
-                    distance,
-                    x,
-                    y,
-                    heading,
-                    elevation,
-                    curve,
-                    hill,
-                });
-            }
-        }
-        const start = points[0];
-        const end = points[points.length - 1];
-        if (Math.hypot(end.x - start.x, end.y - start.y) > 0.001) {
-            points.push({
-                distance: this.totalTrackLength,
-                x: start.x,
-                y: start.y,
-                heading: start.heading + Math.PI * 2,
-                elevation: start.elevation,
-                curve: 0,
-                hill: 0,
-            });
-        }
-        else {
-            end.x = start.x;
-            end.y = start.y;
-            end.heading = start.heading + Math.PI * 2;
-            end.elevation = start.elevation;
-        }
-        this.pathPointsCache = points;
-        this.pathPointsCacheVersion = this.trackVersion;
-        return this.pathPointsCache;
-    }
-    /** @internal */
-    getTrackClosureMetrics() {
-        if (this.trackClosureMetrics &&
-            this.trackClosureMetricsVersion === this.trackVersion) {
-            return this.trackClosureMetrics;
-        }
-        const start = this.sampleRawTrack(0);
-        const end = this.sampleRawTrack(Math.max(0, this.totalTrackLength - 0.0001));
-        this.trackClosureMetrics = {
-            startCurve: start.curve,
-            startHill: start.hill,
-            startOffset: start.lateralOffset,
-            startElevation: start.elevation,
-            endCurve: end.curve,
-            endHill: end.hill,
-            endOffset: end.lateralOffset,
-            endElevation: end.elevation,
-            curveDrift: end.curve - start.curve,
-            hillDrift: end.hill - start.hill,
-            offsetDrift: end.lateralOffset - start.lateralOffset,
-            elevationDrift: end.elevation - start.elevation,
-        };
-        this.trackClosureMetricsVersion = this.trackVersion;
-        return this.trackClosureMetrics;
+        return wrappedTrackDistance >= from || wrappedTrackDistance < to;
     }
     /** @internal */
-    addTrackSegment(config) {
-        const length = Math.max(1, Number.isFinite(config.length) ? config.length : 1);
-        const previous = this.segments[this.segments.length - 1];
-        const curveFrom = previous ? previous.curveTo : 0;
-        const hillFrom = previous ? previous.hillTo : 0;
-        const curveTo = Number.isFinite(config.curve)
-            ? config.curve
-            : curveFrom;
-        const hillTo = Number.isFinite(config.hill)
-            ? config.hill
-            : hillFrom;
-        const start = previous ? previous.end : 0;
-        const offsetAtStart = previous
-            ? previous.offsetAtStart +
-                ((previous.curveFrom + previous.curveTo) * 0.5) * previous.length
-            : 0;
-        const elevationAtStart = previous
-            ? previous.elevationAtStart +
-                ((previous.hillFrom + previous.hillTo) * 0.5) * previous.length
-            : 0;
-        this.segments.push({
-            length,
-            curveFrom,
-            curveTo,
-            hillFrom,
-            hillTo,
-            start,
-            end: start + length,
-            offsetAtStart,
-            elevationAtStart,
-        });
-        this.totalTrackLength = this.segments[this.segments.length - 1].end;
-        this.trackVersion += 1;
-    }
-    /** @internal */
-    resetTrack() {
-        this.segments = [];
-        this.pathPrimitives = [];
-        this.pathPointsCache = [];
-        this.pathPointsCacheVersion = -1;
-        this.totalTrackLength = 0;
-        this.trackExplicitlyClosed = false;
-        this.trackVersion += 1;
-        this.trackClosureMetrics = null;
-        this.trackClosureMetricsVersion = -1;
-    }
-    /** @internal */
-    wrapDistance(distance) {
-        if (this.totalTrackLength <= 0)
-            return 0;
-        const wrapped = distance % this.totalTrackLength;
-        return wrapped < 0 ? wrapped + this.totalTrackLength : wrapped;
+    resolvePlayerTrafficCollisions() {
+        this.collisionSystem.resolvePlayerTrafficCollisions();
     }
     /** @internal */
     makeId(prefix) {
         return `${prefix}-${this.nextId++}`;
     }
     /** @internal */
-    clampRoadLane(value) {
-        if (!Number.isFinite(value))
-            return 0;
-        return Math.max(-1, Math.min(1, value));
-    }
-    /** @internal */
     clampPlayerLane(value) {
         if (!Number.isFinite(value))
             return 0;
@@ -1939,12 +1393,62 @@ export class ArcadeRacerEngine {
         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;
@@ -1996,6 +1500,9 @@ export class ArcadeRacerEngine {
             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 */
@@ -2103,48 +1610,451 @@ export class ArcadeRacerEngine {
     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 */
-    fillRoundedRect(ctx, x, y, width, height, radius) {
-        const r = Math.max(0, Math.min(radius, width / 2, height / 2));
-        ctx.beginPath();
-        ctx.moveTo(x + r, y);
-        ctx.arcTo(x + width, y, x + width, y + height, r);
-        ctx.arcTo(x + width, y + height, x, y + height, r);
-        ctx.arcTo(x, y + height, x, y, r);
-        ctx.arcTo(x, y, x + width, y, r);
-        ctx.closePath();
-        ctx.fill();
+    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 */
-    strokeRoundedRect(ctx, x, y, width, height, radius) {
-        const r = Math.max(0, Math.min(radius, width / 2, height / 2));
-        ctx.beginPath();
-        ctx.moveTo(x + r, y);
-        ctx.arcTo(x + width, y, x + width, y + height, r);
-        ctx.arcTo(x + width, y + height, x, y + height, r);
-        ctx.arcTo(x, y + height, x, y, r);
-        ctx.arcTo(x, y, x + width, y, r);
-        ctx.closePath();
-        ctx.stroke();
+    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 */
-    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();
+    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;
+        });
     }
 }
-class ArcadeRacerRoadSprite extends DrawSprite {
-    constructor(width, height, redrawFrame) {
-        super(width, height);
-        this.redrawFrame = redrawFrame;
+/**
+ * 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;
     }
-    redraw(ctx) {
-        this.redrawFrame(ctx, this.width, this.height);
+    /**
+     * 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);
     }
 }