Facilities (*.facilities.json)

This page describes level facility files.

Facilities define named gameplay locations such as garages, gas stations, dealerships, computers, private sellers, delivery providers, and drag strips. They give gameplay meaning to places in a level, while spatial data usually comes from .sites.json files and scene objects.

For fuel and charging station setup, see Fuel Stations .

File locations

Facility data can be read from the level info.json and from facility files under the level’s facilities folder:

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

Examples:

levels/west_coast_usa/facilities/facilities.facilities.json
levels/west_coast_usa/facilities/dealerships.facilities.json
levels/west_coast_usa/facilities/delivery/shops.facilities.json

Some feature folders can also contain facility-like files for their own systems, such as drag strip facility files. Treat those as feature-specific data unless they are also referenced by the facilities system.

Loading behavior

The facilities system builds a facility list for the current level by reading:

The level’s info.json.
Every *.facilities.json file under levels/<levelName>/facilities/, including nested subfolders.

This means a level can keep simple facility entries in info.json, then split larger feature sets into separate files:

facilities.facilities.json
dealerships.facilities.json
delivery/shops.facilities.json
delivery/warehouses.facilities.json

Splitting files is useful when different systems or designers own different facility types. Facility ids still need to be stable and unique within the facility type after all files are loaded.

Creating facility files

There is no single universal editor for every facility type. The recommended workflow is to create the spatial data in the World Editor, then write or edit the facility JSON that points at that spatial data.

For most facility types:

Create or choose the scene objects used by the facility, such as gameplay areas, POIs, doors, pumps, or visible signs.
Create the required zones and parking spots in a .sites.json file, usually facilities.sites.json or a nearby feature-specific sites file.
Create or edit a *.facilities.json file under levels/<levelName>/facilities/.
Add the facility entry under the correct top-level array, such as garages, dealerships, or deliveryProviders.
Reference the sites file, zone names, parking spot names, and scene object names.
Reload the level or reload the gameplay system that consumes the facility.
Test the facility in freeroam, career, big map, or the feature-specific UI.

Use the dedicated editor or feature page when one exists. For example, fuel stations have a dedicated setup workflow, and drag strip facilities are best maintained through the drag racing tools where possible.

Writing facility files by hand

When writing by hand, start with the smallest valid entry and add feature-specific fields only after the facility appears in game.

Recommended order:

Add id, name, description, and preview.
Add sitesFile, zoneNames, and parkingSpotNames.
Test that the facility is discovered and has a usable position.
Add type-specific fields such as dealership filters, doors, delivery metadata, or gas station pump data.
Test the feature that consumes those type-specific fields.

Avoid copying a large shipped facility entry and changing only the id. Shipped entries may contain career, economy, delivery, or vehicle-shopping fields that are not needed for a simpler facility.

Naming and organization

Use stable ids and descriptive names:

garage_downtown
dealership_city_used
delivery_warehouse_west
computer_service_station

For large levels, split files by feature or owner:

facilities/facilities.facilities.json
facilities/dealerships.facilities.json
facilities/delivery/warehouses.facilities.json
facilities/delivery/shops.facilities.json

Keep related preview images and feature-specific sites files near the facility file when practical.

Facility types

The general facilities system recognizes these top-level arrays:

Facility type	Array name
Garage	`garages`
Gas station / charging station	`gasStations`
Dealership	`dealerships`
Computer	`computers`
Private seller	`privateSellers`
Delivery provider	`deliveryProviders`
Drag strip	`dragstrips`

A file can contain one or more of these arrays.

Common structure

Most facility entries share a small common core:

{
  "garages": [
    {
      "id": "downtownGarage",
      "name": "levels.example.facilities.downtownGarage",
      "description": "levels.example.facilities.downtownGarage.description",
      "preview": "downtownGarage.jpg",
      "sitesFile": "facilities.sites.json",
      "zoneNames": ["downtownGarageZone"],
      "parkingSpotNames": ["downtownGarageParking01"]
    }
  ]
}

Feature-specific fields are allowed and depend on the facility type. For example, dealerships can have vehicle filters and test-drive data, while gas stations define supported energy types and pump object pairs.

Structure by facility type

The examples below show the typical shape of each facility type. They are intentionally minimal; shipped levels may add extra career, economy, filtering, icon, or feature-specific fields.

Garage

{
  "garages": [
    {
      "id": "garage_downtown",
      "name": "levels.example.facilities.garage_downtown",
      "description": "levels.example.facilities.garage_downtown.description",
      "preview": "garage_downtown.jpg",
      "sitesFile": "facilities.sites.json",
      "zoneNames": ["garage_downtown_zone"],
      "parkingSpotNames": ["garage_downtown_parking_01"]
    }
  ]
}

Dealership

{
  "dealerships": [
    {
      "id": "dealership_city_used",
      "name": "levels.example.facilities.dealership_city_used",
      "description": "levels.example.facilities.dealership_city_used.description",
      "preview": "dealership_city_used.jpg",
      "doors": [["dealership_city_area", "dealership_city_icon", 30]],
      "parkingSpotNames": ["dealership_city_parking_01"],
      "filter": {
        "whiteList": {
          "Config Type": ["Factory"]
        },
        "blackList": {}
      }
    }
  ]
}

doors entries usually reference an interaction area/object, a POI/icon object, and an interaction range. Vehicle filters are consumed by career vehicle-shopping systems; keep them conservative until the dealership opens correctly.

Computer

{
  "computers": [
    {
      "id": "computer_service_station",
      "name": "levels.example.facilities.computer_service_station",
      "description": "levels.example.facilities.computer_service_station.description",
      "preview": "computer_service_station.jpg",
      "doors": [["computer_service_area", "computer_service_icon", 20]]
    }
  ]
}

Private seller

{
  "privateSellers": [
    {
      "id": "private_seller_hills",
      "name": "levels.example.facilities.private_seller_hills",
      "description": "levels.example.facilities.private_seller_hills.description",
      "preview": "private_seller_hills.jpg",
      "doors": [["private_seller_hills_area", "private_seller_hills_icon", 20]],
      "parkingSpotNames": ["private_seller_hills_parking"]
    }
  ]
}

Delivery provider

{
  "deliveryProviders": [
    {
      "id": "delivery_warehouse_west",
      "name": "levels.example.facilities.delivery_warehouse_west",
      "description": "levels.example.facilities.delivery_warehouse_west.description",
      "preview": "delivery_warehouse_west.jpg",
      "sitesFile": "delivery/warehouses.sites.json",
      "zoneNames": ["delivery_warehouse_west_zone"],
      "parkingSpotNames": ["delivery_warehouse_west_parking_01"]
    }
  ]
}

Drag strip facility

{
  "dragstrips": [
    {
      "id": "dragstrip_airfield",
      "name": "levels.example.facilities.dragstrip_airfield",
      "description": "levels.example.facilities.dragstrip_airfield.description",
      "preview": "dragstrip_airfield.jpg",
      "sitesFile": "facilities.sites.json",
      "zoneNames": ["dragstrip_airfield_zone"],
      "parkingSpotNames": ["dragstrip_airfield_parking"]
    }
  ]
}

Gas station

Gas stations use the same facilities file family, but their pump and energy setup is more specific. See Fuel Stations for the detailed structure.

Common facility fields

Many facility entries use the same field patterns:

Field	Purpose
`id`	Stable facility identifier used by gameplay, POIs, saves, and scripts.
`name`	Display name or translation key.
`description`	Display description or translation key.
`preview`	Preview image shown by UI where supported.
`sitesFile`	Sites file used to resolve zones and parking spots.
`zoneNames`	Zones associated with the facility.
`parkingSpotNames`	Parking spots associated with the facility.
`icon` / `playModeIconName`	Optional icon identifiers used by UI or map markers.
`tags`	Optional metadata for filtering or feature-specific behavior.

The facilities loader fills some defaults. If id is missing, a generated id may be produced from the file path and index, but this is not recommended for authored content because it is not stable across file reorganization.

Spatial references

Facilities commonly reference spatial data rather than storing all positions inline.

Reference	Usually resolves to
`sitesFile`	A `.sites.json` file, usually `facilities.sites.json` or a file near the facility file.
`zoneNames`	Zones in the referenced sites file.
`parkingSpotNames`	Parking spots in the referenced sites file.
`doors`	Scene object pairs used by dealerships, computers, or other interaction points.
`pumps`	Fuel station gameplay area and POI object pairs.

If sitesFile is missing, the loader falls back to facilities.sites.json where possible.

sitesFile can be a single file or, for advanced setups, a list of files. Use this when a facility must resolve parking spots or zones spread across multiple site files. Keep this rare; a single nearby sites file is easier to validate.

Facility-type notes

Garages

Garages commonly use zoneNames and parkingSpotNames. They are used by freeroam, career inventory, recovery/teleport workflows, and nearby service logic. Make sure parking spots are large enough and oriented correctly for expected vehicles.

To create a simple garage, create at least one zone and one parking spot, then add a garage entry that references them. Test teleport/recovery with several vehicle sizes.

Dealerships and private sellers

Dealerships and private sellers often include vehicle filters, fee data, test-drive settings, and door or POI references. Vehicle filter fields are consumed by career vehicle-shopping logic, so preserve unknown filter keys when editing with tools.

To create a dealership, first make the interaction door/area objects and parking spots, then add the dealership entry. Add filters only after the dealership appears and opens correctly.

Computers

Computer facilities are interaction points for career systems such as shopping, tuning, insurance, or other menus. They commonly use door/area references rather than parking-heavy data.

For computers, the most important part is that the referenced interaction object exists and is reachable by the player.

Delivery providers

Delivery providers are consumed by delivery generation and organization logic. They commonly pair facility metadata with delivery-specific sites and parking spots. Nested files under facilities/delivery/ are common in shipped content.

Delivery providers are easiest to maintain when their sites file lives next to the provider file. This keeps delivery zones, pickup/drop-off locations, and facility entries together.

Drag strips

Drag strip facilities connect freeroam/career UI to drag racing data. The drag racing gameplay still uses its own files under dragstrips/; the facility entry is the map/career integration layer.

Gas stations

Gas stations and EV charging locations have a dedicated setup page. See Fuel Stations for pump pairs, energy types, and price/display details.

Preview paths

Preview images are usually stored next to the facility file or in the level folder:

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

If a preview is missing, the UI may fall back to a generic placeholder.

Relationship with sites and POIs

Facilities are often visible in freeroam, career, and the big map. The displayed marker or interaction may come from:

The facility entry.
Zones or parking spots in a .sites.json file.
BeamNGGameplayArea and BeamNGPointOfInterest objects.
Feature-specific systems such as gas stations, delivery providers, dealerships, or drag strips.

Use Sites for site data and Gameplay Areas and Points of Interest for scene helper objects.

Troubleshooting

Facility does not appear

Check:

The file is in info.json or under levels/<levelName>/facilities/.
The file extension is *.facilities.json.
The facility is inside the correct top-level array, such as garages or dealerships.
The facility id is unique within its type.
Required feature-specific fields are present.

Facility appears but has no usable position