HUD State Reference

HUD State Reference

TaxiDriverHUDState is the complete UI-facing snapshot emitted by the GE extension. Version 3.0.0 Beta and newer also emits TaxiDriverHUDPatch. Every full snapshot carries hudEpoch and hudRevision; every patch carries epoch, baseRevision, revision, changed values, and removed field names. The JavaScript controller accepts only a continuous revision chain and requests a full resynchronization after a gap.

Since 3.4.0 Beta, both the native UI App and Connected Phone use periodic patches. The fast periodic builder omits settings, shiftHistory, fleet, offers, and offerTargetCount. These collections are included after an explicit full-state event or when Fleet/shift ownership reports a real change. A partial patch does not interpret omitted keys as removals; only a complete patch comparison may emit the removed list.

Session and profile

Field	Type	Meaning
active	Boolean	Taxi shift is online
phase	String	Current phase ID from config.lua
phaseLabel	String	Backend diagnostic label; UI normally uses localized phase keys
message	String	Backend status/diagnostic message
balance	Number	Wallet balance rounded to cents
rating	Number	Persistent rating from 0 to 5
ratingCount	Integer	Number of ratings included in the average
completedRides	Integer	Successfully completed rides
difficulty	String	Active preset ID
realisticMode	Boolean	Realistic economy is active for this shift
shift	Object	Current and previous shift accounting snapshots
shiftHistory	Object	Restorable shift cards plus current restore status/ID
currentVehicle	Object	Selected vehicle identity, preview, odometer, work totals, and availability
autopilot	Object	Availability, enabled/suspended state, native-route status, reason, stationary time and stock-AI marker
fleet	Object	Fleet availability, economy, persistent totals, active drivers, garage/traffic candidates, and map markers
driverProfile	Object	{fullName, avatar} header summary
passengerOnboard	Boolean	Current phase logically contains a passenger
deliveryOnboard	Boolean	Current phase logically contains loaded cargo
settings	Object	Canonical settings document
settingsNeedsLegacyImport	Boolean	UI may import old local-storage settings
lan	Object	Experimental external-phone listener, connection count, address, port, URL, and bridge diagnostics

lan.enabled reflects the current session only. The bridge additionally reports bridgeReady and bridgeError; url contains the stable token and should not be published in bug reports.

Shift history projection

shiftHistory.items contains only sanitized, installed and non-zero-ride entries:

id, startedAt, lastSavedAt, vehicleName, vehiclePreview,
modelKey, configKey, rides, aiRides, grossIncome, fuelCost,
penaltyLoss, netIncome, averageRating, energyType, energyPercent

shiftHistory.restoring and restoringId prevent concurrent restore actions while BeamNG replaces and settles the vehicle.

AI driver projection

{
  available, enabled, suspended,
  status, reason,
  stuckSeconds, recoveryAttempt, stockAi
}

Known statuses are off, planning, driving, routeDone, routeUnavailable, playerVehicleChanged, and paused. recoveryAttempt remains zero for UI compatibility; premature native completions are recorded in AI diagnostics rather than exposed as a custom recovery state. See AI Driver and Recovery.

Fleet projection

{
  enabled, activeDrivers, maxDrivers,
  hiringFee, wagePerTenMinutes, ownerSharePercent, canAffordHire,
  stats: { rides, passengerRides, deliveryRides, distanceMeters,
           grossRevenue, ownerRevenue, wages, hiringFees },
  drivers: [{ id, vehicleId, name, preview, source, status, jobType,
              progress, remainingMeters, ai, stats }],
  markers: [{ id, position: [x, y, z], name }],
  trafficCandidates: [{ vehicleId, name, distance }],
  garage: [{ key, modelKey, configKey, name, preview }]
}

drivers are live, session-scoped BeamNG vehicles. stats are persistent. Marker positions are also included in Connected Phone map publication, while the native minimap obtains equivalent markers from the fleet manager's renderer. See Fleet Operations.

Dispatcher and queued offer

Field	Type	Meaning
offers	Array	Current dispatcher cards
offerTargetCount	Integer	Random target from 10 to 12
nextOffer	Object/null	Floating offer, remaining time, duration, accepted flag
notification	Object/null	Phone-local notification key, values, severity, and monotonic ID

Each offer exposes:

id, passengerName, passengerCalmness,
isDelivery, cargoWeightKg, cargoWeightBonusPercent,
cargoWeightBonusAmount, cargoDamagePercent,
pickupDistance, pickupEtaMinutes, pickupWaitSeconds,
rideDistance, etaMinutes,
baseFare, ratingAdjustedFare, estimatedFare,
ratingBonusPercent, ratingBonusAmount,
isMultiStop, stopCount, stopWaitSeconds,
isRush, bonusPercent, bonusAmount, timeLimitMinutes,
randomEvent

Active passenger and mood

Field	Type	Meaning
activeTripId	Integer	Current offer/trip ID; zero when absent
passengerName	String	Current passenger
passengerCalmness	Number	Current dynamic mood percentage
passengerInitialCalmness	Number	Mood at offer creation
passengerMoodMaximum	Number	Initial mood + 40, capped at 100
passengerMoodChangeId	Integer	Increments for each applied mood change
passengerMoodChangeDirection	String	up or down
passengerMoodChangeAmount	Number	Absolute applied change
passengerStressPercent	Number	Stress divided by the current mood-dependent threshold

Active cargo delivery

Field	Type	Meaning
isDelivery	Boolean	Current work item is a cargo delivery
cargoWeightKg	Number	Physical cargo mass selected for the order
cargoWeightBonusPercent	Number	Linear weight fare premium × 100
cargoWeightBonusAmount	Currency	Weight premium included in the delivery base fare
cargoDamagePercent	Number	Cumulative package damage from 0 to 100
finalFare	Currency	Locked completion payout
rideRating	Number	Delivery result from 1 to 5

Route and timing

Field	Type	Meaning
distanceToTarget	Metres	Ground-marker path length to current target
rideDistance	Metres	Complete passenger route length
etaMinutes	Minutes	ETA to current target at 40 km/h
rideEtaMinutes	Minutes	Remaining passenger drive plus scheduled waits
routeProgress	0–1	Current pickup, fuel, or complete passenger-route progress
progressLabel	String	Backend progress label
speedLimit	km/h	Closest road-link speed limit, or zero
currentSpeed	km/h	Active vehicle speed
nextStopDistance	Metres	Remaining distance to the current intermediate stop
fuelEnoughForTrip	Boolean	Estimated current range covers the remaining route
tripEvent	Object	Safe UI projection of the active optional random event

Pickup, stops, and rush

pickupWaitLimit, pickupTimeRemaining, pickupLate, pickupLateSeconds,
isMultiStop, stopCount, currentStopIndex, stopProgressMarkers,
stopWaitDuration, stopWaitRemaining,
rushOrder, rushBonusActive, rushBonusLost,
rushBonusAmount, rushTimeLimit, rushTimeRemaining

Every stop marker has {index, progressPercent, active, completed}.

Fare and penalties

Field	Type	Meaning
estimatedFare	Currency	Offer value including rating/rush bonus before penalties
adjustedFare	Currency	Current payable amount after penalties and lost rush bonus
tipAmount	Currency	Earned conditional event tip, included in final/projected payout
ratingBonusPercent	Number	Current rating bonus rate × 100
ratingBonusAmount	Currency	Rating bonus amount
penaltyPercent	Number	Capped combined penalty × 100
penaltyEvents	Array	UI event log with localized kind data
penalties	Object	Aggregate component values and event counters

Penalty event fields:

id, kind, label, detail, fareAmount, penaltyPercent,
speedExcess, duration, damage, peakG, lateSeconds, stationName

Kinds currently include speeding, collision, aggression, pickupDelay, bonus, fuelStop, and cargoDamage.

Vehicle energy dashboard

vehicleEnergy is refreshed through Vehicle Bridge at a throttled interval:

available, energyType, quantity, maxQuantity, percent, unit, estimatedRangeKm

The full and minimized ride dashboards use it to show current fuel/charge and approximate range without polling Vehicle Lua every frame.

Forced exit and offline confirmation

forcedExitDuration, forcedExitRemaining,
earlyExitRatingLossPercent,
offlinePenaltyExtraPercent, offlinePenaltyRatingLoss, offlinePenaltyFinalRating,
driverAbandonmentRatingLoss, driverAbandonmentExtraPercent

The UI uses the preview fields before calling confirmDriverAbandonment().

Fuel station model

fuelStation contains:

{
  available,
  id,
  name,
  magic,
  balance,
  options: [{
    energyType, unit,
    currentQuantity, maxQuantity, missingQuantity,
    affordableQuantity, currentPercent,
    pricePerUnit, maxCost, consumptionPer100Km
  }],
  refueling: {
    active, completing, energyType,
    quantity, cost, duration, elapsed,
    progress, remainingSeconds, completionId
  }
}

completionId allows the UI to detect a newly completed transaction even when subsequent state snapshots contain no active refueling session.

Fuel detour model

fuelDetour contains:

active, hadTrip, passengerOnboard,
stationName, routeDistance, penaltyPercent, arrived

The underlying Lua state also stores the previous phase and route information, but those internal values are not exposed to the UI.

Earth snapshot (5.0.2)

The full HUD includes earth; TaxiDriverEarthState also publishes planner/runtime updates. A personal route can be active while the ordinary paid-taxi active field is false and phase is inactive. Consumers must inspect earth.freeRoute.active rather than treating paid shift state as all navigation state.

Field	Meaning
available	Earth controls belong in this active supported Earth world; installation alone is insufficient
status	absent, unsupported, outsideWorld, disconnected, loading or ready
mode	vehicle or points
a / b	Query, selected geographic place, bounded results, searching flag and error
route	Preview status, road distance, duration, endpoints and error; no whole route geometry in regular snapshots
maxRandomKm / withoutPassenger	Saved random cap and personal-route preference
owner / startedTripId	Planner lease owner and successful-start acknowledgement
location	Current street or settlement string; empty when unavailable/outside Earth
gps	Compact Earth GPS summary when polled by the planner
freeRoute	Personal navigation runtime state

freeRoute includes active, status, leg (a or b), name of the current target, distanceM, remainingM, etaS and progress (0–1). Progress pauses while Earth is loading. The active session is not part of paid shift persistence.

World order cards add earth, pickupName, destinationName, pickupAddress and destinationAddress. Available address detail arrives asynchronously after the card is published.

fuelStation and repairStation can be available during a personal route even though paid taxi active is false. Use their availability, stopped flags and transaction fields to render service controls; do not infer eligibility solely from an active taxi shift.