AI Driver and Recovery

AI Driver and Recovery

Version 3.1.0 Beta adds an 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 only the final approach, local obstruction bypass 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 layer and restores the vehicle's previous gearbox behavior.

Component boundaries

Component	Runs in	Responsibility
taxiDriver.lua	Game Engine Lua	Selects the current trip/fuel target, records AI use, inserts critical-energy detours, 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 steering, powertrain/gearbox override, 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
  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
  Recovering --> Planning: Bypass completed; rebuild route
  Recovering --> WaitingTraffic: Corridor becomes unsafe
  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 traffic-rule obedience is enabled, the supervisor reads core_trafficSignals.getMapNodeSignals() for the current route edge.

• 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->>S: WaitingTraffic and retry
  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.

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 temporarily uses Arcade gearbox behavior, allowing reliable forward/reverse selection across vehicle configurations;
• short stationary waits remain in Drive with the service brake held;
• after ten seconds of an intentional hold, the controller requests the parked gear state where supported;
• Neutral is not used as the waiting state;
• disabling AI restores the previous Arcade/Realistic gearbox behavior and releases all TaxiDriver input filters.

Critical-energy fuel detours

Critical energy is <= 5% for supported combustion storage and <= 15% for electric storage.

flowchart TD
  Check{AI enabled and<br/>energy critical?}
  Check -->|no| Order[Continue order route]
  Check -->|yes| Occupied{Passenger/cargo<br/>already aboard?}
  Occupied -->|yes| Order
  Occupied -->|no| Station{Compatible station?}
  Station -->|yes| Detour[Insert priority fuel detour]
  Station -->|no| Magic[Stop and open Magic Fuel]
  Detour --> Refuel[Drive into exact station trigger]
  Refuel --> Order
  Magic --> Order

Loading

The accepted order remains intact. TaxiDriver never abandons or replaces it merely because a fuel detour is needed.

Settings and safe defaults

Setting	Range/default	Effect
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 traffic rules	On	Legal route speed and traffic-signal handling
Allow overtaking	On	Same-direction adjacent-lane changes only
Allow oncoming recovery	On	Permits a locally validated bypass across the opposite side when necessary

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.