Freeroam Facilities Fuel Price

Manages fuel price display on gas station 7-segment signs. Reads price configuration from facility data, applies randomness, and renders prices via TSStatic shape swapping.

Public API

Hooks

How It Works

1. On level start, reads all gas station facility data from freeroam_facilities
2. For each fuel type at each station, calculates price: baseline + randomnessGain * (random - bias)
3. Converts to US gallons if level uses gallonUS units
4. Formats price as 4-digit string and updates TSStatic display objects by swapping DAE shapes
5. Original display objects are hidden; cloned objects with correct shapes are created in a SimGroup
6. Disabled fuel types show dashes (-)

Display Object System

Each gas station defines displayObjects per fuel type - an array of arrays mapping digit positions to scene object names:

{
  "prices": {
    "gasoline": {
      "priceBaseline": 1.459,
      "priceRandomnessGain": 0.1,
      "priceRandomnessBias": 0.5,
      "us_9_10_tax": true,
      "displayObjects": [
        ["sign_digit1_a", "sign_digit1_b"],
        ["sign_digit2_a"],
        ["sign_digit3_a"],
        ["sign_digit4_a"]
      ]
    }
  }
}

Usage Examples

-- Get fuel price at a station (metric units)
local price = freeroam_facilities_fuelPrice.getFuelPrice("gas_station_01", "gasoline")

-- Force refresh displays
freeroam_facilities_fuelPrice.setDisplayPrices()

-- Debug: restore original sign shapes
freeroam_facilities_fuelPrice.restoreSign()

Notes

• US stations force digit 4 to 9 when us_9_10_tax is set (9/10 cent convention)
• Cloned display objects are stored in fuelPrice_localCopies SimGroup (non-saveable)
• Extension auto-unloads if no price data is found
• Serialization preserves prices across Lua reloads on the same level

Additional Exports

• M.onExtensionLoaded - (undocumented)
• M.onExtensionUnloaded - (undocumented)

See Also

• Freeroam Guide - Guide