Architecture

Architecture

Runtime layers

flowchart TB
  subgraph Views[UI views]
    HUD[In-game TaxiDriverHUD<br/>AngularJS / CEF]
    Phone[Connected Phone browser<br/>same Angular app + Canvas map]
  end

  subgraph GE[Game Engine Lua — authoritative]
    Orchestrator[taxiDriver.lua<br/>phase and public API]
    Publisher[hudPublisher.lua<br/>epochs, snapshots, patches]
    Domains[Routing, persistence, shifts,<br/>economy, profile, events]
    Supervisor[autopilot.lua<br/>AI supervisor]
    Fleet[fleetManager.lua<br/>economy + worker lifecycle]
    Workers[fleetWorker.lua<br/>one AI instance per taxi]
    AIJournal[aiLogger.lua<br/>streaming JSONL diagnostics]
    Bridge[lanBridge.lua<br/>LAN TCP proxy]
  end

  subgraph VL[Lazy Vehicle Lua]
    Telemetry[taxiDriverTelemetry]
    Cargo[taxiDriverCargo]
    Recovery[taxiDriverAutopilotRecovery<br/>exact approach + safety rays]
  end

  BeamNG[BeamNG Free Roam systems<br/>road graph, traffic, triggers,<br/>stations, minimap, vehicles]

  HUD <-->|engineLua / guihooks| Orchestrator
  Phone <-->|HTTP + WebSocket| Bridge
  Bridge <--> Publisher
  Publisher <--> Orchestrator
  Orchestrator <--> Domains
  Orchestrator <--> Supervisor
  Orchestrator <--> Fleet
  Fleet <--> Workers
  Workers <--> Supervisor
  Supervisor --> AIJournal
  Orchestrator <-->|Vehicle Bridge| Telemetry
  Orchestrator <-->|lazy commands| Cargo
  Supervisor <-->|path and completion callbacks| Recovery
  GE <--> BeamNG
  VL <--> BeamNG

Loading

The GE extension is authoritative for gameplay state, routes, money, rating, penalties, persistence, realistic fuel, delivery state, and external-phone connectivity. The in-game and external UIs are views over the same Lua state. UI-only state includes open pages, local countdown animation, chat scheduling, audio players, and compact/full layout selection. Vehicle Lua supplies damage and g-force telemetry, can enforce an emergency stop, and applies physical cargo mass.

File map

File	Responsibility
lua/ge/extensions/taxiDriver/taxiDriver.lua	Runtime orchestrator, state machine, fares, fuel/cargo integration, and public UI API
lua/ge/extensions/taxiDriver/persistence.lua	Settings, difficulty, profile, progress schemas, validation, and JSON I/O
lua/ge/extensions/taxiDriver/routePlanner.lua	Road-graph routing, semantic stop discovery, speed limits, and level caches
lua/ge/extensions/taxiDriver/vehicleControl.lua	Telemetry, forced-stop/freeze control, and passenger/cargo access triggers
lua/ge/extensions/taxiDriver/vehicleHistory.lua	Vehicle identity, previews, per-configuration odometer, and work history
lua/ge/extensions/taxiDriver/shiftTracker.lua	Current and previous shift totals and net-income calculation
lua/ge/extensions/taxiDriver/shiftHistory.lua	Sanitized 60-second shift snapshots, installed-vehicle validation, and vehicle/energy restoration
lua/ge/extensions/taxiDriver/tripEvents.lua	Optional cancellations, route changes, tips, and fragile cargo rules
lua/ge/extensions/taxiDriver/autopilot.lua	Native-AI route supervision, following, signals, overtaking, exact approach, and recovery state
lua/ge/extensions/taxiDriver/autopilotPerception.lua	Road/obstacle geometry and collision-checked local bypass planning
lua/ge/extensions/taxiDriver/aiLogger.lua	Opt-in streaming JSONL journal for AI route, target, traffic, controller, gearbox, recovery, and damage events
lua/ge/extensions/taxiDriver/fleetManager.lua	Fleet hiring, economy, persistence, native/world markers, and employee lifecycle
lua/ge/extensions/taxiDriver/fleetWorker.lua	One isolated assignment state and autopilot.lua instance per hired vehicle
lua/ge/extensions/taxiDriver/config.lua	Static runtime, offer, balance, difficulty, fuel, and phase configuration
lua/ge/extensions/taxiDriver/identity.lua	Passenger-name pools and driver-avatar whitelist
lua/ge/extensions/taxiDriver/passengerMood.lua	Pure mood calculations and event severity functions
lua/ge/extensions/taxiDriver/offerGenerator.lua	Incremental coroutine job scheduler
lua/ge/extensions/taxiDriver/routeDiversity.lua	Spatial route-pair history and endpoint diversity validation
lua/ge/extensions/taxiDriver/delivery.lua	Cargo weight, fare premium, impact damage, and delivery-rating calculations
lua/ge/extensions/taxiDriver/lanBridge.lua	External UI lifecycle, stable pairing identity, LAN address selection, raw TCP bridge, complete road export, and external vehicle snapshots
lua/ge/extensions/taxiDriver/hudPublisher.lua	Full HUD snapshots, compact field patches, epochs, revisions, and resynchronization checks
lua/ge/extensions/taxiDriver/vehicleScanGuard.lua	Vehicle Config suspension, VM lifecycle generations, and stable-VM settle timing
lua/ge/extensions/taxiDriver/logger.lua	Structured [TaxiDriver] operations, runtime, LAN, vehicle, warning, and error records
lua/vehicle/extensions/taxiDriverTelemetry.lua	Lazy-loaded damage/g-force telemetry and forced-stop inputs
lua/vehicle/extensions/taxiDriverCargo.lua	Lazy-loaded physical cargo mass attached to the active vehicle
lua/vehicle/extensions/taxiDriverAutopilotRecovery.lua	Lazy exact-approach/bypass controller, powertrain/gearbox override, indicators, and trajectory-ray braking
ui/modules/apps/TaxiDriverHUD/app.js	Angular controller, Lua bridge, UI-only state, sounds, chat, minimap geometry
ui/modules/apps/TaxiDriverHUD/app.html	Phone screens and Angular bindings
ui/modules/apps/TaxiDriverHUD/app.css	Complete phone styling and animation
ui/modules/apps/TaxiDriverHUD/locales.json	Nine complete localization dictionaries
ui/modules/apps/TaxiDriverHUD/app.json	BeamNG UI App registration and default dimensions
ui/modules/apps/TaxiDriverHUD/external/	Lightweight browser entry point, detailed loader, synchronized phone runtime, sounds, and canvas map renderer
mod_info/TaxiDriver/info.json	Mod Manager metadata

GE extension dependencies

taxiDriver.lua declares:

• core_groundMarkers — route path and remaining length;
• core_vehicleTriggers — passenger-door trigger support;
• core_vehicle_manager — vehicle integration;
• freeroam_gasStations — station interaction and refueling wrappers;
• gameplay_sites_sitesManager — semantic parking/site candidates.

It additionally uses gameplay/route/route, gameplay/traffic/trafficUtils, map graph APIs, facility APIs, raw POIs, marker interaction, vehicle bridge, settings, and native minimap extension APIs.

State ownership

Persistent state

• userSettings
• driverProfile
• userProgress
• mirrored summary fields in state: balance, rating, rating totals, and completed rides

Shift state

• state.active, state.phase, active vehicle ID, difficulty, realistic-mode flag
• current offers pool
• active trip
• floating nextOffer and acceptance state
• telemetry snapshot
• station, refueling session, and fuel detour
• minimap/navigation ownership
• shiftTracker current totals, shiftHistory active snapshot identity, AI-use flag, and the active order's optional random event
• fleetManager session workers, worker routes, wage clocks, assignment state, and cached nearby traffic candidates

State publication and recovery

sequenceDiagram
  participant GE as taxiDriver.lua
  participant Pub as hudPublisher.lua
  participant UI as In-game UI
  participant LAN as lanBridge.lua
  participant Phone as Connected Phone

  GE->>Pub: authoritative state changed
  Pub->>UI: TaxiDriverHUDState or Patch
  Pub->>LAN: revisioned snapshot/patch
  LAN->>Phone: GUI hook over WebSocket
  Phone->>Phone: validate epoch + baseRevision
  alt continuous revision
    Phone->>Phone: merge changed fields
  else missing or stale revision
    Phone->>GE: request full state on heartbeat
    GE->>Pub: force snapshot
    Pub->>Phone: new authoritative state
  end

Loading

Cached map state

• semantic stop candidates keyed by level identifier;
• 24 recently accepted taxi stop positions;
• dynamic minimap wrapper and original settings.

Main update loop

M.onUpdate(dtReal, dtSim) services vehicle identity, energy, optional LAN state, and taxi gameplay while the mode is active. Vehicle Config temporarily suspends this work before BeamNG rebuilds the current vehicle VM.

• updateActiveMode(dtSim) advances gameplay and refuses to advance timers when dtSim <= 0.
• HUD emission is throttled with dtReal to approximately every 0.2 seconds.
• With Connected Phone active, periodic updates use revisioned field-level patches; full snapshots remain available for load and recovery.
• Refueling progress uses the same configured HUD interval instead of a separate 0.1-second stream.
• Vehicle lifecycle callbacks start a 1.5-second quiet period before telemetry, cargo, energy, and identity work resume.
• External HTTP and WebSocket proxy traffic is pumped non-blockingly before heartbeat evaluation, including while gameplay is paused or offline.
• Fleet workers update independently with simulation time; aggregate HUD data is refreshed once per second, nearby traffic candidates are cached for two seconds, and dirty fleet statistics are flushed after a five-second debounce.

The split means pause-safe gameplay with a responsive CEF interface.

UI communication

The UI never mutates the Lua state directly. It calls public extension methods using bngApi.engineLua. Lua emits authoritative data through:

• TaxiDriverHUDState for full snapshots;
• TaxiDriverHUDPatch for revisioned field-level changes;
• TaxiDriverProfileData.

Every HUD stream has an epoch and revision. Clients reject stale or out-of-order patches and request a full snapshot when baseRevision does not match. The controller also normalizes Lua empty tables because they can arrive as JavaScript objects instead of arrays.

Experimental External Web UI

BeamNG 0.38.6 may create its native External UI listener only on 127.0.0.1 even when it reports a LAN address. lanBridge.lua therefore binds TCP port 8085 specifically to the selected private IPv4 address and proxies raw traffic to 127.0.0.1:8085. Because the proxy is byte-transparent, it carries both static HTTP assets and the bng-ext-app-v1 WebSocket without maintaining a second gameplay state.

The bridge accepts a bounded number of clients, uses non-blocking reads/writes and bounded buffers, and is started only after the player enables Connected phone. The setting is session-only and returns to off whenever the UI App or mod starts. See External Web UI.

Native minimap integration

The map is not a screenshot or duplicated HTML renderer. TaxiDriver loads ui_apps_minimap_minimap, changes it to rectangular mode while owned, and reports the phone map rectangle in normalized screen coordinates.

Five occlusion rectangles protect:

• route/arrival information;
• speed-limit sign;
• phone notifications;
• the AI control overlay;
• the fleet Active drivers overlay.

All transforms and prior minimap settings are reset when the route screen disappears.

Free Roam fuel integration

Realistic Mode uses reversible function wrapping rather than permanently modifying BeamNG source. Restoration checks that the installed wrapper is still active before replacing it with the saved original function. This reduces interference with other extensions, although two mods wrapping the same function can still be load-order sensitive.

LuaJIT local-variable constraint

BeamNG's LuaJIT has a practical limit of 200 local variables in a function/chunk. Version 2.25.0 moved persistence, routing, vehicle control/history, shift accounting, and random events into focused modules. New independent configuration, pure calculations, or data pools should continue to live outside the main orchestrator.