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()	—	Warms the current route and road caches for external polling
pollExternalState(roadRevision, mapRevision)	Browser cache revisions	Returns vehicle position every visible-map poll and returns roads, terrain, or route only when the corresponding revision changed

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 the private native minimap resources 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
Vue component/model disposal	Clears timers, listeners, watchdogs, animation frames and audio; releases the private minimap

Loading safely from UI

The shared game bridge 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.

Map interaction API (4.0.3)

• taxiDriver_taxiDriver.panMinimap(dx, dy): normalized map drag deltas.
• taxiDriver_taxiDriver.zoomMinimap(factor): multiplies manual zoom, clamped to 0.25–4.
• taxiDriver_taxiDriver.resetMinimapView(): clears inspection position and restores default follow/zoom.
• setMinimapOcclusions(..., allowFleet, controlsX, controlsY, controlsWidth, controlsHeight): retains the prior five rectangles and Fleet flag, then appends the map-controls rectangle.
• Native visibility combines ShowApps, UiAppsRouteUpdate.shown, CEF visibility and ui_router_afterRouteChange.request.name. Initial route reads use a callback-compatible Lua expression.

Vue and native AI lifecycle (5.0.0)

app.vue mounts the shared component through the game's vue/@/bridge APIs. The shared model owns hook subscriptions and disposes them on unmount. Late callbacks are ignored after disposal; UI recreation resynchronizes from Lua rather than starting a shift.

The stock-AI observer now handles initialized-route suffix delivery and junction signal ownership in addition to traffic caps and Route Done observation. Signals are derived from the assigned route in manual path mode, set only when the signal state changes, and released on pause, parking, failure and handoff. Hazard lights are retained.

Earth commands and personal service access (5.0.2)

The native/phone model uses requestEarthState() to request TaxiDriverEarthState and earthCommand(action, args) for planner actions. Each open panel sends a unique owner token, heartbeats every 2.5 seconds and releases its lease on close/unmount. The backend expires an abandoned lease after 10 seconds. UI clients include owner in their command arguments and reject stale/foreign acknowledgements.

Action	Principal arguments / behavior
open / close / heartbeat	owner token; open resets the start acknowledgement
mode	mode: vehicle or points
edit / search	field: a or b; query text
select	field and one-based result index
preview / randomPreview	Build an explicit/random route summary
setRandomLimit	maxRandomKm, clamped to 1–600; can save without an open panel lease
setWithoutPassenger	value boolean; persists the checkbox
teleport	target: a; explicit road-snapped movement
navigate	target: a or b; guarded direct Earth GPS action
startTrip	owner and withoutPassenger boolean; requires a ready preview and no incompatible paid phase
stopFreeRoute	End the personal session without a paid-trip abandonment penalty

A positive startedTripId acknowledges a successful start; for a personal route it is not a paid order ID. Personal trips keep ordinary HUD active false and do not create a passenger/paid phase.

requestFuelStop(), requestRealisticFuelData(), purchaseRealisticFuel(), purchaseRepair() and completeFuelStop()/cancelFuelStop() also support the personal-route service context in 5.0.2. That form preserves the personal GPS destination. It still validates vehicle, station, transaction, speed and affordability; it must not activate a taxi shift to obtain service.