Realistic Refueling

Realistic Refueling and Repair

Realistic Mode replaces the stock Free Roam fuel interaction while an active TaxiDriver shift is using that mode. Version 4.0.2 also adds vehicle repair to the same physical-station and Magic Fuel interface; repair remains available even without an active shift.

Activation and restoration

The setting is chosen before going online. startMode() installs wrappers around:

• freeroam_gasStations.refuelCar;
• freeroam_gasStations.onActivityAcceptGatherData.

The wrappers suppress the stock action and route station data into TaxiDriver. Original functions are retained and restored when the player goes offline, changes vehicle, ends the mission, unloads the extension, or fails startup.

Initial vehicle level

On first initialization of a vehicle during the shift:

Energy type	Initial level
Gasoline, diesel, kerosene	5%
Electric energy	30%

Unsupported storage types are not changed. Vehicle IDs are tracked so repeated HUD updates do not reset the same vehicle again.

Version 3.0.0 Beta exposes this same energyStorage request/action path to the Cheat Zone percentage control. Realistic Mode still supplies its fixed 5% combustion / 30% electric values; the cheat supplies one user-selected percentage for both.

Supported energy units

BeamNG stores energy in joules. TaxiDriver converts it using:

Energy type	MJ per readable unit	UI unit
Gasoline	31.125	L
Diesel	36.112	L
Kerosene	34.4	L
N₂O	8.3	kg
Electric energy	3.6	kWh

The conversion is symmetrical when values are read from or written to vehicle energy storage.

Ride-dashboard energy and range

While the shift is active, TaxiDriver requests energy storage through Vehicle Bridge once per second rather than polling every frame. Tanks of the same supported type are aggregated. The ride footer shows quantity to two decimal places and estimates range from configured reference consumption:

Energy type	Reference consumption
Gasoline	10 L/100 km
Diesel	8.5 L/100 km
Kerosene	12.5 L/100 km
Electric	22 kWh/100 km

These values provide a readable planning estimate; they are not a replacement for BeamNG's live powertrain simulation.

Prices

• Gasoline: fixed at $0.93/L.
• Electric energy: fixed at $0.50/kWh.
• Other supported types: use the map facility price when available; otherwise the fallback is $1.00 per readable unit.

Finding a station

The orange Refuel action is available while searching, travelling to pickup, travelling to a scheduled stop, or travelling to destination.

The extension:

1. queries the active vehicle's energy-storage types;
2. enumerates gasStation facilities;
3. filters stations by compatible energyTypes;
4. calculates road-route distance to each station;
5. selects the nearest reachable compatible facility.

The previous phase and route context are stored in realisticFuel.detour. The station becomes the priority target without deleting the active trip, offer pool, or queued request.

Version 3.1.1 RC makes refueling explicit again: low fuel or charge never redirects AI automatically. Press Refuel to create the priority detour, then enable AI from the fuel-route map if you want it to drive to the station. The accepted order remains retained, and fuel targets use exact physical approach so native road-node completion cannot leave the vehicle outside the station trigger.

If no compatible station exists, the phone opens Magic Fuel instead of failing the request. The fallback is visually distinct but deliberately reuses the ordinary vehicle-storage, wallet, refueling-duration, passenger-wait, and route-resume rules.

Magic Fuel also exposes the same repair service as a physical station. It uses the current vehicle position rather than a facility radius, but retains the stationary, damage, duration, pricing, and refuel/repair mutual-exclusion checks.

When no compatible station exists, Magic Fuel waits for the player to choose the amount. The AI button remains accessible above an ordinary fuel-route map. See AI Driver and Recovery.

Arrival and station overlay

Station availability requires:

• the active vehicle to be inside the station radius;
• speed no greater than 2 km/h;
• an active realistic shift.

The station radius is the BeamNG facility radius plus 12 m, with a minimum of 15 m.

The phone aggregates all tanks of the same energy type and provides:

• current and maximum readable quantity;
• current percentage;
• missing quantity;
• price per unit;
• quantity affordable from the TaxiDriver wallet;
• maximum purchase cost.

The overlay additionally shows the fuel/charge level before and after the proposed purchase, unit price, total cost, projected range, and whether that range covers the current order. Quick presets select +5 L, +10 L, 50%, or Full where applicable.

The slider cannot exceed either missing tank capacity or wallet affordability.

Timed refueling

The purchase is validated again against live vehicle storage before it starts. No balance is deducted until the timed process completes successfully.

• Liquid fuel rate: 2 readable units/s (normally litres per second).
• Electric charge rate: 4 battery percentage points/s.
• Minimum animation duration: 0.1 seconds.
• Progress advances with dtSim and pauses with the game.

The process is interrupted without payment if the vehicle changes, leaves the station, exceeds 2 km/h, the station changes, or realistic mode ends.

At completion, setEnergyStorageEnergy updates each affected tank, the wallet is reduced, balance history is recorded, and the overlay returns to the previous route.

Vehicle repair

The station panel reads current beamstate.damage, converts it to a bounded damage percentage, and calculates a repair price from the configured exponential saturation curve. The displayed damage and price are refreshed before purchase.

• In Realistic Mode, the TaxiDriver wallet must cover the quoted repair price and the completed cost is included in shift accounting.
• Outside Realistic Mode, repair is free.
• Repair and refueling cannot be active simultaneously. Both the UI and Lua purchase handlers enforce this rule.
• The vehicle must remain effectively stationary throughout the timed repair.

The original contribution used be:reloadVehicle(0). In BeamNG 0.39 this could crash during vehicle reconstruction. Version 4.0.2 instead uses the same in-place reset primitive as BeamNG's sandbox Repair vehicle action. TaxiDriver suppresses only the expected reset callback so an active shift survives, then restores the captured fuel or battery values after the physics reset has settled. This prevents a repair from also granting free energy.

The free debug-menu repair action uses the same low-level implementation without station or payment requirements.

The gas-station repair feature and its original in-game test matrix were contributed by JamDaBam in PR #2.

Passenger wait penalty

A station detour with a passenger onboard creates one penalty per station visit. Cargo deliveries do not receive a passenger-wait penalty. The passenger base depends on difficulty:

Difficulty	Base penalty
Elementary	0.6%
Easy	0.9%
Standard	1.2%
Professional	1.8%

Passenger mood and driver rating modify this value. The final individual stop penalty is clamped to 0.3–3%, and cumulative fuel-stop penalties for a ride are capped at 6%.

Route recovery

Closing or completing the station overlay restores the prior state:

• searching: keep the existing offer pool;
• toPickup: recalculate the remaining pickup route;
• toStop: recalculate the current stop leg;
• toDestination: recalculate the destination leg.

The already travelled portion is retained when rebuilding trip progress.

Failure cases

The phone reports a localized in-app warning when:

• the vehicle exposes no supported energy storage;
• route guidance to the station cannot be used in the current phase;
• the wallet cannot purchase a positive quantity;
• refueling is interrupted.