Architecture

Architecture

Runtime layers

TaxiDriverHUD (AngularJS / CEF)
        ⇅ bngApi.engineLua + guihooks
taxiDriver_taxiDriver (Game Engine Lua extension)
        ⇅ core_vehicleBridge / queueLuaCommand
taxiDriverTelemetry + taxiDriverCargo (Vehicle Lua extensions)
        ⇅ BeamNG road, route, minimap, trigger, site, and station systems
BeamNG.drive Free Roam

The GE extension is authoritative for gameplay state, routes, money, rating, penalties, persistence, realistic fuel, and delivery state. The UI owns presentation-only state such as 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 controller, state machine, routes, fares, persistence, fuel/cargo integration, HUD payloads
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/vehicle/extensions/auto/taxiDriverTelemetry.lua	Damage/g-force telemetry and forced-stop inputs
lua/vehicle/extensions/auto/taxiDriverCargo.lua	Physical cargo mass attached to the active vehicle
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	Seven complete localization dictionaries
ui/modules/apps/TaxiDriverHUD/app.json	BeamNG UI App registration and default dimensions
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

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) executes only while the mode is active.

• updateActiveMode(dtSim) advances gameplay and refuses to advance timers when dtSim <= 0.
• HUD emission is throttled with dtReal to approximately every 0.2 seconds.
• Refueling can request more frequent HUD updates (0.1 seconds) while its progress bar is active.

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 complete snapshots through:

• TaxiDriverHUDState;
• TaxiDriverProfileData.

The controller normalizes Lua empty tables because they can arrive as JavaScript objects instead of arrays.

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.

Three occlusion rectangles protect:

• route/arrival information;
• speed-limit sign;
• phone notifications.

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. The main extension is intentionally close to this limit. New independent configuration, pure calculations, or data pools should be placed in focused modules rather than adding top-level locals to taxiDriver.lua.