Lua API and UI Events

Lua API and UI Events

The GE extension is loaded as taxiDriver_taxiDriver from:

lua/ge/extensions/taxiDriver/taxiDriver.lua

The methods below are public because BeamNG hooks or the phone UI call them. They are not a compatibility-stable third-party API unless explicitly stated in a future release.

UI command methods

Method	Parameters	Behavior
startMode()	—	Validates vehicle and road graph, installs realistic economy when selected, enables telemetry, starts dispatcher
stopMode()	—	Stops immediately when no passenger/cargo is onboard; otherwise asks UI for confirmation
confirmDriverAbandonment()	—	Applies abandonment penalty and begins forced passenger exit
acceptOrder(offerId)	Numeric offer ID	Starts pickup for a dispatcher offer
acceptNextOffer(offerId)	Numeric offer ID	Marks the current floating offer as queued
expireNextOffer(offerId)	Numeric offer ID	Removes an unaccepted floating offer and schedules retry
requestHudState()	—	Emits TaxiDriverHUDState immediately
requestProfileData()	—	Emits TaxiDriverProfileData immediately
saveSettings(table)	Settings table	Sanitizes, persists, applies difficulty/guidance, and emits HUD state
setDifficulty(presetId)	String	Applies and persists a known difficulty preset
saveDriverProfile(table)	Profile table	Sanitizes and persists name, birth date, and avatar

Realistic fuel methods

Method	Parameters	Behavior
requestRealisticFuelData()	—	Refreshes station options through vehicle bridge
purchaseRealisticFuel(type, quantity)	Energy type string, readable quantity	Starts a validated timed purchase
requestFuelStop()	—	Finds and routes to the nearest compatible station
completeFuelStop()	—	Leaves an arrived detour when no purchase is active
cancelFuelStop()	—	Restores the previous route when no purchase is active

Minimap methods

Method	Parameters	Behavior
setMinimapTransform(x, y, width, height)	Normalized screen rectangle	Positions the native map in the phone or minimized dashboard
setMinimapOcclusions(...)	Three normalized rectangles	Protects route, speed, and notification overlays
hideMinimap()	—	Releases native minimap ownership and transforms

Minimap calls are ignored outside toPickup, toStop, toDestination, and toFuelStation.

BeamNG lifecycle and hooks

Method	Source
onUpdate(dtReal, dtSim)	GE extension update loop
onVehicleSwitched(oldId, newId)	Active vehicle change
onVehicleResetted(vehicleId)	GE vehicle reset hook
onExtensionLoaded()	Loads and canonicalizes persistent JSON
onClientEndMission()	Restores borrowed systems and writes progress
onExtensionUnloaded()	Restores borrowed systems and writes progress
onSerialize()	Legacy BeamNG extension serialization
onDeserialized(data)	One-time legacy progress import and runtime reset
onActivityAcceptGatherData(elements, activities)	Suppresses stock station action in Realistic Mode
onGetRawPoiListForLevel(level, elements)	Preserves station POIs when Free Roam station prompts are disabled

Vehicle telemetry callbacks

Method	Payload
onTelemetry(vehicleId, data)	{damage, longitudinalG, lateralG} every 0.2 seconds
onTelemetryVehicleReset(vehicleId)	Reset notification from Vehicle Lua

onTelemetry is ignored for non-active vehicles. Passenger penalties use passenger-driving phases; cargo deliveries use the same telemetry only for confirmed collision damage.

Vehicle extension API

The automatic extension taxiDriverTelemetry exports:

• setEnabled(boolean) — starts/stops telemetry updates;
• setForcedStop(boolean) — overrides throttle, brake, and parking brake;
• updateGFX(dt) — Vehicle Lua update hook;
• onReset() — releases overrides and notifies GE Lua.

The automatic extension taxiDriverCargo exports:

• setCargoMass(massKg) — creates, updates, or clears the physical cargo mass;
• onReset() — clears cargo state after a vehicle reset;
• onExtensionUnloaded() — guarantees cleanup when Vehicle Lua unloads.

The GE extension controls both automatic extensions through queued Vehicle Lua commands.

Lua → UI events

TaxiDriverHUDState

Emitted by notifyHud(). It is a full snapshot, not a patch. See HUD State Reference.

TaxiDriverProfileData

{
  profile: { schemaVersion, modVersion, fullName, birthDate, avatar },
  progress: { /* complete progress.json model */ },
  avatarOptions: [ /* 32 whitelisted emoji */ ]
}

UI-only events consumed

Event	Use
onCefVisibilityChanged	Hides native minimap when CEF is not visible and restores it when visible
SettingsChanged	Updates effective application volume from AudioUiVol
$destroy	Clears timers/listeners/audio and releases the minimap

Loading safely from UI

The controller uses this pattern for entry points that must work before the GE extension is loaded:

if not taxiDriver_taxiDriver then
  extensions.load("taxiDriver_taxiDriver")
end
taxiDriver_taxiDriver.startMode()

Subsequent calls first verify that taxiDriver_taxiDriver exists.