AI Driver and Recovery

AI Driver and Recovery

Version 3.1.1 RC expands 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 road-graph path, and a lazy Vehicle Lua controller handles final approach, local obstruction bypass, reverse escape, gearbox coordination, and collision-safety inputs.

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	Measures road/vehicle/obstacle geometry and produces a safe minimum-offset bypass path
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 -->|stationary blockage| Perception[autopilotPerception.lua]
  Perception -->|safe seven-point corridor| 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.
3. Normal path following uses BeamNG AI. TaxiDriver periodically observes distance, speed, the closest same-lane lead and the next traffic signal.
4. The Vehicle Lua controller wraps the Route Done GUI hook and reports it immediately to Game Engine Lua.
5. TaxiDriver verifies Euclidean distance. Native completion outside the trigger never counts as arrival.
6. An exact-approach path drives to the target with a 1.25 m completion radius and stops at the end. This is especially important for fuel and order triggers whose road node lies several metres away from their collision volume.

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. 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

The recovery planner is deliberately local. It is not a second global route finder.

1. Resolve the closest road link and orient its tangent with the vehicle heading.
2. Find the nearest stationary obstacle in the forward corridor and obtain both vehicles' initial dimensions.
3. Calculate the minimum lateral offset required on each side.
4. Reject a side if the car would cross the measured road boundary.
5. Sample the full candidate corridor in 1.5 m steps, projecting nearby traffic forward in time.
6. Choose the valid candidate with the smallest absolute offset.
7. Convert a smooth-step lateral profile into seven world-space points and activate the appropriate indicator.

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. Recovery is attempted only after progress has stopped for the configured delay and the geometry check finds an explicit safe corridor.

Reverse escape

When every usable forward angle is blocked, Vehicle Lua samples a rear-facing fan 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.

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 samples three rays across the vehicle width along short segments of the predicted steering arc. It intersects 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

With Cheat Zone debug logging enabled, filter beamng.log for [TaxiDriver] area=autopilot. Useful events include route start, lead acquisition/release, signal acquisition/release, queued-signal waiting, early route completion, exact approach, adaptive bypass reasons and completion. Vehicle-side powertrain and recovery records use the taxiDriverAutopilotRecovery source.