Realistic Refueling

Realistic Refueling

Realistic Mode replaces the stock Free Roam fuel interaction only while an active TaxiDriver shift is using that mode.

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.

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.

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 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.

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 map has no compatible station;
• 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.