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
resumeShift(shiftId)	Numeric history ID	Replaces the current vehicle with a validated saved configuration, waits for its VM, restores energy, and starts that session
toggleAutopilot()	—	Hands the current route to TaxiDriver's AI supervisor or returns control to the player
fleetCommand(action, args)	Action string and validated payload	Hires a garage/traffic vehicle or dismisses an active fleet driver; applies the returned wallet delta authoritatively
openVehicleSelector()	—	Opens BeamNG's native menu.vehicles state from either UI surface
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
cheatSetRating(value)	0–5	Re-rates complete driver, review, vehicle, and shift history and emits profile/HUD snapshots
cheatSetEnergyPercent(value)	0–100	Sets compatible fuel and battery storages through the same bridge as Realistic Mode
hudClientHeartbeat(epoch, revision)	Client state version	Requests recovery when the in-game client has missed state
cheatAddMoney(value)	1, 5, 10, or 50	Adds an allowed wallet increment and records balance history
cheatAddRandomReview()	—	Adds a synthetic review to persistent profile history
cheatResetProgress()	—	Resets wallet, rating, reviews, and analytics after UI confirmation

Experimental External Web UI methods

Method	Parameters	Behavior
externalPhoneHeartbeat(token)	Pairing token	Validates the external session and refreshes connection status
requestExternalMapData()	—	Publishes current route, complete chunked road graph, terrain tiles, and vehicle snapshot

Connected phone actions otherwise call the same public GE methods as the in-game phone through BeamNG's bng-ext-app-v1 transport. See External Web UI.

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

AI completion callbacks

Method	Source	Behavior
onAutopilotRouteDone(vehicleId)	Vehicle Lua Route Done observer	Dispatches Fleet IDs to their worker; for the player, verifies physical target distance and immediately replans a premature completion
onAutopilotBypassComplete(vehicleId, success, reason)	Legacy compatibility callback	Returns Fleet compatibility handling; the current player AI does not start a custom bypass controller

Minimap methods

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

Minimap calls are ignored outside toPickup, toStop, toDestination, and toFuelStation unless the explicit fleet-view flag is active.

BeamNG lifecycle and hooks

Method	Source
onUpdate(dtReal, dtSim)	GE extension update loop
onPreRender()	Draws localized nearby fleet labels while the UI App is visible and unblocked
onVehicleSwitched(oldId, newId)	Active vehicle change
onVehicleResetted(vehicleId)	GE vehicle reset hook
onExtensionLoaded()	Loads and canonicalizes persistent JSON
onClientStartMission()	Refreshes the selected vehicle identity, preview, energy, and odometer
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, g-force, powertrain, gearbox, pedal, and autopilot-controller telemetry every 0.2 seconds

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 lazy 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 lazy 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 lazy extension taxiDriverStockAiObserver exports:

• watch(config) — installs the temporary native Route Done observer and configures following/arrival protection;
• unwatch() — restores the original GUI hook and native route speed mode;
• updateGFX(dt) — updates straight/curved traffic prediction at the configured fixed interval;
• getDebugState() — exposes lead, TTC, speed-cap and curved-risk diagnostics;
• onExtensionUnloaded() — guarantees hook and speed-limit restoration.

The GE extension loads telemetry, cargo and the stock-AI observer only when their domain is required and controls them through queued Vehicle Lua commands.

Lua → UI events

TaxiDriverHUDState

Emitted by notifyHud() as a full authoritative snapshot with hudEpoch and hudRevision. See HUD State Reference.

TaxiDriverHUDPatch

Emitted for compact periodic updates while Connected Phone is active. It contains epoch, baseRevision, revision, values, and removed. A client must not merge a patch whose epoch or base revision differs from its current full state; it requests requestExternalHudState() instead.

TaxiDriverProfileData

{
  profile: { schemaVersion, modVersion, fullName, birthDate, avatar },
  progress: { /* complete progress.json model */ },
  vehicles: [ /* persisted completed-work vehicle journal */ ],
  avatarOptions: [ /* 32 whitelisted emoji */ ]
}

External map events

Event	Payload
TaxiDriverExternalMapData	Route revision, complete route point list, and target
TaxiDriverExternalRoadData	Road revision, chunk index/count, reset/complete flags, terrain tiles, and road segments
TaxiDriverExternalVehicleState	Player XY position and heading vector

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.