AI Driver and Recovery

AI Driver and Recovery

Version 3.3.0 Beta continues the optional supervisor around BeamNG's built-in vehicle AI. TaxiDriver does not replace the native road follower and does not require BeamNGpy. Game Engine Lua decides which trip target is authoritative, BeamNG AI follows the normal road route, and a deterministic predictive layer selects the final graph entrance, evaluates local free space, and hands a densified physical path to a lazy Vehicle Lua controller. Since 3.3.1 Beta this full supervisor is reserved for the player vehicle; Fleet Operations use a separate lightweight native-route implementation.

The button is available over the active trip map and fuel-route map in both the in-game UI App and Connected Phone. Taking control disables TaxiDriver's AI route layer and releases its filtered inputs.

Experimental behavior: this feature is deliberately made more for entertainment than dependable autonomy. BeamNG's built-in vehicle AI can still hesitate, choose an awkward lane, misread community-map metadata, or make a poor recovery decision. TaxiDriver is an attempt to make that native AI more sensible in a clear passenger/cargo route scenario, not a promise of production-grade autonomous driving.

Component boundaries

Component	Runs in	Responsibility
taxiDriver.lua	Game Engine Lua	Selects the current trip/fuel target, records AI use, handles explicit Refuel routes, forwards lifecycle callbacks
autopilot.lua	Game Engine Lua	Supervises native AI, following distance, signals, lane changes, early route completion and recovery state
autopilotPerception.lua	Game Engine Lua	Selects aligned graph entrances, evaluates 3D vehicle-relative free space/surfaces, and produces collision-checked approach or recovery paths
BeamNG ai module	Vehicle Lua	Normal road-graph path following and legal/off speed modes
taxiDriverAutopilotRecovery.lua	Vehicle Lua	Exact target approach, bypass/reverse steering, powertrain/gearbox coordination, indicators and trajectory-ray braking

flowchart LR
  Target[Trip phase chooses<br/>physical target] --> Supervisor[autopilot.lua]
  Supervisor -->|driveUsingPath| Native[BeamNG vehicle AI]
  Native --> Road[Road graph and traffic]
  Native -->|Route Done hook| Supervisor
  Supervisor -->|distance verification| Decision{Inside target radius?}
  Decision -->|yes| Stop[Stop and let trip trigger advance]
  Decision -->|no| Recovery[Vehicle Lua exact approach]
  Supervisor -->|target within 75 m or stationary blockage| Perception[autopilotPerception.lua]
  Perception -->|graph prefix + local suffix or recovery path| Recovery
  Perception -->|no forward corridor| RearFan[Rear collision fan]
  RearFan -->|clear 3–6 m escape| Recovery
  Recovery -->|complete / failed| Supervisor
  Recovery --> Rays[Curved trajectory rays]
  Rays -->|progressive or emergency brake| Vehicle[Vehicle inputs]

Loading

Supervisor state machine

stateDiagram-v2
  [*] --> Off
  Off --> Planning: Enable with valid route
  Planning --> Driving: Native path accepted
  Driving --> WaitingSignal: Red/yellow or queued traffic at signal
  WaitingSignal --> Driving: Signal/queue clears
  Driving --> RouteDone: Native AI reports completion outside trigger
  RouteDone --> Approaching: Exact low-speed path starts
  Approaching --> Stopping: Physical target radius reached
  Driving --> WaitingTraffic: Stationary obstruction has no safe corridor yet
  WaitingTraffic --> Driving: Lead moves or lane clears
  WaitingTraffic --> Recovering: Safe bypass becomes available
  Driving --> Recovering: Stuck timeout + safe bypass/reverse escape
  Recovering --> Recovering: Reverse clear, replan forward bypass
  Recovering --> Planning: Bypass completed; rebuild route
  Recovering --> WaitingTraffic: Corridor blocked / attempts exhausted
  Stopping --> Paused: Boarding, stop wait, loading or unloading
  Paused --> Planning: Next driving leg
  Planning --> Off: Player takes control / invalid phase
  Driving --> Off: Player takes control / vehicle unavailable

Loading

Statuses are UI-facing (planning, driving, waitingSignal, waitingTraffic, recovering, approaching, stopping, paused, off). The Lua state remains authoritative; the UI only sends toggleAutopilot().

Route and target handling

1. The current passenger, cargo, intermediate-stop or fuel target supplies a physical pos plus nearby road nodes.
2. autopilot.lua merges TaxiDriver's route with the target road node and sends ai.driveUsingPath with obstacle avoidance enabled for ordinary road travel.
3. Normal path following uses BeamNG AI. TaxiDriver periodically observes distance, speed, the closest same-lane lead and the next traffic signal.
4. A route-segment projection tracks remaining graph distance, current segment, and cross-track error; the remaining polyline also becomes the reference envelope for predictive access-route selection.
5. Curve and junction look-ahead applies an additional speed cap before a sharp graph transition instead of waiting to brake inside the turn.
6. The Vehicle Lua controller wraps the Route Done GUI hook and reports it immediately to Game Engine Lua.
7. TaxiDriver verifies physical and graph progress. Native completion outside the trigger never counts as arrival.
8. At up to 75 m from the target, the predictive planner can replace the final native leg with an aligned road-graph prefix plus a collision-checked local suffix. The controller uses a 0.7–0.8 m completion radius and stops inside or as close as safely possible to the physical trigger.

Predictive target approach

The final-approach model evaluates all nearby drivable access edges rather than steering toward the closest road node or the target in a straight line. Candidate graph prefixes must initially follow the remaining native route, advance rather than run backwards, and remain inside an early cross-track envelope. A collision-checked exact suffix connects each feasible access point to the physical trigger.

Complete routes are selected primarily by graph-prefix length plus local-suffix length. Clearance and local quality break only near-equal costs. The selected graph polyline is resampled to a maximum four-metre waypoint spacing before Vehicle Lua receives it.

The complete equations, thresholds, branch-and-bound rule, candidate score, surface model, and lifecycle diagrams are documented in Predictive Route Model.

Traffic lights and intersections

When Obey traffic signals is enabled, the supervisor reads core_trafficSignals.getMapNodeSignals() for the current route edge. This is independent from legal-speed mode.

• Red always requests a stop while the stop line remains ahead.
• Yellow compares the available stopping distance with configured braking ability; an unsafe late stop commits to clearing the intersection.
• After crossing the stop line, intersectionActive suppresses new signal holds until the vehicle has travelled beyond the intersection-clear distance.
• A stationary lead close to the same signal is classified as a queue, not a permanent obstruction.
• The queue is rescanned every update. A moving/disappearing lead releases the zero speed cap and rebuilds the normal path immediately.

This prevents both aggressive bypass attempts around ordinary red-light traffic and stopping in the middle of a turn because the signal changed after entry.

Following and same-direction overtaking

Lead selection projects nearby vehicles into the player's forward/lateral axes and ignores traffic outside the current lane corridor. A candidate must remain consistent for a short confirmation period; close candidates are also checked against Vehicle Lua's current collision-ray observation before they can control speed or trigger a lane change. The speed cap combines:

• configured following time gap;
• minimum and emergency bumper gaps;
• relative lead speed;
• comfortable deceleration;
• a short scan interval to avoid command spam.

If overtaking is enabled, a slow lead held within the configured distance can trigger a lane change only when the road metadata exposes at least two lanes in the same travel direction. The adjacent lane must be clear ahead and behind. Intersections, cooldowns, inner-lane position and weak road alignment suppress the manoeuvre. TaxiDriver signals before changing and cancels the signal when the lane-change timer completes.

Adaptive local bypass

Recovery now starts from vehicle-relative space rather than assuming that every useful motion corresponds to a marked lane.

1. Build the vehicle forward/left/up basis, including pitch and roll.
2. Cast a complete 180° fan in the active travel direction, with five width probes per direction.
3. Merge map-tracked traffic with ordinary parked scene vehicles and use oriented dimensions for clearance.
4. Evaluate a smooth minimum-offset path on both sides of the obstruction.
5. Check candidate surface height, steps, longitudinal slope, cross-slope, static geometry, and projected traffic motion.
6. If no simple corridor is sufficient, run bounded A* over a seven-ring, 24-direction local spatial graph.
7. Execute the shortest feasible path and then return control to the native road route.

sequenceDiagram
  participant S as Supervisor
  participant P as Perception
  participant V as Vehicle recovery
  participant M as BeamNG map/traffic

  S->>P: planLocalBypass(vehicle, leadId)
  P->>M: road link + nearby objects
  P->>P: test left/right boundaries
  P->>P: project traffic through corridor
  alt no safe corridor
    P-->>S: reason: tooClose / trafficConflict / roadBoundary
    S->>V: evaluate rear collision fan
    alt rear corridor available
      V->>V: reverse 3–6 m and rescan
      V-->>S: replan forward bypass
    else rear corridor blocked
      V-->>S: wait / stop after attempt limit
    end
  else safe minimum-offset corridor
    P-->>S: seven points + indicator + distance
    S->>V: start(points, speed, timeout, safety config)
    V->>V: steer/throttle/brake + trajectory rays
    V-->>S: onAutopilotBypassComplete
    S->>S: restore native route
  end

Loading

The supervisor does not disable BeamNG collision avoidance during normal driving. A normal obstruction still uses the configured stuck delay. Direct static contact within 1.65 m starts recovery after 1.5 seconds so the vehicle does not continue pushing a charger, wall, or barrier while waiting for the long timer.

Reverse escape

When every usable forward angle is blocked, Vehicle Lua samples rear-facing space across several steering values. Each candidate follows the predicted curved trajectory and checks static ray casts plus nearby vehicle boxes. The widest safe corridor wins; the target distance is clamped to 3–6 metres. Geometric left/right angles are converted once into BeamNG's steering-input sign convention, preventing the controller from turning opposite to the selected path.

During the maneuver, rear clearance is rescanned approximately every 0.08 seconds. A new obstacle aborts the reverse drive, and the controller brakes to a stop before notifying the GE supervisor. A successful escape does not count as route progress by itself: the supervisor immediately asks the forward perception planner for a fresh local bypass. A configurable attempt ceiling prevents an endless reverse/bypass loop.

flowchart TD
  Blocked[Forward recovery blocked] --> Fan[Cast rear steering fan]
  Fan --> Clear{Safe rear corridor?}
  Clear -->|no| Wait[Wait for traffic or player]
  Clear -->|yes| Reverse[Reverse 3–6 m]
  Reverse --> Rescan{Rear path still clear?}
  Rescan -->|no| Brake[Abort and brake]
  Rescan -->|yes| Done{Target distance reached?}
  Done -->|no| Reverse
  Done -->|yes| Forward[Replan minimum-offset forward bypass]

Loading

Trajectory-ray collision safety

Vehicle Lua and the GE planner sample five rays across the vehicle width along short segments of the predicted steering arc. They intersect those segments with:

• oriented boxes for nearby moving vehicles;
• BeamNG static ray casts where available.

The stopping model uses current speed, closing speed, following-gap preference and comfortable deceleration. Braking rises progressively inside the comfortable distance. An emergency distance or a time-to-collision below 0.65 seconds immediately commands full braking. Brake release is slower than brake application to avoid oscillation.

Powertrain and gearbox behavior

While TaxiDriver AI is active:

• combustion engines receive repeatable ignition/starter requests until rotation confirms that the powertrain is ready;
• the main controller switches to Arcade gearbox behavior once, allowing BeamNG to handle the clutch and forward/reverse selection across vehicle configurations;
• short stationary waits remain in Drive with the service brake held;
• Neutral is not used as the waiting state;
• if the controller is found in Neutral or Reverse while a forward departure is needed, a short forward-pedal/parking-brake handoff requests Drive without direct gear-index calls;
• disabling AI releases all TaxiDriver input filters; Arcade remains selected to avoid repeated behavior switching and manual-clutch damage during the same vehicle session.

Explicit refueling routes

AI never creates a fuel detour solely because fuel or charge is low. The player starts the route with Refuel and then chooses whether to enable AI on the refueling map.

flowchart TD
  Player[Player presses Refuel] --> Station{Compatible station?}
  Station -->|yes| Route[Create priority fuel route]
  Station -->|no| Magic[Open Magic Fuel]
  Route --> Choice{Player enables AI?}
  Choice -->|yes| Drive[AI drives to exact station trigger]
  Choice -->|no| Manual[Player drives manually]
  Drive --> Refuel[Player selects amount]
  Manual --> Refuel

Loading

The accepted order remains intact. Creating the refueling route releases any AI route that was already active so the player explicitly decides whether to enable it again.

Settings and safe defaults

Setting	Range/default	Effect
Preset	Balanced	Modest Novice, Cautious Driver, Balanced, Assertive, Mad Racer, or Custom
Aggression	10–80%, default 30%	Native AI aggression and recovery target speed profile
Following gap	1.2–3.5 s, default 2.2 s	Lead speed cap and comfortable braking horizon
Braking	1.5–4.5 m/s², default 2.8	Signal decisions and safety braking distance
Stuck delay	8–30 s, default 15	Time without progress before recovery analysis
Obey speed limits	On	BeamNG legal route-speed mode; independent from signals
Obey traffic signals	On	Red/yellow signal and queue supervision; independent from speed limits
Allow overtaking	On	Same-direction adjacent-lane changes only
Lane-change clearance	50–175%, default 100%	Scales required free distance ahead and behind
Allow oncoming recovery	On	Permits a locally validated bypass across the opposite side when necessary
Allow reverse recovery	On	Permits a rear-fan 3–6 m escape when forward recovery is blocked
Recovery attempts	1–5, default 3	Stops further automatic recovery after the limit
Exact-approach speed	5–20 km/h, default 12	Vehicle Lua speed for the physical trigger handoff

AI remains an assistance feature built on BeamNG traffic and road metadata. Community maps or vehicles with incomplete graph, lane, controller or dimension data can still produce imperfect behavior; the player can take control at any time.

Diagnostics

Two logging layers are available:

• General debug mode in Cheat Zone writes structured [TaxiDriver] records to beamng.log for runtime operations, warnings, and errors.
• AI trip logger in AI Driver settings writes a dedicated taxidriver_ailog_<timestamp>.jsonl file in the BeamNG user current directory. It is disabled by default and runs continuously only while manually enabled AI control is active.
• Visualize AI decisions independently draws the 180° sensor fan, rejected/feasible candidates, surface samples, spatial-graph nodes, selected route, and planner reason in the game world. It is disabled by default and recalculates the strategic model every 330 ms.

sequenceDiagram
  participant AI as autopilot.lua
  participant VL as Vehicle telemetry/recovery
  participant Log as aiLogger.lua
  participant File as taxidriver_ailog_TIMESTAMP.jsonl

  AI->>Log: start(vehicle, phase, target)
  loop each AI update
    AI->>Log: structured route/signal/lead/recovery events
    VL->>Log: gearbox, inputs, obstacle and damage telemetry
    Log->>File: append one-second snapshot + immediate events
    Log->>File: flush every record for crash readability
  end
  AI->>Log: stop(reason)
  Log->>File: final session summary and close

Loading

Each snapshot records the phase, target, physical and graph distance, route segment, cross-track error, speed, speed caps, lead confirmation, traffic signal, recovery signature, controller state, gearbox, ignition, pedals, g-forces, and accumulated damage. Immediate records highlight route changes, safety braking, ignition/gearbox transitions, gear hunting, damage increases, and repeated recovery cycles.

The journal is JSON Lines rather than one large JSON array, so a game crash still leaves every previously flushed record parseable. Disable the setting for normal play when this level of diagnosis is not required.