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 facilities.facilities.json file.
• 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.

File location

Fuel stations are defined in the level facilities file:

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

Example:

levels/italy/facilities/facilities.facilities.json

Preview images can also be placed in the same folder:

levels/<levelName>/facilities/<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 facilities.facilities.json 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 gasoline, diesel, and unknown/fallback fuel types.

Electric charging station

Use this for EV charging stations:

"energyTypes": ["electricEnergy"]

Universal station

Use this only when the station should support every 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 facilities.facilities.json.

The point of interest position is used for the in-world icon and minimap marker.

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

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 keyed by fuel type.

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 formatted to three decimal places and then 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 facilities file.

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.
• The station supports the vehicle’s energy type.
• Fuel stations are enabled for the current game mode.

In freeroam, supported tanks are filled directly.

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

Fuel compatibility behavior

When the player interacts with a station, the game checks the vehicle’s energy storage types.

Behavior:

• If the station supports the vehicle’s fuel type, that tank can be filled.
• If the station has any, all fuel types can be filled.
• If the vehicle has an unsupported fuel type, that tank is not filled.
• air storage is ignored.
• unknown can be used as a fallback category for unrecognized fuel 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 marker position is based on the pump areas. The radius is calculated from the pump layout.

The in-world icon appears near the BeamNGPointOfInterest object for each pump.

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"] for normal fuel stations.
• 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 facilities.facilities.json file is in the wrong 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 station does not support the vehicle’s fuel type.
• 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 include unknown or 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:

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

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.