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

package/dist/minimo-arcaderacer.d.ts

@@ -2,11 +2,16 @@ import { DrawSprite, Game } from "./minimo.js";
 /**
  * Visual source used by the arcade racer module.
  *
- * Sources can be either emoji-based or backed by a preloaded MinimoJS image key.
+ * A source is backed either by a preloaded MinimoJS image key, which is the
+ * first option to reach for, or by an emoji glyph.
  */
-export type ArcadeRacerVisualSource = ArcadeRacerEmojiSource | ArcadeRacerImageSource;
+export type ArcadeRacerVisualSource = ArcadeRacerImageSource | ArcadeRacerEmojiSource;
 /**
  * Emoji-backed visual source.
+ *
+ * An emoji is rasterized with the player's own system emoji font, so it renders
+ * differently across platforms. Prefer {@link ArcadeRacerImageSource} when the
+ * look matters; this remains the quickest way to get a vehicle on the road.
  */
 export interface ArcadeRacerEmojiSource {
     type: "emoji";
@@ -58,12 +63,26 @@ export interface ArcadeRacerPerformanceOptions {
     sixtyToZeroSeconds: number;
     /** Target top speed used by mph helpers. Default: `145`. */
     topSpeedMph: number;
-    /** Steering multiplier when the car is nearly stopped. Default: `0.18`. */
+    /**
+     * Steering authority when the car is nearly stopped.
+     * Higher values make low-speed lane changes build more quickly.
+     * Default: `0.9`.
+     */
     steeringLowSpeedScale: number;
-    /** Steering multiplier near top speed. Default: `0.78`. */
+    /**
+     * Steering authority near top speed.
+     * Lower values make fast lane changes slower and heavier.
+     * Default: `0.34`.
+     */
     steeringHighSpeedScale: number;
-    /** Curve shaping used for steering interpolation. Default: `1.5`. */
+    /** Curve shaping used for steering authority interpolation. Default: `1.8`. */
     steeringSpeedCurvePower: number;
+    /**
+     * Damping applied to lateral velocity.
+     * Higher values make the car settle more quickly after steering input.
+     * Default: `6.8`.
+     */
+    lateralDamping: number;
 }
 /**
  * Horizon layer settings for heading-based background cards.
@@ -170,6 +189,26 @@ export interface ArcadeRacerGroundFillOptions {
      */
     color?: string | null;
 }
+/**
+ * Optional grouping of zero-based lane indices by travel direction.
+ *
+ * Lane indices are counted from left to right across the rendered road. For
+ * example, with `laneCount: 4`, the lanes are indexed as `0, 1, 2, 3`.
+ *
+ * If only one direction is provided, the other direction automatically uses the
+ * remaining lanes. When omitted entirely, direction-aware helpers fall back to
+ * all lanes.
+ */
+export interface ArcadeRacerLaneDirectionsOptions {
+    /**
+     * Lanes reserved for vehicles moving in the same direction as the player.
+     */
+    same?: number[];
+    /**
+     * Lanes reserved for vehicles moving toward the player.
+     */
+    oncoming?: number[];
+}
 /**
  * Optional elevation settings for path-based track primitives.
  */
@@ -241,6 +280,341 @@ export interface ArcadeRacerDebugOptions {
     /** Debug stroke width in screen pixels. Default: `2`. */
     lineWidth: number;
 }
+/**
+ * Projected road point used by road drawers.
+ */
+export interface ArcadeRacerRoadProjection {
+    /** Horizontal screen-space center of the projected road slice. */
+    x: number;
+    /** Vertical screen-space anchor of the projected road slice. */
+    y: number;
+    /** Projected road width in screen pixels at this depth. */
+    roadWidth: number;
+    /** Perspective scale relative to the near road width. */
+    scale: number;
+    /** Normalized depth factor used internally by the projection in range `[0, 1]`. */
+    t: number;
+}
+/**
+ * Exact projected road and shoulder bounds at a specific world distance.
+ */
+export interface ArcadeRacerRoadSurfaceProjection {
+    /** Exact wrapped track distance used for this projection. */
+    trackDistance: number;
+    /** Exact unwrapped world distance used for this projection. */
+    absoluteDistance: number;
+    /** Projected road center and width at this distance. */
+    projection: ArcadeRacerRoadProjection;
+    /** Shoulder width in screen pixels at this distance. */
+    shoulderWidth: number;
+    /** Left paved-road boundary at this distance. */
+    leftRoadX: number;
+    /** Right paved-road boundary at this distance. */
+    rightRoadX: number;
+    /** Left outer shoulder boundary at this distance. */
+    leftOuterX: number;
+    /** Right outer shoulder boundary at this distance. */
+    rightOuterX: number;
+}
+/**
+ * Track sample data exposed to road drawers.
+ */
+export interface ArcadeRacerRoadDrawSample {
+    /** Lateral road offset in track space at this sample. */
+    lateralOffset: number;
+    /** Elevation value used by hills and dips at this sample. */
+    elevation: number;
+    /** Instantaneous curvature value at this sample. */
+    curve: number;
+    /** Instantaneous hill gradient helper value at this sample. */
+    hill: number;
+    /** World-space X value for path-based tracks. */
+    worldX: number;
+    /** World-space Y / forward travel value for path-based tracks. */
+    worldY: number;
+    /** Heading in radians of the road center path at this sample. */
+    heading: number;
+}
+/**
+ * Single projected lane-marker slice inside a road strip.
+ */
+export interface ArcadeRacerRoadLaneMarkerStrip {
+    /** Marker center X at the far edge of the strip. */
+    farX: number;
+    /** Marker center X at the near edge of the strip. */
+    nearX: number;
+    /** Marker width at the far edge of the strip. */
+    farWidth: number;
+    /** Marker width at the near edge of the strip. */
+    nearWidth: number;
+}
+/**
+ * Single projected road strip ready to be painted by a road drawer.
+ */
+export interface ArcadeRacerRoadDrawStrip {
+    /** Zero-based visible strip index within the current frame. */
+    index: number;
+    /** Stable stripe counter used for banding and continuity across frames. */
+    stripeIndex: number;
+    /** Absolute unwrapped distance represented by the middle of this strip. */
+    absoluteDistance: number;
+    /** Wrapped track distance represented by the middle of this strip. */
+    trackDistance: number;
+    /** Absolute distance at the far edge of the strip. */
+    farDistance: number;
+    /** Absolute distance at the near edge of the strip. */
+    nearDistance: number;
+    /** Projected road state at the far edge of the strip. */
+    farProjection: ArcadeRacerRoadProjection;
+    /** Projected road state at the near edge of the strip. */
+    nearProjection: ArcadeRacerRoadProjection;
+    /** Track sample used at the far edge of the strip. */
+    farSample: ArcadeRacerRoadDrawSample;
+    /** Track sample used at the near edge of the strip. */
+    nearSample: ArcadeRacerRoadDrawSample;
+    /** Top scanline of the strip in screen space. */
+    farY: number;
+    /** Bottom scanline of the strip in screen space. */
+    nearY: number;
+    /** Alternating band index used by the default grass drawer. */
+    grassBandIndex: number;
+    /** Alternating band index used by the default shoulder drawer. */
+    shoulderBandIndex: number;
+    /** Alternating band index used by the default road drawer. */
+    roadBandIndex: number;
+    /** Shoulder width at the far edge of the strip. */
+    shoulderFar: number;
+    /** Shoulder width at the near edge of the strip. */
+    shoulderNear: number;
+    /** Far-left outer shoulder boundary. */
+    leftOuterFar: number;
+    /** Far-right outer shoulder boundary. */
+    rightOuterFar: number;
+    /** Near-left outer shoulder boundary. */
+    leftOuterNear: number;
+    /** Near-right outer shoulder boundary. */
+    rightOuterNear: number;
+    /** Far-left paved-road boundary. */
+    leftRoadFar: number;
+    /** Far-right paved-road boundary. */
+    rightRoadFar: number;
+    /** Near-left paved-road boundary. */
+    leftRoadNear: number;
+    /** Near-right paved-road boundary. */
+    rightRoadNear: number;
+    /** Precomputed lane-marker quads available for this strip. */
+    laneMarkers: ArcadeRacerRoadLaneMarkerStrip[];
+}
+/**
+ * Frame-level road drawing data resolved by the engine.
+ */
+export interface ArcadeRacerRoadDrawFrame {
+    /** Render surface width in pixels. */
+    width: number;
+    /** Render surface height in pixels. */
+    height: number;
+    /** Screen-space horizon line used by the road renderer. */
+    horizonY: number;
+    /** Current absolute player distance. */
+    distanceState: number;
+    /** Forward draw distance used to build the visible strips. */
+    drawDistance: number;
+    /** Configured number of visible strips in the frame. */
+    stripCount: number;
+    /** Number of lane bands visible on the road. */
+    laneCount: number;
+    /** Track sample at the player's current position. */
+    currentSample: ArcadeRacerRoadDrawSample;
+    /** Active theme at draw time. */
+    theme: ArcadeRacerTheme;
+    /** Ordered visible road strips for this frame. */
+    strips: readonly ArcadeRacerRoadDrawStrip[];
+    /**
+     * Projects exact road and shoulder bounds for an arbitrary absolute distance.
+     *
+     * Use this when a custom drawer needs stable world-anchored props that
+     * should not depend on which visible strip they happen to fall inside.
+     */
+    projectDistance: (absoluteDistance: number) => ArcadeRacerRoadSurfaceProjection;
+}
+/**
+ * Strategy used by the racer to paint projected road strips.
+ */
+export interface ArcadeRacerRoadDrawer {
+    /**
+     * Paints a single projected strip of road geometry.
+     *
+     * The engine resolves strip geometry before calling this method.
+     */
+    drawStrip(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /**
+     * Optional pass that runs after all strips have been painted.
+     *
+     * The default drawer uses this for the lower-screen vignette.
+     */
+    drawOverlay?(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame): void;
+}
+/**
+ * Distance range that swaps the active road drawer for matching strips.
+ *
+ * Ranges are evaluated in wrapped track distance. When multiple ranges match
+ * the same strip, the most recently added range wins.
+ */
+export interface ArcadeRacerRoadDrawerRange {
+    /** Inclusive wrapped start distance of the styled span. */
+    from: number;
+    /** Exclusive wrapped end distance of the styled span. */
+    to: number;
+    /** Drawer used for strips whose wrapped distance falls inside the span. */
+    drawer: ArcadeRacerRoadDrawer;
+}
+/**
+ * Side of the off-road grass area.
+ */
+export type ArcadeRacerRoadSide = "left" | "right";
+/**
+ * Construction options for {@link CropRoadDrawer}.
+ *
+ * Use tighter `columnSpacing` values for dense crops and larger values for
+ * sparser layouts. `columnSpacingJitter` and height ratios add small natural
+ * variation without changing the overall planting pattern.
+ */
+export interface ArcadeRacerCropRoadDrawerOptions {
+    /** Game instance used to resolve image textures registered through MinimoJS. */
+    game: Game;
+    /** Visual used to paint each crop instance. */
+    visual: ArcadeRacerVisualSource;
+    /** Roadside grass bands that should receive crop instances. Default: both sides. */
+    sides?: readonly ArcadeRacerRoadSide[];
+    /**
+     * Whether the drawer should repaint the grass band under the crops.
+     *
+     * Enable this when the crop section needs a custom soil color instead of the
+     * road theme's default grass colors.
+     * Default: `false`.
+     */
+    paintGround?: boolean;
+    /** Fill color used for the crop soil when `paintGround` is enabled. Default: `#7b5a32`. */
+    groundColor?: string;
+    /** Distance between crop rows along the road, in world units. Default: `82`. */
+    rowSpacing?: number;
+    /**
+     * Base spacing between crop columns across the grass, in world units.
+     *
+     * Lower values create dense plantings; higher values create sparse ones.
+     * Default: `34`.
+     */
+    columnSpacing?: number;
+    /**
+     * Additional random variation applied to spacing between neighboring plants,
+     * in world units. Default: `0`.
+     */
+    columnSpacingJitter?: number;
+    /** Starting offset from the road shoulder before the first plant is placed. Default: `42`. */
+    columnInset?: number;
+    /**
+     * Alternate-row lateral shift, in world units.
+     *
+     * Defaults to half of `columnSpacing`.
+     */
+    rowShift?: number;
+    /** Minimum random height multiplier applied to crop instances. Default: `0.85`. */
+    minHeightRatio?: number;
+    /** Maximum random height multiplier applied to crop instances. Default: `1.35`. */
+    maxHeightRatio?: number;
+    /**
+     * Base crop height relative to projected road width.
+     *
+     * The final height is `roadWidth * baseHeightScale * randomHeightRatio`.
+     * Default: `0.12`.
+     */
+    baseHeightScale?: number;
+    /** Minimum on-screen draw height in pixels. Default: `16`. */
+    minDrawHeight?: number;
+    /** Alpha applied to each crop sprite. Default: `0.9`. */
+    alpha?: number;
+    /** Whether a dark base shadow should be painted under each crop. Default: `true`. */
+    drawBaseShadow?: boolean;
+    /** Fill color used by crop base shadows. Default: `rgba(68, 38, 18, 1)`. */
+    baseShadowColor?: string;
+    /** Alpha applied to crop base shadows. Default: `0.28`. */
+    baseShadowAlpha?: number;
+    /** Horizontal shadow radius relative to crop width. Default: `0.3`. */
+    baseShadowRadiusScale?: number;
+    /** Vertical shadow radius relative to horizontal shadow radius. Default: `0.42`. */
+    baseShadowHeightScale?: number;
+}
+/**
+ * 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 declare class DefaultArcadeRacerRoadDrawer implements ArcadeRacerRoadDrawer {
+    /** Paints the full default strip in four stages: ground, shoulders, road, and lane markers. */
+    drawStrip(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /** Draws the default post-road vignette overlay. */
+    drawOverlay(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame): void;
+    /** Draws the off-road ground area for one strip. */
+    protected drawGround(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /** Draws the shoulder band for one strip. */
+    protected drawShoulders(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /** Draws the paved road surface for one strip. */
+    protected drawRoadSurface(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /** Draws all lane markers for one strip when enabled. */
+    protected drawLaneMarkers(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /** Returns the fill color used for the ground area of a strip. */
+    protected getGrassColor(frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): string;
+    /** Returns the fill color used for the shoulder area of a strip. */
+    protected getShoulderColor(frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): string;
+    /** Returns the fill color used for the paved road of a strip. */
+    protected getRoadColor(frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): string;
+    /** Returns the color used for lane-marker quads. */
+    protected getLaneMarkerColor(frame: ArcadeRacerRoadDrawFrame, _strip: ArcadeRacerRoadDrawStrip): string;
+    /** Controls whether lane markers should be painted for the strip. */
+    protected shouldDrawLaneMarkers(_frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): boolean;
+    /** Helper that fills a four-point polygon, useful for custom subclasses. */
+    protected drawQuad(ctx: CanvasRenderingContext2D, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, x4: number, y4: number, color: string): void;
+}
+/**
+ * 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 declare class CompositeRoadDrawer implements ArcadeRacerRoadDrawer {
+    /** Ordered child drawers that will be invoked for every strip and overlay pass. */
+    readonly drawers: ArcadeRacerRoadDrawer[];
+    /**
+     * Creates a composite drawer from the provided children.
+     *
+     * The order matters: earlier drawers paint first and later drawers paint on top.
+     */
+    constructor(drawers?: ArcadeRacerRoadDrawer[]);
+    /** Paints the strip by forwarding the call to each child drawer in order. */
+    drawStrip(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+    /** Forwards the optional overlay pass to each child drawer that implements it. */
+    drawOverlay(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame): void;
+    /** Appends another child drawer to the composite. */
+    addDrawer(drawer: ArcadeRacerRoadDrawer): void;
+    /** Removes all child drawers from the composite. */
+    clearDrawers(): void;
+}
+/**
+ * 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 declare class CropRoadDrawer extends DefaultArcadeRacerRoadDrawer {
+    /** Creates a crop drawer with configurable density, spacing, and height variation. */
+    constructor(options: ArcadeRacerCropRoadDrawerOptions);
+    /** Paints crop ground and crop instances for the configured roadside bands. */
+    drawStrip(ctx: CanvasRenderingContext2D, frame: ArcadeRacerRoadDrawFrame, strip: ArcadeRacerRoadDrawStrip): void;
+}
 /**
  * Construction options for {@link ArcadeRacerEngine}.
  */
@@ -265,8 +639,18 @@ export interface ArcadeRacerEngineOptions {
     roadFarWidth?: number;
     /** Render layer used by the internal road sprite. Default: `0`. */
     layer?: number;
-    /** Number of visible driving lanes. Default: `3`. */
+    /**
+     * Number of visible driving lanes used by the road renderer.
+     * Default: `3`.
+     */
     laneCount?: number;
+    /**
+     * Optional directional grouping for zero-based lane indices.
+     *
+     * Use this when you want the engine to know which lanes belong to same-
+     * direction traffic versus oncoming traffic.
+     */
+    laneDirections?: ArcadeRacerLaneDirectionsOptions;
     /** Initial player lane position in range `[-1, 1]`. Default: `0`. */
     playerLane?: number;
     /**
@@ -336,6 +720,24 @@ export interface ArcadeRacerEngineOptions {
      * Default: `3.2`.
      */
     offRoadBrakeRate?: number;
+    /**
+     * Multiplier applied to acceleration while the player is off-road.
+     *
+     * `1` keeps full acceleration response. Lower values make the car feel like
+     * it is struggling for traction on grass or dirt.
+     *
+     * Default: `0.28`.
+     */
+    offRoadAccelerationScale?: number;
+    /**
+     * Blend used to soften the vertical displacement of real collision bodies on hills.
+     *
+     * `0` keeps the projected body where road geometry places it. `1` anchors it
+     * fully to the visible sprite bottom. `0.5` is a balanced midpoint.
+     *
+     * Default: `0.5`.
+     */
+    realCollisionVerticalShiftBlend?: number;
     /** Optional partial performance / handling override for the player car. */
     performance?: Partial<ArcadeRacerPerformanceOptions>;
     /** Optional partial heading-based horizon override. */
@@ -346,6 +748,10 @@ export interface ArcadeRacerEngineOptions {
     debug?: boolean | Partial<ArcadeRacerDebugOptions>;
     /** Optional partial theme override. */
     theme?: Partial<ArcadeRacerTheme>;
+    /** Optional global road drawer. Defaults to {@link DefaultArcadeRacerRoadDrawer}. */
+    roadDrawer?: ArcadeRacerRoadDrawer;
+    /** Optional per-range road drawer overrides evaluated in wrapped track distance. */
+    roadDrawerRanges?: ArcadeRacerRoadDrawerRange[];
 }
 /**
  * Billboard configuration.
@@ -362,6 +768,21 @@ export interface ArcadeRacerBillboardConfig {
     side?: "left" | "right";
     /** Additional roadside offset in logical pixels. Default: `48`. */
     offset?: number;
+    /**
+     * Horizontal anchor inside the billboard image in normalized `[0, 1]` space.
+     *
+     * `0` means the left edge of the image, `0.5` the center, and `1` the right
+     * edge. This is useful for wide structures that start on one roadside and
+     * extend inward across the road, such as bridges, arches, poles, or
+     * inward-leaning fences. Default: `0.5`.
+     */
+    anchorX?: number;
+    /**
+     * Vertical anchor inside the billboard image in normalized `[0, 1]` space.
+     *
+     * `0` means the top edge, `0.5` the middle, and `1` the bottom. Default: `1`.
+     */
+    anchorY?: number;
     /** Optional multiplier applied to the projected scale. Default: `1`. */
     baseScale?: number;
     /** Number of copies to create. Default: `1`. */
@@ -409,12 +830,200 @@ export interface ArcadeRacerTrafficConfig {
  * Collision information reported when the player hits a traffic vehicle.
  */
 export interface ArcadeRacerTrafficCollision {
+    /** Id of the traffic vehicle involved in the collision. */
     trafficId: string;
+    /** Forward/back distance difference between player and traffic body centers. */
     distanceDelta: number;
+    /** Lateral lane-space difference between player and traffic body centers. */
     laneDelta: number;
+    /** Absolute traffic distance at the moment of impact. */
     trafficDistance: number;
+    /** Traffic lane-space position at the moment of impact. */
     trafficLane: number;
 }
+/**
+ * Weighted traffic profile used by {@link ArcadeRacerTrafficManager}.
+ */
+export interface ArcadeRacerTrafficProfile {
+    /** Vehicle visual to spawn for this profile. */
+    visual: ArcadeRacerVisualSource;
+    /** Relative selection weight. Default: `1`. */
+    weight?: number;
+    /**
+     * Travel direction for the spawned vehicle.
+     * `"same"` keeps traffic moving with the player, `"oncoming"` sends it toward
+     * the player, and `"either"` lets the manager decide using `oncomingChance`.
+     * Default: `"same"`.
+     */
+    direction?: "same" | "oncoming" | "either";
+    /** Optional fixed lane for this profile. */
+    lane?: number;
+    /** Optional allowed lane list for this profile. Falls back to manager lanes. */
+    lanes?: number[];
+    /** Fixed traffic speed in mph. Overrides the min/max range when provided. */
+    speedMph?: number;
+    /** Minimum traffic speed in mph when using a random speed range. */
+    speedMphMin?: number;
+    /** Maximum traffic speed in mph when using a random speed range. */
+    speedMphMax?: number;
+    /** Fixed scale multiplier for the spawned vehicle. */
+    baseScale?: number;
+    /** Minimum random scale multiplier. */
+    baseScaleMin?: number;
+    /** Maximum random scale multiplier. */
+    baseScaleMax?: number;
+    /** Collision body width in local visual pixels before scale is applied. */
+    bodyWidth?: number;
+    /** Collision body length in local visual pixels before scale is applied. */
+    bodyLength?: number;
+    /** Horizontal collision body offset in local visual pixels. */
+    bodyOffsetX?: number;
+    /** Vertical collision body offset in local visual pixels. */
+    bodyOffsetY?: number;
+}
+/**
+ * Spawn event emitted by {@link ArcadeRacerTrafficManager}.
+ */
+export interface ArcadeRacerTrafficSpawnEvent {
+    /** Generated traffic id assigned by the engine. */
+    id: string;
+    /** Lane-space position used for the spawned vehicle. */
+    lane: number;
+    /** Absolute spawn distance used for the new vehicle. */
+    distance: number;
+    /** Spawn speed in engine world units per second. */
+    speed: number;
+    /** Spawn speed converted to mph for convenience. */
+    speedMph: number;
+    /** Whether the vehicle is traveling toward the player. */
+    oncoming: boolean;
+    /** Profile that produced this spawn. */
+    profile: ArcadeRacerTrafficProfile;
+}
+/**
+ * Despawn event emitted by {@link ArcadeRacerTrafficManager}.
+ */
+export interface ArcadeRacerTrafficDespawnEvent {
+    /** Id of the traffic vehicle being removed. */
+    id: string;
+    /** Why the manager decided to remove the vehicle. */
+    reason: "behind" | "ahead" | "cleared";
+    /** Profile that originally produced the vehicle. */
+    profile: ArcadeRacerTrafficProfile;
+}
+/**
+ * Configuration for {@link ArcadeRacerTrafficManager}.
+ */
+export interface ArcadeRacerTrafficManagerOptions {
+    /** Traffic profiles that may be spawned by the manager. */
+    profiles: ArcadeRacerTrafficProfile[];
+    /** Whether spawning is active. Default: `true`. */
+    enabled?: boolean;
+    /** Maximum number of manager-owned vehicles alive at once. Default: `14`. */
+    maxActive?: number;
+    /** Initial number of vehicles to populate immediately. Default: `6`. */
+    initialActive?: number;
+    /** Time in seconds between spawn attempts. Default: `0.45`. */
+    spawnInterval?: number;
+    /** Minimum distance ahead of the player where a vehicle may spawn. Default: `900`. */
+    spawnAheadMin?: number;
+    /** Maximum distance ahead of the player where a vehicle may spawn. Default: `2200`. */
+    spawnAheadMax?: number;
+    /** Minimum distance behind the player where a faster same-direction vehicle may spawn. Default: `320`. */
+    spawnBehindMin?: number;
+    /** Maximum distance behind the player where a faster same-direction vehicle may spawn. Default: `760`. */
+    spawnBehindMax?: number;
+    /** Distance behind the player at which a managed vehicle is despawned. Default: `260`. */
+    despawnBehindDistance?: number;
+    /** Distance ahead of the player at which a managed vehicle is despawned. Default: `2800`. */
+    despawnAheadDistance?: number;
+    /** Minimum longitudinal gap between same-lane vehicles. Default: `220`. */
+    minGapDistance?: number;
+    /**
+     * Default lane choices used when a profile does not define its own lanes.
+     *
+     * When omitted, the manager uses the engine lane layout. If the engine was
+     * configured with `laneDirections`, same-direction profiles use those lanes
+     * and oncoming profiles use the opposing lanes automatically.
+     */
+    lanePositions?: number[];
+    /** Chance used when a profile has `direction: "either"`. Default: `0.35`. */
+    oncomingChance?: number;
+    /**
+     * Whether same-direction vehicles that are faster than the player should be
+     * allowed to enter from behind instead of popping into view ahead.
+     * Default: `true`.
+     */
+    fasterTrafficSpawnsBehind?: boolean;
+    /** Optional callback fired after a traffic vehicle is spawned. */
+    onSpawn?: (event: ArcadeRacerTrafficSpawnEvent) => void;
+    /** Optional callback fired after a manager-owned vehicle is removed. */
+    onDespawn?: (event: ArcadeRacerTrafficDespawnEvent) => void;
+}
+/**
+ * Fixed competitor description used by {@link ArcadeRacerRaceManager}.
+ */
+export interface ArcadeRacerRaceCompetitorProfile {
+    /** Display name used in standings and race UI. */
+    name: string;
+    /** Vehicle visual used for this competitor. */
+    visual: ArcadeRacerVisualSource;
+    /** Preferred lane for the competitor. */
+    lane?: number;
+    /** Candidate lanes used when `lane` is omitted. */
+    lanes?: number[];
+    /** Initial race distance relative to the start line. Default: `0`. */
+    startDistance?: number;
+    /** Fixed race pace for this competitor in mph. */
+    speedMph?: number;
+    /** Minimum random race pace in mph. */
+    speedMphMin?: number;
+    /** Maximum random race pace in mph. */
+    speedMphMax?: number;
+    /** Fixed scale multiplier for the competitor vehicle. */
+    baseScale?: number;
+    /** Collision body width in local visual pixels before scale is applied. */
+    bodyWidth?: number;
+    /** Collision body length in local visual pixels before scale is applied. */
+    bodyLength?: number;
+    /** Horizontal collision body offset in local visual pixels. */
+    bodyOffsetX?: number;
+    /** Vertical collision body offset in local visual pixels. */
+    bodyOffsetY?: number;
+}
+/**
+ * Single race standing entry returned by {@link ArcadeRacerRaceManager.getStandings}.
+ */
+export interface ArcadeRacerRaceStanding {
+    /** Internal competitor id, or `"player"` for the player row. */
+    id: string;
+    /** Display name shown in standings. */
+    name: string;
+    /** Distance progressed toward the finish line. */
+    distance: number;
+    /** Whether this competitor has already crossed the finish line. */
+    finished: boolean;
+    /** Whether this row corresponds to the player. */
+    isPlayer: boolean;
+    /** 1-based race position after sorting by progress. */
+    position: number;
+}
+/**
+ * Configuration for {@link ArcadeRacerRaceManager}.
+ */
+export interface ArcadeRacerRaceManagerOptions {
+    /** Competitors that participate in the race alongside the player. */
+    competitors: ArcadeRacerRaceCompetitorProfile[];
+    /** Race finish distance measured from the start line. */
+    finishDistance: number;
+    /**
+     * Default lane choices used when a competitor does not define lanes.
+     *
+     * When omitted, the manager uses the engine same-direction lane layout when
+     * available, and otherwise falls back to all engine lanes.
+     */
+    lanePositions?: number[];
+}
 /**
  * Main public API for the MinimoJS arcade racing module.
  *
@@ -457,7 +1066,8 @@ export interface ArcadeRacerTrafficCollision {
  *   speed: 120,
  * });
  *
- * racer.build();
+ * const roadSprite = racer.build();
+ * game.add(roadSprite);
  *
  * game.onUpdate = (dt) => {
  *   racer.accelerateToMph(110, dt);
@@ -478,8 +1088,9 @@ export interface ArcadeRacerTrafficCollision {
  *    {@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,
@@ -498,6 +1109,10 @@ export interface ArcadeRacerTrafficCollision {
  * - `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.
@@ -516,18 +1131,46 @@ export interface ArcadeRacerTrafficCollision {
  * - 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 declare class ArcadeRacerEngine {
-    constructor(game: Game, options?: ArcadeRacerEngineOptions);
+    /**
+     * Number of visible driving lanes configured for the road.
+     */
+    get laneCount(): number;
+    /**
+     * 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: number): number;
+    /**
+     * 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" | "same" | "oncoming"): number[];
     /**
      * Current player speed in world units per second.
      */
@@ -582,7 +1225,10 @@ export declare class ArcadeRacerEngine {
      */
     arcRight(radius: number, degrees: number, options?: ArcadeRacerTrackPrimitiveOptions): void;
     /**
-     * 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(): DrawSprite;
     /**
@@ -633,6 +1279,22 @@ export declare class ArcadeRacerEngine {
      * Adds a traffic vehicle directly and returns its generated id.
      */
     addTraffic(visual: ArcadeRacerVisualSource, config: ArcadeRacerTrafficConfig): string;
+    /**
+     * Removes a traffic vehicle by id.
+     *
+     * Returns `true` when a vehicle was found and removed.
+     */
+    removeTrafficById(id: string): boolean;
+    /**
+     * 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: string, config: Partial<ArcadeRacerTrafficConfig> & {
+        alpha?: number;
+        loop?: boolean;
+    }): boolean;
     /**
      * Clears all configured traffic vehicles.
      */
@@ -641,6 +1303,16 @@ export declare class ArcadeRacerEngine {
      * Clears all configured billboards.
      */
     clearBillboards(): void;
+    /**
+     * Adds a wrapped track-distance range that swaps the active road drawer.
+     *
+     * When multiple ranges overlap, the most recently added range wins.
+     */
+    addRoadDrawerRange(range: ArcadeRacerRoadDrawerRange): void;
+    /**
+     * Clears all per-range road drawer overrides.
+     */
+    clearRoadDrawerRanges(): void;
     /**
      * Adds a heading-based horizon marker directly and returns its generated id.
      */
@@ -658,3 +1330,102 @@ export declare class ArcadeRacerEngine {
      */
     clearBackgroundLayers(): void;
 }
+/**
+ * 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 declare class ArcadeRacerTrafficManager {
+    constructor(racer: ArcadeRacerEngine, options: ArcadeRacerTrafficManagerOptions);
+    /**
+     * 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(): boolean;
+    set enabled(value: boolean);
+    /**
+     * Number of currently active manager-owned traffic vehicles.
+     */
+    get activeCount(): number;
+    /**
+     * Updates manager-owned traffic bookkeeping and performs spawn/despawn work.
+     */
+    update(dt: number): void;
+    /**
+     * Immediately spawns up to `count` new traffic vehicles if valid slots exist.
+     */
+    spawnNow(count?: number): number;
+    /**
+     * Removes all manager-owned vehicles from the racer.
+     */
+    clear(): void;
+}
+/**
+ * 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 declare class ArcadeRacerRaceManager {
+    constructor(racer: ArcadeRacerEngine, options: ArcadeRacerRaceManagerOptions);
+    /**
+     * Number of AI competitors currently managed by the race.
+     */
+    get competitorCount(): number;
+    /**
+     * Advances competitor progress and synchronizes their traffic vehicles.
+     */
+    update(dt: number): void;
+    /**
+     * Returns race standings including the player.
+     */
+    getStandings(): ArcadeRacerRaceStanding[];
+    /**
+     * Returns the player's current race position.
+     */
+    getPlayerPosition(): number;
+    /**
+     * Removes all race competitors from the racer.
+     */
+    clear(): void;
+}