@jgengine/core 0.26.0 → 0.28.0

package/dist/nav/traffic.d.ts

@@ -0,0 +1,222 @@
+import { type LaneGraph } from "./laneGraph.js";
+import type { Waypoint } from "./pathFollow.js";
+/** One car's live state, as a renderer, a game or the devtools overlay reads it. */
+export interface TrafficCarView {
+    id: string;
+    laneId: string;
+    /** Arc, in metres, along the lane. */
+    arc: number;
+    position: Waypoint;
+    /** Yaw of travel, matching engine `rotationY`. */
+    heading: number;
+    /** World units per second. */
+    speed: number;
+    state: "driving" | "boxed" | "parked";
+    /** Parking spot held or reserved, while parking. */
+    spotId: string | null;
+    /** Stable integer for the game's model or colour choice; derived from the injected RNG. */
+    variant: number;
+}
+/** Caller-supplied exit choice at a junction: return one of `options`, or `null` to leave the graph. */
+export type TrafficRoutePolicy = (context: {
+    carId: string;
+    laneId: string;
+    nodeId: string;
+    /** Outbound lanes that are not the lane the car arrived on, sorted by id. */
+    options: readonly string[];
+}) => string | null;
+/** Every per-car behaviour number, retunable in play. */
+export interface TrafficTuning {
+    /** Body length, metres; sets the spacing a follower keeps. Default 4.4. */
+    carLength: number;
+    /** Body width, metres — one lane-change blend and the fallback lane spacing. Default 1.9. */
+    carWidth: number;
+    /** Acceleration while unobstructed, world units/s². Default 2.4. */
+    maxAccel: number;
+    /** Comfortable braking, world units/s². Default 3.2. */
+    comfortBrake: number;
+    /** Bumper-to-bumper gap at a standstill, metres. Default 1.6. */
+    minGap: number;
+    /** Time headway a follower keeps, seconds. Default 1.25. */
+    timeHeadway: number;
+    /** Multiplier on every lane's speed limit. Default 1. */
+    speedScale: number;
+    /** Free space the exit lane must show before a car is let into an intersection, metres. Default 6. */
+    boxClearance: number;
+    /** Seconds after a car clears an intersection before the next may enter. Default 0.55. */
+    boxCooldownSeconds: number;
+    /** Seconds a lane change takes to blend across. Default 1.2. */
+    laneChangeSeconds: number;
+    /** Seconds a car must be held up by a slower leader before it looks for another lane. Default 1.8. */
+    laneChangeBlockedSeconds: number;
+    /** Seconds between lane changes by one car. Default 4. */
+    laneChangeCooldown: number;
+    /** Clear window a lane change needs, as a multiple of the car's own length, each side. Default 1.6. */
+    laneChangeGapFactor: number;
+    /** Free stretch an entry lane must show before a car spawns on it, metres. Default 14. */
+    spawnGap: number;
+    /** Fraction of the lane limit a spawned car starts at. Default 0.55. */
+    spawnSpeedFactor: number;
+    /** Most cars spawned or retired in one tick. Default 3. */
+    fleetPerTick: number;
+    /**
+     * Seconds a car may stay stopped before the deadlock watch reports it. A red light or a queue is
+     * under this; a permanent stop is not. Default 60.
+     */
+    watchSeconds: number;
+    /** Fraction of the lane limit a car may carry into a turn sharper than 45°. Default 0.55. */
+    turnSpeedFactor: number;
+}
+/** Counters a devtools probe, a HUD or a test reads. */
+export interface TrafficStats {
+    cars: number;
+    parked: number;
+    boxed: number;
+    /** Cars holding at a stop line. */
+    waiting: number;
+    /** Cars added by the demand controller. */
+    spawned: number;
+    /** Cars that reached the end of the graph. */
+    exited: number;
+    /** Cars the demand controller removed to shrink the fleet. */
+    retired: number;
+    laneChanges: number;
+    parks: number;
+    /** Cars the deadlock watch has reported (stopped longer than `watchSeconds`). */
+    stalls: number;
+    /** Longest single stop any car has made, seconds — a red light or a queue. */
+    maxStillSeconds: number;
+    /** Longest stop a car made with clear road ahead — the deadlock measure. */
+    maxDeadlockSeconds: number;
+    ticks: number;
+    /** Slowest single `tick` seen so far, milliseconds. */
+    slowestTickMs: number;
+    /** Mean speed of every moving car, world units per second. */
+    meanSpeed: number;
+}
+/** An intersection's signal right now: which phase is green and for how long. */
+export interface TrafficSignalState {
+    node: string;
+    phase: number;
+    state: "green" | "yellow" | "red";
+    /** Seconds this phase has left, including its yellow and all-red. */
+    remaining: number;
+    /** In-lanes this green phase serves. */
+    lanes: readonly string[];
+}
+/** Serializable traffic state: the fleet, the parking occupancy, the signal clocks and the demand. */
+export interface TrafficSnapshot {
+    tunables: TrafficTuning;
+    demand: number;
+    counter: number;
+    rng: number | null;
+    cars: {
+        id: string;
+        laneId: string;
+        arc: number;
+        speed: number;
+        maxSpeed: number;
+        desiredSpeed: number;
+        state: "driving" | "boxed" | "parked";
+        cleared: boolean;
+        nextLane: string | null;
+        spotId: string | null;
+        lateral: number;
+        lateralRate: number;
+        changeCooldown: number;
+        blockedSeconds: number;
+        stillSeconds: number;
+        deadlockSeconds: number;
+        waitingSeconds: number;
+        stalled: boolean;
+        variant: number;
+    }[];
+    spots: {
+        id: string;
+        carId: string | null;
+    }[];
+    intersections: {
+        node: string;
+        elapsed: number;
+        cooldown: number;
+        holder: string | null;
+    }[];
+    counters: {
+        spawned: number;
+        exited: number;
+        retired: number;
+        laneChanges: number;
+        parks: number;
+        stalls: number;
+        ticks: number;
+        maxStillSeconds: number;
+        maxDeadlockSeconds: number;
+    };
+}
+/** Everything {@link createTraffic} needs: the graph, the injected generator and the caller's policies. */
+export interface TrafficOptions {
+    graph: LaneGraph;
+    /** Seed for the injected generator that varies cars. Same seed, same fleet. */
+    seed?: string | number;
+    /** Inject a generator instead of seeding one; its cursor is snapshotted when it has one. */
+    rng?: () => number;
+    tuning?: Partial<TrafficTuning>;
+    /** Exit choice at a junction. Omit for "least turn, never straight back". */
+    route?: TrafficRoutePolicy;
+    /** Initial fleet target; the caller moves this with the time of day. Omit to keep the fleet caller-driven. */
+    demand?: number;
+    /** Prefix for demand-spawned ids. Default `"traffic"`. */
+    idPrefix?: string;
+    /** Register a devtools probe under this name so the perf overlay shows traffic counters. */
+    devtoolsName?: string;
+}
+/**
+ * Traffic on an authored lane graph: cars follow lane spans with IDM car-following, hold at stop
+ * lines, cross intersections under a signal phase or first-come right-of-way, change lanes, park in
+ * authored spots, and grow or shrink with the caller's `demand`. Deterministic — cars advance in
+ * insertion order, ties break on id, and the injected generator is the only source of variety.
+ * Bounded per tick: one pass over the cars, one sorted pass per occupied lane, no path search.
+ */
+export interface Traffic {
+    /** Add a car at the start of a lane. False when the id exists or the lane is unknown. */
+    add(id: string, spec: {
+        laneId: string;
+        arc?: number;
+        speed?: number;
+    }): boolean;
+    remove(id: string): boolean;
+    has(id: string): boolean;
+    count(): number;
+    ids(): readonly string[];
+    car(id: string): TrafficCarView | null;
+    /** Visit every car in insertion order — one view record per car, no snapshot copy. */
+    forEachCar(visit: (car: Readonly<TrafficCarView>) => void): void;
+    /** Advance the whole fleet by `dt` seconds. */
+    tick(dt: number): void;
+    retune(patch: Partial<TrafficTuning>): void;
+    /**
+     * Fleet size the demand controller drives towards — a time-of-day count the caller computes, never a
+     * built-in curve. `-1` turns the controller off and leaves the fleet entirely caller-driven.
+     */
+    setDemand(count: number): void;
+    /** Current fleet target, or `-1` when the fleet is caller-driven. */
+    demand(): number;
+    /** Send a car to a parking spot on the lane it is already on. False when the spot is taken. */
+    park(id: string, spotId?: string): boolean;
+    /** Give up a parked spot and rejoin the lane. */
+    releaseParking(id: string): boolean;
+    /** Id of the car holding or reserving a spot, or null. */
+    spotOwner(spotId: string): string | null;
+    signal(nodeId: string): TrafficSignalState | null;
+    stats(): TrafficStats;
+    snapshot(): TrafficSnapshot;
+    restore(next: TrafficSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Traffic for an authored lane graph (see {@link createLaneGraph}).
+ *
+ * @capability traffic lane-graph traffic with car following, signals, right-of-way, lane changes and parking
+ */
+export declare function createTraffic(options: TrafficOptions): Traffic;