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

package/dist/minimo-arcaderacer.d.ts

@@ -0,0 +1,1431 @@
+import { DrawSprite, Game } from "./minimo.js";
+/**
+ * Visual source used by the arcade racer module.
+ *
+ * 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 = 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";
+    /** Emoji or symbol to rasterize into a reusable offscreen surface. */
+    value: string;
+    /** Logical base size in pixels before perspective scaling. Default: `64`. */
+    size?: number;
+    /** Optional fill color for monochrome glyphs. Default: `#ffffff`. */
+    color?: string;
+}
+/**
+ * Image-backed visual source.
+ */
+export interface ArcadeRacerImageSource {
+    type: "image";
+    /** Preloaded MinimoJS image key. */
+    key: string;
+    /** Optional logical draw width before perspective scaling. */
+    width?: number;
+    /** Optional logical draw height before perspective scaling. */
+    height?: number;
+}
+/**
+ * Theme colors used by the road renderer.
+ */
+export interface ArcadeRacerTheme {
+    skyTop: string;
+    skyBottom: string;
+    mountainBack: string;
+    mountainFront: string;
+    grassA: string;
+    grassB: string;
+    roadA: string;
+    roadB: string;
+    shoulderA: string;
+    shoulderB: string;
+    laneMarker: string;
+    horizonGlow: string;
+    sunInner: string;
+    sunOuter: string;
+}
+/**
+ * Vehicle performance and handling settings for the player car.
+ */
+export interface ArcadeRacerPerformanceOptions {
+    /** Approximate time required to accelerate from 0 to 60 mph. Default: `6.2`. */
+    zeroToSixtySeconds: number;
+    /** Approximate time required to brake from 60 to 0 mph. Default: `3.6`. */
+    sixtyToZeroSeconds: number;
+    /** Target top speed used by mph helpers. Default: `145`. */
+    topSpeedMph: number;
+    /**
+     * Steering authority when the car is nearly stopped.
+     * Higher values make low-speed lane changes build more quickly.
+     * Default: `0.9`.
+     */
+    steeringLowSpeedScale: number;
+    /**
+     * Steering authority near top speed.
+     * Lower values make fast lane changes slower and heavier.
+     * Default: `0.34`.
+     */
+    steeringHighSpeedScale: number;
+    /** 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.
+ */
+export interface ArcadeRacerHorizonOptions {
+    /**
+     * Default angular range in degrees over which a marker fades in/out.
+     * Default: `120`.
+     */
+    influenceAngle: number;
+    /**
+     * Horizontal parallax amount expressed as a fraction of the screen width for
+     * a 90-degree angular offset. Default: `0.26`.
+     */
+    parallaxFactor: number;
+    /**
+     * Vertical offset in pixels from the horizon line to the marker baseline.
+     * Default: `26`.
+     */
+    baseYOffset: number;
+    /**
+     * Maximum number of markers to draw at once after angular sorting.
+     * Default: `3`.
+     */
+    maxVisibleMarkers: number;
+    /**
+     * Multiplier used to convert road curvature and speed into heading change.
+     * Default: `0.24`.
+     */
+    headingResponse: number;
+}
+/**
+ * Configuration for a single angular horizon marker.
+ */
+export interface ArcadeRacerHorizonMarkerConfig {
+    /** Angle in degrees in range `[0, 360)`. */
+    angle: number;
+    /** Optional overall scale multiplier. Default: `1`. */
+    baseScale?: number;
+    /** Optional opacity multiplier in range `[0, 1]`. Default: `1`. */
+    alpha?: number;
+    /** Optional vertical offset from the horizon baseline in pixels. Default: `0`. */
+    yOffset?: number;
+    /**
+     * Optional per-marker angular blend range in degrees.
+     * Defaults to the global horizon `influenceAngle`.
+     */
+    influenceAngle?: number;
+    /**
+     * Optional per-marker parallax amount as a fraction of the screen width for
+     * a 90-degree angular offset. Defaults to the global horizon `parallaxFactor`.
+     */
+    parallaxFactor?: number;
+}
+/**
+ * Configuration for a parallax background image layer.
+ */
+export interface ArcadeRacerBackgroundLayerConfig {
+    /**
+     * Top Y position in screen space. Default: `0`.
+     */
+    y?: number;
+    /**
+     * Base X offset in pixels before parallax is applied. Default: `0`.
+     */
+    xOffset?: number;
+    /**
+     * Overall scale multiplier applied to the visual. Default: `1`.
+     */
+    baseScale?: number;
+    /**
+     * Opacity multiplier in range `[0, 1]`. Default: `1`.
+     */
+    alpha?: number;
+    /**
+     * Whether the layer should repeat horizontally. Default: `true`.
+     */
+    repeat?: boolean;
+    /**
+     * Extra horizontal spacing between repeated tiles in pixels. Default: `0`.
+     */
+    spacing?: number;
+    /**
+     * Horizontal drift in pixels per world unit traveled. Default: `0`.
+     */
+    parallaxDistance?: number;
+    /**
+     * Horizontal parallax amount expressed as a fraction of the screen width for
+     * a 90-degree heading delta. Default: `0`.
+     */
+    parallaxHeading?: number;
+}
+/**
+ * Base ground fill rendered from the horizon downward before the road strips.
+ */
+export interface ArcadeRacerGroundFillOptions {
+    /**
+     * Whether the base ground fill is rendered.
+     * Default: `true`.
+     */
+    enabled: boolean;
+    /**
+     * Optional override color. When omitted, the engine uses `theme.grassA`.
+     */
+    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.
+ */
+export interface ArcadeRacerTrackPrimitiveOptions {
+    /**
+     * Total elevation delta applied over the primitive.
+     * Positive values climb, negative values descend.
+     * Default: `0`.
+     */
+    elevationDelta?: number;
+}
+/**
+ * Overlay minimap settings for the looping track.
+ */
+export interface ArcadeRacerMinimapOptions {
+    /** Whether the minimap is visible. Default: `false`. */
+    visible: boolean;
+    /** Top-left X position in screen-space pixels. Default: `width - 164`. */
+    x: number;
+    /** Top-left Y position in screen-space pixels. Default: `16`. */
+    y: number;
+    /** Minimap width in pixels. Default: `148`. */
+    width: number;
+    /** Minimap height in pixels. Default: `148`. */
+    height: number;
+    /** Inner padding in pixels. Default: `10`. */
+    padding: number;
+    /** Overlay opacity. Default: `1`. */
+    alpha: number;
+    /** Background fill color. Default: `rgba(6, 10, 18, 0.72)`. */
+    backgroundColor: string;
+    /** Border color. Default: `rgba(126, 224, 255, 0.45)`. */
+    borderColor: string;
+    /** Border width in pixels. Default: `2`. */
+    borderWidth: number;
+    /** Track stroke color. Default: `rgba(245, 248, 255, 0.9)`. */
+    trackColor: string;
+    /** Track stroke width in pixels. Default: `3`. */
+    trackLineWidth: number;
+    /** Player marker fill color. Default: `#ff6a6e`. */
+    playerColor: string;
+    /** Player marker outline color. Default: `#fff7dd`. */
+    playerStrokeColor: string;
+    /** Player marker radius in pixels. Default: `4`. */
+    playerRadius: number;
+}
+/**
+ * Debug overlay settings for inspecting projected car bounds and collisions.
+ */
+export interface ArcadeRacerDebugOptions {
+    /** Whether the debug overlay is rendered. Default: `false`. */
+    enabled: boolean;
+    /** Draws the actual screen-space image/emoji rectangle. Default: `true`. */
+    visualBounds: boolean;
+    /** Draws the approximate road-space collision body rectangle. Default: `true`. */
+    collisionBounds: boolean;
+    /** Draws the real gameplay collision body projected from road space. Default: `true`. */
+    realCollisionBounds: boolean;
+    /** Stroke color for the rendered visual rectangle. Default: `rgba(80, 220, 255, 0.9)`. */
+    visualBoundsColor: string;
+    /** Stroke color for the player collision body. Default: `rgba(255, 238, 88, 0.95)`. */
+    playerCollisionBoundsColor: string;
+    /** Stroke color for traffic collision bodies. Default: `rgba(255, 82, 82, 0.95)`. */
+    trafficCollisionBoundsColor: string;
+    /** Stroke color for the player's real gameplay collision body. Default: `rgba(255, 170, 0, 0.95)`. */
+    playerRealCollisionBoundsColor: string;
+    /** Stroke color for traffic real gameplay collision bodies. Default: `rgba(255, 0, 170, 0.95)`. */
+    trafficRealCollisionBoundsColor: string;
+    /** 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}.
+ */
+export interface ArcadeRacerEngineOptions {
+    /** Center X position of the internal road render surface. Default: `game.width / 2`. */
+    x?: number;
+    /** Center Y position of the internal road render surface. Default: `game.height / 2`. */
+    y?: number;
+    /** Width of the road render surface. Default: `game.width`. */
+    width?: number;
+    /** Height of the road render surface. Default: `game.height`. */
+    height?: number;
+    /** Screen-space horizon line in pixels from the top. Default: `Math.round(height * 0.27)`. */
+    horizonY?: number;
+    /** Number of road strips used to build the pseudo-3D road. Default: `78`. */
+    stripCount?: number;
+    /** How far ahead the road renderer samples the track, in world units. Default: `1200`. */
+    drawDistance?: number;
+    /** Logical road width at the bottom of the screen. Default: `width * 0.98`. */
+    roadNearWidth?: number;
+    /** Logical road width near the horizon. Default: `width * 0.1`. */
+    roadFarWidth?: number;
+    /** Render layer used by the internal road sprite. Default: `0`. */
+    layer?: number;
+    /**
+     * 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;
+    /**
+     * Maximum lateral lane offset allowed for the player.
+     * Values above `1` let the car travel fully through the grass/off-road area.
+     * Default: `1.8`.
+     */
+    playerLaneLimit?: number;
+    /** Initial player speed in world units per second. Default: `0`. */
+    speed?: number;
+    /** Player screen-space Y position. Default: `height * 0.86`. */
+    playerScreenY?: number;
+    /** Visual scale multiplier applied to the player render. Default: `1`. */
+    playerBaseScale?: number;
+    /** Player visual source. Default: `🏎️`. */
+    playerVisual?: ArcadeRacerVisualSource;
+    /** Player collision width in local player-visual pixels before scale is applied. Defaults to a value derived from the player visual size. */
+    playerBodyWidth?: number;
+    /** Player collision length in local player-visual pixels before scale is applied. Defaults to a value derived from the player visual size. */
+    playerBodyLength?: number;
+    /**
+     * Horizontal body offset in local player-visual pixels before scale is applied.
+     * Positive values move the collision body to the right.
+     * Default: `0`.
+     */
+    playerBodyOffsetX?: number;
+    /**
+     * Vertical body offset in local player-visual pixels before scale is applied.
+     * Positive values move the collision body downward in the sprite and forward
+     * along the road-facing collision footprint.
+     * Default: `0`.
+     */
+    playerBodyOffsetY?: number;
+    /** Steering speed in lane units per second. Default: `1.85`. */
+    steeringRate?: number;
+    /** Curve-to-screen multiplier. Default: `0.9`. */
+    curveScale?: number;
+    /**
+     * Elevation-to-screen multiplier used by hills and dips.
+     * Default: `0.22`.
+     */
+    hillScale?: number;
+    /**
+     * How strongly road curvature pushes the player sideways when not correcting.
+     * Higher values make curves require more steering input. Default: `0.46`.
+     */
+    playerRoadInfluence?: number;
+    /** Optional base ground fill override. */
+    groundFill?: Partial<ArcadeRacerGroundFillOptions>;
+    /**
+     * Lane threshold beyond which the player is considered off-road.
+     * Default: `0.82`.
+     */
+    offRoadThreshold?: number;
+    /**
+     * Whether the engine should automatically slow the player when off-road.
+     * Default: `false`.
+     */
+    offRoadSlowdownEnabled?: boolean;
+    /**
+     * Target speed used by the automatic off-road slowdown.
+     * Default: `18`.
+     */
+    offRoadTargetSpeedMph?: number;
+    /**
+     * Brake rate used by the automatic off-road slowdown.
+     * 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. */
+    horizon?: Partial<ArcadeRacerHorizonOptions>;
+    /** Optional partial minimap overlay override. */
+    minimap?: Partial<ArcadeRacerMinimapOptions>;
+    /** Optional debug overlay for car visual and collision bounds. */
+    debug?: boolean | Partial<ArcadeRacerDebugOptions>;
+    /** Optional partial theme override. */
+    theme?: Partial<ArcadeRacerTheme>;
+    /** 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.
+ */
+export interface ArcadeRacerBillboardConfig {
+    /** Distance along the looping track where the object should appear. */
+    distance: number;
+    /**
+     * Relative lane position in range `[-1, 1]` when the billboard should sit over the road.
+     * Leave undefined to anchor it outside the road shoulder instead.
+     */
+    lane?: number;
+    /** Which roadside to use when `lane` is not provided. Default: `"right"`. */
+    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`. */
+    repeat?: number;
+    /** Distance between repeated copies. Default: `240`. */
+    spacing?: number;
+    /** Opacity multiplier in range `[0, 1]`. Default: `1`. */
+    alpha?: number;
+}
+/**
+ * Traffic car configuration.
+ */
+export interface ArcadeRacerTrafficConfig {
+    /** Absolute world distance of the traffic vehicle. */
+    distance: number;
+    /** Relative lane position in range `[-1, 1]`. */
+    lane: number;
+    /** Traffic speed in world units per second. Default: `140`. */
+    speed?: number;
+    /** Optional multiplier applied to the projected scale. Default: `1`. */
+    baseScale?: number;
+    /** Collision width in local traffic-visual pixels before scale is applied. Defaults to a value derived from the traffic visual size. */
+    bodyWidth?: number;
+    /** Collision length in local traffic-visual pixels before scale is applied. Defaults to a value derived from the traffic visual size. */
+    bodyLength?: number;
+    /**
+     * Horizontal body offset in local traffic-visual pixels before scale is applied.
+     * Positive values move the collision body to the right.
+     * Default: `0`.
+     */
+    bodyOffsetX?: number;
+    /**
+     * Vertical body offset in local traffic-visual pixels before scale is applied.
+     * Positive values move the collision body downward in the sprite and forward
+     * along the road-facing collision footprint.
+     * Default: `0`.
+     */
+    bodyOffsetY?: number;
+    /** Whether the car should be recycled one lap ahead when it falls behind. Default: `true`. */
+    loop?: boolean;
+    /** Opacity multiplier in range `[0, 1]`. Default: `1`. */
+    alpha?: number;
+}
+/**
+ * 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.
+ *
+ * `ArcadeRacerEngine` is a pseudo-3D road renderer and gameplay helper built
+ * on top of MinimoJS. It is designed for highway racers, Out Run style arcade
+ * games, looping circuits, and simple traffic-heavy road scenes where the
+ * player remains screen-anchored while the road, traffic, roadside objects, and
+ * heading-based background move around them.
+ *
+ * Instead of building the scene out of many ordinary MinimoJS sprites, the
+ * engine owns one internal {@link DrawSprite} and composes most of the frame
+ * inside that surface. That design keeps the API compact while still supporting:
+ *
+ * - straight roads and curved roads using path primitives
+ * - optional elevation changes on straights and arcs
+ * - roadside billboards and traffic vehicles
+ * - heading-based horizon markers
+ * - layered image backgrounds with parallax
+ * - minimap rendering
+ * - off-road detection and optional automatic slowdown
+ * - player speed control in engine units or mph
+ *
+ * Typical usage follows this flow:
+ *
+ * ```ts
+ * const racer = new ArcadeRacerEngine(game, {
+ *   width: game.width,
+ *   height: game.height,
+ *   horizonY: 180,
+ * });
+ *
+ * racer.clearTrack();
+ * racer.straight(2600, { elevationDelta: 40 });
+ * racer.arcRight(1200, 24);
+ * racer.straight(1800);
+ *
+ * racer.addTraffic({ type: "image", key: "truck" }, {
+ *   lane: 0.4,
+ *   distance: 800,
+ *   speed: 120,
+ * });
+ *
+ * const roadSprite = racer.build();
+ * game.add(roadSprite);
+ *
+ * game.onUpdate = (dt) => {
+ *   racer.accelerateToMph(110, dt);
+ *   if (game.isKeyDown("ArrowLeft")) racer.steerLeft(dt);
+ *   if (game.isKeyDown("ArrowRight")) racer.steerRight(dt);
+ *   racer.update(dt);
+ * };
+ * ```
+ *
+ * Conceptually, the engine is split into five parts:
+ *
+ * 1. Track definition:
+ *    Use {@link clearTrack}, {@link straight}, {@link arcLeft}, and
+ *    {@link arcRight} to build the center path of the road. These methods are
+ *    the primary geometry API.
+ * 2. Player state:
+ *    The player is controlled through properties like {@link speedMph},
+ *    {@link playerLane}, and helper methods such as {@link steerLeft},
+ *    {@link steerRight}, {@link accelerateToMph}, and {@link brakeToMph}.
+ * 3. Scene objects:
+ *    Use {@link addTraffic} and {@link addBillboard} to place vehicles,
+ *    roadside decoration, and wide anchored structures such as bridges,
+ *    arches, or fences that extend into the road.
+ * 4. Background and atmosphere:
+ *    Configure atmosphere in the constructor, then use
+ *    {@link addBackgroundLayer} and {@link addHorizonMarker} to place skies,
+ *    mountains, distant landmarks, and horizon visuals.
+ * 5. Presentation and HUD helpers:
+ *    Use constructor options such as `theme`, `minimap`, `horizon`,
+ *    `performance`, and `debug` to set the look and HUD overlays up front.
+ *
+ * Important behavioral notes:
+ *
+ * - The player is screen-anchored. They do not move through MinimoJS world
+ *   coordinates like a regular sprite; instead, the engine projects the road
+ *   and scene around the player.
+ * - `distance` keeps increasing even on looping tracks. The renderer wraps
+ *   internally when sampling road geometry.
+ * - `playerLane` is the main lateral control value. Around `-1..1` the player
+ *   is on the paved road; beyond that they enter shoulders and off-road space
+ *   depending on `playerLaneLimit`.
+ * - `laneCount` controls how many visible lane bands the road renders. When
+ *   you also provide `laneDirections`, the engine can tell which zero-based
+ *   lanes belong to same-direction versus oncoming traffic, and helpers such as
+ *   {@link getLanePositions} can return those subsets for you.
+ * - Traffic collisions are resolved in road space, not by 2D sprite overlap.
+ * - If no image background layers are configured, the engine falls back to a
+ *   built-in procedural sky and mountain backdrop.
+ *
+ * Visual source model:
+ *
+ * Most methods that draw objects accept {@link ArcadeRacerVisualSource}. That
+ * means you can mix emoji-backed visuals and preloaded MinimoJS images in the
+ * same scene. This is especially useful for quick prototypes that later evolve
+ * into art-driven scenes without changing the rest of the engine API.
+ *
+ * Choosing the right APIs:
+ *
+ * - Use {@link speed} / {@link accelerateTo} when working in engine units.
+ * - Use {@link speedMph} / {@link accelerateToMph} for player-facing gameplay.
+ * - Use {@link addBackgroundLayer} for wide, repeating, parallax image bands.
+ * - Use {@link addHorizonMarker} for directional landmarks that appear only at
+ *   certain headings.
+ * - Prefer {@link ArcadeRacerTrafficManager} as the first solution for dynamic
+ *   gameplay traffic. It is the recommended default before building a custom
+ *   spawning system with direct {@link addTraffic} and {@link removeTrafficById}
+ *   calls.
+ * - Use constructor options such as `playerBodyWidth`, `playerBodyLength`,
+ *   `playerBodyOffsetX`, and `playerBodyOffsetY` when you need to tune
+ *   collisions in local image pixels without changing the player artwork.
+ * - Use {@link getLanePosition} and {@link getLanePositions} when you want to
+ *   place traffic, race competitors, or billboards directly on lane centers
+ *   instead of guessing lane-space numbers by hand.
+ * - Use constructor `debug` options when you need to visualize car image
+ *   bounds and collision bodies while tuning traffic hits.
+ * - Use `roadDrawer`, {@link addRoadDrawerRange}, and
+ *   {@link DefaultArcadeRacerRoadDrawer} when you want to restyle the road
+ *   globally or switch to custom road painting on specific track spans.
+ *
+ * This class is the canonical public surface of the module. Its JSDoc is
+ * intended to be consumed directly by AI agents and tooling that generate code
+ * against `minimo-arcaderacer.js`.
+ */
+export declare class ArcadeRacerEngine {
+    /**
+     * 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.
+     */
+    get speed(): number;
+    set speed(value: number);
+    /**
+     * Current player speed in miles per hour.
+     */
+    get speedMph(): number;
+    set speedMph(value: number);
+    /**
+     * Current heading in degrees in range `[0, 360)`.
+     */
+    get headingDegrees(): number;
+    set headingDegrees(value: number);
+    /**
+     * Total forward distance traveled by the player.
+     */
+    get distance(): number;
+    set distance(value: number);
+    /**
+     * Player lane position.
+     */
+    get playerLane(): number;
+    set playerLane(value: number);
+    /**
+     * Whether the player is currently outside the configured road threshold.
+     */
+    get isOffRoad(): boolean;
+    /**
+     * Normalized amount of how far the player has gone off-road in range `[0, 1]`.
+     */
+    get offRoadAmount(): number;
+    /**
+     * Removes all existing track primitives and legacy segments.
+     */
+    clearTrack(): void;
+    /**
+     * Appends a straight path section.
+     */
+    straight(length: number, options?: ArcadeRacerTrackPrimitiveOptions): void;
+    /**
+     * Replaces the track with a naturally closed rounded rectangle circuit.
+     */
+    roundedRect(width: number, height: number, cornerRadius: number): void;
+    /**
+     * Appends a path arc that bends left by the given number of degrees.
+     */
+    arcLeft(radius: number, degrees: number, options?: ArcadeRacerTrackPrimitiveOptions): void;
+    /**
+     * Appends a path arc that bends right by the given number of degrees.
+     */
+    arcRight(radius: number, degrees: number, options?: ArcadeRacerTrackPrimitiveOptions): void;
+    /**
+     * 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;
+    /**
+     * Returns the internal road render sprite, or `null` if `build()` has not run yet.
+     */
+    getRoadSprite(): DrawSprite | null;
+    /**
+     * Advances the racer simulation and redraws on the next MinimoJS render pass.
+     */
+    update(dt: number): void;
+    /**
+     * Moves the player left using the configured steering rate.
+     */
+    steerLeft(dt: number, strength?: number): void;
+    /**
+     * Moves the player right using the configured steering rate.
+     */
+    steerRight(dt: number, strength?: number): void;
+    /**
+     * Smoothly accelerates the player speed toward a target value.
+     */
+    accelerateTo(targetSpeed: number, dt: number, rate?: number): void;
+    /**
+     * Smoothly brakes the player speed toward a target value.
+     */
+    brakeTo(targetSpeed: number, dt: number, rate?: number): void;
+    /**
+     * Smoothly accelerates the player toward a target speed expressed in mph.
+     */
+    accelerateToMph(targetMph: number, dt: number, rate?: number): void;
+    /**
+     * Smoothly brakes the player toward a target speed expressed in mph.
+     */
+    brakeToMph(targetMph: number, dt: number, rate?: number): void;
+    /**
+     * Registers a collision callback without using the builder API.
+     */
+    onPlayerTrafficHit(handler: (collision: ArcadeRacerTrafficCollision) => void): void;
+    /**
+     * Removes all registered player-traffic collision handlers.
+     */
+    clearPlayerTrafficHitHandlers(): void;
+    /**
+     * Adds a billboard directly and returns its generated id.
+     */
+    addBillboard(visual: ArcadeRacerVisualSource, config: ArcadeRacerBillboardConfig): string;
+    /**
+     * 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.
+     */
+    clearTraffic(): void;
+    /**
+     * 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.
+     */
+    addHorizonMarker(visual: ArcadeRacerVisualSource, config: ArcadeRacerHorizonMarkerConfig): string;
+    /**
+     * Clears all configured horizon markers.
+     */
+    clearHorizonMarkers(): void;
+    /**
+     * Adds a parallax background image layer and returns its generated id.
+     */
+    addBackgroundLayer(visual: ArcadeRacerVisualSource, config?: ArcadeRacerBackgroundLayerConfig): string;
+    /**
+     * Clears all configured background image layers.
+     */
+    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;
+}