Fuel Station Setup

This page explains how to add fuel stations and electric charging stations to a level.

A fuel station setup has two main parts:

• A facility entry in the level’s info.json or a *.facilities.json file under its facilities folder.
• A pair of level objects for each pump:
  • BeamNGGameplayArea
  • BeamNGPointOfInterest

The facility entry defines the station data, such as name, preview image, supported fuel types, and pump object references. The level objects define where the player can interact with the station.

See Facilities for the shared facility format and Gameplay Areas and Points of Interest for the two scene object classes.

File locations

Fuel stations can be defined in the level’s info.json or any facility file under:

levels/<levelName>/info.json
levels/<levelName>/facilities/*.facilities.json
levels/<levelName>/facilities/**/*.facilities.json

Example:

levels/italy/facilities/facilities.facilities.json

Preview filenames are resolved relative to the facility file first, then relative to the level root:

levels/<levelName>/facilities/<previewImage>.jpg
levels/<levelName>/<previewImage>.jpg

Basic structure

Fuel stations are listed under the gasStations array.

Example:

{
  "gasStations": [
    {
      "id": "fuel_example_station",
      "name": "Example Fuel Station",
      "description": "A fuel station near the main road.",
      "preview": "fuel_example_station.jpg",
      "energyTypes": ["gasoline", "diesel", "unknown"],
      "pumps": [
        ["fuel_example_station_pump_area_1", "fuel_example_station_pump_icon_1"],
        ["fuel_example_station_pump_area_2", "fuel_example_station_pump_icon_2"]
      ]
    }
  ]
}

A facility file may contain other facility types as well. In that case, gasStations is only one section of the file.

Gas station fields

Pump references

Each pump entry is an array containing two object names:

["<areaObjectName>", "<iconObjectName>"]

Example:

[
  "fuel_example_station_pump_area_1",
  "fuel_example_station_pump_icon_1"
]

The first object must be a BeamNGGameplayArea.

The second object must be a BeamNGPointOfInterest.

The order matters:

[BeamNGGameplayArea name, BeamNGPointOfInterest name]

Energy types

The energyTypes array defines which vehicle energy storage types the station can refill or recharge.

Common values:

Common energy type setups

Regular fuel station

Use this for most normal gas stations:

"energyTypes": ["gasoline", "diesel", "unknown"]

This supports the exact gasoline, diesel, and unknown energy storage types.

Electric charging station

Use this for EV charging stations:

"energyTypes": ["electricEnergy"]

Universal station

Use this only when the station should support every non-air energy type:

"energyTypes": ["any"]

Game object setup

For each pump, create:

BeamNGGameplayArea
BeamNGPointOfInterest

The BeamNGGameplayArea defines the interaction volume.

The BeamNGPointOfInterest defines where the in-world pump icon appears.

BeamNGGameplayArea placement

Place the BeamNGGameplayArea where the vehicle should stop to refuel.

Recommended placement:

• Put the area on the ground beside or around the fuel pump.
• Extend it outward from the pump so the vehicle can overlap it.
• Make it large enough for different vehicle sizes.
• Keep it small enough that vehicles do not trigger it from unrelated lanes or roads.
• Align it with the pump bay if possible.

The player can interact with the fuel station when their vehicle overlaps this area.

BeamNGPointOfInterest placement

Place the BeamNGPointOfInterest on or above the pump.

Recommended placement:

• Put it above the fuel pump or charging unit.
• Keep it visually associated with the pump.
• Use one point of interest per pump area.
• Give it a unique name.
• Reference it in the matching pump pair in the facility entry.

The point of interest position is used for the in-world pump icon and minimap marker. The big-map station marker uses the center of the valid gameplay-area objects.

Object naming

Use clear and stable object names.

Example naming pattern:

fuel_<stationName>_pump_area_1
fuel_<stationName>_pump_icon_1
fuel_<stationName>_pump_area_2
fuel_<stationName>_pump_icon_2

Example:

fuel_apex_mountainside_pump_area_1
fuel_apex_mountainside_pump_icon_1

Then reference them in the facility file:

"pumps": [
  ["fuel_apex_mountainside_pump_area_1", "fuel_apex_mountainside_pump_icon_1"],
  ["fuel_apex_mountainside_pump_area_2", "fuel_apex_mountainside_pump_icon_2"]
]

Complete basic example

{
  "gasStations": [
    {
      "id": "fuel_apex_mountainside",
      "name": "Apex Mountainside Fuel",
      "description": "Fuel station near the mountainside road.",
      "preview": "fuel_apex_mountainside.jpg",
      "energyTypes": ["gasoline", "diesel", "unknown"],
      "pumps": [
        ["fuel_apex_mountainside_pump_area_1", "fuel_apex_mountainside_pump_icon_1"],
        ["fuel_apex_mountainside_pump_area_2", "fuel_apex_mountainside_pump_icon_2"]
      ]
    }
  ]
}

Required level objects:

BeamNGGameplayArea:     fuel_apex_mountainside_pump_area_1
BeamNGPointOfInterest:  fuel_apex_mountainside_pump_icon_1

BeamNGGameplayArea:     fuel_apex_mountainside_pump_area_2
BeamNGPointOfInterest:  fuel_apex_mountainside_pump_icon_2

Optional preview image:

levels/<levelName>/facilities/fuel_apex_mountainside.jpg

Electric charging station example

{
  "gasStations": [
    {
      "id": "charge_downtown_01",
      "name": "Downtown Charging Station",
      "description": "Electric vehicle charging station.",
      "preview": "charge_downtown_01.jpg",
      "energyTypes": ["electricEnergy"],
      "pumps": [
        ["charge_downtown_01_area_1", "charge_downtown_01_icon_1"],
        ["charge_downtown_01_area_2", "charge_downtown_01_icon_2"]
      ]
    }
  ]
}

Stations with electricEnergy use charging-style map and interaction icons.

Preview image

The preview field points to an image used by map and facility UI.

Example:

"preview": "fuel_apex_mountainside.jpg"

Recommended location:

levels/<levelName>/facilities/fuel_apex_mountainside.jpg
levels/<levelName>/fuel_apex_mountainside.jpg

Best practices:

• Use a clear view of the station.
• Keep the file size reasonable.
• Use a descriptive filename.
• Make sure the filename in JSON matches the actual file.

Localization

The name and description fields can be plain text or localization keys.

Plain text example:

"name": "Apex Mountainside Fuel",
"description": "Fuel station near the mountainside road."

Localization key example:

"name": "levels.italy.gasStationPoints.fuel_apex_mountainside",
"description": "levels.italy.gasStationPoints.fuel_apex_mountainside.description"

For public mods, plain text is acceptable. For content that supports multiple languages, use localization keys and provide translations.

Optional fuel prices

Fuel stations can optionally define price data with a prices object.

Example:

{
  "id": "fuel_example_station",
  "name": "Example Fuel Station",
  "description": "A station with fuel price data.",
  "preview": "fuel_example_station.jpg",
  "energyTypes": ["gasoline", "diesel", "unknown"],
  "pumps": [
    ["fuel_example_station_pump_area_1", "fuel_example_station_pump_icon_1"]
  ],
  "prices": {
    "gasoline": {
      "priceBaseline": 1.65
    },
    "diesel": {
      "priceBaseline": 1.72
    }
  }
}

The prices object is normally keyed by the exact energy type so career refueling can look up its price. Additional keys can be used for disabled physical sign rows, but they are not fuel prices.

Price fields

Optional physical price displays

A station can drive physical price display objects using displayObjects.

The display is configured as a list of digit positions. Each digit position contains one or more object names.

Example:

"prices": {
  "gasoline": {
    "priceBaseline": 1.659,
    "displayObjects": [
      ["fuel_price_gasoline_digit_1"],
      ["fuel_price_gasoline_digit_2"],
      ["fuel_price_gasoline_digit_3"],
      ["fuel_price_gasoline_digit_4"]
    ],
    "us_9_10_tax": true
  }
}

The price is converted to US gallons first when the level’s local unit for that fuel is gallonUS, then formatted to three decimal places and displayed as individual digits.

For example:

1.659 -> 1659

Each display object is replaced at runtime with the matching digit mesh.

If disabled is set, the display shows - placeholders:

"prices": {
  "diesel": {
    "disabled": true,
    "displayObjects": [
      ["fuel_price_diesel_digit_1"],
      ["fuel_price_diesel_digit_2"],
      ["fuel_price_diesel_digit_3"],
      ["fuel_price_diesel_digit_4"]
    ]
  }
}

Runtime behavior

Fuel stations are loaded from the level’s info.json and *.facilities.json files discovered under its facilities folder.

When available, they appear as points of interest on the map and as in-world pump markers.

A player can interact with the station when:

• The vehicle overlaps one of the station’s BeamNGGameplayArea pump areas.
• Play-mode interaction is available and the vehicle is moving slowly enough for the pump marker to activate.
• Fuel stations are enabled for the current game mode.

In freeroam, tanks whose exact energy type is listed by the station are filled directly. any matches every non-air energy type.

In career mode, refueling may be handled by the career fuel transaction system.

Fuel compatibility behavior

In freeroam, the game checks the vehicle’s energy storage types when the player activates a station.

Behavior:

• If the station lists the tank’s exact energy type, that tank can be filled.
• If the station has any, every non-air energy type can be filled.
• If the vehicle has an unsupported fuel type, that tank is not filled.
• air storage is ignored.
• unknown matches only a tank whose energy type is literally unknown; it does not match other unlisted types.

If a vehicle has multiple energy storage types, the station may partially fill only the supported ones.

Map and marker behavior

Fuel station markers are generated from the facility entry.

The big-map marker position is the average position of the valid pump-area objects. Its radius is the greatest distance from that center to a valid pump area.

The in-world icon and minimap point use the matching BeamNGPointOfInterest position for each valid pump pair. A pair is skipped if either referenced object is missing.

Marker icon type depends on energy types:

A station is treated as electric if its energyTypes include:

"electricEnergy"

Best practices

• Add one gasStations entry per station.
• Use a unique and stable id.
• Use clear object names for pump areas and icons.
• Use one BeamNGGameplayArea and one BeamNGPointOfInterest per pump.
• Place the gameplay area where the player’s vehicle should stop.
• Make the gameplay area large enough for different vehicles.
• Place the point of interest above or on the pump.
• Add a preview image for map UI.
• Use ["gasoline", "diesel", "unknown"] only when the station should support those three exact types.
• Use ["electricEnergy"] for charging stations.
• Do not reference missing objects in the pumps list.
• Keep pump names stable after release to avoid breaking references.
• Test with several vehicle types and sizes.

Common issues

Station does not appear

Possible causes:

• The station is not listed under gasStations.
• The facility entry is not in info.json or a *.facilities.json file under the level’s facilities folder.
• The JSON file is invalid.
• Fuel stations are disabled in the current mode/settings.
• The station has no valid pump object pairs.

Interaction prompt does not appear

Possible causes:

• The vehicle is not overlapping the BeamNGGameplayArea.
• The gameplay area is too small.
• The gameplay area object name does not match the JSON entry.
• The vehicle is moving too quickly for the pump marker to activate.
• Play-mode interaction is unavailable.
• The pump pair references missing objects.

Icon appears in the wrong place

Possible causes:

• The BeamNGPointOfInterest is misplaced.
• The wrong icon object is referenced in the pump pair.
• The pump pair order is reversed.

Correct order:

["area_object_name", "icon_object_name"]

Vehicle does not refuel

Possible causes:

• The vehicle uses an energy type not listed in energyTypes.
• The station does not list the tank’s exact energy type and does not include any.
• The vehicle has multiple tanks and only some are supported.
• Career mode fuel transactions are unavailable or blocked.

Preview image is missing

Possible causes:

• The preview filename is wrong.
• The image is not included with the level or mod.
• The image is not in the expected folder.

Summary

To add a fuel station:

1. Create an entry under gasStations in either:

   levels/<levelName>/info.json
   levels/<levelName>/facilities/
   

2. Give the station a unique id.

3. Set name, description, and preview.

4. Set supported energyTypes.

5. For each pump, create:

   • BeamNGGameplayArea
   • BeamNGPointOfInterest

6. Add each pump pair to the pumps array:

   ["pump_area_name", "pump_icon_name"]
   

7. Optionally add a preview image and price data.

8. Test the station in game with compatible vehicles.

Related pages

• Facilities
• Gameplay Areas and Points of Interest
• Level Gameplay Data